# 设计:xz 压缩与统一压缩档位 ## 依赖选择 采用 `github.com/ulikunitz/xz`(纯 Go、BSD-3、读写齐全)。 | 方案 | 结论 | |---|---| | `klauspost/compress` | 不支持 xz | | cgo 绑定 liblzma | 破坏交叉编译与"纯 Go 构建"约束 | | 外部 `xz` 进程 | 额外运行时依赖、错误处理与安全面变大 | | `ulikunitz/xz` | 唯一可行,本机 module cache 已有 v0.5.17 | ## 档位模型:1–9 是语义档位,不是原生级别 zstd 库没有连续 1–22 级别,只有 4 个 `EncoderLevel`;xz 库没有 preset 参数。因此 1–9 被定义为**跨格式语义档位**,各格式显式映射,9 表示该格式最强: | level | gzip (flate) | zstd | xz 字典 | |---|---|---|---| | 1 | 1 | SpeedFastest | 1 MiB | | 2 | 2 | SpeedFastest | 2 MiB | | 3 | 3 | SpeedDefault | 4 MiB | | 4 | 4 | SpeedDefault | 4 MiB | | 5 | 5 | SpeedDefault | 8 MiB | | 6 | 6 | SpeedBetterCompression | 8 MiB | | 7 | 7 | SpeedBetterCompression | 16 MiB | | 8 | 8 | SpeedBetterCompression | 32 MiB | | 9 | 9 | SpeedBestCompression | 64 MiB | 默认 3:gzip 与现行 `NewWriterLevel(3)` 一致;zstd 的 `SpeedDefault` 与现行代码一致;xz 无历史行为。 xz 映射只设置 `WriterConfig.DictCap`,其余使用库默认(CRC64、hash-table matcher)。这与 `xz -N` 的字典表一致,但不比特级复刻 xz-utils 的 preset(matcher 不同,压缩率略低),文档需说明产物仍是标准 xz。 ## xz 读取的字典上限 `ulikunitz/xz` 的 reader 默认 `DictCap = 8 MiB`;读取 level 9(64 MiB 字典)的流会失败。 **决定:xz reader 固定使用 64 MiB 上限,而不是按当前 level 推导。** 原因: 1. 本工具可能产出的最大字典就是 64 MiB; 2. `--force-resume` 允许改配置续跑。若按当前 level 推导,从 9 降到 1 后读取旧分片会因上限不足而失败; 3. 读侧只出现在续跑与清单补录路径,不在主写入热路径,一次 64 MiB 缓冲可接受。 ## checkpoint 会产生多 stream `Writer.Checkpoint()` 关闭当前压缩流、记录偏移,再在偏移处开启新流。gzip 多 member、zstd 多 frame、xz 多 stream 都是合法拼接;`ulikunitz/xz` 的 `SingleStream` 默认 `false`,会解码全部 stream,`xz -dc` 同样如此。 **要求:必须有测试覆盖"checkpoint 后的 xz 分片能被完整读回",防止 `--purge` 场景下静默丢行。** ## 指纹兼容性 现有 `state.json` 的指纹里没有 `compress_level`。无条件加字段会让本功能上线前启动的任务全部续跑失败。 **决定:仅当 `compress != none && level != 3` 时把 `compress_level` 加入指纹。** - 老任务(无键)+ 新进程默认 3 → 哈希输入逐字节不变,无缝续跑; - 非默认档位才出现新键,`DiffFields` 会显示 `compress_level: "5" -> (absent)` 并拒绝; - 从 5 改回 3 也因键消失被识别。 `compress == none` 时档位不参与哈希,因为不影响产物。 ## none 与 level 的组合 `compress == none && level != 3` → 配置错误;`level == 3`(默认值)静默接受。这样既能拒绝无意义组合,又不会惩罚"只是没传"的用户。 ## 崩溃恢复识别 `.xz` `manifest.go` 的 `shardNameRE` 目前只列 `\.gz|\.zst`,且 `Adopt` 用 `mt[3] != comp.Ext` 过滤。不加 `\.xz` 时,崩溃在 rename 与 manifest 追加之间的 xz 分片不会被计入 `maxSeq`,续跑会重算序号并覆盖已封分片。 **决定:正则与扩展名判断都识别 `.xz`,并补一条针对性测试。** ## Compressor 结构与扩展名收敛 `Compressor` 从 `{Name, Ext}` 扩展为 `{Name, Ext, Level}`,构造签名改为 `NewCompressor(name string, level int)`。gzip/zstd/xz 都从同一个对象取 `Ext`。 `app/dryrun.go` 的 `compressExt()` 是第二份扩展名表,改成复用 `Compressor.Ext`,避免新增格式时漏改一处。 ## 被否决的方案 - **把 zstd 暴露为 1–22**:与 gzip/xz 的 1–9 不一致,校验和文档复杂度上升;zstd `best` 已足够,空间优先交给 xz。 - **按当前 level 推导 reader 字典**:与 `--force-resume` 降级续跑冲突。 - **xz 使用默认 8 MiB 字典**:level 3 与 xz preset 3 不一致,且高档位无法表达。 - **无条件把档位写入指纹**:打断存量任务续跑。