From c17d9a91474731576f0283ae244bd1726e225d70 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 17:06:08 +0000 Subject: [PATCH] std/brotli: update the docs and changelog for the finished port Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UZ978Fjdsyig4v3wYAZRg5 --- doc/changelog.md | 5 ++++- std/brotli/README.md | 24 ++++++++++++++++-------- std/brotli/encode_brotli.wuffs | 7 +++---- 3 files changed, 23 insertions(+), 13 deletions(-) diff --git a/doc/changelog.md b/doc/changelog.md index a05bb1b3..0cb162f3 100644 --- a/doc/changelog.md +++ b/doc/changelog.md @@ -15,10 +15,12 @@ The LICENSE has changed from a single license (Apache 2) to a dual license - Added `base.rect_ie_i32`. - Added `compact_retaining` and `dst_history_retain_length`. - Added `example/toy-aux-image`. +- Added `example/brcat`. - Added `example/mzcat`. - Added `get_quirk(key: u32) u64`. - Added `std/brotli`. -- Added a `std/brotli` encoder (qualities 0 and 1). +- Added a `std/brotli` encoder (qualities 0 to 11, byte-exact with libbrotlienc + v1.2.1). - Added `std/crc64`. - Added `std/etc2`. - Added `std/handsum`. @@ -28,6 +30,7 @@ The LICENSE has changed from a single license (Apache 2) to a dual license - Added `std/netpbm`. - Added `std/qoi`. - Added `std/sha256`. +- Added `std/softfloat`. - Added `std/thumbhash`. - Added `std/vp8`. - Added `std/webp`. diff --git a/std/brotli/README.md b/std/brotli/README.md index 06bee128..26a78475 100644 --- a/std/brotli/README.md +++ b/std/brotli/README.md @@ -6,8 +6,9 @@ and a built-in static dictionary. It is specified by [RFC 7932](https://www.rfc-editor.org/rfc/rfc7932). The reference implementation is at [github.com/google/brotli](https://github.com/google/brotli). -This package (`std/brotli`) is a decoder. It aims for exact parity with the -reference implementation's decoder (libbrotlidec), version v1.2.1, and in +This package (`std/brotli`) has a decoder and an encoder (see the "Encoder" +section below). The decoder aims for exact parity with the reference +implementation's decoder (libbrotlidec), version v1.2.1, and in particular its `c/dec/decode.c` file: the same output for valid input and the same verdict (and the same error code, mapped as below) for invalid input. The Wuffs code mirrors the C code's logic and validation checks, function by @@ -185,8 +186,6 @@ invariants for memory safety but Wuffs requires explicit bounds checks. ## TODO -- Metadata callbacks (metadata blocks are currently skipped). See the - "Metadata Blocks" section below. - More fast paths, for example for dictionary words, for copies that wrap around the ring buffer and for block switches. @@ -1264,7 +1263,16 @@ Differences from the C code: libbrotlidec can report metadata blocks' contents through callbacks (`BrotliDecoderSetMetadataCallbacks`). Wuffs code cannot call back into its -caller, so there is no equivalent: metadata blocks are skipped (validated and -consumed but not reported), exactly as libbrotlidec does without callbacks, -so the decoded output is the same. A future quirk could expose metadata -blocks, e.g. by suspending with a status when one starts. +caller. By default, metadata blocks are skipped (validated and consumed but +not reported), exactly as libbrotlidec does without callbacks. + +With the `QUIRK_REPORT_METADATA` quirk, the decoder reports them instead. At +each metadata block (after every previously decoded byte has been written to +`dst`), `transform_io` returns `base."@metadata reported"`, and +`metadata_length()` returns the block's length, which can be zero (the C +code's start callback's `size`). The next `metadata_length()` bytes that +`transform_io` writes to `dst` (over one or more subsequent calls) are the +block's contents (the C code's chunk callbacks' data). Decoded bytes follow as +usual. The decoded output (the bytes outside of metadata blocks) is the same +with or without the quirk. `test_mimic_brotli_decode_metadata` checks that the +lengths and contents match libbrotlidec's callbacks. diff --git a/std/brotli/encode_brotli.wuffs b/std/brotli/encode_brotli.wuffs index d4bd962f..7c2117da 100644 --- a/std/brotli/encode_brotli.wuffs +++ b/std/brotli/encode_brotli.wuffs @@ -24,10 +24,9 @@ // EncodeData, see encode_data.wuffs, with Zopfli and BrotliBuildMetaBlock at // qualities 10 and 11) are implemented. See README.md for the API, including // how the C code's FLUSH and EMIT_METADATA operations map to the -// request_flush and request_emit_metadata methods. -// -// TODO: large-window brotli at qualities 3 and above and custom (prepared or -// shared) dictionaries. +// request_flush and request_emit_metadata methods. Large-window brotli and raw +// (prepared) dictionaries are also implemented. Serialized (shared) +// dictionaries are rejected, like the default (non-experimental) C build. use "std/softfloat"