Skip to content

サーバーエンジン ​

Ktorサーバーアプリケーションを実行するには、まずサーバーを作成および設定する必要があります。 サーバー設定にはさまざまな項目が含まれます:

  • ネットワークリクエストを処理するためのエンジン
  • サーバーへのアクセスに使用されるホストとポートの値
  • SSL設定

サポートされているプラットフォーム ​

以下の表は、各エンジンでサポートされているプラットフォームの一覧です:

エンジンプラットフォームHTTP/2
NettyJVM✅
JettyJVM✅
TomcatJVM✅
CIO (Coroutine-based I/O)JVM, Native, GraalVM, JavaScript, WasmJs✖️
ServletApplicationEngineJVM✅

依存関係の追加 ​

目的のエンジンを使用する前に、対応する依存関係をビルドスクリプトに追加する必要があります:

  • ktor-server-netty
  • ktor-server-jetty-jakarta
  • ktor-server-tomcat-jakarta
  • ktor-server-cio

以下は、Nettyの依存関係を追加する例です:

kotlin
implementation(ktorLibs.server.netty)
上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
groovy
implementation ktorLibs.server.netty
上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-netty-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

サーバー作成方法の選択 ​

Ktorサーバーアプリケーションは、2つの方法で作成および実行できます:

  • コード内で手軽にサーバーパラメータを渡せるembeddedServerを使用する
  • 外部のapplication.confまたはapplication.yamlファイルから設定を読み込むEngineMainを使用する

embeddedServer ​

embeddedServer()関数は、特定のタイプのエンジンを作成するためのエンジンファクトリを受け取ります。以下の例では、Nettyファクトリを渡してNettyエンジンでサーバーを実行し、8080ポートでリッスンします:

kotlin
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main(args: Array<String>) {
    embeddedServer(Netty, port = 8080) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

EngineMain ​

EngineMainは、サーバーを実行するためのエンジンを表します。以下のエンジンを使用できます:

  • io.ktor.server.netty.EngineMain
  • io.ktor.server.jetty.jakarta.EngineMain
  • io.ktor.server.tomcat.jakarta.EngineMain
  • io.ktor.server.cio.EngineMain

サーバーの作成と起動 ​

EngineMain.main()関数は、選択したエンジンでサーバーを起動し、外部の設定ファイルで指定されたアプリケーションモジュールを読み込むために使用されます。以下の例では、アプリケーションのmain関数がサーバーを起動します:

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.module() {
    routing {
        get("/") {
            call.respondText("Hello, world!")
        }
    }
}
shell
ktor {
    deployment {
        port = 8080
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.module

ビルドシステムのタスクを使用してサーバーを起動する必要がある場合は、必要なEngineMainをメインクラスとして設定する必要があります:

kotlin
application {
    mainClass.set("io.ktor.server.netty.EngineMain")
}
groovy
mainClassName = "io.ktor.server.netty.EngineMain"
xml
<properties>
    <main.class>io.ktor.server.netty.EngineMain</main.class>
</properties>

起動せずにサーバーインスタンスを作成する ​

EngineMain.main()を直接呼び出して即座にサーバーを起動するだけでなく、代わりにサーバーを起動せずにEmbeddedServerインスタンスを返すEngineMain.createServer()を呼び出すこともできます。

このアプローチにより、リクエストの受け付けを開始する前に、.start()や.stop()を呼び出すタイミングを制御したり、サーバーに対する各種操作を実行したりできます。

Kotlin
// Nettyを使用した例
val server = io.ktor.server.netty.EngineMain.createServer(args)
// 追加の初期化、ロギング、インストルメンテーションなどを実行
server.start(wait = true)

エンジンの設定 ​

このセクションでは、エンジン固有のさまざまなオプションを指定する方法について説明します。

コード内での設定 ​

embeddedServer関数では、configureパラメータを使用してエンジン固有のオプションを渡すことができます。このパラメータには、すべてのエンジンに共通し、 ApplicationEngine.Configuration クラスによって公開されているオプションが含まれます。

以下の例は、Nettyエンジンを使用してサーバーを設定する方法を示しています。configureブロック内で、ホストとポートを指定するconnectorを定義し、さまざまなサーバーパラメータをカスタマイズしています:

kotlin
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main(args: Array<String>) {
    embeddedServer(Netty, configure = {
        connectors.add(EngineConnectorBuilder().apply {
            host = "127.0.0.1"
            port = 8080
        })
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

connectors.add()メソッドは、指定されたホスト(127.0.0.1)とポート(8080)を持つコネクタを定義します。

これらのオプションに加えて、その他のエンジン固有のプロパティを設定することもできます。

Netty

Netty固有のオプションは、 NettyApplicationEngine.Configuration クラスによって公開されています。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main() {
    embeddedServer(Netty, configure = {
        requestQueueLimit = 16
        shareWorkGroup = false
        configureBootstrap = {
            // ...
        }
        responseWriteTimeoutSeconds = 10
    }) {
        // ...
    }.start(true)
}

Jetty

Jetty固有のオプションは、 JettyApplicationEngineBase.Configuration クラスによって公開されています。

Serverインスタンスへのアクセスを提供する configureServer ブロック内でJettyサーバーを設定できます。

接続がクローズされるまでにアイドル状態でいられる期間を指定するには、idleTimeoutプロパティを使用します。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.jetty.jakarta.*

fun main() {
    embeddedServer(Jetty, configure = {
        configureServer = { // this: Server -&gt;
            // ...
        }
        idleTimeout = 30.seconds
    }) {
        // ...
    }.start(true)
}

CIO

CIO固有のオプションは、 CIOApplicationEngine.Configuration クラスによって公開されています。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.cio.*

fun main() {
    embeddedServer(CIO, configure = {
        connectionIdleTimeoutSeconds = 45
    }) {
        // ...
    }.start(true)
}

Tomcat

Tomcatをエンジンとして使用する場合、 Tomcat インスタンスへのアクセスを提供する configureTomcat プロパティを使用して設定できます。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.tomcat.jakarta.*

fun main() {
    embeddedServer(Tomcat, configure = {
        configureTomcat = { // this: Tomcat -&gt;
            // ...
        }
    }) {
        // ...
    }.start(true)
}

設定ファイル内での設定 ​

EngineMainを使用する場合、 ktor.deploymentグループ内ですべてのエンジンに共通のオプションを指定できます。

shell
ktor {
    deployment {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }
}
yaml
ktor:
    deployment:
        connectionGroupSize: 2
        workerGroupSize: 5
        callGroupSize: 10
        shutdownGracePeriod: 2000
        shutdownTimeout: 3000

Netty

設定ファイル内のktor.deploymentグループでNetty固有のオプションを設定することもできます:

shell
ktor {
    deployment {
        maxInitialLineLength = 2048
        maxHeaderSize = 1024
        maxChunkSize = 42
    }
}
yaml
ktor:
    deployment:
        maxInitialLineLength: 2048
        maxHeaderSize: 1024
        maxChunkSize: 42