Struct ObjectStoreCheckpointStore 

pub struct ObjectStoreCheckpointStore { /* private fields */ }

Object-store-backed checkpoint store with hierarchical layout.

Bridges the sync CheckpointStore trait to the async [ObjectStore] API via a dedicated single-threaded Tokio runtime. Checkpoints run infrequently (every ~10s) and are not on the hot path.

Object Layout (v2 — hierarchical)

{prefix}/
  manifests/
    manifest-000001.json    # Checkpoint manifest (JSON)
    manifest-000002.json
    latest.json             # {"checkpoint_id": 2}
  checkpoints/
    state-000001.bin        # Optional sidecar state
    state-000002.bin

Legacy Layout (v1 — flat, read-only)

{prefix}/checkpoints/
  checkpoint_000001/
    manifest.json
    state.bin
  latest.txt                # "checkpoint_000002"

Reads check v2 paths first, then fall back to v1 for backward compatibility. Writes always use v2 layout. Manifest writes use [PutMode::Create] for split-brain prevention (conditional PUT).

Implementations

impl ObjectStoreCheckpointStore

pub fn new( store: Arc<dyn ObjectStore>, prefix: String, max_retained: usize, ) -> Result<Self>

Create a new object-store-backed checkpoint store.

prefix is prepended to all object paths (e.g., "nodes/abc123/"). It should end with / or be empty.

Errors

Returns std::io::Error if the internal Tokio runtime cannot be created.

Trait Implementations

impl CheckpointStore for ObjectStoreCheckpointStore

fn save( &self, manifest: &CheckpointManifest, ) -> Result<(), CheckpointStoreError>

Persists a checkpoint manifest atomically.

fn update_manifest( &self, manifest: &CheckpointManifest, ) -> Result<(), CheckpointStoreError>

Overwrites an existing checkpoint manifest.

fn load_latest( &self, ) -> Result<Option<CheckpointManifest>, CheckpointStoreError>

Loads the most recent checkpoint manifest.

fn load_by_id( &self, id: u64, ) -> Result<Option<CheckpointManifest>, CheckpointStoreError>

Loads a specific checkpoint manifest by ID.

fn list_ids(&self) -> Result<Vec<u64>, CheckpointStoreError>

Lists all checkpoint IDs without loading manifests.

fn list(&self) -> Result<Vec<(u64, u64)>, CheckpointStoreError>

Lists all available checkpoints as (checkpoint_id, epoch) pairs.

fn prune(&self, keep_count: usize) -> Result<usize, CheckpointStoreError>

Prunes old checkpoints, keeping at most keep_count recent ones.

fn save_state_data( &self, id: u64, data: &[u8], ) -> Result<(), CheckpointStoreError>

Writes large operator state data to a sidecar file for a given checkpoint.

fn load_state_data( &self, id: u64, ) -> Result<Option<Vec<u8>>, CheckpointStoreError>

Loads large operator state data from a sidecar file.

fn cleanup_orphans(&self) -> Result<usize, CheckpointStoreError>

Delete orphaned state files that have no matching manifest.

fn validate_checkpoint( &self, id: u64, ) -> Result<ValidationResult, CheckpointStoreError>

Validate a specific checkpoint’s integrity.

fn recover_latest_validated( &self, ) -> Result<RecoveryReport, CheckpointStoreError>

Walk backward from latest to find the first valid checkpoint.

fn save_with_state( &self, manifest: &CheckpointManifest, state_data: Option<&[u8]>, ) -> Result<(), CheckpointStoreError>

Atomically saves a checkpoint manifest with optional sidecar state data.