From f3b47af551fa6cd85509a65bb77d8d1b9bcb744a Mon Sep 17 00:00:00 2001 From: Matthias Andreas Benkard 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 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