Add bilingual JSON-library analysis reports (EN/DE)

ANALYSE_DE.md

@@ -0,0 +1,235 @@
+# 1. Kurzfazit
+
+## Kurze Antwort
+Auf Basis dieses Repositories **im aktuellen Zustand** ist die einzige tatsächlich integrierte und benchmark-relevante JSON-Bibliothek **YAJL**. Die anderen in deinem Briefing genannten Bibliotheken (RapidJSON, nlohmann/json, json-c, Jansson, cJSON, JsonCpp, jsoncons, simdjson, yyjson, Glaze) sind **im Codebestand nicht vorhanden**; daher kann man sie ohne zusätzliche Integrationsarbeit nicht seriös als „besten Fit für dieses Repository“ auswählen.
+
+## Praktische Entscheidung
+- **Beste Gesamtwahl für dieses Repository heute:** **YAJL** (weil produktiv integriert, nicht wegen theoretischer Rohgeschwindigkeit).
+- **Beste Wahl für maximale Performance:** **Unklar in diesem Repo-Zustand** (kein in-repo, fairer Vergleich aller Bibliotheken).
+- **Beste Wahl für Robustheit hier:** **YAJL**, da echte Request-Body-Verarbeitung, Fehlerpfade und Tiefenlimit bereits angebunden sind.
+- **Beste Wahl für modernes C++-API:** allgemein eher **nlohmann/json / Glaze / simdjson**, aber **hier nicht durch Code belegt**.
+- **Beste Wahl für minimale Abhängigkeiten in diesem Repo:** YAJL ist bereits Pflicht und integriert.
+- **Beste Wahl für strikte JSON-Compliance:** allgemein eher simdjson/yyjson/RapidJSON im Strict-Mode; **hier nicht nachweisbar**.
+- **Beste Wahl für tolerantes Parsing:** YAJL wirkt gemäß deiner externen Beobachtung tolerant (test05), aber **diese Datei fehlt im Repo** und ist hier nicht verifizierbar.
+
+---
+
+# 2. Überblick über das Repository
+
+## Was hier tatsächlich gebenchmarkt wird
+Der Benchmark unter `test/benchmark/benchmark.cc` misst **ModSecurity-Transaktionsdurchsatz**, nicht den direkten JSON-Parservergleich. Es wird eine vollständige Transaktion pro Iteration ausgeführt (Connection/URI/Header/Body/Response/Logging). JSON-Parsing ist dabei nur ein möglicher Teilkostenfaktor.
+
+### Fakten aus dem Code
+- Die Benchmark-Schleife erzeugt `Transaction`, durchläuft Phasen und ruft danach `processLogging()` auf.
+- Eingaben sind größtenteils fixe HTTP-Metadaten plus ein fixer XML-Response-Body.
+- Standard-Regeldatei ist `test/benchmark/basic_rules.conf` mit nur `modsecurity.conf-recommended`.
+
+### Wichtige Implikation
+Dieser Benchmark passt zu **End-to-End-Laufzeit von ModSecurity**, aber nicht zu direkten Aussagen „JSON-Library X ist schneller als Y“.
+
+---
+
+# 3. Nutzung der JSON-Bibliotheken
+
+## JSON im produktiven Pfad (Fakten)
+1. **Request-Body-JSON-Parsing** läuft über YAJL-Callbacks (`yajl_alloc`, `yajl_parse`, Callbacks für map/array/string/number etc.).
+2. **JSON-Serialisierung/Erzeugung** nutzt YAJL-Generator-API in Core-Pfaden.
+3. **JSON-Dateien in Unit/Regression-Tests** werden ebenfalls via YAJL-Tree-API verarbeitet.
+4. Configure/Build bindet YAJL explizit ein (`configure.ac`, `build/yajl.m4`, `test/benchmark/Makefile.am`).
+
+## Verwendetes Parsing-Modell
+- **Streaming/Event-basiert (SAX-ähnlich)** im Request-Body-Prozessor.
+- Kein DOM-zentrischer Hot Path.
+- Numerische Werte werden bewusst als Strings weitergereicht (laut Kommentar im Code).
+- Es gibt ein explizites Tiefenlimit für verschachtelte JSON-Strukturen.
+
+## Bibliotheken aus deiner Liste
+Alle Nicht-YAJL-Bibliotheken aus deiner Liste sind in dieser Revision **nicht eingebunden**.
+
+---
+
+# 4. Validität des Benchmarks
+
+## Stärken
+- Lange, wiederholte Transaktionsschleife mit konfigurierbarer Iterationszahl.
+- Realistische Phasenreihenfolge inkl. Intervention-Checks.
+- Mit OWASP CRS per Skript erweiterbar.
+
+## Schwächen / Fairness-Probleme
+1. **Kein JSON-Library-Benchmark**: Es wird die komplette WAF-Pipeline gemessen.
+2. **Default-Payload ist kein JSON-Stresstest** (fixe Requestdaten + XML-Response).
+3. **Keine bibliotheksübergreifende Implementierungsparität** (nur YAJL vorhanden).
+4. **Keine Methodik-Kontrollen gefunden** für CPU-Pinning, Warmup, Governor, NUMA, Varianzmetriken.
+5. **Doku-Drift möglich**: README sagt, die letzte Logging-Phase werde nicht aufgerufen; der aktuelle Code ruft `processLogging()` auf.
+
+## Konsequenz
+Aussagen wie „YYJSON gewinnt“ oder „SIMDJSON gewinnt nicht immer“ sind aus diesem Repository **allein nicht reproduzierbar**.
+
+---
+
+# 5. Analyse pro Bibliothek
+
+Ich trenne je Bibliothek in:
+- **Code-basierter Fakt (Repo)**
+- **Inference (allgemeines Ökosystemwissen)**
+- **Unsicherheit**
+
+## YAJL
+- Fakt: Voll integriert für Parsing, Generierung, Tests, Configure/Build und Benchmark-Linking.
+- Fakt: Request-Body-Parser nutzt Callback-Stil mit Tiefenlimit/Fehlerbehandlung.
+- Inference: Sehr guter Fit zur bestehenden Architektur, weil die Logik auf Streaming-Callbacks aufgebaut ist.
+- Schwäche: C-API, manuelles State-Management, weniger modernes C++-Erlebnis.
+- Empfehlung für dieses Repo: **Ja**.
+
+## RapidJSON
+- Fakt: Nicht integriert.
+- Inference: Könnte SAX/DOM abdecken und schnell sein; Migrationsaufwand mittel/hoch wegen notwendigem Re-Design der Callback/Argument-Extraktion.
+- Unsicherheit: Kein Benchmark-Nachweis im Repo.
+- Empfehlung: **Eher nein (aktuell)**.
+
+## nlohmann/json
+- Fakt: Nicht integriert.
+- Inference: Sehr hohe Entwicklerproduktivität/Lesbarkeit, aber meist langsamer/allokationsintensiver für Streaming-WAF-Hot-Path.
+- Unsicherheit: Keine in-repo Messung.
+- Empfehlung: **Eher nein** für Hot Path, **eher ja** für Tooling/Control-Plane-Code.
+
+## json-c
+- Fakt: Nicht integriert.
+- Inference: Solide C-Bibliothek, oft DOM-lastig; kann je Integration mehr Speicher erzeugen als Streaming-Ansatz.
+- Empfehlung: **Eher nein**.
+
+## Jansson
+- Fakt: Nicht integriert.
+- Inference: Saubere C-API, robust, aber nicht ohne Adapter-Aufwand passend zum aktuellen Streaming-Pfad.
+- Empfehlung: **Eher nein**.
+
+## cJSON
+- Fakt: Nicht integriert.
+- Inference: Klein/einfach, aber für komplexes Security-Parsing oft zu limitiert bei Features/Fehlerbehandlung.
+- Empfehlung: **Nein**.
+
+## JsonCpp
+- Fakt: Nicht integriert.
+- Inference: Älterer C++-DOM-Stil; für High-Performance-Streaming tendenziell weniger attraktiv.
+- Empfehlung: **Eher nein**.
+
+## jsoncons
+- Fakt: Nicht integriert.
+- Inference: Moderne C++-Features, aber zusätzliche Komplexität/Abhängigkeiten plus Integrationsaufwand.
+- Empfehlung: **Eher nein**.
+
+## simdjson
+- Fakt: Nicht integriert.
+- Inference: Sehr hoher Durchsatz bei großen validen JSON-Daten; reale Vorteile brauchen idiomatische Nutzung (Padding, ondemand, wenig Konvertierungsoverhead).
+- Risiko: DOM-Umwege oder viele String-Kopien können Vorteile stark reduzieren.
+- Empfehlung: **Eher ja** nur bei gezielter Integrationsneugestaltung und sauberer Benchmark-Methodik.
+
+## yyjson
+- Fakt: Nicht integriert.
+- Inference: Häufig Top-Performance bei Parse/Write; C-API passt grundsätzlich zu low-level Performance-Zielen.
+- Risiko: Aktuelle Repo-Semantik (Callback-basierte Extraktion) kann naive Portierung ausbremsen.
+- Empfehlung: **Eher ja** für Performance-Experimente, **kein sofortiger Drop-in**.
+
+## Glaze
+- Fakt: Nicht integriert.
+- Inference: Stark für C++-Reflexion/Serialization; weniger natürlicher Fit bei dynamischem, potenziell untrusted JSON in Security-Pfaden.
+- Empfehlung: **Eher nein** für diesen spezifischen Hot Path.
+
+---
+
+# 6. Analyse von test05.json
+
+## Was sich aus diesem Repository verifizieren lässt
+- `test05.json` ist im Tree **nicht vorhanden**.
+- Es gibt hier **kein** Multi-Library-JSON-Benchmark-Harness.
+
+## Daher
+Die Aussage „nur YAJL besteht test05.json“ ist aus dem Repository-Code allein nicht verifizierbar.
+
+## Wahrscheinliche Ursachen (Inference)
+Wenn YAJL besteht und strengere Parser scheitern, sind typische Ursachen:
+- nicht-standardkonforme Zahlenformate,
+- trailing commas / Kommentare (JSON5-ähnlich),
+- UTF-8-/Control-Character-Kantenfälle,
+- Unterschiede bei Duplicate Keys, Tiefenlimits oder unvollständigen Tokens,
+- unterschiedliche Toleranz-/Quirk-Modi.
+
+## Striktes vs. tolerantes Parsing für dieses Projekt
+Für eine Security Engine ist als Default meist sinnvoll:
+- **striktes Parsing für Vorhersagbarkeit/Korrektheit**, plus
+- optional toleranter Modus nur, wenn explizit für Kompatibilität benötigt.
+
+---
+
+# 7. Bewertung nach Kriterien
+
+## Entscheidungs-Matrix (Kontext: aktueller Repo-Zustand)
+
+| Library | Language | Strengths | Weaknesses | Repo Fit | Recommendation |
+|---|---|---|---|---|---|
+| YAJL | C | Bereits end-to-end integriert; Streaming-Callbacks; Build/Test vorhanden | Weniger ergonomische C-API; manuelles State-Handling | Exzellent (aktuelle Architektur) | Yes |
+| RapidJSON | C++ | Schnell, SAX+DOM, reif | Nicht integriert; Migrationsaufwand | Aktuell gering | Probably no |
+| nlohmann/json | C++ | Sehr produktiv/lesbar | Meist langsamer; nicht integriert | Für Hot Path gering | Probably no |
+| json-c | C | Solide C-Bibliothek | Oft DOM-lastig; nicht integriert | Gering | Probably no |
+| Jansson | C | Saubere API, robust | Nicht integriert; Adapteraufwand | Gering | Probably no |
+| cJSON | C | Minimal/einfach | Begrenzte Robustheit für komplexe Security-Fälle | Sehr gering | No |
+| JsonCpp | C++ | Bekanntes Legacy-API | Älterer Stil/Perf-Trade-offs; nicht integriert | Gering | Probably no |
+| jsoncons | C++ | Reiches modernes Feature-Set | Nicht integriert; mehr Komplexität | Gering | Probably no |
+| simdjson | C++ | Sehr hoher Durchsatz bei großen Dateien | Integrations-Neudesign nötig; Fehlbenutzungsrisiko | Mittel (bei Invest) | Probably yes |
+| yyjson | C | Sehr hohe Parse/Write-Performance in vielen Workloads | Nicht integriert; Semantik-Mismatch möglich | Mittel (bei Invest) | Probably yes |
+| Glaze | C++ | Modern, stark bei compile-time Serialization | Weniger natürlicher Fit für dynamisches/untrusted Parsing | Gering | Probably no |
+
+---
+
+# 8. Konkrete Empfehlung
+
+## Für dieses Repository jetzt
+1. **YAJL als Produktionsparser beibehalten**, solange keine architektonische Integrationsinitiative gestartet wird.
+2. Bei Performance-Fokus: **separates Parser-Mikrobenchmark-Harness** + **End-to-End-ModSecurity-Benchmark** mit identischer Semantik.
+3. Erste Challengers für Prototyping: **yyjson** (C, low-level speed) und **simdjson** (stark bei großen validen JSON-Daten bei korrekter Nutzung).
+
+## Kategorien (mit aktueller Evidenzqualität)
+- Beste Gesamtwahl für DIESES Repo: **YAJL**.
+- Höchstes Performance-Potenzial: **yyjson / simdjson** (Inference, hier nicht validiert).
+- Höchste Robustheit in DIESEM Repo: **YAJL** (reife Integration).
+- Bestes modernes C++-API: **nlohmann/json** (Ergonomie), **simdjson** (performance-orientiertes modernes API).
+- Minimale Abhängigkeiten in DIESEM Repo: **YAJL**.
+- Strikte Compliance: **Unklar aus Repo; benötigt Conformance-Testsuite**.
+- Tolerantes Parsing: **Möglicherweise YAJL laut externer Beobachtung; hier nicht verifizierbar**.
+
+---
+
+# 9. Verbesserungen / To-dos
+
+## Benchmark-Design
+1. Dediziertes JSON-Parser-Benchmark-Binary unabhängig von Transaktionsphasen ergänzen.
+2. Semantische Gleichheit je Bibliothek erzwingen:
+   - identische Input-Bytes,
+   - identische Output-Extraktion (Pfade/Werte),
+   - identische Fehlerpolitik.
+3. Umgebungsparameter dokumentieren:
+   - CPU-Modell, Governor, Core-Pinning, SMT,
+   - Compiler + Flags,
+   - Anzahl Läufe, Median/p95/Stdabw.
+4. Zusätzliche Metriken:
+   - Parse-Latenz/Throughput,
+   - Allokationen (Anzahl/Bytes),
+   - Peak RSS,
+   - Fehlerdiagnostik.
+
+## Korrektheits-Korpus
+- RFC-8259-valid, invalid, UTF-8-Edge-Cases, tiefe Verschachtelung, Duplicate Keys, Zahlen-Extrema sowie `test05.json` mit klarer Expected-Policy.
+
+## Integrationshygiene
+- In Reports strikt zwischen Fakten und Inference trennen.
+- README/Code-Mismatch zur Logging-Phase korrigieren.
+- CI-Target für reproduzierbare JSON-Benchmarks ergänzen.
+
+---
+
+# 10. Unsicherheiten
+
+1. Die in deinem Kontext genannten Bibliotheken sind in dieser Repo-Revision nicht enthalten; deren Bewertung bleibt inferenziell.
+2. `test05.json` und Python-Validierungsbefunde sind extern zu diesem Tree.
+3. Compiler-Optimierungsflags und Laufzeit-Pinning früherer Benchmarks sind hier nicht dokumentiert.
+4. Jede Gewinner-Aussage jenseits von YAJL-Fit braucht erst gleichwertige Adapter-Implementierung + Validierung.