Create a custom ApplicationEngine

Ktor’s HTTP client and server provide a common interface while allowing to use of several different engines to perform and handle HTTP requests.

Ktor includes several artifacts and engines:

  • For the server: Netty, Jetty, Tomcat, CIO, TestEngine
  • For the client: ApacheEngine, JettyHttp2Engine, CIOEngine, TestHttpClientEngine

ApplicationEngine API

A simplified version of the ApplicationEngine looks like this:

ApplicationEngineInterface.kt

1. interface ApplicationEngineFactory<
2. out TEngine : ApplicationEngine,
3. TConfiguration : ApplicationEngine.Configuration
4. > {
5. fun create(environment: ApplicationEngineEnvironment, configure: TConfiguration.() -> Unit): TEngine
6. }

8. interface ApplicationEngine {
9. val environment: ApplicationEngineEnvironment
10. fun start(wait: Boolean = false): ApplicationEngine
11. fun stop(gracePeriod: Long, timeout: Long, timeUnit: TimeUnit)

13. open class Configuration {
14. val parallelism: Int
15. var connectionGroupSize: Int
16. var workerGroupSize: Int
17. var callGroupSize: Int
18. }
19. }

21. interface ApplicationEngineEnvironment {
22. val connectors: List<EngineConnectorConfig>
23. val application: Application
24. fun start()
25. fun stop()

27. val classLoader: ClassLoader
28. val log: Logger
29. val config: ApplicationConfig
30. val monitor: ApplicationEvents
31. }

33. interface EngineConnectorConfig {
34. val type: ConnectorType
35. val host: String
36. val port: Int
37. }

39. data class ConnectorType(val name: String) {
40. companion object {
41. val HTTP = ConnectorType("HTTP")
42. val HTTPS = ConnectorType("HTTPS")
43. }
44. }

46. abstract class BaseApplicationEngine(
47. final override val environment: ApplicationEngineEnvironment,
48. val pipeline: EnginePipeline = defaultEnginePipeline(environment)
49. ) : ApplicationEngine {
50. val application: Application
51. }

ApplicationEngineFactory

Each implementation of the ApplicationEngineFactory along with a subtyped ApplicationEngine.Configuration define the publicly exposed APIs for each engine.

1. fun ApplicationEngineFactory.create(environment: ApplicationEngineEnvironment, configure: TConfiguration.() -> Unit): TEngine

The ApplicationEngineFactory.create instantiates the correct subtyped ApplicationEngine.Configuration and calls the provided configure: TConfiguration.() -> Unit lambda that should mutate the configuration object. It also constructs an implementation of the ApplicationEngine, most likely a subtype of BaseApplicationEngine.

For example:

1. class MyApplicationEngineFactory
2. <MyApplicationEngine, MyApplicationEngineConfiguration>
3. {

5. fun create(
6. environment: ApplicationEngineEnvironment,
7. configure: MyApplicationEngineConfiguration.() -> Unit
8. ): MyApplicationEngine {

10. val configuration = MyApplicationEngineConfiguration()
11. configure(configuration)
12. return MyApplicationEngine(environment, configuration)
13. }

15. }

BaseApplicationEngine

The interface ApplicationEngine with an abstract implementation of BaseApplicationEngine starts and stops the application.It holds the ApplicationEngineEnvironment as well as the constructed configuration of the application.

This class has two methods:

  • The start method: connects to the ApplicationEngineEnvironment.connectors (from the environment), starts the environment,and starts and configures the engine to trigger execution of the application pipeline for each HTTP request with an ApplicationCall.
  • The stop method: stops the engine and the environment, and unregisters all items registered by the start method.

The BaseApplicationEngine exposes an ApplicationEngineEnvironment passed to the constructor and creates an EnginePipeline,which is used as an intermediary to pre-intercept the application pipeline. It also installs default transformations in the send and receive pipelines,and logs the defined connection endpoints.

For example:

1. class MyApplicationEngine(
2. environment: ApplicationEngineEnvironment,
3. configuration: MyApplicationEngineConfiguration
4. ) : BaseApplicationEngine(environment) {
5. val myEngine = MyEngine()

7. override fun start(wait: Boolean): MyApplicationEngine {
8. environment.start()
9. myEngine.start()
10. myEngine.addRequestHandler(::handleRequest)
11. return this
12. }

14. override fun stop(gracePeriod: Long, timeout: Long, timeUnit: TimeUnit) {
15. myEngine.removeRequestHandler(::handleRequest)
16. myEngine.stop()
17. environment.stop()
18. }

20. private fun handleRequest(request: MyEngineCall) {
21. val call: ApplicationCall = request.toApplicationCall()
22. pipeline.execute(call)
23. }
24. }