Skip to content
Server Plugin

圧縮 (Compression)

必要な依存関係: io.ktor:ktor-server-compression

コード例: compression

Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✖️

Ktor は、Compression プラグインを使用して、レスポンスボディの圧縮およびリクエストボディの解凍を行う機能を提供します。

Compression プラグインを使用すると、以下のことが可能です。

  • gzip、zstd、deflate などのさまざまな圧縮アルゴリズムの使用。
  • コンテンツタイプやレスポンスサイズなど、データを圧縮するために必要な条件の指定。
  • 特定のリクエストパラメータに基づいたデータの圧縮。

Compression プラグインは現在、SSE レスポンスをサポートしていないことに注意してください。

Ktor で事前圧縮された静的ファイルを提供する方法については、事前圧縮ファイルを参照してください。

依存関係の追加 ​

Compression を使用するには、ビルドスクリプトに ktor-server-compression アーティファクトを追加します。

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

Zstandard 圧縮を含めるには、ktor-server-compression-zstd 依存関係を追加します。

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

Compression のインストール ​

アプリケーションに Compression プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、Compression をインストールする方法を示しています。

  • embeddedServer() 関数の呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Compression)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(Compression)
    // ...
}

これにより、サーバー上で gzip、deflate、identity エンコーダーが有効になります。

圧縮設定の構成 ​

特定のエンコーダーのみを有効にする、優先順位を指定する、特定のコンテンツタイプのみを圧縮するなど、さまざまな方法で圧縮を設定できます。

特定のエンコーダーの追加 ​

特定のエンコーダーのみを有効にするには、対応する拡張関数を呼び出します(例:):

kotlin
install(Compression) {
    gzip()
    deflate()
    zstd()
}

priority プロパティを設定することで、各圧縮アルゴリズムの優先順位を指定できます。

kotlin
install(Compression) {
    gzip {
        priority = 0.9
    }
    deflate {
        priority = 1.0
    }
    zstd {
        priority = 0.8
    }
}

上記の例では、deflate の優先度の値が高いため、gzip や zstd よりも優先されます。なお、サーバーはまず Accept-Encoding ヘッダー内の quality(品質)値を確認し、その後に指定された優先順位を考慮することに注意してください。

コンテンツタイプの構成 ​

デフォルトでは、Ktor は audio、video、image、text/event-stream などの特定のコンテンツタイプを圧縮しません。matchContentType を呼び出して圧縮対象のコンテンツタイプを選択するか、excludeContentType を使用して目的のメディアタイプを圧縮から除外することができます。以下のコードスニペットは、gzip を使用して JavaScript コードを圧縮し、deflate を使用してすべてのテキストサブタイプを圧縮する方法を示しています。

kotlin
install(Compression) {
    gzip {
        matchContentType(
            ContentType.Application.JavaScript
        )
    }
    deflate {
        matchContentType(
            ContentType.Text.Any
        )
    }
}

完全なコード例はこちらで確認できます: compression

レスポンスサイズの構成 ​

Compression プラグインを使用すると、指定されたサイズを超えないレスポンスの圧縮を無効にすることができます。これを行うには、minimumSize 関数に必要な値(バイト単位)を渡します。

kotlin
    install(Compression) {
    deflate {
        minimumSize(1024)
    }
}

カスタム条件の指定 ​

必要に応じて、condition 関数を使用してカスタム条件を指定し、特定のリクエストパラメータに応じてデータを圧縮できます。以下のコードスニペットは、指定された URI に対するリクエストでデータを圧縮する方法を示しています。

kotlin
install(Compression) {
    gzip {
        condition {
            request.uri == "/orders"
        }
    }
}

HTTPS のセキュリティ ​

圧縮が有効になっている HTTPS は、BREACH 攻撃に対して脆弱です。この攻撃を緩和するには、さまざまなアプローチを使用できます。たとえば、Referer ヘッダーがクロスサイトリクエストを示している場合に圧縮を無効化できます。Ktor では、Referer ヘッダーの値をチェックすることでこれを実現できます。

kotlin
install(Compression) {
    gzip {
        condition {
            request.headers[HttpHeaders.Referrer]?.startsWith("https://my.domain/") == true
        }
    }
}

Zstandard の圧縮レベル ​

level パラメータを使用して、zstd の圧縮レベルを設定できます。デフォルトの圧縮レベルは 3 ですが、必要に応じて調整できます。

kotlin
install(Compression) {
    // デフォルトは level = 3
    zstd(level = 20)
}

リクエストの解凍 ​

デフォルトでは、Compression プラグインはサーバーレスポンスを圧縮します。リクエストの解凍を有効にするには、mode プロパティを CompressionConfig.Mode.DecompressRequest に設定します。

kotlin
install(Compression) { 
    mode = CompressionConfig.Mode.DecompressRequest
    gzip()
}

リクエストの解凍が有効になっている場合、プラグインは設定されたデコーダーを使用して、デシリアライゼーションやマルチパート処理などの他の受信変換によって処理される前に、リクエストボディを解凍します。

カスタムエンコーダーの実装 ​

必要に応じて、ContentEncoder インターフェースを実装することで、独自のエンコーダーを提供できます。 実装例については、GzipEncoder を参照してください。