Skip to content

カスタムプラグイン - Base API ​

Ktorは、複数のアプリケーション間で再利用可能な機能を実装するカスタムプラグインを開発するためのBase APIを提供しています。

Base APIを使用すると、さまざまなパイプラインフェーズをインターセプトし、リクエストとレスポンスの処理にカスタムロジックを追加できます。たとえば、Monitoring フェーズをインターセプトして受信リクエストをログに記録したり、メトリクスを収集したりできます。

プラグインの作成 ​

Base APIを使用してカスタムプラグインを作成するには:

  1. プラグインクラスを作成し、プラグインインターフェースを実装するコンパニオンオブジェクトを宣言します。
  2. コンパニオンオブジェクトで key プロパティと install() 関数を実装します。
  3. プラグイン設定を提供します。
  4. 必要なパイプラインフェーズをインターセプトして呼び出しを処理します。
  5. プラグインをインストールします。

コンパニオンオブジェクトの作成 ​

カスタムプラグインのクラスには、以下のいずれかのインターフェースを実装するコンパニオンオブジェクトが必要です。

BaseApplicationPlugin インターフェースは、以下の型パラメータを受け入れます:

  • プラグインがサポートするパイプラインの型。
  • プラグインの設定型。
  • プラグインインスタンスの型。
kotlin
class CustomHeader() {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        // ...
    }
}

'key' プロパティと 'install()' 関数の実装 ​

BaseApplicationPlugin を実装するコンパニオンオブジェクトは、以下を定義する必要があります。

  • key プロパティはプラグインを識別します。Ktorはプラグインインスタンスをアプリケーションの属性(attributes)に保存し、このキーを使用してプラグインインスタンスにアクセスします。
  • install() 関数はプラグインを設定します。この関数内で必要なパイプラインフェーズをインターセプトし、プラグインインスタンスを返します。呼び出しの処理セクションでパイプラインフェーズをインターセプトする方法を説明しています。
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()
            // パイプラインをインターセプト ...
            return plugin
        }
    }
}

呼び出しの処理 ​

カスタムプラグインでは、既存のパイプラインフェーズや新しく定義したフェーズをインターセプトすることで、リクエストとレスポンスを処理できます。たとえば、認証プラグインは、デフォルトのパイプラインに Authenticate と Challenge のカスタムフェーズを追加します。

特定のフェーズをインターセプトすることで、呼び出し処理の特定のステージにアクセスできます。

  • ApplicationCallPipeline.Monitoring: リクエストロギング、メトリクス、トレーシング、および同様の監視タスクにこのフェーズを使用します。
  • ApplicationCallPipeline.Plugins: 呼び出しを処理したり、カスタムヘッダーの追加などレスポンスパラメータを変更したりするためにこのフェーズを使用します。
  • ApplicationReceivePipeline.Transform および ApplicationSendPipeline.Transform: クライアントから受信したデータまたはクライアントに送信するデータへのアクセスや変換にこれらのフェーズを使用します。

以下の例では、ApplicationCallPipeline.Plugins フェーズをインターセプトし、各レスポンスにカスタムヘッダーを追加します。

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()
            pipeline.intercept(ApplicationCallPipeline.Plugins) {
                call.response.header("X-Custom-Header", "Hello, world!")
            }
            return plugin
        }
    }
}

この例では、ヘッダー名と値がハードコードされています。プラグインを再利用可能にするには、ユーザーがヘッダー名と値を指定できるようにする設定を提供します。

カスタムプラグインは、呼び出しに関連付けられた値を異なるハンドラー間で共有できます。詳細については、呼び出し状態の共有を参照してください。

プラグイン設定の提供 ​

前のセクションでは、各レスポンスに事前定義されたカスタムヘッダーを追加するプラグインの作成方法を示しました。このプラグインを再利用可能にするには、ユーザーがヘッダー名と値を指定できる設定を定義します。

まず、プラグインクラス内に設定クラスを定義します。

kotlin
class Configuration {
    var headerName = "Custom-Header-Name"
    var headerValue = "Default value"
}

プラグインのインストール中にプラグイン設定プロパティを更新できます。プラグインがインターセプター内でこれらの値を使用する場合は、install() 関数内のローカル変数に保存します。

kotlin
class CustomHeader(configuration: Configuration) {
    private val name = configuration.headerName
    private val value = configuration.headerValue

    class Configuration {
        var headerName = "Custom-Header-Name"
        var headerValue = "Default value"
    }
}

次に、install() 関数で設定を読み取り、そのプロパティを使用します。

kotlin
class CustomHeader(configuration: Configuration) {
    private val name = configuration.headerName
    private val value = configuration.headerValue

