圧縮

OxPHP は HTTP レスポンスを Brotli、Zstandard、gzip のうちクライアントが受け入れるもので圧縮します。圧縮は固定されたコンテンツタイプの一覧（テキスト、JSON、XML、SVG、WebAssembly、いくつかのフォント形式）に自動的に適用されるため、アプリケーションコードを変更することなく転送サイズが削減されます。

仕組み

クライアントの Accept-Encoding ヘッダーは、リクエストがルーティングパイプラインに到達する前に一度だけ読み取られ、サーバーが提供するエンコーディングと照らし合わせて評価されます。その後の処理は、バイト列がどこから来るかによって異なります。

圧縮済みのコピーが既に保存されている、キャッシュ済みの静的ファイルには、そのコピーから直接応答します。リクエスト時には何も圧縮されず、以下のチェックも一切適用されません。キャッシュされた静的ファイルを参照してください。

それ以外のすべてのレスポンス（PHP の出力、カスタムエラーページ、保存済みコピーがまだない静的ファイル）は、レスポンスが組み立てられた後に、以下のチェックを順番に通過します。

1. 部分レスポンスはスキップされます。 206 はエンコードされません。その Content-Range のオフセットは、エンコードされていない表現を基準にしているためです。
2. コンテンツタイプのチェック。 レスポンスの MIME タイプが、圧縮可能なタイプの一覧から検索されます。
3. エンコード済みのチェック。 既に Content-Encoding ヘッダーを持つレスポンスには手を加えません。
4. サイズのチェック。 256 バイトから 3 MiB（3,145,728 バイト）までのボディのみが圧縮されます（両端を含む）。レスポンスに Content-Length ヘッダーがあればそれが使われます。PHP のレスポンスには通常このヘッダーがないため、代わりにバッファリングされたボディのサイズが測定されます。
5. 圧縮。 ネゴシエートされたエンコーディングが、設定されたレベルで適用されます。圧縮後の出力が元のサイズよりも小さくならない場合は、代わりに非圧縮のレスポンスが送信されます。

小さなボディはインラインで圧縮されます。しきい値を超えると、非同期ランタイムを停滞させないよう、処理はブロッキングスレッドに移されます。しきい値は 64 KiB ですが、コスト曲線が急になるほどレベルが高い場合は 4 KiB に下がります。その境目は Brotli では品質 4 超、gzip ではレベル 6 超、Zstandard ではレベル 9 超です。出荷時のデフォルトでは Brotli は既に急な側にあるため、4 KiB を超える Brotli のボディは非同期スレッドの外で圧縮されます。

flowchart TD
    AE["Accept-Encoding, read once per request"]
    W["Ranked by weight. A coding the server<br/>does not offer scores zero and drops out"]
    Q{"Is a stored copy<br/>being served?"}
    A["Tie broken br, then zstd, then gzip.<br/>Built once at br 11, zstd 19, gzip 9"]
    P["Tie broken zstd, then br, then gzip.<br/>Compressed now at the configured<br/>zstd 6, br 5, gzip 6"]
    H["Content-Encoding, recomputed Content-Length,<br/>Vary, weakened ETag, no Accept-Ranges"]
    AE --> W
    W --> Q
    Q -->|yes| A
    Q -->|no| P
    A --> H
    P --> H

エンコーディングの選択

Accept-Encoding はエンコーディングを重み（RFC 9110 §12.5.3）で順位付けし、OxPHP もそのとおりに解釈します。

• エンコーディング名は大文字と小文字を区別せずに照合され、未知のエンコーディングは無視されます。
• br;q=0 は Brotli を拒否します。これはエンコーディングを記載しないこととは異なります。記載されていないエンコーディングは * で拾われる可能性がありますが、明示的に拒否されたエンコーディングは拾われません。
• * は、ヘッダーで明示的に名前が挙げられていないあらゆるエンコーディングを、それに与えられた重みで対象にします。
• 解析できない重みを持つエンコーディングはデフォルトの重みのまま扱われ、不正なパラメーターがあってもそのエンコーディングは除外されません。これは q=0 で問題になります。qvalue は小数点以下 3 桁までしか持てないため、q=0.000 はエンコーディングを拒否しますが、q=0.0000 はそもそも有効な重みではなく、完全な受け入れとして解釈されます。2 回記載されたエンコーディングは、最初の重みで読み取られます。
• クライアントが受け入れ、かつサーバーが提供するエンコーディングのうち、最も高い重みを付けられたものが選ばれます。設定によって取り下げられたエンコーディングは順位付けの前にスコアがゼロになるため、最も好むエンコーディングをサーバーが提供していないクライアントは、非圧縮のレスポンスではなく次の候補にフォールバックします。
• 何も受け入れないヘッダー（空、または *;q=0）の場合は、エンコードされていないレスポンスになります。OxPHP はコンテンツエンコーディングを理由に 406 を返すことはなく、identity をトークンとして読むこともありません。

