perf: stream the decoder page index and spill the encoder index to disk

[corylanou]

Stacked on #95 (base branch perf/page-index-slice). Closes #96.

Summary

After #95 the encoder's index still grows with page count (24 B/page), and the decoder side turned out to be the larger remaining term: Decoder.Close slurped the tail of the file and built the full map[uint32]PageIndexElem even for compaction inputs that never read it (~80 B/page, ≈2.7 GiB per input at the 34M pages in benbjohnson/litestream#1477). Three commits, no wire-format change, no new dependencies, no platform-specific code:

1. Decoder streams the page index on Close (decoder.go). Records are parsed straight from the reader through a small bufio buffer and hashed as consumed; the map is only built when retention is on (default, so PageIndex() keeps working). Compactor turns retention off for its inputs. The streamed path also validates what the old parser didn't: ascending page numbers within Commit, int64-bounded offsets/sizes, positive non-overlapping frames, size field equal to bytes read, nothing after the trailer, entry count equal to pages decoded, and a CRC64 over the index's page numbers equal to the same over the decoded pages (so the index must name exactly the decoded pages, without retaining them). DecodePageIndex shares the parser. Checksum coverage is unchanged — the perf(encoder): store page index in chunked slices, not a map #95 golden checksums still pass.

2. Encoder spills the index to a temp file past a threshold (encoder.go). The index is append-only in ascending order and emitted sequentially on Close, so it never needed map semantics or random access: once it reaches SetSpillThreshold entries (default 1M, ~24 MiB) and SetSpillDir is configured, entries are appended to a buffered temp file in their final varint record format and copied into the output on Close. Buffered file I/O rides the OS page cache, which is the effect the mmap idea was after, without unsafe slices, remapping on growth, Windows unmap-before-delete ordering, SIGBUS on disk exhaustion, or 32-bit address-space limits (litestream ships armv6/armv7). Spilling is opt-in by directory because the encoder only sees an io.Writer and cannot pick a safe location itself; litestream's hardened image is FROM scratch with no /tmp, so it will pass its per-database meta directory.

   Lifecycle is strict, per review: Cleanup (idempotent, returns removal errors, keeps the path for retry) aborts an unclosed encoder so a later Close cannot emit a checksum-valid file with an empty index; Close installs its cleanup+abort defer before its first write and any failure is terminal (ErrEncoderAborted on retry); header/page/spill write failures abort; short writes are guarded everywhere. Spilled output is byte-identical to in-memory output, including across chunk boundaries, for deletion files and NoChecksum files.

3. Compactor passthroughs SetSpillDir / Cleanup so callers can enable the spill for compaction output and clean up abandoned compactions.

Windows / platform check (asked before choosing this over mmap)

Both projects cross-build for Windows (ltx release.yml, litestream commit.yml + goreleaser), ltx also builds for plan9 and js/wasm, and syscall.Mmap is undefined on GOOS=windows — so an mmap design needs //go:build unix plus a fallback and gains nothing for a write-once/read-once sequential file. This branch has no build tags; GOOS=windows go vet ./..., go test ./..., and go test -race ./... are green. Details in #96.

Evidence

litestream-soak snapshot-compaction-overlap rig (corylanou/litestream-soak#196): the snapshot's replica stream is held at 95% so its index stays resident while an L1 compaction runs; heap growth = peak HeapInuse − post-GC baseline, GOGC=25, peak heap profile per phase. Litestream is benbjohnson/litestream#1479 plus the follow-up that sets SetSpillDir(db.MetaPath()) (linked below), built via local replace.

ltx	fixture	snapshot	L1 compaction	overlap (held snapshot + compaction)
v0.5.2 (litestream main)	4 GiB / 1,051,216 pages	168.6 MB	306.3 MB	470.6 MB
#95	4 GiB	68.8 MB	203.4 MB	199.6 MB
this PR	4 GiB	70.4 MB	73.7 MB	73.1 MB
this PR	8 GiB / 2,102,433 pages	73.1 MB	72.9 MB	73.9 MB

Doubling the database from 4 to 8 GiB no longer changes any phase: ~32 MB is the S3 multipart upload buffers (fixed), the rest is the ≤24 MiB of index chunks before the spill kicks in. Peak profile of the 8 GiB compaction phase: s3/manager.(*maxSlicePool).newSlice 32 MB, ltx.(*pageIndex).append 22.8 MB, and DecodePageIndex no longer appears at all (it was 81–84 MB at 4 GiB on #95).

Follow-ups (not here)

• Litestream: Hydrator.ApplyLTX reads pages and returns without dec.Close(), so it never verifies the index/trailer/file checksum (pre-existing; noted by review). It should close the decoder with retention off.
• Decoder.Close still cannot check index offsets against actual compressed frame positions, because the decoder tracks logical bytes, not file offsets.

Test plan

• go test ./..., go test -race ./..., go vet ./..., GOOS=windows GOARCH=amd64 go vet ./...
• Golden checksums from perf(encoder): store page index in chunked slices, not a map #95 unchanged; TestDecoder_PageIndexStructure builds checksum-valid files with phantom / missing / renamed / overlapping / out-of-range index entries and confirms only the structural checks reject them; TestEncoder_SpillLifecycle covers cleanup-before-close, first-write failure, non-retryable failed close, removal-error retry, deletion + NoChecksum parity
• Rig evidence above (4 GiB, 8 GiB); litestream root suite green against this branch
• Four adversarial Codex passes; every confirmed finding addressed (the first pass drove the strict lifecycle semantics)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79888f3787

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".