refactor(storage): split db.rs into a directory module — mod/hash_ttl/kv_ops/accessors

[TinDang97]

What

db.rs (3113 lines, vs the repo's 1500-line rule) becomes a directory module:

File	Lines	Contents
db/mod.rs	1152	Database struct, constants, cost fns, HashTtlCond/FieldState/WrongType, ctor/clock, memory accounting, Default, all tests
db/kv_ops.rs	833	get/set/remove families, lazy expiry, cold-tier promotion/read-through, scan, versioning/LRU
db/accessors.rs	701	W5 ValueKind/OwnedKind generics, per-type delegators, intset/listpack bespoke accessors, read-only refs, blocking-hook helpers, streams
db/hash_ttl.rs	476	HEXPIRE-family per-field TTL primitives

Why now

The W5 typed-accessor unification (#400) concentrated the accessor matrix into three generics, leaving clean seams. Follow-up flagged at campaign close.

Invariants

• Pure code motion — every method body moved verbatim; public paths unchanged (submodules only add inherent impl Database blocks; pub use re-exports untouched).
• Only visibility changed: check_expired / is_expired / wrongtype_error / cold_contains_alive / cold_read_only → pub(super) (cross-file access within the module tree).
• Submodule files use crate:: imports; tests stay in mod.rs — both per the CLAUDE.md module-structure convention.

Gates

• macOS lib: 4427 passed (identical count to pre-split main)
• VM Linux lib: 4449 (monoio) + 3616 (tokio,jemalloc), both green
• clippy -D warnings clean on both feature sets; fmt clean; CHANGELOG entry added

Summary by CodeRabbit

• New Features

  • Added per-field expiration controls for hashes, including conditional expiration, TTL inspection, persistence, and atomic get-and-delete operations.
  • Improved support for collections stored in the cold tier, including read-through access and promotion when needed.
  • Added more consistent expiration handling across keys and collection types.

• Bug Fixes

  • Prevented expired or cold-stored data from appearing as missing or being replaced by empty containers.
  • Improved key existence, scanning, random-key selection, and memory tracking across hot and cold storage.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 36bee76b-08ca-4fe5-a172-45c92d6ee3f1

📥 Commits

Reviewing files that changed from the base of the PR and between 3cf6474 and 5a217e1.

📒 Files selected for processing (6)

• CHANGELOG.md
• src/storage/db.rs
• src/storage/db/accessors.rs
• src/storage/db/hash_ttl.rs
• src/storage/db/kv_ops.rs
• src/storage/db/mod.rs

---

📝 Walkthrough

Walkthrough

The database implementation is reorganized into src/storage/db modules for core state, keyspace operations, typed collection access, and hash field TTL behavior. It adds hot/cold promotion and read-through paths, O(1) memory accounting, and tests covering expiration, encoding upgrades, and cold-tier visibility.

Changes

Database storage implementation

Layer / File(s)	Summary
Database core contracts and state src/storage/db/mod.rs, CHANGELOG.md	Defines database state, TTL semantic types, memory-cost helpers, cached time handling, accounting APIs, and documents the module split.
Hot and cold keyspace operations src/storage/db/kv_ops.rs	Implements lazy expiration, cold-tier reads and promotion, mutations, deletion, enumeration, sampling, TTL updates, versioning, and LRU tracking.
Typed collection and stream access src/storage/db/accessors.rs	Adds typed read and mutation accessors for collections and streams, compact encoding upgrades, existence checks, and list/sorted-set helpers.
Hash field TTL and atomic removal src/storage/db/hash_ttl.rs	Adds conditional field expiry, persistence and clearing, encoding downgrades, field deletion, atomic get-and-delete, and empty-hash cleanup.
Database behavior validation src/storage/db/mod.rs	Adds coverage for expiration, memory accounting, hot/cold shadows, typed access, and cold collection visibility.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Database
  participant ColdIndex
  participant ColdDisk
  Client->>Database: Read key
  Database->>ColdIndex: Check cold location and TTL
  ColdIndex-->>Database: Return location
  Database->>ColdDisk: Read cold value
  ColdDisk-->>Database: Return decoded value
  Database->>ColdIndex: Revalidate and update cold state
  Database-->>Client: Return value or absence

Loading

Possibly related PRs

• pilotspace/moon#63: Uses related database loading and memory-management APIs.
• pilotspace/moon#119: Relies on the hash field TTL APIs introduced here.
• pilotspace/moon#287: Shares cold-visibility, promotion, and typed accessor behavior.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/db-directory-split

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}