Ktor

https://ktor.io/docs/
Admin
Ktor is a framework for building asynchronous server-side and client-side applications with ease,...
Tokens:379,016
Snippets:3,677
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Routing plugin with install(RoutingRoot)

Source: https://ktor.io/docs/server-routing.html

Installs the Routing plugin using the `install` function. The `RoutingRoot` object is passed to `install`. The handler block is empty in this example.

```kotlin
import io.ktor.server.routing.*

install(RoutingRoot) {
    // ...
}
```

--------------------------------

### Example: LocalDate converter and manual usage

Source: https://ktor.io/docs/server-data-conversion.html

Full example: installs a converter for LocalDate using DateTimeFormatterBuilder and SimpleDateFormat, then manually calls the service to get encoded and decoded values.

```kotlin
install(DataConversion) {
    convert<LocalDate> { // this: DelegatingConversionService
        val formatter = DateTimeFormatterBuilder()
            .appendValue(ChronoField.YEAR, 4, 4, SignStyle.NEVER)
            .appendValue(ChronoField.MONTH_OF_YEAR, 2)
            .appendValue(ChronoField.DAY_OF_MONTH, 2)
            .toFormatter(Locale.ROOT)

        decode { values -> // converter: (values: List<String>) -> Any?
            LocalDate.from(formatter.parse(values.single()))
        }

        encode { value -> // converter: (value: Any?) -> List<String>
            listOf(SimpleDateFormat.getInstance().format(value))
        }
    }
}
```

```kotlin
val encodedDate = application.conversionService.toValues(call.parameters["date"])
val decodedDate = application.conversionService.fromValues(encodedDate, typeInfo<LocalDate>())
```

--------------------------------

### Install WebSockets plugin

Source: https://ktor.io/docs/client-websockets.html

Install the WebSockets plugin by passing it to the install function inside a client configuration block. This example uses the CIO engine.

```kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.websocket.*

//...
val client = HttpClient(CIO) {
    install(WebSockets)
}
```

--------------------------------

### Install FreeMarker plugin (embeddedServer and module)

Source: https://ktor.io/docs/server-freemarker.html

Install the FreeMarker plugin by passing it to the install function. The first example shows installation inside an embeddedServer() call, the second inside an explicitly defined module() extension function on the Application class.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.freemarker.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(FreeMarker)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.freemarker.*
// ...
fun Application.module() {
    install(FreeMarker)
    // ...
}
```

--------------------------------

### Install Routing plugin with routing function

Source: https://ktor.io/docs/server-routing.html

Uses the convenient `routing` function to install the Routing plugin, replacing `install(RoutingRoot)`. The handler block is empty in this example.

```kotlin
import io.ktor.server.routing.*

routing {
    // ...
}
```

--------------------------------

### Ktor API Key authentication minimal example

Source: https://ktor.io/docs/server-api-key-auth.html

Complete minimal Ktor server example that installs the API Key authentication provider, validates a header key against a hardcoded expected value, and exposes a protected route that returns the authenticated principal's key.

```kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

data class AppPrincipal(val key: String) : Principal

fun Application.module() {
    val expectedApiKey = "this-is-expected-key"

    install(Authentication) {
        apiKey {
            validate { keyFromHeader ->
                keyFromHeader
                    .takeIf { it == expectedApiKey }
                    ?.let { AppPrincipal(it) }
            }
        }
    }

    routing {
        authenticate {
            get("/") {
                val principal = call.principal<AppPrincipal>()!!
                call.respondText("Key: ${principal.key}")
            }
        }
    }
}
```

--------------------------------

### Custom header plugin example (partial)

Source: https://ktor.io/docs/client-custom-plugins.html

Starts a custom plugin example that adds a custom header to each request. The code is incomplete in the source, showing only the package and import statements.

```kotlin
package com.example.plugins

import io.ktor.client.plugins.api.*
```

--------------------------------

### Install Authentication plugin

Source: https://ktor.io/docs/server-auth.html

Install the Authentication plugin in an embeddedServer() call or in an explicit Application.module() extension function. Both examples show the required imports and the install(Authentication) call.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.auth.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Authentication)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
fun Application.module() {
    install(Authentication)
    // ...
}
```

