Ktor 1.6.7 Help

Custom engines

Ktor's HTTP client and server provide a common interface while allowing to use of 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:

interface ApplicationEngineFactory< out TEngine : ApplicationEngine, TConfiguration : ApplicationEngine.Configuration > { fun create(environment: ApplicationEngineEnvironment, configure: TConfiguration.() -> Unit): TEngine } interface ApplicationEngine { val environment: ApplicationEngineEnvironment fun start(wait: Boolean = false): ApplicationEngine fun stop(gracePeriod: Long, timeout: Long, timeUnit: TimeUnit) open class Configuration { val parallelism: Int var connectionGroupSize: Int var workerGroupSize: Int var callGroupSize: Int } } interface ApplicationEngineEnvironment { val connectors: List<EngineConnectorConfig> val application: Application fun start() fun stop() val classLoader: ClassLoader val log: Logger val config: ApplicationConfig val monitor: ApplicationEvents } interface EngineConnectorConfig { val type: ConnectorType val host: String val port: Int } data class ConnectorType(val name: String) { companion object { val HTTP = ConnectorType("HTTP") val HTTPS = ConnectorType("HTTPS") } } abstract class BaseApplicationEngine( final override val environment: ApplicationEngineEnvironment, val pipeline: EnginePipeline = defaultEnginePipeline(environment) ) : ApplicationEngine { val application: Application }

ApplicationEngineFactory

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

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:

class MyApplicationEngineFactory <MyApplicationEngine, MyApplicationEngineConfiguration> { fun create( environment: ApplicationEngineEnvironment, configure: MyApplicationEngineConfiguration.() -> Unit ): MyApplicationEngine { val configuration = MyApplicationEngineConfiguration() configure(configuration) return MyApplicationEngine(environment, configuration) } }

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:

class MyApplicationEngine( environment: ApplicationEngineEnvironment, configuration: MyApplicationEngineConfiguration ) : BaseApplicationEngine(environment) { val myEngine = MyEngine() override fun start(wait: Boolean): MyApplicationEngine { environment.start() myEngine.start() myEngine.addRequestHandler(::handleRequest) return this } override fun stop(gracePeriod: Long, timeout: Long, timeUnit: TimeUnit) { myEngine.removeRequestHandler(::handleRequest) myEngine.stop() environment.stop() } private fun handleRequest(request: MyEngineCall) { val call: ApplicationCall = request.toApplicationCall() pipeline.execute(call) } }
Last modified: 09 September 2021