Trait CheckpointStore 

pub trait CheckpointStore: Send + Sync {
    // Required methods
    fn max_state_data_bytes(&self) -> u64;
    fn save<'life0, 'life1, 'async_trait>(
        &'life0 self,
        manifest: &'life1 CheckpointManifest,
    ) -> Pin<Box<dyn Future<Output = Result<(), CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn load_latest<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointManifest>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn load_by_id<'life0, 'async_trait>(
        &'life0 self,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointManifest>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn list<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<(u64, u64)>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn list_ids<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u64>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn prune_before<'life0, 'async_trait>(
        &'life0 self,
        before_epoch: u64,
    ) -> Pin<Box<dyn Future<Output = Result<usize, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn save_state_data<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: u64,
        chunks: &'life1 [Bytes],
    ) -> Pin<Box<dyn Future<Output = Result<(), CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn load_state_data<'life0, 'async_trait>(
        &'life0 self,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn key_group_count(&self) -> KeyGroupCount { ... }
    fn participant_id(&self) -> u64 { ... }
    fn ensure_manifest_participant(
        &self,
        manifest: &CheckpointManifest,
    ) -> Result<(), CheckpointStoreError> { ... }
    fn ensure_manifest_valid(
        &self,
        manifest: &CheckpointManifest,
    ) -> Result<(), CheckpointStoreError> { ... }
    fn load_manifest_for_participant<'life0, 'async_trait>(
        &'life0 self,
        participant_id: u64,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointManifest>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn finalize<'life0, 'async_trait>(
        &'life0 self,
        checkpoint_id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<CheckpointManifest, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn load_state_data_for_participant<'life0, 'async_trait>(
        &'life0 self,
        participant_id: u64,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn state_data_len_for_participant<'life0, 'async_trait>(
        &'life0 self,
        participant_id: u64,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<u64>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn load_checkpoint_artifacts<'life0, 'async_trait>(
        &'life0 self,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointArtifacts>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn load_checkpoint_artifacts_for_participant<'life0, 'async_trait>(
        &'life0 self,
        participant_id: u64,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointArtifacts>, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn validate_checkpoint<'life0, 'async_trait>(
        &'life0 self,
        id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<ValidationResult, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn recover_latest_validated<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<RecoveryReport, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn save_with_state<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        manifest: &'life1 CheckpointManifest,
        state_data: Option<&'life2 [Bytes]>,
    ) -> Pin<Box<dyn Future<Output = Result<CheckpointManifest, CheckpointStoreError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
}

Trait for checkpoint persistence backends.

Implementations must guarantee atomic manifest writes (readers never see a partial manifest). The latest.txt pointer is updated only after the manifest is fully written and synced.

Required Methods

fn max_state_data_bytes(&self) -> u64

Maximum aggregate raw logical operator-state bytes admitted for one checkpoint.

The same bound independently limits the physical sidecar. Implementations must enforce it on writes, body reads, metadata-only length reads, and artifact validation.

fn save<'life0, 'life1, 'async_trait>( &'life0 self, manifest: &'life1 CheckpointManifest, ) -> Pin<Box<dyn Future<Output = Result<(), CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Atomically persists a checkpoint manifest. Implementations must guarantee readers never observe a partial manifest.

Errors

Returns CheckpointStoreError on I/O or serialization failure.

fn load_latest<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointManifest>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Loads the most recent checkpoint manifest, or Ok(None) when the recovery pointer does not exist in a fresh store.

Errors

Returns CheckpointStoreError on I/O or deserialization failure, or when an existing recovery pointer is malformed, dangling, or references anything other than the matching Finalized manifest.

fn load_by_id<'life0, 'async_trait>( &'life0 self, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointManifest>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Loads a specific manifest, or Ok(None) if absent.

Errors

Returns CheckpointStoreError on I/O or deserialization failure.

fn list<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<(u64, u64)>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Lists all available checkpoints as (id, epoch) pairs, sorted ascending by ID. May read every manifest; callers that only need IDs should use Self::list_ids.

Errors

Returns CheckpointStoreError on I/O, deserialization, or manifest validation failure.

fn list_ids<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<u64>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Lists all checkpoint IDs, sorted ascending. Unlike Self::list this enumerates corrupt manifests too (used by crash recovery). Callers rely on the ascending invariant.

Errors

Returns CheckpointStoreError on I/O failure.

fn prune_before<'life0, 'async_trait>( &'life0 self, before_epoch: u64, ) -> Pin<Box<dyn Future<Output = Result<usize, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Prunes manifests whose checkpoint epoch is strictly below before_epoch.

This is the production retention primitive. The coordinator supplies the same externally-committed/recovery-safe horizon used for state and decision retention, so all three durable inventories advance together. The manifest referenced by the latest recovery pointer is always retained.

Errors

Returns CheckpointStoreError on I/O or deserialization failure. A malformed latest pointer or manifest fails closed without deleting it.

fn save_state_data<'life0, 'life1, 'async_trait>( &'life0 self, id: u64, chunks: &'life1 [Bytes], ) -> Pin<Box<dyn Future<Output = Result<(), CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Writes operator state sidecar bytes for a checkpoint.

Accepts a chain of Bytes chunks (one per operator) rather than a single concatenated slice. Backends that support native multi-chunk writes (object-store PutPayload) avoid copying the chunks into a contiguous buffer; backends without such support write sequentially.

Errors

Returns CheckpointStoreError on I/O failure or when the sidecar exceeds Self::max_state_data_bytes.

fn load_state_data<'life0, 'async_trait>( &'life0 self, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Loads operator state sidecar bytes for a checkpoint, or Ok(None) if no sidecar was written.

Errors

Returns CheckpointStoreError on I/O failure, malformed storage metadata/body, or a sidecar above Self::max_state_data_bytes.

Provided Methods

fn key_group_count(&self) -> KeyGroupCount

Runtime key-group count that manifests written by this store are expected to use. Consulted when validating loaded manifests. Embedded and single-node stores default to one key group.

fn participant_id(&self) -> u64

Participant whose manifests belong in this store namespace.

Embedded and standalone stores use participant 0; cluster stores use their stable numeric instance id and a matching participant-specific namespace.

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

Reject a manifest that was routed to another participant’s namespace.

Errors

Returns CheckpointStoreError::Invalid when the manifest participant does not match this store’s participant.

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

Reject an invalid manifest before any sidecar, directory, or object is created.

Errors

Returns CheckpointStoreError::Invalid when the manifest violates an invariant.

fn load_manifest_for_participant<'life0, 'async_trait>( &'life0 self, participant_id: u64, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointManifest>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Load an exact checkpoint from a participant namespace.

Cluster recovery uses this only when the durable decision proves that the local participant was not part of the committed cut. Implementations that do not expose a shared participant namespace reject non-local reads.

fn finalize<'life0, 'async_trait>( &'life0 self, checkpoint_id: u64, ) -> Pin<Box<dyn Future<Output = Result<CheckpointManifest, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Atomically publish a prepared checkpoint as the latest recoverable cut.

The transition is idempotent and preserves the checksum stamped by Self::save_with_state.

fn load_state_data_for_participant<'life0, 'async_trait>( &'life0 self, participant_id: u64, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Load operator state sidecar bytes from a participant namespace.

Stores without a shared participant namespace reject non-local reads.

fn state_data_len_for_participant<'life0, 'async_trait>( &'life0 self, participant_id: u64, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<u64>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Read only the durable sidecar object’s length from storage metadata.

Cluster retention uses this to prove that a manifest’s immutable sidecar still exists without downloading its body. Custom stores fail closed until they provide an equivalent metadata-only lookup.

fn load_checkpoint_artifacts<'life0, 'async_trait>( &'life0 self, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointArtifacts>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Load the manifest and checksum-required sidecar for a local checkpoint exactly once.

fn load_checkpoint_artifacts_for_participant<'life0, 'async_trait>( &'life0 self, participant_id: u64, id: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<CheckpointArtifacts>, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Load the manifest and checksum-required sidecar from a participant namespace exactly once.

Inline-only checkpoints do not read state.bin. External and mixed shapes perform one sidecar read after the manifest has selected that shape.

fn validate_checkpoint<'life0, 'async_trait>( &'life0 self, id: u64, ) -> Pin<Box<dyn Future<Output = Result<ValidationResult, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Validate a specific checkpoint’s integrity.

Checks that the manifest is parseable and, if a state_checksum is present, verifies the sidecar data matches.

Errors

Returns CheckpointStoreError on I/O failure.

fn recover_latest_validated<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RecoveryReport, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Walk backward from latest to find the first valid checkpoint.

Returns a RecoveryReport describing the walk. If no valid checkpoint is found, chosen_id is None (fresh start).

Errors

Returns CheckpointStoreError on I/O failure.

fn save_with_state<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, manifest: &'life1 CheckpointManifest, state_data: Option<&'life2 [Bytes]>, ) -> Pin<Box<dyn Future<Output = Result<CheckpointManifest, CheckpointStoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Atomically saves a checkpoint manifest with optional sidecar state data.

When state_data is provided, the sidecar (state.bin) is written and fsynced before the manifest. This ensures that if the sidecar write fails, the manifest is never persisted and latest.txt still points to the previous valid checkpoint.

A state.bin written without a manifest is not visible to checkpoint inventory or recovery.

Errors

Returns CheckpointStoreError on I/O, serialization, validation, or operator state above Self::max_state_data_bytes.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl CheckpointStore for FileSystemCheckpointStore

impl CheckpointStore for ObjectStoreCheckpointStore