ブラウザはサポートするすべてのエンコーディングを重みなしで送信するため、通常は重みが同点になります。OxPHP はこの同点を、圧縮されたバイト列がその後どう扱われるかによって決着させます。

1 行目が適用されるのは、保存済みコピーが存在してからです。それより前のヒットと、キャッシュするには大きすぎるすべてのファイルは 2 行目に従います。そのため、静的アセットは通常、Brotli で応答される前に Zstandard で応答されます。

この優先順位は同点を決着させるためだけのものです。br;q=0.2, gzip;q=0.9 と記述したクライアントはどちらの経路でも gzip を受け取り、そのクライアントのために作られる保存済みコピーも gzip になります。

3 つのどれも受け入れないクライアントは、エンコードされていないレスポンスを受け取ります。実際には gzip がフォールバックになります。過去 20 年間のあらゆる HTTP クライアントが gzip を受け入れる一方、Zstandard には 2024 年以降にリリースされたブラウザが必要です。

Vary: Accept-Encoding

応答内容がリクエストヘッダーに依存するため、圧縮ウィンドウ内のすべてのレスポンスは、圧縮されているかどうか、静的か動的かに関係なく Vary: Accept-Encoding を持ちます。サーバーが一部のクライアントに対してエンコードする表現は、今回のクライアントに identity のバイト列を渡している場合でも、このヘッダーによって変化します。共有キャッシュがそうでないと伝えられると、エンコーディングを要求したクライアントにその identity のバイト列を渡してしまいます。

このルールの例外は 2 つあります。

• サーバーが全体を保持しない動的レスポンス（PHP が生成するそばからストリーミングされるもの）は Vary を持ちません。この経路はどのヘッダーでも圧縮できないため、レスポンスは実際に変化しないからです。ストリーミングされるほど大きな静的ファイルはこのグループには含まれず、ヘッダーを持ちます。同じファイルでも、エンコーディングをネゴシエートしたクライアントに対しては全体が読み込まれて圧縮されるためです。
• 304 は Vary も Content-Encoding も持ちません。新しい表現を記述するのではなく、クライアントが既に保持している表現を更新するものだからです。

Vary は、アプリケーションが既に送信したものにマージされるのではなく、独立したヘッダー行として追加されます。そのため、Vary: Cookie を設定したレスポンスは 2 行の Vary を持って送信されます。これは規格上正当であり、OxPHP は追加の前にそのすべてを読むため Accept-Encoding が重複することはありませんが、最初の行しか読まない中継サーバーはこれを見落とします。

キャッシュされた静的ファイル

コンテンツキャッシュに収まり（1 MiB 以下）、かつ圧縮可能な（一覧にあるタイプで、256 バイト以上の）静的ファイルは、リクエストのたびではなく一度だけ圧縮されます。

1. 1
   最初のリクエスト: キャッシュミス。 ファイルはディスクから読み込まれて保存され、そのリクエストに対しては他のレスポンスと同様に圧縮されます。
2. 2
   次のリクエスト: ビルドの開始。 ファイルはキャッシュ済みで、このリクエストでネゴシエートされたエンコーディングの保存済みコピーがまだなければ、サーバーはバックグラウンドスレッドでのビルドを要求します。ビルドを開始したリクエストは、ビルド中に届くすべてのリクエストと同様に、リクエストごとの方法で配信されます。
3. 3
   コピーの完成。 同じエンコーディングをネゴシエートする以降のリクエストには、保存済みコピーから応答します。

ヒットカウンターはありません。トリガーは、そのエンコーディングの保存済みコピーがない状態での最初のキャッシュヒットです。そのため、これまで gzip クライアントにしか配信されていなかったファイルは、最初に Brotli クライアントがヒットした時点で Brotli のコピーを得ます。

保存済みコピーは、設定されたリクエストごとのレベルに関係なく、各エンコーディングの最大レベル（Brotli 11、Zstandard 19、gzip 9）でビルドされます。保存済みコピーがリクエストごとのレベルを使うことはありません。専用の設定はなく、コピーがビルドされないようにする唯一の方法は、そのエンコーディング自体を取り下げることです。最大品質では、Brotli のリクエストごとのレベルと比べて通常 8〜12% 少ないバイト数になります。

