#1306

docs: propose disk cache codec architecture

DraftMrCroxxwants to merge intofrom

What changed

  • Added an English RFC for disk cache codecs and zero-copy decode, together with a Simplified Chinese translation.
  • Designed a simple serde path, an owner-backed zero-copy path for advanced users, and an engine-neutral codec service.
  • Clarified that Raw, IoSliceMut, and IoBuf remain the direct-I/O submission layer, while Bytes and OwnedBytes are immutable owner-backed decode views created after I/O completion.
  • Distinguished direct-I/O alignment from payload alignment and required every derived byte slice to validate its actual pointer.
  • Defined a versioned and aligned entry envelope, compression semantics, engine capabilities, validation criteria, and a five-stage implementation plan.

Why

Code::decode currently constructs an owned value from Read, so it cannot transfer ownership of the I/O buffer to the decoded result. Serialization is also embedded directly in the block-engine data path. The RFC proposes OwnedBytes and EntryCodec<K, V> to separate application formats from storage engines while preserving the existing serde and Code compatibility path.

Bytes::from_owner can preserve a 4K-aligned allocation without copying, but Bytes does not provide a type-level alignment guarantee and arbitrary slices may shift the pointer. The RFC therefore keeps direct-I/O buffers and post-I/O decode views as separate abstractions.

Impact

This PR adds documentation only. It does not change public APIs, persistent formats, or runtime behavior. Follow-up implementation work can proceed in the stages described by the RFC, with the remaining format decisions resolved before the v2 envelope becomes the default write format.

Validation

  • Confirmed that the PR scope contains only the two RFC documents.
  • Checked both Markdown files for whitespace errors.
  • Ran the repository typo checker against the English RFC.
  • Scanned the English RFC for remaining CJK text.
  • Verified that code blocks in the Chinese translation contain only English text.
  • Reviewed the proposal against the current Code, Engine, block-engine, direct-I/O buffer, and I/O-buffer ownership data paths.

Activity

4
codecov[bot]3mo ago

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. see 2 files with indirect coverage changes

:rocket: New features to boost your workflow:
  • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This pull request is a draft

Merging is unavailable until it is marked ready for review.