Repository navigation
Description
Why
StateMachine and the log StorageEngine are extension points: developers embed their own
engine. Today the trait asks every implementer to remember framework-level duties
(TTL, snapshot metadata, serving gate, flush/persist ordering), and implementations drift:
File and sled close() rely on Drop; File and RocksDB swallow persist errors; File's
apply_chunk has no NotServing check. See #455/#458.
Principle
Move framework concerns out to the framework layer (read layer / writer layer) so an
implementation only provides the actions the contract names.
Test: does the duty depend on the storage engine's internal transaction?
- Yes -> stays in the implementation (e.g. data and
last_appliedcommitted atomically). - No -> moves to the framework (e.g. serving gate, error policy, TTL, snapshot metadata).
Contracts are written as observable postconditions, not steps. The shared test suite is the
single source of truth; an implementation is valid iff it passes the suite (ADR-046).
Scope: StateMachine (22 methods)
Verdicts are proposals; audit call sites of each method before removing it.
Keep (engine-bound)
-
start- load durable state -
close- make state recoverable, release exclusive resources, idempotent; becomes fallible -
get/get_multi/scan_prefix- reads (scan_prefix,get_multioptional) -
apply_chunk-Okimplies data andlast_appliedare atomically recoverable -
last_applied- read-only -
apply_snapshot_from_file- atomically updateslast_appliedtoo -
generate_snapshot_data- pinned atlast_included -
reset- optional
Remove or move to the framework
-
update_last_applied/persist_last_applied- folded intoapply_chunkatomicity -
update_last_snapshot_metadata/snapshot_metadata/persist_last_snapshot_metadata- framework-owned snapshot store -
save_hard_state/flush/flush_async- folded into theclosepostcondition -
is_running- serving state owned by the framework -
len/is_empty- cannot expressNotServing, O(n) on RocksDB; demote to diagnostics or remove -
lease_background_cleanupand TTL hooks - see TTL below
Cross-cutting items
-
close() -> Result<(), Error>: always release, return first error; worker propagates it - TTL: leader writes absolute expiry into the value so TTL is applied atomically with
apply_chunk; expiry stops bypassing Raft; no SM-side TTL file - Serving gate (
NotServing) implemented once in the framework, not per method per impl;
builder takes the state machine by value so a retained rawArccannot bypass it - Suite covers the postconditions: reopen without
Drop,NotServingafterclose
(reads and writes),last_appliednever regresses; suite is public for third parties
Log side (StorageEngine / LogStore / MetaStore)
- Apply the same test to each method; audit not done yet
- fix: RocksDB log/meta stores should release their DB handle on close #457: release DB handle on
close,NotServingafterwards; acceptance test goes into
StorageEngineTestSuite, not RocksDB-only
To verify first
- RocksDB
atomic_flush(data and meta live in different CFs, WAL disabled) - Snapshot export pins both CFs at one point under concurrent
apply_chunk - Where TTL lives after a
kill -9(RocksDB) - Framework already has a place to own snapshot metadata
Activity