Server Plugin

圧縮

必須の依存関係: io.ktor:ktor-server-compression

コード例: compression

Nativeサーバー

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

のサポート: ✖️

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

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

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

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

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

依存関係の追加

Compressionを使用するには、ビルドスクリプトにktor-server-compressionアーティファクトを含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

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

Gradle (Kotlin)Gradle (Groovy)Maven

Compressionのインストール

Compressionプラグインをアプリケーションにインストールするには、指定された

モジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

内のinstall関数に渡します。 以下のコードスニペットは、Compressionをインストールする方法を示しています...

• ... embeddedServer関数の呼び出し内。
• ... Applicationクラスの拡張関数である、明示的に定義されたmodule内。

embeddedServermodule

これにより、サーバー上でgzip、deflate、およびidentityエンコーダーが有効になります。 次の章では、特定のエンコーダーのみを有効にし、データの圧縮条件を設定する方法を説明します。 追加されたすべてのエンコーダーは、必要に応じてリクエストボディの展開に使用されることに注意してください。

圧縮設定の構成

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

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

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

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

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

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を使用してすべてのテキストサブタイプを圧縮する方法を示しています：

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

完全な例はこちらにあります：compression

レスポンスサイズの構成

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

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

カスタム条件の指定

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

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

HTTPSセキュリティ

圧縮が有効なHTTPSは、BREACH攻撃に対して脆弱です。この攻撃を軽減するためにさまざまな方法を使用できます。例えば、リファラーヘッダーがクロスサイトリクエストを示している場合に圧縮を無効にできます。Ktorでは、リファラーヘッダーの値をチェックすることでこれを行うことができます：

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

Zstandard圧縮レベル

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

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

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

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