What Happens in a Server?

    In this section, you will discover what Ktor is doing under the hood, and you will learn moreabout its generic infrastructure.

    Table of contents:

    You can run a Ktor application in several ways:

    Start-up

    ApplicationEngineEnvironment:

    To begin with, this immutable environment has to be built;with a classLoader, a logger, a ,a monitor that acts as an event bus for application events,and a set of connectors and modules, that will form the application and watchPaths.

    You can build it using ApplicationEngineEnvironmentBuilder,and handy DSL functions applicationEngineEnvironment, commandLineEnvironment among others.

    :

    There are multiple ApplicationEngine, one per supported server like:Netty, Jetty, CIO or Tomcat.

    The application engine is the class in charge of running the application,it has a specific configuration, an associated environment and can be started and stopped.

    When you start a specific application engine, it will use the configurationprovided to listen, to the right ports and hosts,by using SSL, certificates and so on, with the specified workers.

    Connectors will be used for listening to specific http/https hosts and ports.While the Application pipeline will be used to handle the requests.

    It is created by the and it is initially empty.It is a pipeline without a subject that has ApplicationCall as the context.Each specified module will be called to configure this application when theenvironment is created.

    When you run your own main method and call the embeddedServer function,you provide a specific ApplicationEngineFactory andan ApplicationEngineEnvironment is then created or provided.

    Ktor defines one EngineMain class per each supported server engine.This class defines a main method that can be executed to run the application.By using commandLineEnvironment it will load the HOCON application.conffile from your resources and will use extra arguments to determine which modules to installand how to configure the server.

    Those classes are normally declared in CommandLine.kt source files.

    For testing, Ktor defines a TestApplicationEngine and withTestApplication handy method,that will allow you to test your application modules, pipeline, and other features withoutactually starting any server or mocking any facility.It will use an in-memory configuration that you can use to determine if it is to run in a test environment.

    Associated with the environment is a monitor instance that Ktor uses to raise application events.You can use it to subscribe to events. For example, you can subscribe to a stop application eventto shutdown specific services or finalize some resources.

    A list of :

    Pipelines

    Ktor defines pipelines for asynchronous extensible computations. Pipelines are used all over Ktor.

    All the pipelines have an associated subject type, context type, and a list of phaseswith interceptors associated to them. As well as, attributes that act as a small typed object container.

    Phases are ordered and can be defined to be executed, after or before another phase, or at the end.

    Each pipeline has an ordered list of phase contexts for that instance, which contain a set ofinterceptors for each phase.

    • Pipeline
      • Phase1
        • Interceptor1
        • Interceptor2
      • Phase2
        • Interceptor3
        • Interceptor4

    The idea here is that each interceptor for a specific phase does not depend on other interceptorson the same phase, but on interceptors from previous phases.

    When executing a pipeline, all the registered interceptors will be executed in the order defined by the phases.

    The server part of Ktor defines an ApplicationCallPipeline without a subjectand with ApplicationCall as context.The Application instance is an ApplicationCallPipeline.

    So when the server’s application engine handles a HTTP request, it will execute the Applicationpipeline.

    The context class ApplicationCall contains the application, the request, the response,and the attributes and parameters.

    In the end, the application modules, will end registering interceptorsfor specific phases for the Application pipeline, to process the request and emitting a response.

    The ApplicationCallPipeline defines the following built-in phases for its pipeline:

    Ktor defines application features using the class.A feature is something that you can install to a specific pipeline.It has access to the pipeline, and it can register interceptors and do all sorts of other things.

    Routing

    To illustrate how features and a pipeline tree work together, let’s have a look at how works.

    Routing, like other features, is normally installed like this:

    But there is an easy method to register and start using it, that also installs it if it is not already registered: