Struct ResilienceService 

pub struct ResilienceService { /* private fields */ }

Indexing-layer manager for leases, health, jitter, and repair fetches.

Implementations

impl ResilienceService

pub fn new(config: ResilienceConfig) -> Self

Create a resilience service from explicit configuration.

pub fn with_database( database: IndexingDatabase, config: ResilienceConfig, ) -> Self

Create a resilience service backed by an indexing database.

Active leases and bans are hydrated from the database on construction. Mutations are persisted through the database on every operation.

pub fn with_budget(budget: ReplicationBudget) -> Self

Create a resilience service using a replication budget.

pub fn with_wot(config: ResilienceConfig, wot: WotService) -> Self

Create a resilience service which filters providers through local WoT.

pub fn with_reputation( config: ResilienceConfig, reputation_config: ReputationConfig, wot: Option<WotService>, ) -> Self

Create a service with explicit reputation and WoT policy state.

pub const fn config(&self) -> &ResilienceConfig

pub fn reputation_store(&self) -> Arc<Mutex<ProviderReputationStore>>

Return the shared historical provider reputation store.

pub fn with_trust_policy(self, wot: WotService) -> Self

Replace the local WoT service used for provider filtering.

pub fn record_lease(&self, lease: &ProviderLease) -> Result<LeaseUpdate>

Track a verified lease and wake pending fetches when it is new.

Errors

Returns an error if the lease is invalid or the service state lock is poisoned.

pub fn track_lease(&self, lease: &ProviderLease) -> Result<LeaseUpdate>

Alias for Self::record_lease.

Errors

Returns an error if the lease is invalid or the service state lock is poisoned.

pub fn ingest_lease(&self, lease: &ProviderLease) -> Result<LeaseUpdate>

Alias for Self::record_lease.

Errors

Returns an error if the lease is invalid or the service state lock is poisoned.

pub fn invalidate_provider( &self, hash: Hash, provider: PublicKey, ) -> Result<bool>

Invalidate a provider’s lease and cancel pending fetches for its blob.

Errors

Returns an error if the provider lease tracker or generation state is poisoned.

pub fn ban_provider( &self, provider: PublicKey, reason: impl Into<String>, scope: Option<Hash>, duration: Option<Duration>, ) -> Result<BanRecord>

Add a manual global or hash-scoped provider ban.

Errors

Returns an error if provider state or generation state is poisoned.

pub fn unban_provider( &self, provider: PublicKey, scope: Option<Hash>, ) -> Result<bool>

Remove a manual global or hash-scoped provider ban.

Errors

Returns an error if provider state or generation state is poisoned.

pub fn retroactive_invalidate( &self, hash: Hash, successful_provider: PublicKey, ) -> Result<Vec<PublicKey>>

Retroactively invalidate providers that definitively failed after a successful fetch.

Errors

Returns an error if provider state or generation state is poisoned.

pub fn observe_provider(&self, hash: Hash, provider: PublicKey) -> Result<()>

Record a locally observed provider.

Errors

Returns an error if the service state lock is poisoned.

pub fn health(&self, hash: &Hash) -> Result<AvailabilityHealth>

Return the current health report for a blob.

Errors

Returns an error if the service state lock is poisoned.

pub fn health_batch( &self, hashes: &[Hash], ) -> Result<HashMap<Hash, AvailabilityHealth>>

Query health for many hashes at once using a reverse index.

This is O(n + m) where n = total provider leases and m = queried hashes, instead of O(n * m) for calling health() per hash.

Errors

Returns an error if the service state lock is poisoned.

pub fn needs_replication(&self, hash: &Hash) -> Result<bool>

Return whether a blob is below the configured verified lease budget.

Errors

Returns an error if the service state lock is poisoned.

pub fn responsible_providers(&self, hash: &Hash) -> Result<Vec<PublicKey>>

Return the closest active providers selected by consistent hashing.

Errors

Returns an error if the service state lock is poisoned.

pub fn list_providers(&self) -> Result<Vec<PublicKey>>

Return all providers with active leases across all blobs.

Errors

Returns an error if the service state lock is poisoned.

pub fn blobs_for_provider(&self, provider: &PublicKey) -> Result<Vec<Hash>>

Return all blob hashes that the given provider has an active lease for.

Errors

Returns an error if the service state lock is poisoned.

pub fn record_failure( &self, hash: Hash, provider: PublicKey, failure: FetchFailure, ) -> Result<()>

Record a fetch failure in the shared provider tracker.

Errors

Returns an error if the service state lock is poisoned.

pub fn record_failure_at( &self, hash: Hash, provider: PublicKey, failure: FetchFailure, now: u64, ) -> Result<()>

Record a fetch failure at an explicit time.

Errors

Returns an error if the service state lock is poisoned.

pub fn clear_failures_for_provider( &self, hash: &Hash, provider: &PublicKey, ) -> Result<()>

Clear a provider’s recorded failures after a successful fetch.

Errors

Returns an error if the service state lock is poisoned.

pub fn record_success(&self, hash: &Hash, provider: &PublicKey) -> Result<()>

Record a successful provider fetch and clear its transient failure history.

Errors

Returns an error if provider state is poisoned.

pub fn reputation_score(&self, provider: PublicKey) -> Result<f64>

Return the current historical score for a provider.

Errors

Returns an error if provider state is poisoned.

pub fn jitter_delay(&self, hash: Hash, provider: PublicKey) -> Duration

Return the deterministic jitter assigned to one provider.

pub async fn wait_for_fetch_slot( &self, hash: Hash, provider: PublicKey, ) -> Result<FetchWait>

Wait for a provider’s jitter slot, cancelling when a newer lease is observed for the same blob.

Errors

Returns an error if service state cannot be accessed.

pub async fn ensure_replication( &self, endpoint: &Endpoint, blobs: &BlobStore, hash: Hash, ) -> Result<ReplicationResult>

Fetch and pin a blob when its verified availability is below budget.

Providers are tried in consistent-hash order and each fetch is delayed by its provider-specific jitter. A newly accepted lease short-circuits the pending fetch instead of creating a thundering herd.

Errors

Returns an error if state cannot be read, a selected provider ticket is invalid, or pinning fails. Provider fetch failures are returned in ReplicationResult::failed_from so another provider can be tried.

pub async fn replicate( &self, endpoint: &Endpoint, blobs: &BlobStore, hash: Hash, ) -> Result<ReplicationResult>

Alias for Self::ensure_replication.

Errors

Returns an error if the repair fetch fails.

pub async fn subscribe( &self, gossip: &GossipService, bootstrap: Vec<PublicKey>, ) -> Result<GossipTopic>

Subscribe to the provider-lease gossip topic.

Errors

Returns an error if the gossip subscription cannot be created.

pub async fn announce( &self, gossip: &GossipService, sender: &GossipSender, lease: &ProviderLease, ) -> Result<()>

Publish a signed provider lease to gossip.

Errors

Returns an error if the lease is unsigned, invalid, or cannot be sent.

pub async fn consume_gossip( &self, topic: &mut GossipTopic, timeout: Duration, ) -> Result<usize>

Consume provider leases until the topic closes or timeout expires.

A timeout is a normal end condition because gossip has no finite response boundary.

Errors

Returns an error if a gossip event or lease is malformed.

pub fn spawn_gossip_listener( &self, topic: GossipTopic, ) -> JoinHandle<Result<usize>>

Spawn a background provider-lease gossip consumer.

Trait Implementations

impl Clone for ResilienceService

fn clone(&self) -> ResilienceService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ResilienceService

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

Formats the value using the given formatter.