From f3b47af551fa6cd85509a65bb77d8d1b9bcb744a Mon Sep 17 00:00:00 2001
From: Matthias Andreas Benkard <code@mail.matthias.benkard.de>
Date: Sat, 22 Aug 2026 21:23:06 +0200
Subject: =?UTF-8?q?Die=20Auslieferung=20tr=C3=A4gt=20nur,=20was=20der=20Br?=
 =?UTF-8?q?owser=20wirklich=20braucht?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Die Browserfassung soll künftig über Cloudflare Workers gehen, und dort gilt
eine Grenze von 25 MiB je Datei, unkomprimiert gemessen. Zwei der
ausgelieferten Dateien standen dem entgegen: Das Quelltextarchiv maß 29,7 MB
und war damit schon nicht mehr hochzuladen, das Wasm-Modul mit 24,5 MB zu
achtundneunzig Hundertsteln der Grenze und ohne jeden Spielraum.

Das Archiv war ein ungefiltertes „git archive“ des Repositoriums, und über
fünfundneunzig Hundertstel davon waren die Beispiel-PDFs. Der Quelltext selbst
misst keine dreihunderttausend Zeichen. Die Gesetzes- und Drucksachentexte sind
fremde Werke, an denen allein die Tests messen; sie sind nicht der Quelltext,
aus dem sich das Ausgelieferte herstellen ließe, und die Auflage des AGPLv3 § 13
verlangt sie deshalb nicht. Sie sind aus dem Archiv genommen, und
„quelltext-fassung.txt“ sagt fortan, dass sie fehlen, warum sie fehlen und wo
sie vollständig liegen. Damit dies nicht stillschweigend zurückfällt, bricht
„webpaket.sh“ ab, sobald das Archiv acht Mebibyte überschreitet, und ebenso,
wenn irgendeine ausgelieferte Datei die Grenze der Zielplattform reißt: Lieber
hier auffallen als beim Hochladen.

Der Korpus lag überdies unter „src/main/resources“ und wanderte deshalb in
jedes Erzeugnis: in das Klassenverzeichnis, in die ausführbare Archivdatei —
achtundzwanzig Megabyte für ein Werk von sechshundert Kilobyte Java — und auf
den Klassenpfad des Übersetzers, dessen Ressourcentabelle die Verzeichnisnamen
bis ins Wasm trug. Er liegt nunmehr unter „src/test/resources“, wo er hingehört,
und ist von der Kopie nach „target/test-classes“ ausgenommen: Die Tests lesen
ihn über Dateisystempfade, eine Kopie wäre bei jedem Bau fünfunddreißig
Megabyte umsonst.