--------------------------------

### Install Logging plugin on HttpClient

Source: https://ktor.io/docs/client-logging.html

Installs the Logging plugin on an HttpClient using the install function inside a client configuration block. This is the minimal setup required to enable logging.

```kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.logging.*
//...
val client = HttpClient(CIO) {
    install(Logging)
}
```

--------------------------------

### Install DefaultRequest using install function

Source: https://ktor.io/docs/client-default-request.html

Shows how to install the DefaultRequest plugin by passing it to the install function inside a client configuration block.

```kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    install(DefaultRequest)
}
```

--------------------------------

### Install Resources plugin in embeddedServer or module

Source: https://ktor.io/docs/server-resources.html

Install the Resources plugin by passing it to the install function. The first example uses an embeddedServer() call, the second uses an Application.module() extension function.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.resources.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Resources)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.resources.*
// ...
fun Application.module() {
    install(Resources)
    // ...
}
```

--------------------------------

### Install Webjars plugin

Source: https://ktor.io/docs/server-webjars.html

Installs the Webjars plugin by passing it to the install function. The first example installs it inside an embeddedServer() call, the second inside an explicitly defined module() extension function on the Application class.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.webjars.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Webjars)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.webjars.*
// ...
fun Application.module() {
    install(Webjars)
    // ...
}
```

--------------------------------

### Install WebSocket extensions with install and extensions

Source: https://ktor.io/docs/server-websocket-extensions.html

Shows how to install a custom WebSocket extension using the `extensions` and `install` methods within the `WebSockets` configuration. Extensions are used in the order of installation.

```kotlin
install(WebSockets) {
    extensions { /* WebSocketExtensionConfig.() -> Unit */
        install(MyWebSocketExtension) { /* MyWebSocketExtensionConfig.() -> Unit */
        /* Optional extension configuration. */
        }
    }
}
```

--------------------------------

### Install KtorServerTelemetry in embeddedServer or module

Source: https://ktor.io/docs/server-opentelemetry.html

Install the KtorServerTelemetry plugin in either an embeddedServer block or an Application.module() function. Both examples create an OpenTelemetry instance with getOpenTelemetry and pass it to setOpenTelemetry. Ensure KtorServerTelemetry is installed before any other logging or telemetry-related plugins.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.opentelemetry.instrumentation.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-sample-server")

        install(KtorServerTelemetry){
            setOpenTelemetry(openTelemetry)
        }
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.opentelemetry.instrumentation.*
// ...

fun Application.module() {
    val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-sample-server")

    install(KtorServerTelemetry){
        setOpenTelemetry(openTelemetry)
    }
    // ...
}
```

--------------------------------

### Install libcurl on Windows with pacman

Source: https://ktor.io/docs/faq.html

Install the curl library for the Ktor Curl client engine on Windows. Requires MinGW/MSYS2 installed first. After installation, add C:\msys64\mingw64\bin\ to the PATH environment variable if using the default installation location.

```bash
pacman -S mingw-w64-x86_64-curl
```

--------------------------------

### Routing.kt initial configuration

Source: https://ktor.io/docs/server-create-a-new-project.html

Initial Ktor routing configuration with a single GET endpoint at "/" that responds with "Hello World!". This is the starting point for adding a new HTTP endpoint.

```kotlin
fun Application.configureRouting() {
    routing {
        get("/") {
            call.respondText("Hello World!")
        }
    }
}

```

--------------------------------

### Install a custom plugin

Source: https://ktor.io/docs/server-custom-plugins-base-api.html

Shows how to install the custom plugin by calling Application.install() and passing configuration parameters.

```kotlin
install(CustomHeader) {
    headerName = "X-Custom-Header"
    headerValue = "Hello, world!"
}
```

--------------------------------

### Ktor receive JSON with ContentNegotiation

Source: https://ktor.io/docs/migration-from-express-js.html

Ktor setup for receiving JSON: install ContentNegotiation with the Json serializer, define a @Serializable data class, and use call.receive<Car>() in the route. Full example in the 7_receive_request project.

```kotlin
install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
    })
}
```

```kotlin
@Serializable
data class Car(val type: String, val model: String, val color: String)
```

```kotlin
post("/json") {
    val car = call.receive<Car>()
    call.respond(car)
}
```

--------------------------------

### Create Ktor client with custom AuthPlugin and send GET request

Source: https://ktor.io/docs/client-custom-plugins.html

Shows how to create an HTTP client with the CIO engine, install a custom AuthPlugin, and send a GET request to a local server. The token is set to "abc123" and the response body is printed. Requires the server to be started via startServer().

```kotlin
import com.example.plugins.*
import com.example.server.*
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.*

