サーバーエンジン
Ktorサーバーアプリケーションを実行するには、まずサーバーを作成および設定する必要があります。 サーバー設定にはさまざまな項目が含まれます:
- ネットワークリクエストを処理するためのエンジン
- サーバーへのアクセスに使用されるホストとポートの値
- SSL設定
サポートされているプラットフォーム
以下の表は、各エンジンでサポートされているプラットフォームの一覧です:
| エンジン | プラットフォーム | HTTP/2 |
|---|---|---|
Netty | JVM | ✅ |
Jetty | JVM | ✅ |
Tomcat | JVM | ✅ |
CIO (Coroutine-based I/O) | JVM, Native, GraalVM, JavaScript, WasmJs | ✖️ |
ServletApplicationEngine | JVM | ✅ |
依存関係の追加
目的のエンジンを使用する前に、対応する依存関係をビルドスクリプトに追加する必要があります:
ktor-server-nettyktor-server-jetty-jakartaktor-server-tomcat-jakartaktor-server-cio
以下は、Nettyの依存関係を追加する例です:
implementation(ktorLibs.server.netty)implementation ktorLibs.server.netty<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ポートでリッスンします:
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.EngineMainio.ktor.server.jetty.jakarta.EngineMainio.ktor.server.tomcat.jakarta.EngineMainio.ktor.server.cio.EngineMain
サーバーの作成と起動
EngineMain.main()関数は、選択したエンジンでサーバーを起動し、外部の設定ファイルで指定されたアプリケーションモジュールを読み込むために使用されます。以下の例では、アプリケーションのmain関数がサーバーを起動します:
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!")
}
}
}ktor {
deployment {
port = 8080
}
application {
modules = [ com.example.ApplicationKt.module ]
}
}ktor:
deployment:
port: 8080
application:
modules:
- com.example.ApplicationKt.moduleビルドシステムのタスクを使用してサーバーを起動する必要がある場合は、必要なEngineMainをメインクラスとして設定する必要があります:
application {
mainClass.set("io.ktor.server.netty.EngineMain")
}mainClassName = "io.ktor.server.netty.EngineMain"<properties>
<main.class>io.ktor.server.netty.EngineMain</main.class>
</properties>起動せずにサーバーインスタンスを作成する
EngineMain.main()を直接呼び出して即座にサーバーを起動するだけでなく、代わりにサーバーを起動せずにEmbeddedServerインスタンスを返すEngineMain.createServer()を呼び出すこともできます。
このアプローチにより、リクエストの受け付けを開始する前に、.start()や.stop()を呼び出すタイミングを制御したり、サーバーに対する各種操作を実行したりできます。
// Nettyを使用した例
val server = io.ktor.server.netty.EngineMain.createServer(args)
// 追加の初期化、ロギング、インストルメンテーションなどを実行
server.start(wait = true)エンジンの設定
このセクションでは、エンジン固有のさまざまなオプションを指定する方法について説明します。
コード内での設定
embeddedServer関数では、configureパラメータを使用してエンジン固有のオプションを渡すことができます。このパラメータには、すべてのエンジンに共通し、 ApplicationEngine.Configuration クラスによって公開されているオプションが含まれます。
以下の例は、Nettyエンジンを使用してサーバーを設定する方法を示しています。configureブロック内で、ホストとポートを指定するconnectorを定義し、さまざまなサーバーパラメータをカスタマイズしています:
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 クラスによって公開されています。
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プロパティを使用します。
import io.ktor.server.engine.*
import io.ktor.server.jetty.jakarta.*
fun main() {
embeddedServer(Jetty, configure = {
configureServer = { // this: Server ->
// ...
}
idleTimeout = 30.seconds
}) {
// ...
}.start(true)
}CIO
CIO固有のオプションは、 CIOApplicationEngine.Configuration クラスによって公開されています。
import io.ktor.server.engine.*
import io.ktor.server.cio.*
fun main() {
embeddedServer(CIO, configure = {
connectionIdleTimeoutSeconds = 45
}) {
// ...
}.start(true)
}Tomcat
Tomcatをエンジンとして使用する場合、 Tomcat インスタンスへのアクセスを提供する configureTomcat プロパティを使用して設定できます。
import io.ktor.server.engine.*
import io.ktor.server.tomcat.jakarta.*
fun main() {
embeddedServer(Tomcat, configure = {
configureTomcat = { // this: Tomcat ->
// ...
}
}) {
// ...
}.start(true)
}設定ファイル内での設定
EngineMainを使用する場合、 ktor.deploymentグループ内ですべてのエンジンに共通のオプションを指定できます。
ktor {
deployment {
connectionGroupSize = 2
workerGroupSize = 5
callGroupSize = 10
shutdownGracePeriod = 2000
shutdownTimeout = 3000
}
}ktor:
deployment:
connectionGroupSize: 2
workerGroupSize: 5
callGroupSize: 10
shutdownGracePeriod: 2000
shutdownTimeout: 3000