各エンコーディングはそれぞれ独自の保存済みコピーを必要に応じてビルドするため、gzip クライアントにしか配信されないファイルに Brotli の圧縮コストがかかることはありません。すべてのコピーはキャッシュされたファイルのバリデーターを共有し、キャッシュされたバイト列と一緒に破棄されます。破棄されるのは、保存済みコピーの分も計上される 64 MiB のキャッシュ予算内に収めるためにエントリが追い出されたとき、または STATIC_REVALIDATE が有効でディスク上のファイルの変更を検出したときです。この設定はデフォルトで無効なので、デフォルトのデプロイでは、保存済みコピーが破棄されるのは追い出しと再起動の 2 つの場合だけです。圧縮できないバイト列はその旨が記録されて再試行されず、304 はビルドのトリガーにも保存済みコピーの配信にもなりません。

キャッシュするには大きすぎるファイル

キャッシュの上限と圧縮ウィンドウの上限の間（1 MiB〜3 MiB。フレームワークのバンドル、ソースマップ、WebAssembly モジュールがここに入ります）にあるファイルは、クライアントがエンコーディングをネゴシエートし、かつタイプが圧縮可能であれば、全体が読み込まれてリクエストごとに圧縮されます。キャッシュされず、保存済みコピーも作られないため、これはサーバーがリクエストごとに行う圧縮の中で最もコストの高いものです。

このようなファイルを読み込むと、レスポンスが書き出されるまでメモリ上に保持されるため、同時に読み込まれる数には上限があります。その上限を超えて届いたリクエストには、空きを待つのではなく、ストリーミングかつ非エンコードでファイルが配信されます。そのため、大きなアセットに持続的な負荷がかかると、圧縮されたものを受け取るクライアントとそうでないクライアントが出てきます。どちらの応答もその URL に対して正しく、いずれの場合も Vary: Accept-Encoding が付きます。

それ以外の場合、1 MiB を超えるファイルは手を加えずにディスクからストリーミングされます。圧縮できないタイプ、どのエンコーディングも受け入れないクライアント、または 3 MiB を超えるものがこれに当たります。

サイズ別の静的ファイルのコスト:

flowchart TD
    F["Static file"]
    C1{"256 B or larger?"}
    C2{"1 MiB or smaller?"}
    C3{"3 MiB or smaller?"}
    N1["Sent as-is, and cached.<br/>The framing would cost more than it saves"]
    N2["Cached, and a stored copy is built once<br/>in the background on the first cache hit"]
    N3["Read whole and compressed on every request.<br/>Too large to cache, so no copy is kept"]
    N4["Streamed from disk, never compressed.<br/>Past the compression window"]
    F --> C1
    C1 -->|no| N1
    C1 -->|yes| C2
    C2 -->|yes| N2
    C2 -->|no| C3
    C3 -->|yes| N3
    C3 -->|no| N4

この経路は、圧縮可能なタイプであることと、クライアントがエンコーディングをネゴシエートしたことを前提としています。どちらかの条件がなければ、ファイルは 1 MiB までキャッシュされ、それを超えるとストリーミングされ、範囲リクエストは常に尊重され、どこでも何もエンコードされません。

設定

エンコーディングが提供されるのは、COMPRESSION_ENCODINGS に記載され、かつそのレベルが 0 でない場合です。どちらか一方だけでそのエンコーディングは取り下げられます。取り下げられたエンコーディングは機能全体から消えます。ネゴシエートされることも、リクエストの経路で圧縮されることも、保存済みコピーとしてビルドされることもありません。

デフォルト値の理由

• Brotli は 4 ではなく 5。 Brotli の品質の分岐点（ハッシャーの切り替わり）はこの 2 つの間にあります。4 では、4 KB を超える JSON や実際の minify 済みアセットにおいて、デフォルト設定の gzip よりも多いバイト数を出力し、しかもより多くの CPU を消費しました。これでは gzip より Brotli を選ぶ理由がまったくありません。5 では、測定したすべてのボディで 2 つのうち小さい方になり、CPU は gzip のおよそ 2 倍です。
• gzip は 6。 zlib 自身のデフォルトで、収穫逓減が始まる点に近い値です。レベル 9 はおよそ 2 倍のコストで、得られるのは 1〜2% です。
• Zstandard は、自身のデフォルトの 3 ではなく 6。 数キロバイトを超えるボディでは、レベル 6 は以前のリリースがすべてを圧縮していた Brotli の品質よりも時間がかからず、しかも出力バイト数が少ないため、それらのリリースが送信していたものと比べて何も後退しません。