fun main() {
    startServer()
    runBlocking {
        val client = HttpClient(CIO) {
            install(AuthPlugin) {
                token = "abc123"
            }
        }
        val response = client.get("http://0.0.0.0:8080/")
        println(response.bodyAsText())
    }
}
```

--------------------------------

### Create and install a custom Ktor server plugin

Source: https://ktor.io/docs/server-custom-plugins.html

Steps to create and install a custom Ktor server plugin. First, define the plugin with createApplicationPlugin(name = "SimplePlugin") and print a message. Then install it in the application module using install(SimplePlugin). Running the application shows the plugin message in the console output.

```kotlin
import io.ktor.server.application.*

val SimplePlugin = createApplicationPlugin(name = "SimplePlugin") {
    println("SimplePlugin is installed!")
}

```

```kotlin
fun Application.module() {
    install(SimplePlugin)
}

```

```text
2021-10-14 14:54:08.269 [main] INFO  Application - Autoreload is disabled because the development mode is off.
SimplePlugin is installed!
2021-10-14 14:54:08.900 [main] INFO  Application - Responding at http://0.0.0.0:8080

```

--------------------------------

### Install AutoHeadResponse and define a GET route

Source: https://ktor.io/docs/server-autoheadresponse.html

Installs the AutoHeadResponse plugin and defines a GET route for /home. With this plugin, the route automatically responds to HEAD requests even without an explicit HEAD handler. Note that custom HEAD definitions for the same GET route will be ignored.

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.autohead.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.main() {
    install(AutoHeadResponse)
    routing {
        get("/home") {
            call.respondText("This is a response to a GET, but HEAD also works")
        }
    }
}
```

--------------------------------

### Build fat JAR and start Docker Compose services

Source: https://ktor.io/docs/docker-compose.html

Builds the fat JAR for the tutorial-server-docker-compose module, then uses Docker Compose to build images and start containers. After startup, the web application is available at http://localhost:8080/static/index.html.

```bash
./gradlew :tutorial-server-docker-compose:buildFatJar
```

```bash
docker compose --project-directory snippets/tutorial-server-docker-compose up
```

--------------------------------

### Create and install a custom client plugin with createClientPlugin

Source: https://ktor.io/docs/client-custom-plugins.html

Steps to create and install a custom client plugin: define the plugin with createClientPlugin, add an onRequest handler to append a custom header, then install it in the client configuration.

```kotlin
package com.example.plugins

import io.ktor.client.plugins.api.*

val CustomHeaderPlugin = createClientPlugin("CustomHeaderPlugin") {
    // Configure the plugin ...
}
```

```kotlin
package com.example.plugins

import io.ktor.client.plugins.api.*

val CustomHeaderPlugin = createClientPlugin("CustomHeaderPlugin") {
    onRequest { request, _ ->
        request.headers.append("X-Custom-Header", "Default value")
    }
}
```

```kotlin
import com.example.plugins.*

val client = HttpClient(CIO) {
    install(CustomHeaderPlugin)
}
```

--------------------------------

### Handle X-Http-Method-Override requests with delete route

Source: https://ktor.io/docs/server-method-override.html

Complete example showing how to handle requests with the X-Http-Method-Override header. It installs XHttpMethodOverride and ContentNegotiation, defines a Customer data class, and sets up GET and DELETE routes for /customer/{id}. The delete route removes the customer and responds with a NoContent status.

