# Phase 1: WAL 子系统开发方案 基于 `docs/design.md` §3.2 设计文档。 ## 目标 实现完整的 WAL（预写日志）子系统，使其能够支撑单 key autocommit 的写入、崩溃恢复和读可见性语义。 ## 开发阶段总览 ``` Phase 1A: 项目骨架 + WAL 编码格式层 Phase 1B: WAL 文件写入 + Segment 管理 Phase 1C: WAL Writer（Group Commit） Phase 1D: WAL Recovery Phase 1E: MemTable（SkipList + Arena） Phase 1F: 写入路径集成（WAL → MemTable 完整流水线） Phase 1G: 读路径 + 嵌入式 API Phase 1H: MANIFEST + 文件管理 Phase 1I: 集成测试 + Benchmark ``` --- ## Phase 1A: 项目骨架 + WAL 编码格式层 **目标**: 建立 Go 项目结构，实现 WAL 物理格式（Block / Physical Record / WAL Batch / Entry）的编码与解码。 ### 任务 #### 1A-1: 项目初始化 - `go.mod` 初始化（模块名 `github.com/dailz/go-kv`） - 目录结构： ``` go-kv/ ├── go.mod ├── wal/ # WAL 子系统 │ ├── wal.go # 公共类型、常量、配置 │ ├── record.go # Physical Record 编解码 │ ├── batch.go # WAL Batch 编解码 │ ├── entry.go # Entry 编解码 │ ├── header.go # WAL File Header 编解码 │ └── wal_test.go ├── memtable/ # MemTable（Phase 1E） ├── config/ # 全局配置 ├── errors.go # 公共错误类型 └── db.go # DB 入口 ``` - `.golangci.yml` 配置（参考 golang-lint skill） #### 1A-2: 公共错误类型 (`errors.go`) - `ErrCommitUnknown` — maybe committed 语义 - `ErrWriteStopped` — 引擎 write-stopped - `ErrSequenceExhausted` — sequence 耗尽 - `ErrWALCorrupted` — WAL 损坏 - `ErrInvalidConfig` — 配置不合法 #### 1A-3: WAL 常量与配置 (`wal/wal.go`) ```go const ( WalMagic uint32 = 0x... // 待定 WalFormatVersion uint16 = 1 WalFileHeaderSize = 32 WalBlockSize = 32 * 1024 // 32KB PhysicalRecordHeaderSize = 7 WalBatchHeaderSize = 18 MaxWalBatchEntryCount = 10_000 MaxWalBatchEntriesSize = 4 * 1024 * 1024 // 4MB MaxWalKeyBytes = 4 * 1024 // 4KB MaxWalInlineValueBytes = 4 * 1024 // 4KB MaxWalVarintBytes = 5 DefaultMaxWalSegmentSize = 64 * 1024 * 1024 // 64MB DefaultImmutableCount = 2 ) // Fragment types const ( RecInvalid uint8 = 0 RecFull uint8 = 1 RecFirst uint8 = 2 RecMiddle uint8 = 3 RecLast uint8 = 4 ) // OpType const ( OpInvalid uint8 = 0 OpPut uint8 = 1 OpDelete uint8 = 2 ) // ValueKind const ( VKNone uint8 = 0 VKInline uint8 = 1 VKValueLogPointer uint8 = 2 ) ``` WAL 配置结构体： ```go type WalConfig struct { MaxSegmentSize uint64 // default 64MB BlockSize uint32 // default 32KB SyncMode SyncMode // Always/Periodic/Never PeriodicSyncMs uint32 // Periodic 模式的 fsync 间隔 MaxBatchEntries uint32 // default 10000 MaxBatchSize uint32 // default 4MB MaxKeyBytes uint32 // default 4KB MaxInlineValue uint32 // default 4KB } ``` 配置校验函数 — 必须在 DB 打开时验证不变量： ```text maxWalSegmentPayload >= maxEncodedWalBatchSize + worstCasePhysicalRecordOverhead + worstCaseBlockPadding ``` #### 1A-4: WAL File Header 编解码 (`wal/header.go`) - `WalFileHeader` 结构体：magic, formatVersion, headerSize, blockSize, segmentID, startSequence, headerCRC - `EncodeWalHeader(h *WalFileHeader) [WalFileHeaderSize]byte` - `DecodeWalHeader(data []byte) (*WalFileHeader, error)` — 校验 magic、formatVersion、headerSize、headerCRC - CRC 覆盖范围：magic 到 startSequence，不包含 headerCRC 自身 - 字节序：little-endian #### 1A-5: Physical Record 编解码 (`wal/record.go`) - `PhysicalRecord` 结构体：CRC, Length, Type, Payload - `EncodePhysicalRecord(recType uint8, payload []byte) []byte` — 返回编码后的 bytes - `DecodePhysicalRecord(data []byte) (*PhysicalRecord, error)` — CRC 校验 - Block 边界处理辅助函数： - `PaddingNeeded(blockOffset, blockSize uint32) int` — 剩余空间 <= 7 时返回需要 padding 的字节数 - `CanFitRecord(blockOffset, blockSize, payloadLen uint32) bool` #### 1A-6: WAL Batch 编解码 (`wal/batch.go`) - `WalBatch` 结构体：Flags, BaseSequence, EntryCount, EntriesSize, Entries - `EncodeWalBatch(batch *WalBatch) ([]byte, error)` — 编码 Batch Header + Entries - `DecodeWalBatch(data []byte) (*WalBatch, error)` — 校验 flags、entryCount、entriesSize - Batch 分片：`SplitIntoRecords(encodedBatch []byte, blockSize uint32) [][]byte` — 将编码后的 Batch 拆分为 Physical Record payloads - Batch 重组：`FragmentCollector` — 收集 fragments 并重组成完整 Batch FragmentCollector 状态机： ``` Idle → 收到 Full → 重放 batch → Idle Idle → 收到 First → CollectingFragments CollectingFragments → 收到 Middle → 追加 CollectingFragments → 收到 Last → 重组 → 重放 → Idle ``` #### 1A-7: Entry 编解码 (`wal/entry.go`) - `WalEntry` 结构体：OpType, ValueKind, Key, Value - `EncodeEntry(e *WalEntry) ([]byte, error)` — 编码为 varint 长度 + bytes - `DecodeEntry(data []byte) (*WalEntry, int, error)` — 解码，返回 entry 和 consumed bytes - 校验规则： - keyLen > 0 && keyLen <= maxKeyBytes - Put 要求 valueKind ∈ {Inline, ValueLogPointer} - Put + Inline: valLen <= maxInlineValueBytes (允许 valLen = 0) - Put + ValueLogPointer: valLen > 0 - Delete: valueKind == None, valLen == 0 #### 1A-8: WAL Batch 资源校验 - `ValidateBatchLimits(entries []*WalEntry) error` — 在 sequence 分配之前检查： - entryCount <= maxBatchEntries - 每个 keyLen <= maxKeyBytes - 每个 inline valLen <= maxInlineValueBytes - entries 编码后总大小 <= maxBatchSize - 单个 Batch 的最坏 Physical Record overhead 不超过 segment capacity ### 验收标准 - [ ] 所有编解码函数有 table-driven test - [ ] CRC 校验正确 - [ ] Fragment 分片/重组 round-trip 正确 - [ ] 资源限制校验覆盖所有边界条件 - [ ] `go vet` / `golangci-lint` 通过 --- ## Phase 1B: WAL 文件写入 + Segment 管理 **目标**: 实现 WAL segment 文件的写入、轮转和持久化协议。 ### 任务 #### 1B-1: Segment 文件格式写入器 (`wal/segment_writer.go`) - `SegmentWriter` — 封装 WAL segment 文件的追加写入 - 状态：当前 segment fd、当前 block offset、当前 segmentID、payload written bytes - `NewSegmentWriter(dir string, segmentID uint64, startSequence uint64, cfg *WalConfig) (*SegmentWriter, error)` - 创建 segment-N.wal.tmp - 写入 WAL File Header - fsync - rename → segment-N.wal - fsync directory - 进入 durable-ready 状态 - `AppendBatch(batch *WalBatch) error` — 编码 batch → split into records → 按 block 边界写入 - `Sync() error` — fsync 当前 segment 文件 - `Close() error` - `RemainingPayload() uint64` — 当前 segment 剩余可用 payload 空间 - `CurrentOffset() uint64` — 当前写入偏移 #### 1B-2: Block 写入缓冲 (`wal/block_writer.go`) - 管理 32KB block 的填充和 padding - `BlockWriter` — 封装 block 内的 Physical Record 写入 - 自动处理 block 边界：剩余 <= 7 bytes 时 padding - 跨 block 的 batch fragment 自动拆分 #### 1B-3: Segment 轮转逻辑 - 写入 batch 前检查 `RemainingPayload()` 是否足够容纳整个 batch - 不足时：当前 segment 完成（在 batch 边界）、创建新 segment - 新 segment 的 durable-ready 协议： 1. create segment-N+1.wal.tmp 2. write WAL File Header（含 startSequence = nextExpectedSequence） 3. fsync segment-N+1.wal.tmp 4. rename → segment-N+1.wal 5. fsync WAL directory 6. segment-N+1 进入 durable-ready - 旧的 active segment 密封 #### 1B-4: CURRENT 文件管理 - best-effort 更新 CURRENT 文件 - temp + rename 模式 - 更新失败不影响已 durable-ready 的 segment #### 1B-5: WAL 目录管理工具 - 扫描 WAL 目录中的 segment 文件 - 按 segmentID 排序 - 解析文件名中的 segmentID - 文件名格式：`segment-{id}.wal` ### 验收标准 - [ ] Segment 创建遵循 durable-ready 协议 - [ ] Batch 不跨 segment - [ ] Block padding 正确 - [ ] Segment 轮转在 batch 边界发生 - [ ] 多 segment 写入后，每个 segment 的 header 可以正确解析 - [ ] 测试覆盖：正常写入、跨 block batch、segment 轮转触发 --- ## Phase 1C: WAL Writer（Group Commit） **目标**: 实现完整的 WAL 写入路径，包括 group commit、sequence 管理、fsync 策略和错误分类。 ### 任务 #### 1C-1: Sequence 管理器 (`wal/sequence.go`) - `SequenceManager` — 管理 WAL 物理 mutation sequence - `atomic.Uint64` 存储 nextSequence、publishedSequence、durableSequence - `AllocateBatch(count uint32) (baseSequence uint64, err error)` — checked arithmetic 检查溢出 - `Publish(sequence uint64)` — release 语义 store publishedSequence - `MarkDurable(snapshot SegmentEndState)` — 推进 durableSequence - `Published() uint64` — load publishedSequence - `Durable() uint64` — load durableSequence #### 1C-2: Commit Queue (`wal/commit_queue.go`) - 写请求进入的队列 - 每个写请求关联一个 `*sync.Cond` 或 channel 用于等待/唤醒 - `CommitBatch` 结构体：entries、完成 channel、错误结果、baseSequence #### 1C-3: WAL Writer 主循环 (`wal/writer.go`) 核心写入循环： ``` loop: 1. 从 commit queue 收集一批写入 2. 等待触发条件（500µs 或 32KB）或 queue 非空 3. 组装 WAL Batch 4. 校验 batch 资源限制 5. 预留 MemTable Arena 容量 6. 分配 sequence（baseSequence） 7. 在私有缓冲区编码 WAL Batch 8. 检查/触发 segment 轮转 9. Append WAL Batch 到 segment 文件 10. 写入 MemTable（pending/unpublished） 11. fsync（Always 模式） 12. 发布 publishedSequence 13. 唤醒所有等待的调用方 ``` 错误分类逻辑： - 步骤 4-7 失败（未分配 sequence）→ 普通错误，可继续 - 步骤 6 后失败（sequence 已分配）→ write-stopped - 步骤 9 后失败（WAL write 已尝试）→ ErrCommitUnknown + write-stopped - 步骤 11 失败（fsync）→ ErrCommitUnknown + write-stopped #### 1C-4: Fsync 策略实现 (`wal/fsync.go`) - `SyncMode` 类型：Always / Periodic / Never - `Always`: 每次 batch fsync 后再 publish - `Periodic`: 后台 goroutine 定期 fsync，write 成功即可 publish - `Never`: 不主动 fsync - `Periodic` 的 fsync worker： - 快照当前 append high-water mark: (segmentID, endOffset, endSequence) - fsync 成功后按连续 batch 推进 durableSequence - fsync 失败 → write-stopped #### 1C-5: durableSequence 推进逻辑 - 每个 batch 记录 `(segmentID, endOffset, endSequence)` - fsync snapshot 后只推进满足条件的最大连续 batch - 跨 segment 推进需要 segment 已 durable-ready #### 1C-6: Write-Stopped 状态管理 - `atomic.Bool` 存储 writeStopped - 进入 write-stopped 后拒绝新写入 - 已存在的 MemTable / Immutable MemTable 可继续后台处理 - 提供 `IsWriteStopped() bool` 查询接口 ### 验收标准 - [ ] Group commit 正确合并多个写请求 - [ ] 双触发（时间/大小）工作正常 - [ ] Sequence 分配无溢出 - [ ] Always 模式下 publish 在 fsync 之后 - [ ] 错误分类准确（普通错误 / write-stopped / ErrCommitUnknown） - [ ] 并发写入正确（多 goroutine 同时 Put） - [ ] Write-stopped 后新写入被拒绝 --- ## Phase 1D: WAL Recovery **目标**: 实现 WAL 崩溃恢复，包括 segment 扫描、fragment 重组、batch 校验和尾部截断。 ### 任务 #### 1D-1: Segment 扫描器 (`wal/scanner.go`) - 从 WAL 目录扫描 segment 文件 - 按 segmentID 排序 - 从 MANIFEST 指定的 recoverySegmentID 开始 - 过滤掉 segmentID < recoverySegmentID 的旧 segment - 校验连续性：segmentID 和 startSequence 都必须连续 #### 1D-2: Physical Record 解析器 (`wal/record_parser.go`) - Block 级别的顺序解析 - 处理 padding（全 0 校验） - Physical Record header 解析和 CRC 校验 - 错误分类：尾部 vs 中间损坏 #### 1D-3: Fragment 重组器 (`wal/fragment_collector.go`) - 实现 Idle / CollectingFragments 状态机 - 收集 First / Middle / Last fragments - Buffer 大小限制（Batch Header 长度 + entriesSize 上限） - Fragment 顺序合法性检查 #### 1D-4: Batch 校验与重放 (`wal/recovery.go`) - Batch Header 校验：flags、entryCount、entriesSize - Batch sequence 连续性：batch.baseSequence == expectedSequence - Entry 逐条校验：opType、valueKind、keyLen、valLen - 重放回调：对每个合法 entry 调用 replay 函数 - Sequence 推进：expectedSequence += entryCount #### 1D-5: 尾部截断持久化 (`wal/truncation.go`) - 识别最后一个完整 batch 的结束位置 - ftruncate segment 文件 - fsync 被截断的 segment - 删除不含任何 complete batch 的后续空 segment - fsync WAL directory - 任一步失败 → recovery 报错 #### 1D-6: Recovery 主流程 (`wal/recovery.go`) ``` 1. 读取 MANIFEST → recoverySegmentID 2. 扫描 WAL 目录 → 过滤出 recovery segments 3. 排序并校验连续性 4. 逐 segment 扫描： a. 校验 File Header b. 逐 Block 解析 Physical Records c. Fragment 重组 → 完整 Batch d. Batch 校验 → 重放 e. 更新 expectedSequence 5. 处理尾部异常 6. 持久化截断（如需要） 7. 返回恢复结果：recoveredSequence, nextSequence, publishedSequence ``` ### 验收标准 - [ ] 正常 WAL 完整恢复 - [ ] 尾部 partial write 正确截断 - [ ] 中间损坏正确报错 - [ ] 跨 segment 恢复正确 - [ ] Fragment 重组 round-trip 正确 - [ ] Segment 连续性校验 - [ ] Sequence 溢出检测 - [ ] 资源限制校验（recovery 侧） --- ## Phase 1E: MemTable（SkipList + Arena） **目标**: 实现基于 Arena 的 SkipList，支持 pending/unpublished/aborted 状态，容量预留，和原子发布。 ### 任务 #### 1E-1: Arena 分配器 (`memtable/arena.go`) - 固定大小 Arena（默认 64MB） - 线程安全的内存分配 - 对齐分配 - 剩余容量查询 - 支持预留（reserve）操作 #### 1E-2: SkipList (`memtable/skiplist.go`) - 最大 20 层 - Mutex 写 + 无锁读 - `atomic.Pointer` 发布 next 指针（release 语义） - 有序遍历（Iterator） - key 比较（bytes comparison） #### 1E-3: Entry 状态管理 (`memtable/entry.go`) - Entry 结构：key、value、sequence、pending/aborted 标记 - 原子发布：`atomic.Pointer` store-release - 可见性判断：`entry.sequence <= loadedPublishedSequence && !aborted` #### 1E-4: MemTable (`memtable/memtable.go`) - 封装 SkipList + Arena - `Put(key, value, sequence) error` — 写入 pending entry - `PublishEntries(upToSequence)` — 批量发布 pending entries - `AbortEntries(fromSequence)` — 标记 aborted - `Get(key, publishedSequence) (GetResult, error)` — 无锁读，只返回 sequence <= publishedSequence 且非 aborted 的 entry - `NewIterator(publishedSequence) Iterator` — 无锁有序遍历 - `ApproximateSize() uint64` — 近似内存使用量 - `IsFull() bool` - `Reserve(entries []ReserveEntry) (uint64, error)` — 容量预留（最坏情况计算） #### 1E-5: 容量预留计算 - 每个 entry 的预留大小 = key bytes + value bytes + skiplist node overhead + next 指针数组（最大层高）+ arena 对齐 padding - 批量预留必须覆盖整个 batch - checked arithmetic 检查单个 batch 是否超过空 MemTable 容量 #### 1E-6: Immutable MemTable 管理 - Freeze 流程：当前 MemTable → Immutable - Immutable 队列（上限 2） - 队列满时阻塞 ### 验收标准 - [ ] SkipList 正确性：插入、查找、有序遍历 - [ ] Arena 分配无泄漏 - [ ] 并发读写正确（racetest） - [ ] pending/unpublished entry 对读不可见 - [ ] 发布后 entry 可见 - [ ] aborted entry 对读不可见 - [ ] 容量预留准确 - [ ] 内存序正确（go test -race 通过） --- ## Phase 1F: 写入路径集成 **目标**: 将 WAL Writer 和 MemTable 连通，实现完整的写入流水线。 ### 任务 #### 1F-1: DB 写入 API (`db.go`) ```go type DB struct { ... } func Open(dir string, opts ...Option) (*DB, error) func (db *DB) Close() error func (db *DB) Put(key, value []byte) error func (db *DB) Delete(key []byte) error ``` #### 1F-2: 写入路径集成 完整写入流程： ``` Put(key, value) → commit queue → group commit 组装 batch → 校验 batch limits → 预留 MemTable Arena → 分配 sequence → 私有缓冲编码 → 检查 segment 轮转 → WAL append → MemTable pending write → fsync（Always 模式） → 原子发布 MemTable entries → 推进 publishedSequence → 唤醒调用方 ``` #### 1F-3: MemTable Freeze + Switch - 写入前检查容量，不足时 freeze + switch - Immutable 队列满时阻塞等待 - Freeze 时确保当前 MemTable 已完成所有 pending 发布 #### 1F-4: 恢复启动集成 - Open 时执行 recovery - 恢复的 entries 写入 MemTable 并标记为 published - 设置 nextSequence、publishedSequence ### 验收标准 - [ ] 单条 Put 写入成功 - [ ] 并发 Put 正确 - [ ] 写入后读取可见（Always 模式） - [ ] WAL crash recovery 后数据完整 - [ ] MemTable freeze/switch 正确 - [ ] Sequence 连续无间隙 - [ ] `go test -race` 通过 --- ## Phase 1G: 读路径 + 嵌入式 API **目标**: 实现完整的读路径和嵌入式 API。 ### 任务 #### 1G-1: Get API ```go type GetResult struct { Value []byte Found bool } func (db *DB) Get(key []byte) (GetResult, error) ``` #### 1G-2: 读路径实现 - 读取 publishedSequence（atomic load） - 遍历 MemTable → Immutable MemTables - 只返回 `sequence <= publishedSequence` 且非 aborted 的 entry - Delete (tombstone) 返回 `Found=false` #### 1G-3: 辅助 API ```go func (db *DB) GetDurableSequence() uint64 func (db *DB) IsWriteStopped() bool ``` ### 验收标准 - [ ] Put 后 Get 返回正确值 - [ ] Delete 后 Get 返回 Found=false - [ ] 空 value 正确区分（Found=true, Value=[]byte{}） - [ ] 并发读写正确 - [ ] 未发布 entry 对 Get 不可见 --- ## Phase 1H: MANIFEST + 文件管理 **目标**: 实现 MANIFEST 持久化和 WAL segment 生命周期管理。 ### 任务 #### 1H-1: MANIFEST 格式 - 记录 recovery 起点的 recoverySegmentID - temp + rename 原子更新 - MANIFEST 只在 checkpoint（MemTable flush）后推进 #### 1H-2: 首次创建 DB 流程 - 创建目录结构 - 创建初始 MANIFEST（recoverySegmentID=0） - 创建初始 WAL segment #### 1H-3: WAL Segment 生命周期 - 旧 segment 删除条件：已被 MANIFEST checkpoint 覆盖 - 删除顺序：先删除文件，再 fsync directory ### 验收标准 - [ ] 首次创建 DB 成功 - [ ] 重复打开 DB 正确恢复 - [ ] MANIFEST 原子更新 - [ ] 旧 WAL segment 正确清理 --- ## Phase 1I: 集成测试 + Benchmark **目标**: 端到端测试和性能基准。 ### 任务 #### 1I-1: 集成测试 - 正常写入 + 读取 round-trip - 并发写入 + 读取一致性 - 崩溃恢复（kill -9 模拟） - WAL 尾部损坏恢复 - Write-stopped 后的行为 - Sequence 耗尽处理 - 配置校验拒绝非法配置 - 空 value 写入/读取 - 大量数据写入（触发 segment 轮转） #### 1I-2: Benchmark - 单线程 Put 吞吐 - 多线程 Put 吞吐 - 单线程 Get 延迟 - 多线程 Get 延迟 - WAL Recovery 时间 - 写入放大测量 #### 1I-3: Race Condition 测试 - `go test -race -count=100` - 并发 Put + Get - 并发 Put + Close ### 验收标准 - [ ] 所有集成测试通过 - [ ] Benchmark 数字可作为后续优化基线 - [ ] Race test 无 data race --- ## 依赖关系与并行度 ``` 1A ─────┐ ├── 1B ─────┐ │ ├── 1C ─────┐ │ │ ├── 1F ── 1G ── 1I │ │ │ 1A ── 1E ──────────┘ │ │ │ ├── 1D ─────────────────┘ │ └── 1H ────────────────────────────── 1I ``` 可并行开发的模块： - 1A 完成后，1B/1D/1E/1H 可以并行开发 - 1B 完成后，1C 可以开始 - 1C + 1D + 1E 完成后，1F 可以集成 - 1F + 1H 完成后，1G 可以集成 - 所有完成后，1I 集成测试 ## 技术要点备忘 ### 内存序（最关键） - skiplist next 指针：`atomic.Pointer` store-release - `publishedSequence`：`atomic.Uint64` store（在所有 entry 节点发布后） - 读者先 load publishedSequence（acquire），再遍历 skiplist ### WAL 副作用边界 - 未调用 `write()` → 普通错误 - 已调用 `write()` → ErrCommitUnknown + write-stopped - 私有缓冲区编码，不共享 bufio.Writer ### ErrCommitUnknown 语义 - maybe committed，不是 definitely failed - 不盲目重试 - 第一阶段为弱确认 ### WAL Batch 资源前置校验 - sequence 分配之前完成所有可失败校验 - 减少 write-stopped 触发机会