    class Configuration {
        var headerName = "Custom-Header-Name"
        var headerValue = "Default value"
    }

    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val configuration = Configuration().apply(configure)
            val plugin = CustomHeader(configuration)
            pipeline.intercept(ApplicationCallPipeline.Plugins) {
                call.response.header(plugin.name, plugin.value)
            }
            return plugin
        }
    }
}

プラグインのインストール ​

カスタムプラグインをアプリケーションにインストールするには、Application.install() 関数を呼び出し、必要な設定パラメータを渡します。

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

例 ​

以下の例は、Base APIを使用して構築されたいくつかのカスタムプラグインを示しています。

完全に実行可能なプロジェクトについては、custom-plugin-base-api を参照してください。

リクエストロギング ​

以下の例では、受信リクエストをログに記録するカスタムプラグインを作成します。

kotlin
package com.example.plugins

import io.ktor.serialization.*
import io.ktor.server.application.*
import io.ktor.server.plugins.*
import io.ktor.util.*

class RequestLogging {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, RequestLogging> {
        override val key = AttributeKey<RequestLogging>("RequestLogging")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): RequestLogging {
            val plugin = RequestLogging()
            pipeline.intercept(ApplicationCallPipeline.Monitoring) {
                call.request.origin.apply {
                    println("Request URL: $scheme://$localHost:$localPort$uri")
                }
            }
            return plugin
        }
    }
}

カスタムヘッダー ​

以下の例では、各レスポンスにカスタムヘッダーを追加するプラグインを作成します。

kotlin
package com.example.plugins

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

class CustomHeader(configuration: Configuration) {
    private val name = configuration.headerName
    private val value = configuration.headerValue

    class Configuration {
        var headerName = "Custom-Header-Name"
        var headerValue = "Default value"
    }

    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val configuration = Configuration().apply(configure)
            val plugin = CustomHeader(configuration)
            pipeline.intercept(ApplicationCallPipeline.Plugins) {
                call.response.header(plugin.name, plugin.value)
            }
            return plugin
        }
    }
}

ボディの変換 ​

以下の例では、リクエストボディとレスポンスボディを変換するプラグインを作成します。

kotlin
package com.example.plugins

import io.ktor.serialization.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.util.*
import io.ktor.utils.io.*

class DataTransformation {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, DataTransformation> {
        override val key = AttributeKey<DataTransformation>("DataTransformation")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): DataTransformation {
            val plugin = DataTransformation()
            pipeline.receivePipeline.intercept(ApplicationReceivePipeline.Transform) { data ->
                val newValue = (data as ByteReadChannel).readLine()?.toInt()?.plus(1)
                if (newValue != null) {
                    proceedWith(newValue)
                }
            }
            pipeline.sendPipeline.intercept(ApplicationSendPipeline.Transform) { data ->
                if (subject is Int) {
                    val newValue = data.toString().toInt() + 1
                    proceedWith(newValue.toString())
                }
            }
            return plugin
        }
    }
}

パイプライン ​

Ktorにおける Pipeline は、1つ以上の順序付けられたフェーズにグループ化されたインターセプターのコレクションです。各インターセプターは、リクエスト処理の継続前後にカスタムロジックを実行できます。

ApplicationCallPipeline はアプリケーションの呼び出しを実行します。以下のフェーズを定義しています:

  • Setup: 呼び出しとその属性を処理のために準備します。
  • Monitoring: 呼び出しをトレースします。リクエストロギング、メトリクス、エラー処理、および同様のタスクにこのフェーズを使用します。
  • Plugins: 呼び出しを処理します。ほとんどのプラグインはこのフェーズをインターセプトします。
  • Call: 呼び出しを完了します。
  • Fallback: 前のフェーズで処理されなかった呼び出しを処理します。

パイプラインフェーズから新しいAPIハンドラーへのマッピング ​

簡略化されたカスタムプラグインAPIを使用してカスタムプラグインを作成できます。多くの場合、このAPIではパイプラインやフェーズなどのKtor内部の概念に関する直接的な知識は不要です。代わりに、リクエストとレスポンスの処理のさまざまなステージ向けに、onCall()、onCallReceive()、onCallRespond() などのハンドラーが提供されます。

以下の表は、Base APIのパイプラインフェーズが簡略化されたAPIハンドラーにどのように対応しているかを示しています。

Base API新しいAPI
ApplicationCallPipeline.Setup より前on(CallFailed)
ApplicationCallPipeline.Setupon(CallSetup)
ApplicationCallPipeline.PluginsonCall()
ApplicationCallPipeline.CallonCallValidators()
ApplicationReceivePipeline.TransformonCallReceive()
ApplicationSendPipeline.TransformonCallRespond()
ApplicationSendPipeline.Afteron(ResponseBodyReadyForSend)
ApplicationSendPipeline.Engineon(ResponseSent)
Authentication.ChallengePhase より後on(AuthenticationChecked)