```kotlin
package com.example

import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.plugins.methodoverride.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import io.ktor.server.util.getValue

@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

fun Application.main() {
    val customerStorage = mutableListOf<Customer>()
    customerStorage.addAll(
        arrayOf(
            Customer(1, "Jane", "Smith"),
            Customer(2, "John", "Smith"),
            Customer(3, "Jet", "Brains")
        )
    )

    install(XHttpMethodOverride)
    install(ContentNegotiation) {
        json(Json)
    }
    routing {
        get("/customer/{id}") {
            val id: Int by call.parameters
            val customer: Customer = customerStorage.find { it.id == id }!!
            call.respond(customer)
        }

        delete("/customer/{id}") {
            val id: Int by call.parameters
            customerStorage.removeIf { it.id == id }
            call.respondText("Customer is removed", status = HttpStatusCode.NoContent)
        }
    }
}
```

--------------------------------

### Install XForwardedHeaders in embeddedServer

Source: https://ktor.io/docs/server-forward-headers.html

Installs the XForwardedHeaders plugin inside an embeddedServer(Netty) call. Place install(XForwardedHeaders) in the server configuration block before starting the server.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(XForwardedHeaders)
        // ...
    }.start(wait = true)
}
```

--------------------------------

### Create the Ktor client with installKrpc

Source: https://ktor.io/docs/tutorial-first-steps-with-kotlin-rpc.html

Creates an HttpClient and installs the kotlinx.rpc plugin using installKrpc, configuring JSON serialization. The kotlinx.rpc library uses the WebSockets plugin under the hood, and installKrpc ensures it is loaded.

```kotlin
val ktorClient = HttpClient {
    installKrpc {
        serialization { json() }
    }
}
```

--------------------------------

### Install ForwardedHeaders in embeddedServer

Source: https://ktor.io/docs/server-forward-headers.html

Installs the ForwardedHeaders plugin inside an embeddedServer(Netty) call. Place install(ForwardedHeaders) in the server configuration block before starting the server.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(ForwardedHeaders)
        // ...
    }.start(wait = true)
}
```

--------------------------------

### Configuration file: modules in Application.kt and Sample.kt

Source: https://ktor.io/docs/server-modules.html

Shows how to define modules in two separate files (Application.kt and Sample.kt) that will be loaded via a configuration file. The modules are defined as extension functions on Application and each sets up a route.

```kotlin
package com.example

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

fun Application.module1() {
    routing {
        get("/module1") {
            call.respondText("Hello from 'module1'!")
        }
    }
}

fun Application.module2() {
    routing {
        get("/module2") {
            call.respondText("Hello from 'module2'!")
        }
    }
}
```

```kotlin
package org.sample

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module3() {
    routing {
        get("/module3") {
            call.respondText("Hello from 'module3'!")
        }
    }
}
```

--------------------------------

### Navigate into the unpacked project folder

Source: https://ktor.io/docs/server-create-a-new-project.html

Change to the newly created project directory.

```bash
cd ktor-sample
```

--------------------------------

### Install or replace plugin with installOrReplace()

Source: https://ktor.io/docs/client-plugins.html

Use installOrReplace() to install a plugin if it is not present or replace its existing configuration if it has already been installed, for example by shared client configuration code.

```kotlin
val client = HttpClient(CIO) {
    installOrReplace(ContentNegotiation) {
        // ...
    }
}
```

--------------------------------

### Install DefaultRequest using defaultRequest function

Source: https://ktor.io/docs/client-default-request.html

Shows how to install the DefaultRequest plugin by calling the defaultRequest() function and configuring required request parameters.

```kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    defaultRequest {
        // this: DefaultRequestBuilder
    }
}
```

--------------------------------

### Install PartialContent in embeddedServer

Source: https://ktor.io/docs/server-partial-content.html

Installs the PartialContent plugin inside an embeddedServer function call. This is one of two ways to install the plugin, useful for standalone server setups.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.partialcontent.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(PartialContent)
        // ...
    }.start(wait = true)
}
```

--------------------------------

### Sample HTML file for static content

Source: https://ktor.io/docs/server-create-a-new-project.html

Example HTML file to be placed in the 'mycontent' directory. It displays a simple page with a list of technologies.

```html
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>My sample</title>
    </head>
    <body>
        <h1>This page is built with:</h1>
        <ol>
            <li>Ktor</li>
            <li>Kotlin</li>
            <li>HTML</li>
        </ol>
    </body>
