Kompresja

OxPHP kompresuje odpowiedzi HTTP za pomocą Brotli, Zstandard lub gzip, zależnie od tego, co akceptuje klient. Kompresja stosowana jest automatycznie do zamkniętej listy typów zawartości (tekst, JSON, XML, SVG, WebAssembly i kilka formatów czcionek), dzięki czemu rozmiar transferu spada bez żadnych zmian w kodzie aplikacji.

Jak to działa

Nagłówek Accept-Encoding klienta jest odczytywany raz, zanim żądanie trafi do potoku routingu, i zestawiany z kodowaniami, które oferuje serwer. Co dzieje się dalej, zależy od tego, skąd pochodzą bajty.

Buforowany plik statyczny, który ma już zapisaną skompresowaną kopię, jest serwowany bezpośrednio z tej kopii. Przy żądaniu nic nie jest kompresowane i żadna z poniższych kontroli nie ma zastosowania. Zobacz Buforowane pliki statyczne.

Każda inna odpowiedź (wynik PHP, własna strona błędu, plik statyczny, który nie ma jeszcze zapisanej kopii) przechodzi przez ten sam zestaw kontroli, w podanej kolejności, po zbudowaniu odpowiedzi:

1. Odpowiedzi częściowe są pomijane. Odpowiedź 206 nigdy nie jest kodowana, ponieważ offsety w jej Content-Range opisują niezakodowaną reprezentację.
2. Kontrola typu zawartości. Typ MIME odpowiedzi jest wyszukiwany na liście kompresowalnych typów.
3. Kontrola istniejącego kodowania. Odpowiedź, która ma już nagłówek Content-Encoding, pozostaje nietknięta.
4. Kontrola rozmiaru. Kompresowane są tylko ciała o rozmiarze od 256 bajtów do 3 MiB (3 145 728 bajtów), włącznie z obiema granicami. Gdy odpowiedź ma nagłówek Content-Length, używany jest on; odpowiedzi PHP zwykle go nie mają i są mierzone na podstawie zbuforowanego ciała.
5. Kompresja. Wynegocjowane kodowanie jest stosowane na skonfigurowanym dla niego poziomie. Jeśli skompresowany wynik nie jest mniejszy od oryginału, wysyłana jest odpowiedź nieskompresowana.

Małe ciała są kompresowane w miejscu; powyżej progu praca przenosi się na wątek blokujący, żeby nie mogła zatrzymać asynchronicznego runtime'u. Próg wynosi 64 KiB i spada do 4 KiB, gdy poziom jest na tyle wysoki, że krzywa kosztu zaczyna gwałtownie rosnąć: powyżej jakości 4 dla Brotli, poziomu 6 dla gzip i poziomu 9 dla Zstandard. Przy domyślnych ustawieniach Brotli jest już w tej stromej części, więc ciała Brotli większe niż 4 KiB są kompresowane poza wątkiem asynchronicznym.

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

Wybór kodowania

Accept-Encoding szereguje kodowania według wag (RFC 9110 §12.5.3) i OxPHP odczytuje go właśnie w ten sposób:

• Nazwy kodowań są dopasowywane bez rozróżniania wielkości liter, a nieznane kodowania są ignorowane.
• br;q=0 odrzuca Brotli. To coś innego niż pominięcie kodowania: * może jeszcze objąć pominięte kodowanie, ale nie takie, które zostało jawnie odrzucone.
• * obejmuje każde kodowanie, którego nagłówek nie wymienia jawnie, z przypisaną mu wagą.
• Waga, której nie da się sparsować, pozostawia kodowanie z wagą domyślną; źle sformatowany parametr nie usuwa kodowania. Ma to znaczenie przy q=0. Wartość qvalue ma co najwyżej trzy miejsca po przecinku, więc q=0.000 odrzuca kodowanie, a q=0.0000 w ogóle nie jest poprawną wagą i oznacza pełną akceptację. Kodowanie wymienione dwukrotnie jest odczytywane z pierwszą wagą.
• Spośród kodowań, które klient akceptuje i które serwer oferuje, wygrywa to z najwyższą wagą. Kodowanie wycofane w konfiguracji dostaje zero przed ustaleniem kolejności, więc klient, którego ulubionego kodowania serwer nie oferuje, przechodzi do swojego kolejnego wyboru, a nie do odpowiedzi nieskompresowanej.
• Nagłówek, który niczego nie akceptuje (pusty albo *;q=0), daje odpowiedź niezakodowaną. OxPHP nigdy nie odpowiada 406 z powodu kodowania zawartości i nigdy nie traktuje identity jako tokenu.