Das Modul wiegt statt 24,5 nunmehr 17,2 Megabyte; komprimiert geht es mit 5,5
statt 7,1 Megabyte über die Leitung. Vier Ursachen liegen dem zugrunde. Der
Picocli-Annotationsprozessor meldete die Befehlszeilenklasse mit sämtlichen
Methoden zur Reflexion an, worauf die Erreichbarkeitsanalyse die ganze
Befehlszeilenfassung samt Dateizugriffen in ein Bild zog, in dem es keine
Befehlszeile gibt; im Profil „wasm“ läuft er nicht mehr, und eine von einem
früheren Lauf liegengebliebene Konfiguration wird vor dem Übersetzen entfernt,
damit die Größe nicht davon abhängt, was vorher lief. Der Ressourcen-Glob
„org/apache/fontbox/**“ bettete 3,3 Megabyte ostasiatischer CMaps, die
Schrifttabelle „Scripts.txt“ und — weil zwei Sterne auch Klassendateien treffen
— 0,7 Megabyte „.class“-Dateien ein, von denen ein deutsches Gesetzes-PDF nichts
braucht; geblieben sind die beiden Identity-CMaps. Die Metriken unter
„org/apache/pdfbox/resources“ bleiben vollständig, denn an ihnen hängt die
Breitenberechnung bei nicht eingebetteten Schriften. Übersetzt wird mit „-Os“,
und den Rest holt „wasm-opt -Oz“ im Webpaket.

Dessen Merkmale sind einzeln aufgezählt und nicht als „--all-features“ erteilt.
Der bequeme Weg war gangbar und führte doch ins Leere: Binaryen nutzte
daraufhin Vorschläge, die noch kein Browser annimmt, und das Modul scheiterte
erst beim Instanziieren — erst an einem exakten Heap-Typ aus den „custom
descriptors“, nach dessen Abschaltung an der kompakten Importsektion. Zugelassen
ist nunmehr, was ausgeliefert in den Browsern steht und was Web Image braucht.

Die Vorkompression nach „.gz“ und „.br“ entfällt als Regelfall, denn Cloudflare
komprimiert selbst und jede Beilage wäre dort eine weitere Datei; wer mit nginx
selbst ausliefert, fordert sie mit VORKOMPRIMIEREN=1 an. Das
Auslieferungsverzeichnis fällt damit von achtundsechzig auf siebzehn Megabyte,
und ein liegengebliebenes „.DS_Store“ geht nicht mehr mit hoch.

Dreihundertfünfundzwanzig Testfälle bestehen. Das Modul ist im Browser
gelaufen: Vier Dokumentenpaare — IfSG, UWG, AGG und das Bayerische Jagdgesetz,
also gii-XML wie PDF als Stammfassung, Bundesgesetzblatt, Drucksache und
Gesetz- und Verordnungsblatt als Änderungsdokument — ergeben Synopsen, deren
SHA-256-Summen denen der Befehlszeilenfassung gleichen. Der Ressourcenbeschnitt
kostet also keine Zeichen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Change-Id: I31a47d1dcf3b27ffa4ae891947b1c4e083107a71
---
 README.adoc | 74 ++++++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 56 insertions(+), 18 deletions(-)

(limited to 'README.adoc')

diff --git a/README.adoc b/README.adoc
index 996a0be..ee363d4 100644
--- a/README.adoc
+++ b/README.adoc
@@ -111,7 +111,7 @@ https://matthias.benkard.de/aendggner/.
 (2) Fortlaufende Quelltextquelle ist
 https://gerrit.benkard.de/plugins/gitiles/aendggner. Die jeweils betriebene
 Fassung liegt der Browserfassung überdies als `aendggner-quelltext.tar.gz` bei
-(§ 15 Absatz 4).
+(§ 15 Absatz 5).
 
 (3) Das Erzeugnis steht unter der GNU Affero General Public License, Fassung 3;
 der Lizenztext ist der Datei `COPYING` zu entnehmen.
@@ -486,15 +486,42 @@ JAVA_HOME=/pfad/zu/oracle-graalvm ./mvnw -Pwasm package
 ----
 
 (4) Ergebnis ist `target/web/` mit `index.html`, `app.js`, `worker.js`,
-`style.css`, `favicon.svg`, `aendggner.js` und `aendggner.js.wasm` (rund 24 MB,
-komprimiert etwa 7 MB). Das Verzeichnis ist so, wie es dasteht, auslieferbar:
+`style.css`, `favicon.svg`, `aendggner.js` und `aendggner.js.wasm` (rund 17 MB,
+komprimiert etwa 5 MB). Das Verzeichnis ist so, wie es dasteht, auslieferbar:
 `deploy/webpaket.sh` läuft am Ende desselben Befehls, wirft den mehrere hundert
-Megabyte großen Textzwischenschritt `aendggner.js.wat` fort, legt den Quelltext
-der gebauten Fassung als `aendggner-quelltext.tar.gz` samt
-`quelltext-fassung.txt` bei und komprimiert die großen Dateien nach `.gz` und
-`.br` vor.
-
-(5) Trägt der Arbeitsbaum uneingecheckte Änderungen, so bricht die Herstellung
+Megabyte großen Textzwischenschritt `aendggner.js.wat` fort, schickt das Modul
+durch `wasm-opt -Oz` und legt den Quelltext der gebauten Fassung als
+`aendggner-quelltext.tar.gz` samt `quelltext-fassung.txt` bei.
+
+(5) Die Größe des Moduls beruht auf vier Vorkehrungen; wer eine davon zurücknimmt,
+handelt sich die Megabyte wieder ein:
+
+1. `-Os` beim Übersetzen statt der auf Durchsatz gerichteten Voreinstellung;
+2. kein Picocli-Annotationsprozessor im Profil `wasm`. Er meldete die
+   Befehlszeilenklasse zur Reflexion an, worauf die Erreichbarkeitsanalyse die
+   gesamte Befehlszeilenfassung ins Browser-Image zog, die dort niemand aufruft;
+3. ein enger Ressourcen-Glob in `reachability-metadata.json`. Das frühere
+   `org/apache/fontbox/**` bettete 3,3 MB CJK-CMaps, `Scripts.txt` und — weil
+   `**` auch Klassendateien trifft — 0,7 MB `.class`-Dateien ein, von denen
+   deutsche Gesetzes-PDFs nichts brauchen. Geblieben sind die beiden
+   Identity-CMaps; `org/apache/pdfbox/resources/**` bleibt vollständig, damit die
+   Breitenberechnung bei nicht eingebetteten Schriften unangetastet ist;
+4. `wasm-opt -Oz` als Nachlauf. Die zugelassenen Wasm-Merkmale sind in
+   `webpaket.sh` einzeln aufgezählt und nicht als `--all-features` erteilt: Sonst
+   nutzt Binaryen auch Vorschläge, die noch kein Browser annimmt, und das Modul
+   scheitert erst beim Instanziieren.
+
+(6) Im Quelltextarchiv fehlt der Beispielkorpus; `.gitattributes` nimmt
+`src/test/resources/sampledata` von `git archive` aus. Es sind Gesetzes- und
+Drucksachentexte fremder Urheberschaft, an denen allein die Tests messen —
+Quelltext im Sinne der AGPLv3 sind sie nicht, gebaut wird ohne sie, und sie
+machten das Archiv dreißigmal so groß wie den Quelltext (29,7 MB statt 0,26 MB).
+`quelltext-fassung.txt` sagt dies und verweist für den vollständigen Korpus auf
+die Anschrift nach § 3 Absatz 2. Wächst das Archiv wieder über 8 MiB, so bricht
+`webpaket.sh` ab; alsdann sind Massendaten ins Repository geraten, die dort nicht
+hingehören.
+
+(7) Trägt der Arbeitsbaum uneingecheckte Änderungen, so bricht die Herstellung
 nach Absatz 3 ab, denn der beigelegte Quelltext wäre alsdann nicht der gebaute.
 Für einen Probelauf hilft `QUELLTEXT_UNGEPRUEFT=1`.
 
@@ -513,26 +540,37 @@ Weg für Massenläufe.
 [[ausrollen]]
 == § 15 Ausrollen
 
-(1) Betrieben wird die Fassung unter einem Unterpfad einer bestehenden Domain,
-https://matthias.benkard.de/aendggner/. Ein eigener Server und ein eigenes
-Zertifikat sind hierfür nicht erforderlich; erforderlich ist nur ein Webserver
-für statische Dateien.
+(1) Erforderlich ist nur ein Ort für statische Dateien. Ausgeliefert wird über
+Cloudflare Workers. Dort gilt eine Grenze von 25 MiB je Datei — unkomprimiert
+gemessen —, und komprimiert wird beim Ausliefern ohnehin. `webpaket.sh` legt
+deshalb keine `.gz`/`.br`-Beilagen mehr an und hält am Ende jede Datei gegen
+diese Grenze; überschreitet eine sie, so bricht der Bau ab, statt das Hochladen
+scheitern zu lassen.
 
 [source,shell script]
 ----
 JAVA_HOME=/pfad/zu/oracle-graalvm ./mvnw -Pwasm package
+----
+
+(2) Wer die Fassung stattdessen selbst ausliefert — unter einem Unterpfad einer
+bestehenden Domain, wie zuvor unter https://matthias.benkard.de/aendggner/ —,
+braucht die Vorkompression und fordert sie beim Bau an:
+
+[source,shell script]
+----
+JAVA_HOME=/pfad/zu/oracle-graalvm VORKOMPRIMIEREN=1 ./mvnw -Pwasm package
 rsync -av --delete target/web/ server:/var/www/aendggner/
 ----
 
-(2) `deploy/nginx-aendggner.conf` ist kein eigener `server`-Block, sondern ein
+(3) `deploy/nginx-aendggner.conf` ist kein eigener `server`-Block, sondern ein
 Schnipsel zum Einfügen in den vorhandenen (`include`). Er bringt mit:
 
 1. die Weiterleitung von `/aendggner` auf `/aendggner/`, ohne die alle relativen
    Verweise der Seite auf die Domainwurzel zielten;
 2. den MIME-Typ `application/wasm`, ohne den der Browser die Instanziierung des
    Moduls verweigert;
-3. `gzip_static`/`brotli_static` für die vorkomprimierten Dateien, statt 24 MB je
-   Abruf neu zu packen;
+3. `gzip_static`/`brotli_static` für die nach Absatz 2 vorkomprimierten Dateien,
+   statt 17 MB je Abruf neu zu packen;
 4. `Cache-Control: no-cache` statt einer Haltefrist. Die Dateinamen tragen keine
    Fassungskennung, und ein Browser mit altem `app.js` und neuem `.wasm` bekäme
    sonst eine Mischfassung, die es nie gegeben hat. Revalidiert wird per ETag; das
@@ -543,11 +581,11 @@ Schnipsel zum Einfügen in den vorhandenen (`include`). Er bringt mit:
    Synopse als `blob:`-Dokument die Richtlinie der erzeugenden Seite erbt, ihr
    Stylesheet aber eingebettet trägt.
 
-(3) `impressum.html` und `datenschutz.html` tragen die Angaben nach § 5 DDG und
+(4) `impressum.html` und `datenschutz.html` tragen die Angaben nach § 5 DDG und
 Art. 13 DSGVO. Die dort genannte Aufbewahrungsfrist der Zugriffsprotokolle
 (14 Tage) muss zu derjenigen des Servers passen.
 
-(4) Der Footer der Startseite verweist auf den beigelegten Quelltext-Tarball; dies
+(5) Der Footer der Startseite verweist auf den beigelegten Quelltext-Tarball; dies
 verlangt AGPLv3 § 13 für den Netzwerkbetrieb. Als fortlaufende Zweitquelle ist
 die Anschrift nach § 3 Absatz 2 genannt.
 
-- 
cgit v1.2.1

