Files
archer/openspec/changes/archive/2026-11-06-add-compress-level-and-xz/design.md
T
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

4.2 KiB
Raw Blame History

设计: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 不一致,且高档位无法表达。
  • 无条件把档位写入指纹:打断存量任务续跑。