</html>
```

--------------------------------

### Create Procfile with web command

Source: https://ktor.io/docs/heroku.html

Create a Procfile in the project root with this content. It specifies the path to the executable generated by the stage task. Replace ktor-get-started-sample with your project name.

```plaintext
web: ./build/install/ktor-get-started-sample/bin/ktor-get-started-sample
```

--------------------------------

### Install Pebble in embeddedServer

Source: https://ktor.io/docs/server-pebble.html

Installs the Pebble plugin inside an embeddedServer() call. The server starts on port 8080 with Netty engine.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.pebble.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Pebble)
        // ...
    }.start(wait = true)
}
```

--------------------------------

### Install HSTS plugin in embeddedServer or module

Source: https://ktor.io/docs/server-hsts.html

Install the HSTS plugin by passing it to the install function. The first example installs it inside an embeddedServer() call, the second inside an explicitly defined module() extension function on the Application class.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.hsts.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(HSTS)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.hsts.*
// ...
fun Application.module() {
    install(HSTS)
    // ...
}
```

--------------------------------

### Install Resources in Application.module()

Source: https://ktor.io/docs/server-locations.html

Shows how to install the Resources plugin in an explicitly defined module() extension function on the Application class. Requires the io.ktor.server.resources.* import.

```kotlin
import io.ktor.server.application.*
import io.ktor.server.resources.*
// ...
fun Application.module() {
    install(Resources)
    // ...
}
```

--------------------------------

### Install WebSockets plugin

Source: https://ktor.io/docs/server-websockets.html

Install the WebSockets plugin either inside an embeddedServer() call or in an explicitly defined Application.module() extension function. Both examples show the required imports and the install(WebSockets) call.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.websocket.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(WebSockets)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.websocket.*
// ...
fun Application.module() {
    install(WebSockets)
    // ...
}
```

--------------------------------

### Install StatusPages in embeddedServer or module

Source: https://ktor.io/docs/server-status-pages.html

Install the StatusPages plugin either inside an embeddedServer() call or in an explicit Application.module() extension function. Both examples show the required imports and the install(StatusPages) call.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(StatusPages)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*
// ...
fun Application.module() {
    install(StatusPages)
    // ...
}
```

--------------------------------

### Run packaged application

Source: https://ktor.io/docs/server-packaging.html

Executes the packaged application from the build/install/<project_name>/bin folder. The first command is for Linux/macOS, the second for Windows.

```bash
./ktor-sample
```

```batch
ktor-sample.bat
```

--------------------------------

### Implement key and install() for a custom plugin

Source: https://ktor.io/docs/server-custom-plugins-base-api.html

Implements the required key property and install() function. The key identifies the plugin in Ktor's attributes, and install() configures the plugin by intercepting pipeline phases before returning the plugin instance.

```kotlin
class CustomHeader() {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val plugin = CustomHeader()
            // Intercept a pipeline ...
            return plugin
        }
    }
}
```

--------------------------------

### Install PartialContent in module function

Source: https://ktor.io/docs/server-partial-content.html

Installs the PartialContent plugin inside an explicitly defined module extension function on the Application class. This is the second way to install the plugin, useful for modular application setups.

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.partialcontent.*
// ...
fun Application.module() {
    install(PartialContent)
    // ...
}
```

--------------------------------

### Example: DefaultRequest configuration with URL and header

Source: https://ktor.io/docs/client-default-request.html

Complete example of DefaultRequest configuration using url and header functions. The url defines protocol, host, path, and query parameter; header adds a custom header to all requests.

```kotlin
val client = HttpClient(CIO) {
    defaultRequest {
        url {
            protocol = URLProtocol.HTTPS
            host = "ktor.io"
            path("docs/")
            parameters.append("token", "abc123")
        }
        header("X-Custom-Header", "Hello")
    }
}
```

--------------------------------

### Install HttpCallValidator with HttpResponseValidator

Source: https://ktor.io/docs/client-response-validation.html

Installs the HttpCallValidator plugin by calling HttpResponseValidator inside the client configuration block. This is the starting point for custom response validation.