W typowym przypadku wagi są równe, bo przeglądarki wysyłają wszystkie obsługiwane kodowania bez wag. OxPHP rozstrzyga taki remis według tego, co stanie się ze skompresowanymi bajtami:

Pierwszy wiersz ma zastosowanie dopiero wtedy, gdy zapisana kopia już istnieje. Trafienia przed jej powstaniem, a także każdy plik zbyt duży do buforowania, podlegają drugiemu wierszowi, dlatego zasób statyczny jest zwykle serwowany najpierw z Zstandard, a dopiero później z Brotli.

Preferencja rozstrzyga wyłącznie remisy. Klient, który wysyła br;q=0.2, gzip;q=0.9, dostaje gzip na obu ścieżkach, a zapisana kopia zbudowana dla niego jest kopią gzip.

Klient, który nie akceptuje żadnego z trzech kodowań, otrzymuje odpowiedź niezakodowaną. W praktyce rolę zapasowego kodowania pełni gzip: akceptuje go każdy klient HTTP z ostatnich dwudziestu lat, podczas gdy Zstandard wymaga przeglądarki wydanej w 2024 roku lub później.

Vary: Accept-Encoding

Ponieważ odpowiedź zależy od nagłówka żądania, każda odpowiedź mieszcząca się w oknie kompresji ma nagłówek Vary: Accept-Encoding, skompresowana czy nie, statyczna czy dynamiczna. Reprezentacja, którą serwer zakodowałby dla jakiegoś klienta, zmienia się względem tego nagłówka nawet wtedy, gdy bieżący klient dostaje bajty identity, a współdzielona pamięć podręczna poinformowana inaczej przekazałaby te bajty klientowi, który prosił o kodowanie.

Poza tą regułą są dwa przypadki:

• Dynamiczna odpowiedź, której serwer nigdy nie trzyma w całości (wszystko, co jest strumieniowane w miarę generowania przez PHP), nie ma Vary: ta ścieżka nie może kompresować przy żadnym nagłówku, więc odpowiedź faktycznie się nie zmienia. Plik statyczny na tyle duży, że jest strumieniowany, nie należy do tej grupy i ma ten nagłówek, ponieważ ten sam plik jest wczytywany w całości i kompresowany dla klienta, który wynegocjował kodowanie.
• Odpowiedź 304 nie ma ani Vary, ani Content-Encoding: odświeża reprezentację, którą klient już ma, zamiast opisywać nową.

Vary jest dodawany jako osobna linia nagłówka, a nie scalany z tym, który aplikacja już wysłała, więc odpowiedź, która ustawiła Vary: Cookie, wychodzi z dwiema liniami Vary. Jest to poprawne i OxPHP przed dopisaniem odczytuje je wszystkie, żeby Accept-Encoding nigdy się nie powtórzył, ale pośrednik, który czyta tylko pierwszą linię, go nie zauważy.

Buforowane pliki statyczne

Plik statyczny, który mieści się w pamięci podręcznej zawartości (1 MiB lub mniej) i jest kompresowalny (typ z listy, co najmniej 256 bajtów), jest kompresowany raz, a nie przy każdym żądaniu.

1. 1
   Pierwsze żądanie: chybienie pamięci podręcznej. Plik jest wczytywany z dysku, zapisywany w pamięci podręcznej i kompresowany na potrzeby tego żądania jak wszystko inne.
2. 2
   Następne żądanie: uruchomienie budowy. Plik jest w pamięci podręcznej i jeśli nie ma jeszcze zapisanej kopii dla kodowania wynegocjowanego w tym żądaniu, serwer zleca jej zbudowanie w wątku w tle. Żądanie, które uruchomiło budowę, jest obsługiwane w trybie kompresji na żądanie, podobnie jak każde żądanie, które nadejdzie w trakcie budowy.
3. 3
   Kopia gotowa. Kolejne żądania, które negocjują to samo kodowanie, są obsługiwane z zapisanej kopii.

Nie ma licznika trafień: wyzwalaczem jest pierwsze trafienie w pamięci podręcznej bez zapisanej kopii dla danego kodowania, więc plik serwowany dotąd wyłącznie klientom gzip dostaje kopię Brotli przy pierwszym kliencie Brotli, który na niego trafi.

