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

86 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 设计: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 不一致,且高档位无法表达。
- **无条件把档位写入指纹**:打断存量任务续跑。