```kotlin
val client = HttpClient(CIO) {
    HttpResponseValidator {
        // ...
    }
}
```

--------------------------------

### Create Procfile for Dokku

Source: https://ktor.io/docs/dokku.html

Tells Dokku how to start the application after build. Replace <project-name> with your project name.

```procfile
web: ./build/install/<project-name>/bin/<project-name>
```

--------------------------------

### Install Velocity plugin in embeddedServer or module

Source: https://ktor.io/docs/server-velocity.html

Installs the Velocity plugin in an embeddedServer() call or in an explicitly defined module() extension function on the Application class. Both examples show the required imports and the install(Velocity) call.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.velocity.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Velocity)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.velocity.*
// ...
fun Application.module() {
    install(Velocity)
    // ...
}
```

--------------------------------

### Serve a React application with singlePageApplication

Source: https://ktor.io/docs/server-serving-spa.html

Shows the folder structure of a React application and the Ktor configuration to serve it using the `react` function inside `singlePageApplication`. The `react` function takes the folder name as an argument, and Ktor automatically looks up `index.html`.

```text
react-app
├── index.html
├── ...
└── static
    └── ...
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.http.content.*
import io.ktor.server.routing.*

fun Application.module() {
    routing {
        singlePageApplication {
            react("react-app")
        }
    }
}
```

--------------------------------

### Install XHttpMethodOverride plugin

Source: https://ktor.io/docs/server-method-override.html

Install the XHttpMethodOverride plugin in an embeddedServer() function call or in an explicitly defined module() extension function on the Application class. Both examples show the install(XHttpMethodOverride) call within the application module.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.methodoverride.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(XHttpMethodOverride)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.methodoverride.*
// ...
fun Application.module() {
    install(XHttpMethodOverride)
    // ...
}
```

--------------------------------

### Create logback.xml configuration file

Source: https://ktor.io/docs/client-create-new-application.html

Create a logback.xml file in src/main/resources with the provided configuration to enable console logging with a specific pattern and trace level.

```xml
<configuration>
    <appender name="APPENDER" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="trace">
        <appender-ref ref="APPENDER"/>
    </root>
</configuration>
```

--------------------------------

### Install Auth plugin and configure bearer provider

Source: https://ktor.io/docs/client-bearer-auth.html

Basic setup for bearer authentication in a Ktor client. Install the Auth plugin and configure the bearer provider.

```kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
//...
val client = HttpClient(CIO) {
   install(Auth) {
      bearer {
         // Configure bearer authentication
      }
   }
}
```

--------------------------------

### Multiplatform InputProvider with SystemFileSystem.source()

Source: https://ktor.io/docs/client-requests.html

Alternative InputProvider for multiplatform projects, using SystemFileSystem.source() to read the file as a buffered stream.

```kotlin
InputProvider { SystemFileSystem.source(Path("ktor_logo.png")).buffered() }
```

--------------------------------

### Install ContentNegotiation in embeddedServer

Source: https://ktor.io/docs/server-serialization.html

