dailz/go-kv
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix: persist WAL tail truncation per design protocol (C5+H8)

Browse Source 
Recovery tail-truncation had two compounding bugs in wal/recover.go:

C5: truncateSegment only called os.Truncate. Missing per design §3.2
    line 787-794:
      - Step 2: fsync the truncated segment
      - Step 3: delete empty trailing segments
      - Step 4: fsync WAL directory
    And all errors were swallowed into result.TruncateError with recovery
    still returning success, violating design line 799: "若 ftruncate、
    segment fsync、空 segment 删除或 WAL directory fsync 任一步失败，
    recovery 必须报错，DB 不得进入可写状态".

H8: findValidOffset only checked physical record CRCs, ignoring the
    FragmentCollector state machine. For a tail of First + Middle*
    without Last, it returned the offset AFTER the last Middle fragment
    instead of the last COMPLETE batch end. Result: residual half-batch
    fragments caused repeated tail-corruption reports on every restart.

Changes:
- wal/recover.go:
  - Add findLastCompleteBatchEnd: batch-aware offset finder using
    FragmentCollector state machine. Handles block-boundary padding
    correctly (continue across full-block padding, return on short-block).
  - Add truncateAndPersist: 4-step protocol (ftruncate + fsync segment +
    delete empty trailing + fsync dir). Any step failure is fatal.
  - Add segmentFsyncFn (package-level var for test injection, same
    pattern as C6's dirFsyncFn).
  - Refactor Recover failure path: use new functions, hard-error on
    truncation persist failure (was: swallow to TruncateError).
  - TruncateError field semantics: informational only ("tail corruption
    was detected and repair attempted"). Persist failures return error.
  - Delete findValidOffset and truncateSegment (replaced).
- wal/recover_offset_test.go (new): 8 unit tests for
  findLastCompleteBatchEnd covering clean/partial-tail/no-batch/
  physical-corruption/partial-only/block-boundary-padding/non-zero-tail/
  zero-tail cases. 5 unit tests for truncateAndPersist covering success/
  ftruncate-fail/dir-fsync-fail/segment-fsync-fail/retry-after-failure.
- wal/recover_test.go: add TestRecoverPartialFragmentTailIdempotent
  (H8 e2e regression: truncation point must be at last complete batch),
  TestRecoverTruncationFailureFailsRecovery (C5 e2e regression: any
  step failure fails Recover), TestRecoverInvalidBatchNotTruncatable
  (design line 778-781: invalid batch content hard-fails, NOT truncatable).

Injection note: segmentFsyncFn and dirFsyncFn (from C6) are package-level
vars; tests that override either must not use t.Parallel().

Verified: each new test fails on pre-fix code by logical analysis and
passes after the fix. Full suite green including go test -race ./... .

Phase 1 simplification: emptyTrailingSegments is always nil in Phase 1
(truncated segment is always segments[last]). The parameter is kept in
truncateAndPersist's signature for forward compatibility with the C4 fix.

Audit context: docs/audit-3.2.md C5 and H8 (H8 Oracle-verified bg_ef425776).
This commit is contained in:
dailz
2026-06-15 15:15:49 +08:00
parent 0739966e55
commit 273229ac9b
4 changed files with 1202 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wal/recover.go
+129 -72
View File
@@ -13,12 +13,15 @@ type RecoveryResult struct {
NextSegmentID uint64
ReplayedEntries int
Truncated bool
TruncateError error // non-nil if tail corruption was found
// TruncateError is informational only: non-nil means "tail corruption
// was found and repair was attempted". It does NOT report persistence
// failures — those cause Recover to return an error instead.
TruncateError error
}
// Recover performs a full WAL recovery: reads the recovery checkpoint from
// MANIFEST (or CURRENT), scans segments, replays entries, and handles tail
// truncation. On success the MANIFEST is updated with the new recovery state.
// MANIFEST, scans segments, replays entries, and persists tail truncation
// per design §3.2 line 787-800.
func Recover(dir string, replayer BatchReplayer) (*RecoveryResult, error) {
if replayer == nil {
return nil, fmt.Errorf("wal: recover: replayer is nil")
@@ -37,15 +40,14 @@ func Recover(dir string, replayer BatchReplayer) (*RecoveryResult, error) {
return nil, fmt.Errorf("wal: recover: %w", err)
}
// Step 3: Tail corruption — truncate the last segment and accept
// partial data loss for Phase 1.
// Step 3: Tail corruption — truncate the last segment per design
// §3.2 line 787-800.
result := &RecoveryResult{
NextSequence: nextSequence,
Truncated: true,
TruncateError: err,
TruncateError: err, // informational: tail corruption was detected
}
// Determine nextSegmentID from scanned segments.
segments, scanErr := ScanSegments(dir, recoverySegmentID)
if scanErr != nil {
return nil, fmt.Errorf("wal: recover: scan after tail corruption: %w", scanErr)
@@ -56,27 +58,31 @@ func Recover(dir string, replayer BatchReplayer) (*RecoveryResult, error) {
result.NextSegmentID = recoverySegmentID
}
// Truncate the last segment file to remove corrupted tail.
if len(segments) > 0 {
lastSeg := segments[len(segments)-1]
validOffset, truncErr := findValidOffset(lastSeg.FilePath)
if truncErr != nil {
// Best-effort: record the truncation error but don't fail recovery.
result.TruncateError = fmt.Errorf("%w (find valid offset: %v)", err, truncErr)
} else if truncErr := truncateSegment(lastSeg.FilePath, validOffset); truncErr != nil {
result.TruncateError = fmt.Errorf("%w (truncate: %v)", err, truncErr)
lastCompleteBatchEnd, findErr := findLastCompleteBatchEnd(lastSeg.FilePath)
if findErr != nil {
return nil, fmt.Errorf("wal: recover: find truncation offset: %w", findErr)
}
// Phase 1: truncated segment is always segments[last], no
// trailing empty segments to clean up. C4 fix will need to
// identify trailing empties based on the actually-corrupted
// segment's index, which is not the same as segments[last].
var emptyTrailing []string
if err := truncateAndPersist(lastSeg.FilePath, lastCompleteBatchEnd, dir, emptyTrailing); err != nil {
// Per design §3.2 line 799: DB must NOT enter writable state.
return nil, fmt.Errorf("wal: recover: persist tail truncation: %w", err)
}
}
// Count replayed entries by re-scanning the replayer state.
// For Phase 1 we accept that ReplayedEntries may be approximate;
// the replayer interface doesn't expose a count.
result.ReplayedEntries = 0 // caller can inspect replayer directly
result.ReplayedEntries = 0 // Phase 1: replayer interface doesn't expose count
// Per design §3.2 line 280, recovery repair must NOT update MANIFEST.
// The truncated WAL state is persisted via ftruncate (see C5 for the
// remaining fsync gaps). MANIFEST can only advance via checkpoint
// (MemTable flush) in future phases.
// The truncated WAL state is persisted via ftruncate + fsync segment
// + fsync dir (see truncateAndPersist). MANIFEST can only advance via
// checkpoint (MemTable flush) in future phases.
return result, nil
}
@@ -114,23 +120,76 @@ func resolveRecoverySegmentID(dir string) (uint64, error) {
return mf.RecoverySegmentID, nil
}
// truncateSegment truncates the file at filePath to validOffset bytes,
// removing any corrupted data after that point.
func truncateSegment(filePath string, validOffset int64) error {
if validOffset < 0 {
return fmt.Errorf("wal: truncate: invalid offset %d", validOffset)
// segmentFsyncFn is the package-level indirection for fsyncing a truncated
// segment file. Tests that override this must not use t.Parallel().
// Same pattern as dirFsyncFn (see wal/dir_fsync.go).
var segmentFsyncFn = segmentFsync
func segmentFsync(filePath string) error {
f, err := os.OpenFile(filePath, os.O_WRONLY, 0o644)
if err != nil {
return fmt.Errorf("open for fsync: %w", err)
}
return os.Truncate(filePath, validOffset)
defer f.Close()
if err := f.Sync(); err != nil {
return fmt.Errorf("fsync: %w", err)
}
return nil
}
// findValidOffset parses a segment file and returns the byte offset of the
// last valid record boundary. The offset includes the file header size.
func findValidOffset(filePath string) (int64, error) {
// Re-parse the file to find where valid records end.
// We need to track the byte offset as we parse.
// truncateAndPersist executes the 4-step tail-truncation protocol per
// design §3.2 line 787-794. Any step failure is fatal: per line 799,
// DB must NOT enter writable state if truncation cannot be persisted.
func truncateAndPersist(
filePath string,
lastCompleteBatchEnd int64,
dir string,
emptyTrailingSegments []string,
) error {
// Step 1: ftruncate
if lastCompleteBatchEnd < 0 {
return fmt.Errorf("wal: invalid truncate offset %d", lastCompleteBatchEnd)
}
if err := os.Truncate(filePath, lastCompleteBatchEnd); err != nil {
return fmt.Errorf("ftruncate %s to %d: %w", filePath, lastCompleteBatchEnd, err)
}
// Step 2: fsync the truncated segment
if err := segmentFsyncFn(filePath); err != nil {
return fmt.Errorf("fsync truncated segment: %w", err)
}
// Step 3: delete empty trailing segments
for _, segPath := range emptyTrailingSegments {
if err := os.Remove(segPath); err != nil {
return fmt.Errorf("remove empty segment %s: %w", segPath, err)
}
}
// Step 4: fsync WAL directory (reuses C6's dirFsyncFn)
if err := dirFsyncFn(dir); err != nil {
return fmt.Errorf("fsync WAL dir after truncation: %w", err)
}
return nil
}
// findLastCompleteBatchEnd walks the segment file, runs physical records
// through the FragmentCollector state machine, and returns the byte offset
// of the END of the last complete WAL Batch.
//
// This is the correct truncation target per design §3.2 line 786. A previous
// version (findValidOffset) only checked physical record CRCs, missing the
// case where a First + Middle* fragment chain has no Last (H8 bug): physical
// CRCs pass but no complete batch exists at that offset.
//
// Block-boundary handling: WAL format allows a full block to end with zero
// padding when the next record doesn't fit (see BlockWriter.paddingNeeded).
// This function CONTINUES to the next block on padding in a full block, and
// only RETURNS on padding in a short (final) block or actual corruption.
func findLastCompleteBatchEnd(filePath string) (int64, error) {
f, err := os.Open(filePath)
if err != nil {
return 0, fmt.Errorf("open for offset scan: %w", err)
return 0, fmt.Errorf("open %s: %w", filePath, err)
}
defer f.Close()
@@ -138,58 +197,56 @@ func findValidOffset(filePath string) (int64, error) {
return 0, fmt.Errorf("seek past header: %w", err)
}
validOffset := int64(WalFileHeaderSize)
collector := NewFragmentCollector()
lastCompleteEnd := int64(WalFileHeaderSize)
blockStartOffset := int64(WalFileHeaderSize)
buf := make([]byte, WalBlockSize)
for {
n, readErr := f.Read(buf)
if readErr != nil {
break
}
if n == 0 {
break
}
if n > 0 {
blockData := buf[:n]
isFullBlock := n == WalBlockSize && readErr == nil
pos := 0
for pos < len(blockData) {
remaining := len(blockData) - pos
blockData := buf[:n]
blockStartOffset := validOffset
pos := 0
for pos < len(blockData) {
remaining := len(blockData) - pos
if remaining < PhysicalRecordHeaderSize {
// Check if remaining bytes are zero-padding.
if isAllZeros(blockData[pos:]) {
// Valid padding — update offset to end of last valid record.
validOffset = blockStartOffset + int64(pos)
if remaining < PhysicalRecordHeaderSize {
if isFullBlock {
break // padding in full block, continue to next block
}
return lastCompleteEnd, nil // tail padding in short block
}
// Either way, we're done with this block.
break
}
if isAllZeros(blockData[pos : pos+PhysicalRecordHeaderSize]) {
if isAllZeros(blockData[pos:]) {
validOffset = blockStartOffset + int64(pos)
if isAllZeros(blockData[pos : pos+PhysicalRecordHeaderSize]) {
if isFullBlock {
break // zero-led padding in full block, continue
}
return lastCompleteEnd, nil // tail padding
}
break
}
_, consumed, err := DecodePhysicalRecord(blockData[pos:])
if err != nil {
// Corruption starts here — offset is up to last valid record.
validOffset = blockStartOffset + int64(pos)
return validOffset, nil
}
rec, consumed, err := DecodePhysicalRecord(blockData[pos:])
if err != nil {
return lastCompleteEnd, nil // physical corruption
}
if err := collector.Append(rec.Type, rec.Payload); err != nil {
return lastCompleteEnd, nil // fragment state machine rejected
}
// Valid record found.
validOffset = blockStartOffset + int64(pos+consumed)
pos += consumed
pos += consumed
recordEndAbsolute := blockStartOffset + int64(pos)
if collector.IsComplete() {
lastCompleteEnd = recordEndAbsolute
collector.Reset()
}
}
blockStartOffset += int64(n)
}
if n < WalBlockSize {
if readErr != nil || n < WalBlockSize {
break
}
}
return validOffset, nil
return lastCompleteEnd, nil
}