レベル 9〜11 は、リクエストごとの処理よりも、オフラインまたはビルド時の圧縮に適しています。それでもキャッシュされた静的ファイルにこれらのレベルが使われるのは、そのコストが一度しか発生しないからです。

圧縮可能なコンテンツタイプ

この一覧は閉じています。プレフィックスやワイルドカードのルールはないため、一覧にないタイプは、たとえよく圧縮できるものであっても圧縮されません。一覧内での照合は寛容です。パラメーターと前後の空白は取り除かれ、タイプ自体は大文字と小文字を区別せずに比較されるため、text/html; charset=utf-8 も Application/JSON も一致します。

テキストタイプ:

• text/html
• text/css
• text/plain
• text/xml
• text/javascript

アプリケーションタイプ:

• application/javascript
• application/json
• application/xml
• application/xhtml+xml
• application/rss+xml
• application/atom+xml
• application/manifest+json
• application/ld+json
• application/wasm

その他のタイプ:

• image/svg+xml
• font/ttf
• font/otf
• application/x-font-ttf
• application/x-font-opentype
• application/vnd.ms-fontobject

圧縮されないケース

以下のいずれかの条件を満たす場合、レスポンスは圧縮されずに送信されます。

• クライアントが Accept-Encoding ヘッダーで br、zstd、gzip のいずれも受け入れていない、重みゼロでしか受け入れていない（br;q=0, zstd;q=0, gzip;q=0）、またはそのヘッダー自体を送信していない
• クライアントが受け入れるすべてのエンコーディングが、COMPRESSION_ENCODINGS またはレベル 0 によって取り下げられている
• レスポンスに既に Content-Encoding ヘッダーが設定されている（例: アプリケーションが生成した圧縮済みのコンテンツ）
• レスポンスボディが 256 バイト未満、または 3 MiB を超えている
• レスポンスが 206 Partial Content である。範囲のオフセットはエンコードされていない表現を基準にしているため、部分的なボディがエンコードされることはありません
• コンテンツタイプが上記の一覧に含まれていない。image/png、image/jpeg、font/woff2、application/zip は、これらのフォーマットが既に独自の圧縮を持っているため除外されています。text/event-stream は、イベントストリームがイベントごとにクライアントへ届く必要があるため除外されています。text/csv、application/pdf、image/x-icon、および Content-Type をまったく持たないレスポンスも、一覧にないため除外されます
• サーバーがボディ全体を保持していない。oxphp_stream_flush() を使う PHP スクリプト、Server-Sent Events、送信しながらディスクから読み込まれる静的ファイルがこれに当たります。OxPHP はレスポンスを一括で圧縮します。Brotli、Zstandard、gzip はいずれもインクリメンタルにエンコードできるため、これはエンコーディングではなくサーバー側の制約です
• パイプラインが実行される前に応答したプラグインからのレスポンスである。たとえばレート制限による 429 は、圧縮ステップより前に返されます
• レスポンスが内部リスナー（INTERNAL_ADDR）からのものである。内部リスナーは /metrics とヘルスエンドポイントを、スクレイパーが何を受け入れるかに関係なく非エンコードで配信します

レスポンスヘッダー

サーバーがエンコードするレスポンスは、そのリクエスト用に圧縮されたものか保存済みコピーから配信されたものかに関係なく、以下のように書き換えられます。

1 つの静的ファイルのすべてのエンコーディングは、identity のサイズと更新日時から導出されるその弱いタグを共有します。変種を区別するのは Vary であり、タグは鮮度を決めるだけです。そのため、ある変種を再検証するキャッシュは、そのうちどれを保持しているかをサーバーに伝えることができません。

可観測性

メトリクスエンドポイントの 2 つのカウンターが、圧縮が実際に何をしたかを報告します。

• oxphp_compressed_responses_total: コンテンツエンコーディングを適用して送信されたレスポンス
• oxphp_compression_bytes_saved_total: identity のサイズから圧縮後のサイズを引いた値の合計

どちらもリクエストごとの圧縮に加えて保存済みコピーのヒットも数えるため、oxphp_requests_total との比率を見れば、「圧縮がトラフィックに届いているか」という問いに、1 回の curl -I よりも確実に答えられます。

トラブルシューティング

Docker の例

エージェント向けプロンプト

これらのプロンプトは、OxPHP ドキュメント MCP サーバー を接続したエージェントを前提としています — 必要なページはエージェントが自分で読み取ります。

関連項目

• 静的ファイル — ファイル配信、MIME 検出、HTTP キャッシュ
• メトリクス — 圧縮のカウンターとエンドポイントのその他の項目
• 設定リファレンス — 環境変数の完全な一覧