docs(kompresja): gzip_static bez plików .gz był atrapą — dowody + werdykt brotli

[mpasternak]

Co się stało

gzip_static on siedzi w _bpp-locations.conf od dawna. Ta dyrektywa nie znaczy „kompresuj statyki" — znaczy „wyślij x.js.gz, jeśli istnieje".

Zmierzone na iplweb/bpp_appserver:202608.1399rc5: 3429 plików w staticroot.baked, z tego 0 sztuk .gz. Nginx nie miał czego znaleźć, więc cicho spadał na gzip on i kompresował plotly.min.js (4,4 MB) od nowa przy każdym cache-missie.

Objawu nie ma żadnego — strona działa, Content-Encoding: gzip jest, rozmiar się zgadza. Różnica siedzi wyłącznie w CPU brzegu i poziomie kompresji (w locie 5, offline 9).

Co robi ten PR

Nie zmienia zachowania. Sama prekompresja trafia do obrazu BPP (osobny PR w iplweb/bpp), bo .gz musi powstawać w tym samym kroku co plik źródłowy: nginx serwując x.js.gz nie porównuje mtime z x.js, więc nieaktualny .gz = wieczne serwowanie starego JS-a wszystkim przeglądarkom, bez śladu w logach. Tutaj gzip_static on zacznie działać samo, gdy przyjedzie nowy obraz.

Ten PR zapisuje dowody, żeby nie zginęły:

• nowa strona docs/rozwoj/pulapki-kompresji.md (+ wpis w mkdocs.yml),
• tripwire w CLAUDE.md (reguła + objaw + anty-fix, zgodnie z podziałem z docs-sync),
• akapit w docs/konfiguracja/architektura.md.

Brotli i zstd — zmierzone i odrzucone

Pytanie wraca w każdym review, więc niech ma pisemną odpowiedź.

Zysk jest realny: plotly.min.js 1315 KB → 948 KB (−28%), bundle.js 225 KB → 187 KB (−17%). Ale dotyczy tylko /static/, które ma Cache-Control: immutable — czyli poprawia głównie pierwszą wizytę.

Trzy blokady, wszystkie zweryfikowane empirycznie na owasp/modsecurity-crs:nginx:

1. Repo nginx.org nie ma modułu brotli. Pełna lista dla trixie: geoip, image-filter, njs, otel, perl, xslt. Wariant „doinstaluj pakiet" nie istnieje.
2. Moduł debianowy odbija się o ABI: [emerg] module version 1026003 instead of 1030004. --with-compat tego nie ratuje. Zostaje kompilacja ze źródeł (73 s).
3. Łatka na nginx.conf nie przeżywa startu kontenera — entrypoint CRS regeneruje go z templates/nginx.conf.template. Build wychodzi zielony, a kontener nie wstaje: [emerg] unknown directive "brotli_static".

Prawdziwy koszt to nie Dockerfile (~25 linii), tylko szósty utrzymywany obraz sprzężony wersyjnie z pływającym tagiem upstreamu, gdzie tryb awarii brzmi „nginx nie wstaje" — plus zmiana modelu wdrożenia z pull na build, autoupdate.sh bez digestów i make test-waf testujący inny artefakt niż wdrożony.

zstd odpada bez dyskusji — tylko kompilacja ze źródeł trzeciej strony.

Niezmierzone i do sprawdzenia, gdyby temat wrócił: kolejność filtra brotli względem inspekcji odpowiedzi przez ModSecurity (RESPONSE-95x).

Przy okazji: dokumentacja kłamała

CLAUDE.md i docs/konfiguracja/architektura.md opisywały entrypoint jako cp -ru. Upstream zmienił to na cp -rf właśnie dlatego, że -u był pułapką — mtime w .baked pochodzi z builda obrazu, więc restart późniejszy niż build kazał -u pominąć kopiowanie i zostawić stare pliki. Opis mówił dosłownie odwrotnie niż kod.

Weryfikacja

mkdocs build --strict przechodzi. Brak zmian w kodzie i konfiguracji → brak wpływu na make up.

Zależność

Sparowany z PR-em w iplweb/bpp (prekompresja w obrazie). Ten może wejść niezależnie i wcześniej — nic nie psuje.

🤖 Generated with Claude Code

https://claude.ai/code/session_01J35fM3toviqNDsGxRg6P1c