Use this snippet to install the ContentNegotiation plugin when starting a Ktor server with embeddedServer(). It imports the necessary Ktor server and Netty engine classes and calls install(ContentNegotiation) inside the server configuration block.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(ContentNegotiation)
        // ...
    }.start(wait = true)
}
```

--------------------------------

### Echo WebSocket client example

Source: https://ktor.io/docs/client-websockets.html

Complete example that creates an echo WebSocket endpoint and shows how to send and receive messages to and from a server. It uses incoming.receive() to read text frames and send() to send user input.

```kotlin
fun main() {
    val client = HttpClient(CIO) {
        install(WebSockets) {
            pingIntervalMillis = 20_000
        }
    }
    runBlocking {
        client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo") {
            while(true) {
                val othersMessage = incoming.receive() as? Frame.Text
                println(othersMessage?.readText())
                val myMessage = Scanner(System.`in`).next()
                if(myMessage != null) {
                    send(myMessage)
                }
            }
        }
    }
    client.close()
}
```

--------------------------------

### Get session content with call.sessions.get

Source: https://ktor.io/docs/server-sessions.html

Use this snippet to retrieve session content by calling get with the registered session type. The example checks if the session is not null before using it.

```kotlin
get("/user") {
    val userSession = call.sessions.get<UserSession>()
    if (userSession != null) {
}
```

--------------------------------

### Install Compression in Application.module

Source: https://ktor.io/docs/compression.html

Shows how to install the Compression plugin in an explicitly defined module() extension function on the Application class. Enables gzip, deflate, and identity encoders.

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(Compression)
    // ...
}
```

--------------------------------

### Build the Ktor project

Source: https://ktor.io/docs/server-create-a-new-project.html

Build the project using the Gradle wrapper. On macOS use ./gradlew build; on Windows use gradlew build.

```bash
./gradlew build
```

```bash
gradlew build
```

--------------------------------

### Install HttpsRedirect plugin

Source: https://ktor.io/docs/server-https-redirect.html

Install the HttpsRedirect plugin with default configuration. The first example installs it inside an embeddedServer() call, the second inside an explicitly defined module() extension function on the Application class. When behind a reverse proxy, install the ForwardedHeader or XForwardedHeader plugin to detect HTTPS requests properly.

```kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.httpsredirect.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(HttpsRedirect)
        // ...
    }.start(wait = true)
}
```

```kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.httpsredirect.*
// ...
fun Application.module() {
    install(HttpsRedirect)
    // ...
}
```

--------------------------------

### Install Krpc plugin in Application.module()

Source: https://ktor.io/docs/tutorial-first-steps-with-kotlin-rpc.html

Declares an Application extension that installs the kotlinx.rpc plugin and sets up an empty routing block. This is the setup function used by the embedded server to configure the application.

```kotlin
fun Application.module() {
    install(Krpc)

    routing {
    }
}

```

--------------------------------

### Configure Cache-Control header with cacheControl()

Source: https://ktor.io/docs/server-static-content.html

Configures the Cache-Control header for HTTP caching. In this example, 'file.txt' gets an immutable cache with a max age of 10000 seconds; other files get an empty list.

```kotlin
fun Application.module() {
    routing {
        staticFiles("/files", File("textFiles")) {
            cacheControl { file ->
                when (file.name) {
                    "file.txt" -> listOf(Immutable, CacheControl.MaxAge(10000))
                    else -> emptyList()
                }
            }
        }
    }
}
object Immutable : CacheControl(null) {
    override fun toString(): String = "immutable"
}
```

--------------------------------

### Create Google Cloud project

Source: https://ktor.io/docs/google-app-engine.html

Create a Google Cloud project with the specified name and set it as default.

```bash
gcloud projects create ktor-sample-app-engine --set-as-default
```

--------------------------------

### Handle GET and POST requests in Express and Ktor

Source: https://ktor.io/docs/migration-from-express-js.html

These examples show how to handle GET and POST requests to the '/' path. The Express version uses app.get and app.post, while the Ktor version uses the routing block with get and post functions. Both respond with a text message.

```javascript
app.get('/', (req, res) => {
    res.send('GET request to the homepage')
})

app.post('/', (req, res) => {
    res.send('POST request to the homepage')
})
```

```kotlin
routing {
    get("/") {
        call.respondText("GET request to the homepage")
    }
    post("/") {
        call.respondText("POST request to the homepage")
    }
}
```

--------------------------------

### Start embedded Ktor server with Netty

Source: https://ktor.io/docs/tutorial-first-steps-with-kotlin-rpc.html

Creates an embedded Ktor/Netty server on port 8080, calls the module() extension, prints "Server running", and starts it with wait = true. This is the server entry point for the RPC demo.

```kotlin
embeddedServer(Netty, port = 8080) {
    module()
    println("Server running")
}.start(wait = true)

```

--------------------------------

### Respond with serialized object using call.respond()

Source: https://ktor.io/docs/server-responses.html

Sends a data object as a response using `call.respond()`. Requires the ContentNegotiation plugin with a converter (e.g., JSON) installed. The example is incomplete; see the full example in json-kotlinx.

```kotlin
routing {
    get("/customer/{id}") {
        val id: Int by call.parameters
        val customer: Customer = customerStorage.find { it.id == id }!!
        call.respond(customer)
```
Tokens:
Raw