brotli

压缩

2026-10-29：新增普通 C 文件接口 xrtBrotliCompressFile/DecompressFile，回调为同步 xrtprogressproc + user，不需 xvalue 或 xruntime；XLang 复用同一文件事务，用法/ABI不变。新 C 功能、八组打开态双故障、新双语范例与 JIT/AOT 两平台通过。Windows 已关闭事务回滚再遇 OOM 留临时文件、原目标保持，Linux 同组16场景通过。本项 RFS 与 M2 全局退役独立，完整发布门禁仍红。

2026-10-29：修复桥接头启用宿主未选择的XRT VALUE模块，以及桥接头先于核心头时缺少buffer/reader/writer类型的问题；四种包含组合加入严格C门禁，物理ABI不变。新增顶层真实流对象用例的JIT通过，但Windows独立EXE在往返验证完成后，于退出期报运行时状态错误。默认完整门禁保留红项，须由主线处理native-backed class的模块退役边界，本包暂不完整签收；不把顶层对象挪进main换绿灯。

当日较早的桥接头审查中，Windows完整80项仅新增顶层AOT退出项未达到预期，其余正常及拒绝负例符合预期。Linux原生文件系统C sanitizer、四种头组合、旧C/XLang JIT/AOT与双语输出均过，同一顶层EXE在退出时报错；仅创建一个全局对象的最小源也在两平台复现。后续普通C文件审查另补RFS，当前状态以前述99阶段记录为准。

2026-10-27 使用当前源码重建 Windows 发布版后，完整包级门禁通过严格 C、分配故障、外部 Brotli 流夹具、生成原型、语言 JIT/AOT、C/XLang 范例同输出，以及事务文件分配故障的 C/JIT/AOT。xl.dll/xlc.dll 的公开 C 源码执行宿主另有既往专项验证；本次未重跑 Linux、32 位、TSan 或长时压力。

标准 Brotli 字节流、UTF-8 文本、增量处理与事务文件。内嵌 Brotli 1.1.0 后端，复用宿主 XRT/xruntime，无需安装 Brotli 动态库。

API

函数	参数与返回
`version()`	返回后端版本字符串。
`compress(data)`	Buffer 或 string 输入，返回 Buffer。quality=11，window=22，mode=0。
`decompress(data)`	Buffer 输入，返回 Buffer；maxRatio=1000。
`decompressText(data)`	解压并读取字符串；任意二进制数据使用 decompress。
`compressFile(source, destination)`	支持质量、窗口、模式、overwrite=true、限额和 onProgress=null。
`decompressFile(source, destination)`	支持 overwrite=true、限额、解压比和 onProgress=null。
`compressor()`	BrotliCompressor；参数与 compress 的压缩配置及限额相同。
`decompressor()`	BrotliDecompressor；参数为输入、输出与解压比限额。

maxInput 默认 268435456 字节，maxOutput 默认 536870912 字节，均须为正。 quality 范围 0..11，window 范围 10..24；模式为 GENERIC=0、TEXT=1、FONT=2，模块提供 BROTLI_MODE_* 和质量、窗口上下限常量。Q11 并非所有实时场景的合适配置。

压缩器支持 update(Buffer|string)、drain() as Buffer、finish() as bool，只读属性为 valid、inputBytes、outputBytes。解压器 update 只接收 Buffer，另有 finished、members 属性。

xlang 范例

import brotli

Buffer packed = brotli.compress("你好，Brotli", quality = 4)
assert brotli.decompressText(packed) == "你好，Brotli"

auto encoder = brotli.compressor(quality = 4)
Buffer output = Buffer()
encoder.update("part one")
output.append(encoder.drain())
encoder.update("part two")
encoder.finish()
output.append(encoder.drain())

文件与回调

brotli.compressFile("input.txt", "output.br", quality = 4,
    onProgress = func(int inputBytes, int totalBytes, int outputBytes) as bool
        println(inputBytes, "/", totalBytes)
        return true
    end)

回调同步执行，三个参数均为字节数；返回 false 抛 CancelledError，抛出的异常保留原类型与消息。无法查询总长度时 totalBytes=0。文件在目标目录建立独占临时文件，成功关闭后再替换目标；常规失败或取消保留原目标并清理临时文件，冻结运行库的晚期 OOM 限制见页首。支持源与目标相同；含 NUL 的源/目标路径报 ValueError，不访问前缀路径。不覆盖模式区分目标缺失与查询失败。这不是断电持久性承诺。

