Framework-agnostic model layer for Compression Dictionary Transport headers

[dfa1]

Builds on #91 (which covers only the dcz frame codec).

Idea

A pure "model" layer for RFC 9842's HTTP semantics — builder-style objects that produce/parse the values of the three headers, with zero dependency on any HTTP framework (no Servlet, Spring, Quarkus, Micronaut, Netty types). Framework integrations would be thin adapters on top: read the raw header string in, hand it to this model, get a value object back (or the reverse for building outgoing header values).

Scope:

• Use-As-Dictionary — parse/build the response header value (match patterns, options).
• Available-Dictionary — parse/build the request header value (dictionary hash).
• Dictionary-ID — parse/build the echoed identifier.
• URL pattern matching against WHATWG URL Pattern to decide dictionary applicability.
• Header values follow RFC 8941 Structured Field Values grammar — needs a small SFV parser/serializer.

Explicitly still out of scope: actual dictionary storage/cache lifecycle, cross-origin/CORS enforcement, HTTPS-only checks, and any framework wiring itself.

Why separate from #91

This is a meaningfully bigger surface than the dcz codec (SFV parsing + URL Pattern matching are their own subspecs), and it's a different kind of concern — no relation to the native zstd bindings. Likely belongs in its own module/artifact so the core zstd module stays dependency-free and scoped to FFM bindings.

Open questions

• Separate Maven module (e.g. dictionary-transport) vs. new artifact entirely outside this repo?
• Roll our own minimal SFV/URL-Pattern parsers, or is there a small dependency-free Java implementation worth vendoring?

[dfa1]

Naming decision (recorded so we don't re-litigate this): new module/artifact io.github.dfa1.zstd:dictionary-transport. Considered and rejected: zstd-http (implies HTTP framework/client coupling, which this explicitly avoids), rfc9842 (poor discoverability, ages badly if the spec gets errata/a successor), zstd-transport (ambiguous — reads as generic zstd data transport, not specifically HTTP dictionary negotiation). "dictionary-transport" mirrors the RFC's own title and describes purpose without pinning to a document number.

Full rationale: ADR 0016.

[dfa1]

Non-HTTP use case: internal microservice-to-microservice dictionary negotiation

Beyond browsers/CDNs, the negotiation headers (Available-Dictionary / Dictionary-ID) are also useful for services calling each other directly: a caller announces the dictionary hash it already has, and the dictionary version can rotate at the source without needing a synchronized redeploy of every service that hardcodes a dictionary id in config.

What's not needed for that use case is the Use-As-Dictionary + URL-pattern-matching half. That machinery solves a browser-specific problem — "which of the many resources fetched over time can serve as a dictionary for which future URL" — which doesn't apply when a service has one canonical dictionary per schema/message-type rather than many candidate resources to pick from via pattern matching.

Practical implication for this module's design: keep the header-value parsing/building (the negotiation primitive) usable independently of the URL-pattern-matching engine, so a microservice consumer can adopt just the former without pulling in the latter.

[dfa1]

Implemented in the same module as #91 (io.github.dfa1.zstd:zstd-rfc9842, per discussion — kept both layers of RFC 9842 support together rather than splitting into a separate module), commit 4150e9c.

• UseAsDictionary — the response header (match/match-dest/id/type), with matchesPath(String) and appliesToDestination(String) for applicability checks.
• AvailableDictionary — the request header (SHA-256 hash, byte sequence), with AvailableDictionary.of(ZstdDictionary) as the producer side; verified to agree with Rfc9842Frame's embedded hash for the same dictionary.
• DictionaryId — the request header (echoed id, string).
• Sfv — a minimal, hand-rolled RFC 8941 (Structured Field Values) parser/serializer, scoped to exactly what these three headers use (String, Token, Byte Sequence, Inner List of Strings, Dictionary member-keys). No Integers/Decimals/Booleans/Parameters — not needed here.

On the two open questions from the issue:

• Module placement: same module as the dcz codec, not a separate one — both are RFC 9842 support and share a release cadence.
• SFV/URL Pattern: rolled our own minimal parser rather than vendoring a dependency, matching this project's zero-transitive-dependency convention. URL Pattern matching is a deliberate subset: literal text plus * wildcards only (covers the RFC's own examples, /app/*/main.js and /product/*). WHATWG named groups (:name), optional groups ({...}), and regex groups are not interpreted specially — those characters match literally rather than being silently misinterpreted, and this is documented on UseAsDictionary.

All three header models parse and re-serialize the RFC's own example header values exactly, verified in tests. Storage/cache lifecycle, cross-origin/CORS checks, and HTTPS-only enforcement remain out of scope, as originally intended — this is the header value model only, with framework wiring left to whatever HTTP stack consumes it.