Zapisane kopie są budowane na maksymalnym poziomie każdego kodowania (Brotli 11, Zstandard 19, gzip 9), niezależnie od skonfigurowanych poziomów dla żądań, z których zapisana kopia nigdy nie korzysta. Nie ma dla nich osobnego ustawienia: jedynym sposobem, żeby kopia nie była budowana, jest całkowite wycofanie kodowania. Maksymalna jakość daje zwykle o 8–12% mniej bajtów niż poziom Brotli używany dla żądań.

Każde kodowanie ma własną zapisaną kopię, budowaną na żądanie, więc plik serwowany wyłącznie klientom gzip nigdy nie kosztuje kompresji Brotli. Wszystkie kopie współdzielą walidator buforowanego pliku i są odrzucane razem z buforowanymi bajtami: gdy wpis zostaje usunięty, by zmieścić się w budżecie pamięci podręcznej 64 MiB (zapisane kopie są wliczane do tego budżetu), albo gdy włączone jest STATIC_REVALIDATE i wykryje zmianę pliku na dysku. To ustawienie jest domyślnie wyłączone, więc w domyślnym wdrożeniu zapisana kopia może zostać odrzucona tylko na dwa sposoby: przez usunięcie z pamięci podręcznej i przez restart. Bajty, które się nie kompresują, są oznaczane i nie są ponownie próbowane, a odpowiedź 304 ani nie uruchamia budowy, ani nie serwuje zapisanej kopii.

Pliki zbyt duże do buforowania

Między limitem pamięci podręcznej a górną granicą okna kompresji (od 1 MiB do 3 MiB, gdzie mieszczą się bundle frameworków, mapy źródeł i moduły WebAssembly) plik jest wczytywany w całości i kompresowany przy każdym żądaniu, o ile klient wynegocjował kodowanie, a typ jest kompresowalny. Nie jest buforowany i nigdy nie dostaje zapisanej kopii, więc jest to najdroższa kompresja, jaką serwer wykonuje w przeliczeniu na żądanie.

Wczytanie takiego pliku trzyma go w pamięci do czasu zapisania odpowiedzi, więc jednocześnie wczytywana jest tylko ograniczona liczba takich plików. Żądanie, które przekroczy ten limit, dostaje plik strumieniowany i niezakodowany, zamiast czekać na zwolnienie miejsca. Przy utrzymującym się obciążeniu dużego zasobu część klientów dostaje go więc skompresowanego, a część nie; obie odpowiedzi są poprawne dla tego URL i w obu przypadkach mają Vary: Accept-Encoding.

Poza tym przypadkiem plik większy niż 1 MiB jest strumieniowany z dysku bez zmian: typ niekompresowalny, klient nieakceptujący żadnego kodowania albo cokolwiek powyżej 3 MiB.

Ile kosztuje plik statyczny, zależnie od rozmiaru:

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

Ta ścieżka zakłada typ kompresowalny i klienta, który wynegocjował kodowanie. Gdy zabraknie któregokolwiek z tych warunków, plik jest buforowany do 1 MiB, powyżej tego strumieniowany, zakresy są obsługiwane w całym przedziale i nic nie jest nigdzie kodowane.

Konfiguracja

Kodowanie jest oferowane, gdy znajduje się w COMPRESSION_ENCODINGS i jego poziom nie wynosi 0; każdy z tych warunków osobno je wycofuje. Wycofane kodowanie znika z całej funkcji: nigdy nie jest negocjowane, nigdy nie jest używane do kompresji przy żądaniu i nigdy nie jest budowana dla niego zapisana kopia.

Dlaczego takie wartości domyślne

• Brotli 5, nie 4. Kolano krzywej jakości Brotli (zmiana hashera) leży między tymi dwoma poziomami. Na poziomie 4 dawał on więcej bajtów niż gzip na własnym poziomie domyślnym dla JSON powyżej 4 KB i dla prawdziwych zminifikowanych zasobów, zużywając przy tym więcej CPU, co nie pozostawia żadnego powodu, by przedkładać go nad gzip. Na poziomie 5 daje mniejszy wynik z tych dwóch na każdym zmierzonym ciele, przy mniej więcej dwukrotnym zużyciu CPU gzip.
• Gzip 6. Domyślna wartość samego zlib, blisko punktu malejących korzyści. Poziom 9 kosztuje mniej więcej dwa razy więcej za procent lub dwa.
• Zstandard 6, nie jego własne domyślne 3. Na ciałach większych niż kilka kilobajtów poziom 6 zajmuje mniej czasu niż jakość Brotli, którą wcześniejsze wydania kompresowały wszystko, i daje mniej bajtów, więc nic nie pogarsza się względem tego, co wysyłały tamte wydania.

