Struct LeaderLeaseStore 

pub struct LeaderLeaseStore { /* private fields */ }

Append-only object-store authority for the cluster leader.

Implementations

impl LeaderLeaseStore

pub fn new(store: Arc<dyn ObjectStore>, ttl_ms: i64) -> Self

Create a leader lease authority.

The store must provide linearizable PutMode::Create/Update and GET ETag or version metadata; unsupported conditional updates fail closed.

pub async fn verify_store_contract( &self, timeout: Duration, ) -> Result<(), LeaseError>

Verify the conditional-write contract required by the mutable authority head.

Validation and cleanup each receive the supplied timeout. The probe uses a unique path and cleanup is attempted after every validation outcome.

Errors

Returns an error when the store does not enforce native conditional writes, omits update metadata, times out, or cannot remove the probe.

pub async fn load(&self) -> Result<Option<LeaderLease>, LeaseError>

Load the highest durable sequence.

Errors

Fails closed on object-store I/O or malformed durable state.

pub async fn record_cluster_outcome( &self, proof: &LeaderProof, epoch: u64, checkpoint_id: u64, assignment_fence: CheckpointAssignmentFence, verdict: CheckpointVerdict, recovery_capsule: Option<RecoveryCapsuleRef>, ) -> Result<RecordOutcomeResult, ClusterCheckpointAuthorityError>

Admit one cluster terminal outcome through the exact next leader-authority sequence.

Renewals, takeovers, catalog seals, floor advances, and other decisions all contend on the same create-only object. An identical retry converges on the durable winner.

Errors

Fails closed for a stale proof, non-monotonic or conflicting outcome, malformed recovery capsule, or object-store failure.

pub async fn record_assignment_drain_decision( &self, proof: &LeaderProof, decision: AssignmentDrainDecision, ) -> Result<RecordAssignmentDrainDecisionResult, ClusterCheckpointAuthorityError>

Admit one assignment-drain settlement through the exact next authority sequence.

Lease renewals, takeovers, checkpoint outcomes, and other decisions contend on that same create-only sequence. An identical retry converges on the durable winner.

Errors

Fails closed for a stale proof, malformed/non-monotonic decision, or storage failure.

pub async fn assignment_drain_decision( &self, target_version: u64, ) -> Result<Option<AssignmentDrainDecision>, ClusterCheckpointAuthorityError>

Read the immutable settlement for one exact target assignment version.

Errors

Fails closed on malformed or incomplete authority history.

pub async fn assignment_recovery_decision( &self, target_version: u64, ) -> Result<Option<AssignmentRecoveryDecision>, ClusterCheckpointAuthorityError>

Read the immutable recovery authorization for one exact target assignment version.

Errors

Fails closed on malformed, incomplete, or cross-kind authority history.

pub async fn materialize_assignment_recovery( &self, target_version: u64, ) -> Result<RotateOutcome, ClusterCheckpointAuthorityError>

Materialize the immutable authority winner for one recovery target version.

The caller supplies only the version; an arbitrary staged proposal can never bypass the shared leader-decision chain.

Errors

Fails closed when no recovery decision exists, its proposal is invalid, or storage fails.

pub async fn prune_assignment_drain_decisions_before( &self, proof: &LeaderProof, before_target_version: u64, ) -> Result<u64, ClusterCheckpointAuthorityError>

Advance the shared assignment-decision floor through the exact next authority sequence.

The compatibility-shaped API retains both drain and recovery decisions on one ordered chain. The caller must first durably prune assignment snapshots below the same target-version horizon. Decision-bearing authority records below the durable floor then become eligible for best-effort deletion while the exact terminal anchor preserves chain continuity.

Errors

Fails for a stale proof, invalid horizon, corrupt history, or storage failure.

pub async fn cluster_outcome( &self, epoch: u64, ) -> Result<Option<CheckpointOutcome>, ClusterCheckpointAuthorityError>

Read one live cluster outcome from the shared authority.

Errors

Fails when the durable authority history is unavailable or invalid.

pub async fn cluster_outcome_with_recovery_capsule( &self, epoch: u64, ) -> Result<Option<(CheckpointOutcome, Option<ClusterRecoveryCapsule>)>, ClusterCheckpointAuthorityError>

Read one live cluster outcome together with its content-addressed recovery capsule. Commit always returns a validated capsule; Abort returns None for the capsule.

Errors

Fails when the authority history or selected recovery capsule is unavailable or invalid.

pub async fn cluster_outcome_inventory( &self, ) -> Result<ClusterOutcomeInventory, ClusterCheckpointAuthorityError>

Audit and return every live cluster outcome in ascending epoch order.

Errors

Fails when the durable authority history is unavailable or invalid.

pub async fn cluster_outcomes( &self, ) -> Result<Vec<CheckpointOutcome>, ClusterCheckpointAuthorityError>

