gzip

压缩

2026-10-31：修复打开态文件回滚的二次分配，正式native文件ABI的96组Windows旧8组残留降为0，首因、旧目标及内存平衡保持。新增C/XL文件事务范例验证UTF-8文件名、取消、业务异常和重试。Win78阶段76符合预期、Linux原生ASan/UBSan、各13条普通AOT、25条实际生成原型及错改返回负例、Python/zlib普通与优化模式139项互通过。首次IO首因原本正确，新增30场景只补覆盖；算法、公开ABI、主线和固定XRT未改。

默认门禁仍失败：Windows关闭态16组有2组临时文件残留，Linux同例0；两平台M2全局流对象AOT仍打印后退出1，不以函数内范例通过签收整包。详细范围、成本及现场见包内docs/io-file-audit-2026-10-31.md；官网只在隔离目录生成，不代表部署。

2026-10-29：桥接头的宿主模块污染与包含顺序已修，四种严格C组合两平台先红后绿，25个生成原型不变。新全局压缩器用例确认M2主线阻断：Windows/Linux JIT退出0，独立EXE均打印校验PASS后于退出期报状态错误、退出1。两平台完整门禁的旧C/算法/互通与双语JIT/AOT先通过，最后在该新边界报红；默认保留检查，当前不作完整发布签收，不移动全局对象绕开。下列旧通过记录不覆盖这一新增边界。

2026-10-26 当前 Windows/Linux 发布版的完整包门禁均通过：严格 C、Linux ASan/UBSan、139 项 zlib 互通、文件事务、语言核心与错误边界，以及双语范例独立 EXE 同输出。旧 Linux typed XLIR 与 AOT 缺符号问题在本次发布物中未复现；下方早期失败记录只反映当时的构建。不把本次检查外推为超大文件、并发压力、断电恢复或性能认证。

UTF-8 文本、二进制、增量流与事务文件压缩。直接复用宿主 XRT 的 gzip 编解码器和校验，无额外压缩 DLL。

API

函数	参数与返回
`compress(data)`	Buffer 或 string 输入，返回 Buffer；level=-1、mtime=0。
`decompress(data)`	Buffer 输入，返回 Buffer；maxRatio=1000。
`decompressText(data)`	解压后按字符串读取；任意二进制内容使用 decompress。
`compressFile(source, destination)`	level、mtime、overwrite=true、输入/输出限额、onProgress=null。
`decompressFile(source, destination)`	overwrite=true、输入/输出限额、maxRatio、onProgress=null。
`compressor()`	gzip.GzipCompressor；level、mtime、输入/输出限额。
`decompressor()`	gzip.GzipDecompressor；输入/输出限额、maxRatio。

maxInput 默认 268435456 字节，maxOutput 默认 536870912 字节，均须为正。 level 为 -1 或 0..9，-1 使用 XRT 默认级别；mtime 为 Unix 秒数 0..4294967295，默认零。普通字符串按 UTF-8 字节数编码，不把字符数量当作字节长度。

两个导出类均有 valid、inputBytes、outputBytes、finished 只读属性，以及 drain() as Buffer、finish() as Buffer。压缩器 update 接收 Buffer 或 string，解压器只接收 Buffer。

xlang 范例

import gzip

Buffer packed = gzip.compress("你好，gzip", level = 6)
assert gzip.decompressText(packed) == "你好，gzip"

gzip.GzipCompressor encoder = gzip.compressor()
encoder.update("left")
Buffer output = encoder.drain()
encoder.update("right")
output.append(encoder.finish())
assert gzip.decompressText(output) == "leftright"

以上保留语言应支持的顶层流对象写法；当前JIT可运行，AOT正文断言后仍命中M2退役错误，不用改成局部对象掩盖此问题。

drain 移交当前输出，不强制后端刷新；finish 只交付剩余字节，重复调用返回空 Buffer。已交付的 Buffer 独立持有。完成后不能继续 update，同一对象需要串行访问。

文件与回调

import gzip

func main(...) as int
    string work = dir.temp(prefix = "xlang-gzip-example-")
    string source = path.join(work, "输入.txt")
    string packed = path.join(work, "output.gz")
    string restored = path.join(work, "restored.txt")
    try
        assert file.writeText(source, "hello gzip")
        assert file.writeText(packed, "keep")
        bool cancelled = false
        try
            gzip.compressFile(source, packed, onProgress = func(int inputBytes,
                int totalBytes, int outputBytes) as bool
                return false
            end)
        catch CancelledError error
            cancelled = true
        end
        assert cancelled and file.readText(packed) == "keep"
        gzip.compressFile(source, packed)
        gzip.decompressFile(packed, restored)
        assert file.readText(restored) == "hello gzip"
    finally
        if file.exists(source) then assert file.delete(source) end
        if file.exists(packed) then assert file.delete(packed) end
        if file.exists(restored) then assert file.delete(restored) end
        assert dir.delete(work)
    end
    return 0