流与错误边界

输出无私有帧头、结束记录或 CRC。Brotli 不提供内容认证；有些翻位仍会形成合法数据。
空明文有效，空压缩输入无效。截断或识别出的格式错误为 IOError，限额为 RangeError，非法参数为 ValueError，分配失败为 MemoryError，结束后 update 为 RuntimeError。
drain 转移已积累的输出，不强制后端刷新，也不重置累计限额。finish 可重复调用。
本解压器可以连续读取多个独立流；不能假定所有第三方解码器都支持这种拼接。
maxRatio 为 1..4294967295，在完整流边界检查；硬输出限额始终生效。这些限制不等于 CPU 截止时间或后端峰值堆内存限制。
裸 reader/writer 失败前可能已有部分输出；只有文件便捷接口提供目标替换的失败原子性。
同一对象须串行访问，不允许 update 过程中重入；不同对象可以独立使用。

C API 与对照范例

核心头为 include/xrt_brotli.h，薄绑定 ABI 为 include/brotli_native.h。 xrtBrotliOptionsInit 初始化配置，xrtBrotliCompress/Decompress 返回拥有型 xbuffer，由调用方 xrtBufferDestroy。配置长度/版本必须匹配、限额保留字段必须为零，错误配置在读取前拒绝。C 核心只使用输入、输出和解压倍率限额；OptionsInit 将无关的单项、条目、节点及深度字段清零，显式设置这些字段或 iFlags 会报参数错误。C 核心有效限额为零表示禁用对应限额；薄绑定零值使用默认限额。

模块选择须在第一次包含 XRT 单头文件之前完成，完整依赖见包清单的 artifact.xrtModules。 C 示例 extlibs/brotli/examples/basic.c 与 examples/extlibs/brotli_basic.xl 使用相同数据与黄金输出；教学范例为 examples/extlibs/brotli.xl。其文件段使用独占系统临时目录并在异常路径清理，不写入固定的构建目录。

验证记录

新增 examples/files.xl 与 files_c.c 用同一四字节二进制验证往返、进度与取消目标保留，匹配三行黄金输出；普通 C 单独链接 XRT/核心/文件层/后端，不含语言桥接。NULL options 使用默认配置，NULL 进度不报告；失败从 xrtGetError 读取，回调设置的原始错误优先保留。XLang 仍有 xcall 整数装箱/调用帧与检查成本，不称整条链零开销。

本轮 Windows 默认99阶段，95正例和两项预期私有访问拒绝符合要求，关闭态回滚及全局AOT退役两项失败，152项指纹不变。新 C 文件逐点故障118个，Linux104个，旧内存116个故障点仍通过。Linux 包含纯XRT宿主、ASan/UBSan、八组打开态、16组关闭态及新旧双语JIT/AOT，最终在既有M2处失败。冻结XRT与编译器未更换，详见包内当前README和阻断报告。

2026-09-27 的固定输入专项包含 60 项 Windows 检查：独立 GCC、C/xlang JIT/AOT、 23 个实际生成原型、回调取消与异常、文件原子性、双语范例、109 次分配故障。 Linux 联合门禁同次通过 C ASan/UBSan 与泄漏检查、两组 XLang JIT 用例及 C/XLang 基础范例逐字节黄金输出对照；不代表 Linux AOT 已验收。

2026-10-24 当时 Windows 发布版通过 70 项包级检查，包括中央 XLang 用例 JIT/AOT、文件故障夹具 JIT/AOT 和综合范例；Linux C ASan/UBSan、泄漏检查及双语门禁通过。此前 AOT 缺符号属于旧发布物记录。

2026-10-26 当前 Windows 门禁报告 passed，73 项检查、23 个生成原型，严格 C、分配故障、C/XLang JIT/AOT 和双语范例均通过。Linux C ASan/UBSan、六条独立 XLang EXE AOT、C 文件分配故障 AOT 与输出对照通过；默认构建目录按运行隔离。32 位/ARM、TSan、长期压力和性能基准尚未验收。

门禁为 tools/check_extlib_brotli.ps1 和 tools/check_extlib_brotli.sh。尚未覆盖 Windows ARM、全部外部解码器和生产负载性能。后端必须保留 CLEANUP_ON_OOM 配置，不能在内存不足时退出宿主进程。