Kotlin — Ktor Server Foundations

Ktor Server Foundations

Introduction

Ktor is a Kotlin framework for constructing connected applications. In my opinion, the capabilities built into Ktor make building full-stack applications more efficient, adaptable, and maintainable with much less effort. This session focuses on the basic server components of Ktor. Subsequent sessions will expand on the server components, discuss client features, as well as cover advanced Ktor capabilities.

Getting Setup

Below is an excellent reference of an up-to-date setup page from ktor.io. This will allow you to get your development environment setup and start getting a feel for the dependencies and flow of Ktor. This setup will be useful for future sessions to follow along with the source examples and try them out for yourself.

Quick Start - Quick Start - Ktor

Ktor Server

Let’s start with some key concepts that will assist with learning how Ktor server applications are constructed. The next sections will breakdown three primary server components utilized extensively with the Ktor framework.

Application, Module, & Feature

Application

A custom program having modules that include installed features. An Application instance is the primary unit of a Ktor application which can listen on 1..* ports utilizing a configured server engine.

When requests are received by the Application, the request is converted to an ApplicationCall and goes through an application pipeline. That pipeline is composed of of 1..* interceptors (as installed) that can provide things like compression and routing that ultimately ends the request processing.

A Ktor application can be executed in a number of ways.

• Included as a test using withTestApplication from a ktor-server-test-host artifact
• Running as a main function of the EngineMain
• As a plain old main by invoking embeddedServer
• As a servlet in a web server

Modules

Modules are where the features are installed and configured. Think of them as user-defined functions accepting the Application class modeling things such as:

• Feature installations
• Configuration of the pipeline, routes, and request handling.

The application pipeline (referred to earlier) is typically defined through the set of modules used. As such, the modules are the core of the Ktor application.

What do modules look like?

Below is a mars module defined that routes a specific HTTP GET request where a plain text response is provided back to the caller. In this case, the routing (to /index) is the feature provided by the owned module mars.

package com.jjbanks.examples
fun Application.mars() {
    routing {
      get("/index") {
        call.respondText("Hello Oppy!")
      }
    }
}

The module’s fully qualified name becomes the following.

com.jjbanks.examples.MainKt.mars

Above, the mars function is defined as an extension method of the class Application. Under the covers, the following is created in the MainKt class.

static public void mars(Application app)

If you are not familiar with Kotlin extensions, checkout the reference below.

Extensions - Kotlin Programming Language

Modules are specified in an application.conf file and loaded when the servers starts. As stated earlier, modules are where features are installed and configured.

Now, let’s take a look at Ktor features.

Features

Features are basically objects that are installed and configured for a pipeline. The feature is a implemented as a singleton (think Kotlin companion object here).

The features can be custom, obtained from a shared community, or may be provided by Ktor as a standard feature. The features are included in an Application by invoking the install function. For example, if default headers, call logging, and routing features are needed, just invoke install with the built-in features.

install(DefaultHeaders) 
install(CallLogging)
install(Routing) 

Feature’s Helpers

Some features have helper functions defined as an extension function to Application. This removes the need to explicitly invoke the install function in your code.

routing {
        get("/") {
            call.respondText("Hello, World!")
        }
    }

The helpers may requires adding an additional dependency, but worth the cost in my opinion to have logic that flows and is easy to read with less code. It’s important to note that you can create your own features and share those across your Ktor applications.

Summary

Remember, the application pipeline is referred through the modules that contain the features. This is how features, modules, and the overall application are used for Ktor Server development.

When looking at a Ktor server application it becomes a little easier to understand when knowing about the relationship and usefulness of applications, modules, and features.

There are many more Ktor capabilities to explore in upcoming sessions, so stay tuned.

Until next time …

References

Servers - Servers - Ktor

Application - Servers - Ktor