end

回调同步执行，参数均为字节数；总量未知时 totalBytes=0。返回 false 抛 CancelledError，回调抛出的异常保留原类型与消息。最终通知也可以取消；不能用 inputBytes==totalBytes 判定唯一的最终事件，输入读完之后仍可能有结束输出。

目标目录中建立独占临时文件，处理、最终通知、flush 和 close 全部成功后才替换目标。常规失败或取消保留原目标并清理临时文件；当前发布物的文件 OOM 专项证据与其他边界见页首。支持源和目标为同一路径；不覆盖模式区分目标缺失与查询失败。 overwrite=false 禁止覆盖；即使目标在预检后出现，最终提交仍拒绝替换。源或目标路径含 NUL 时抛 ValueError，不会静默操作前缀文件。这不承诺断电持久性或多写者事务隔离。

格式、错误与资源边界

支持合法空内容、串联成员、可选头字段和头校验；目前没有读取头元数据的 API。
CRC/ISIZE、保留标志错误、截断与尾部垃圾均拒绝；CRC 不是加密认证。
格式和文件错误为 IOError，限额为 RangeError，无效 level 或非正限额为 ValueError，错误状态为 RuntimeError，分配失败为 MemoryError。不要统一只捕获 CompressionError。
maxRatio 为 1..4294967295，按累计输出/已提交压缩输入检查，分块会影响检查时点。 maxOutput 为硬输出限额；这些选项不是 CPU 截止时间、总内存上限或沙箱。
输入参数错误可纠正重试；编解码、限额或 writer 失败后必须新建对象。
借用 reader/writer 的裸流失败前可能已有部分输出；只有文件便捷接口提供失败原子性。

C 接口与双语范例

核心头 include/xrt_gzip.h 提供 OptionsInit、ErrorInit、Compress/Decompress、 Compressor/Decompressor 对象与 CompressStream/DecompressStream。首次包含 XRT 完整头前完成模块选择，完整清单见 artifact.xrtModules；只链接一份 XRT/xruntime。

C 结果由 xrtBufferDestroy 释放；Finish 不移交 Buffer，DrainBuffer 可多次移交， TakeBuffer 仅在完成后移交一次。流函数借用 Reader/Writer，不关闭它们。 C 进度结构另有 TOTAL_KNOWN、FINAL 标志，支持任意 user 指针。

C 配置 level=-1..9、strategy 为 XRT DEFAULT..FIXED。输入、输出与倍率限制为零时关闭对应限制； OptionsInit 将 tLimits 中不适用的归档/文档字段清零；显式设置这些字段或 iFlags 会报参数错误，不会静默忽略。薄绑定头 include/gzip_native.h 的 25 个实际生成原型接受GCC比对，并以故意错改返回类型验证拒绝。 native文件接口沿用XRT callable；普通C进度由核心流接口提供，两者不是同一ABI。

extlibs/gzip/examples/basic.c 与 examples/extlibs/gzip_basic.xl 使用相同输入与黄金输出；C 范例可从发布目录直接运行 ./xl run extlibs/gzip/examples/basic.c。单文件路径仅包含所用的包实现，正式构建仍分离编译。examples/extlibs/gzip.xl 覆盖增量、mtime、串联成员和文件回调；文件段使用独占临时目录，其 JIT 与独立 EXE 在当前双平台门禁均完整运行并输出 gzip example: PASS。

验证范围

2026-09-27：Windows 固定快照专项 34 项通过，含 C/xlang JIT/AOT、22 个生成原型、 139 项 Python/zlib 双向验证、9 个分配故障点、UTF-8 路径、取消和异常、同路径替换及原目标保留。 WSL Linux C 路径通过相同互通测试及 ASan/UBSan/泄漏检查；包内 test/file_ops.xl 在 Windows/Linux 通过 UTF-8 文件往返、取消与失败目标保护。

可重复门禁为 tools/check_extlib_gzip.ps1 和 tools/check_extlib_gzip.sh。 2026-10-26 Linux 门禁另构建运行核心、进度、文件、错误和 C/XLang 范例独立 EXE，并核对黄金输出；超大文件、并发压力、性能基准和断电恢复尚未验收。不把有日期、有范围的通过记录当作所有平台生产认证。

2026-10-19：C 范例单文件直跑、独立构建和包运行器输出一致；Linux ASan/UBSan、139 项 zlib 互通、文件事务及 C/XLang 范例对照通过。当时共享 XLIR 阻断仍在，整包尚未签收；当前状态以上方最新复核为准。