Audit and return every live cluster outcome in ascending epoch order.

Errors

Fails when the durable authority history is unavailable or invalid.

pub async fn highest_cluster_committed_outcome( &self, ) -> Result<Option<CheckpointOutcome>, ClusterCheckpointAuthorityError>

Greatest live cluster commit recovery cut.

Errors

Fails when the durable authority history is unavailable or invalid.

pub async fn highest_cluster_terminal_outcome( &self, ) -> Result<Option<CheckpointOutcome>, ClusterCheckpointAuthorityError>

Greatest terminal cluster outcome, including the compacted continuity anchor.

Errors

Fails when the durable authority history is unavailable or invalid.

pub async fn cluster_attempt_settlement( &self, attempt: CheckpointAttempt, ) -> Result<Option<CheckpointOutcome>, ClusterCheckpointAuthorityError>

Return the exact immutable outcome for attempt, or the first audited terminal outcome known to close that older checkpoint. Compacted continuity anchors are included in the audit.

Errors

Returns an error for a noncanonical attempt identity or an unavailable or invalid durable authority chain.

pub async fn cluster_outcome_retention_boundary( &self, ) -> Result<ClusterOutcomeRetentionBoundary, ClusterCheckpointAuthorityError>

Exact continuity boundary for cluster outcomes compacted from the authority history.

Errors

Fails when the durable authority history is unavailable or invalid.

pub async fn audited_cluster_outcome_retention_boundary( &self, ) -> Result<ClusterOutcomeRetentionBoundary, ClusterCheckpointAuthorityError>

Read an existing cluster retention boundary after auditing its outcome chain and selected recovery capsule, without invoking a caller-supplied state-artifact preflight.

Errors

Returns an error when the authority history or selected recovery capsule is invalid.

pub async fn validated_cluster_outcome_inventory<V, Fut>( &self, validate_artifacts: V, ) -> Result<ClusterOutcomeInventory, ClusterCheckpointAuthorityError>

where V: Fn(CheckpointOutcome) -> Fut, Fut: Future<Output = Result<(), String>>,

Read live outcomes and their retention boundary only after the selected live Commit passes the caller’s durable recovery metadata preflight and both outcome heads and the floor remain unchanged.

Errors

Fails when authority history is invalid or artifact validation fails.

pub async fn maintain_cluster_recovery_capsules( &self, ) -> Result<RecoveryCapsuleGcStep, ClusterCheckpointAuthorityError>

Run one bounded recovery-capsule cleanup step below the durable artifact horizon.

This is deliberately independent of floor publication: cleanup failure cannot revoke an already-authorized manifest/state retention horizon.

Errors

Fails when the authority history is invalid or cleanup storage operations fail.

pub async fn prune_cluster_outcomes_before<V, Fut>( &self, proof: &LeaderProof, before_epoch: u64, validate_artifacts: V, ) -> Result<u64, ClusterCheckpointAuthorityError>

where V: Fn(CheckpointOutcome) -> Fut, Fut: Future<Output = Result<(), String>>,

Advance the cluster outcome floor through the exact next authority sequence.

At least one live commit remains at or above the requested horizon. Outcome-bearing records below the floor and unreferenced old recovery capsules become eligible for best-effort deletion only after the floor is durable.

Errors

Fails for a stale proof, invalid horizon, failed artifact validation, or storage failure.

pub async fn begin_new_term( &self, owner: &LeaderLeaseOwner, now_ms: i64, ) -> Result<LeaseOutcome, LeaseError>

Acquire an empty authority as a new term, or rotate the fencing token when this exact process incarnation already owns the durable head. Rival wall clocks never authorize takeover.

Errors

Fails closed on invalid input, object-store I/O, or arithmetic exhaustion.

pub async fn renew_exact( &self, owner: &LeaderLeaseOwner, token: u64, now_ms: i64, ) -> Result<LeaseOutcome, LeaseError>

Renew only the exact durable authority term identified by token.

Errors

Returns LeaseError::Fenced if the durable head is absent or belongs to another owner or term. Also fails closed on invalid input, object-store I/O, or arithmetic exhaustion.

pub fn observe_rival( &self, owner: &LeaderLeaseOwner, lease: &LeaderLease, ) -> Result<LeaderLeaseObservation, LeaseError>

Start a candidate-local observation of a rival durable liveness identity.

Errors

Rejects malformed state or an observation of the candidate itself.

pub async fn try_takeover( &self, owner: &LeaderLeaseOwner, observation: &LeaderLeaseObservation, now_ms: i64, ) -> Result<LeaseOutcome, LeaseError>

Take over only after the rival’s owner, fencing token, and renewal sequence remained current for a full TTL on the candidate’s monotonic clock.

Errors

Fails closed on early observation, invalid state, I/O, or arithmetic exhaustion.

Trait Implementations

impl Debug for LeaderLeaseStore

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.