Poziomy 9–11 lepiej nadają się do kompresji offline lub w czasie budowania niż do pracy przy każdym żądaniu; buforowane pliki statyczne i tak ich używają, ponieważ ten koszt jest ponoszony raz.

Kompresowalne typy zawartości

Lista jest zamknięta: nie ma reguły prefiksu ani wieloznacznika, więc typ, którego na niej nie ma, nigdy nie jest kompresowany, nawet jeśli dobrze by się kompresował. W jej obrębie dopasowanie jest wyrozumiałe. Parametry i otaczające białe znaki są pomijane, a sam typ jest porównywany bez rozróżniania wielkości liter, więc text/html; charset=utf-8 i Application/JSON oba pasują.

Typy tekstowe:

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

Typy application:

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

Inne typy:

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

Bez kompresji

Odpowiedzi są wysyłane bez kompresji, gdy spełniony jest którykolwiek z poniższych warunków:

• Klient nie akceptuje w nagłówku Accept-Encoding żadnego z br, zstd i gzip, akceptuje je tylko z zerową wagą (br;q=0, zstd;q=0, gzip;q=0) albo w ogóle nie wysyła tego nagłówka
• Każde kodowanie akceptowane przez klienta zostało wycofane przez COMPRESSION_ENCODINGS lub przez poziom 0
• Odpowiedź ma już nagłówek Content-Encoding (np. treść wstępnie skompresowana przez aplikację)
• Ciało odpowiedzi jest mniejsze niż 256 bajtów lub większe niż 3 MiB
• Odpowiedź to 206 Partial Content: offsety zakresów opisują niezakodowaną reprezentację, więc częściowe ciało nigdy nie jest kodowane
• Typu zawartości nie ma na powyższej liście. image/png, image/jpeg, font/woff2 i application/zip są wykluczone, bo te formaty mają już własną kompresję, a text/event-stream dlatego, że strumień zdarzeń musi docierać do klienta zdarzenie po zdarzeniu. text/csv, application/pdf, image/x-icon oraz odpowiedź w ogóle bez Content-Type również są wykluczone, bo nie ma ich na liście
• Serwer nie trzyma ciała w całości: skrypty PHP używające oxphp_stream_flush(), Server-Sent Events i pliki statyczne czytane z dysku w trakcie wysyłania. OxPHP kompresuje odpowiedź w jednym kawałku. Brotli, Zstandard i gzip potrafią kodować przyrostowo, więc jest to ograniczenie serwera, a nie samych kodowań
• Odpowiedź pochodzi z pluginu, który odpowiedział przed uruchomieniem potoku, np. 429 z limitu żądań, zwracane przed krokiem kompresji
• Odpowiedź pochodzi z wewnętrznego listenera (INTERNAL_ADDR), który serwuje /metrics i endpointy health niezakodowane, niezależnie od tego, co akceptuje scraper

Nagłówki odpowiedzi

Odpowiedź kodowana przez serwer jest przepisywana następująco, niezależnie od tego, czy została skompresowana na potrzeby tego żądania, czy podana z zapisanej kopii:

Wszystkie kodowania jednego pliku statycznego współdzielą ten słaby tag, wyliczany z rozmiaru identity i czasu modyfikacji. To Vary rozdziela warianty; tag decyduje tylko o świeżości, więc pamięć podręczna rewalidująca jeden wariant nie może powiedzieć serwerowi, który z nich przechowuje.

Obserwowalność

Dwa liczniki na endpoincie metryk pokazują, co kompresja faktycznie zrobiła:

• oxphp_compressed_responses_total: odpowiedzi wysłane z kodowaniem zawartości
• oxphp_compression_bytes_saved_total: suma różnic między rozmiarem identity a rozmiarem po kompresji

Oba liczą zarówno trafienia w zapisane kopie, jak i kompresje przy żądaniu, więc stosunek do oxphp_requests_total odpowiada na pytanie „czy kompresja obejmuje mój ruch” pewniej niż pojedyncze curl -I.

Rozwiązywanie problemów

Przykład Docker

Prompty dla Twojego agenta

Te prompty zakładają agenta z podłączonym serwerem MCP dokumentacji OxPHP — sam przeczyta strony, których potrzebuje.

Zobacz także

• Pliki statyczne — serwowanie plików, wykrywanie MIME i buforowanie HTTP
• Metryki — liczniki kompresji i reszta endpointu
• Dokumentacja konfiguracji — pełna lista zmiennych środowiskowych