brotli

压缩

文件 OOM 修复已进入隔离候选，65 步专项通过，包含独立 C、JIT/AOT 新建与替换目标故障注入；共享门禁覆盖两份 DLL 和纯 VFS。包层修复了查询 OOM 后返回成功及清理覆盖首错。正式 release 尚未替换，旧程序的文件风险仍需注意。

标准 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 限制见页首。支持源与目标相同；不覆盖模式区分目标缺失与查询失败。这不是断电持久性承诺。

流与错误边界

输出无私有帧头、结束记录或 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 核心限额为零表示禁用对应限额；薄绑定零值使用默认限额。

模块选择须在第一次包含 XRT 单头文件之前完成，完整依赖见包清单的 artifact.xrtModules。 C 示例 extlibs/brotli/examples/basic.c 与 examples/extlibs/brotli_basic.xl 使用相同数据与黄金输出；教学范例为 examples/extlibs/brotli.xl。

验证记录

2026-09-27 的固定输入专项包含 60 项 Windows 检查：独立 GCC、C/xlang JIT/AOT、 23 个实际生成原型、回调取消与异常、文件原子性、双语范例、109 次分配故障。 Linux 独立 C 的 ASan/UBSan 与泄漏检查通过，不代表 Linux xlang JIT/AOT 已验收。

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