Struct ScheduledRefreshCipher 

pub struct ScheduledRefreshCipher<C> { /* private fields */ }

An AEAD cipher that bounds the age of its keys to a TTL by reloading on the read path — so a decryption key removed upstream is dropped within the TTL even though it never fails to decrypt (you still hold it). The TTL bounds how long a removed key lingers; key additions are handled by the miss-triggered RetryingDecryptor layered on top.

On each decrypt/unseal, and inside each select_cipher/select_sealer, the first caller past the TTL reloads single-flight (non-blocking for others), then proceeds against a frozen snapshot; for the outbound selectors the TTL bounds how quickly a rotated-in key is discovered rather than how quickly a removed one is dropped. Using the type directly as an AeadEncryptor serves the current snapshot without a reload — go through the selector for the freshness guarantee. The pure swap mechanism without policy is RefreshableCipher.

See composing crypto strategies for how this layer (removals) pairs with the retrying layer (additions). All clones share the same underlying state, so a refresh through any clone is visible to all others.

Implementations

impl<C: Debug + MaybeSendSync + 'static> ScheduledRefreshCipher<C>

pub async fn refresh_if_stale(&self) -> bool

Reloads the key if it has outlived its TTL and the rate-limit/backoff policy permits; a within-TTL key is left in place. Blocking.

A manual staleness poll: the selector paths (select_cipher, select_sealer) already reload a stale key during selection, so this only pre-warms the key ahead of a latency-sensitive encrypt/seal. Distinct from the inbound miss path AeadDecryptor::try_refresh, which is not TTL-gated; refresh reloads unconditionally.

Returns true if this call refreshed successfully, false if the policy blocked it or the refresh failed.

pub async fn refresh(&self) -> Result<bool, Error>

Forces a refresh bypassing the scheduling policy, but still records the outcome.

Returns Ok(true) if new key material was fetched by this call, or Ok(false) if another task already refreshed concurrently.

Errors

Returns an error if the factory call fails.

pub fn builder<I1>() -> ScheduledRefreshCipherBuilder<C, I1>

where I1: Fn() -> Pin<Box<dyn MaybeSendFuture<Output = Result<C, Error>>>> + MaybeSendSync + 'static,

Creates a new ScheduledRefreshCipher using the given factory and policy parameters.

The factory is called immediately to produce the initial cipher. The same factory is called on subsequent refreshes.

Errors

Returns an error if the initial factory call fails.

Trait Implementations

impl<C: AeadEncryptor + 'static> AeadCipherSelector for ScheduledRefreshCipher<C>

fn select_cipher(&self) -> MaybeSendBoxFuture<'_, Arc<dyn AeadEncryptor>>

Selects the current encryptor to use for encryption, refreshing stale key material first where the implementation supports it.

impl<C: AeadDecryptor + 'static> AeadDecryptor for ScheduledRefreshCipher<C>

fn cipher_match(&self, m: &CipherMatch<'_>) -> Option<KeyMatchStrength>

Returns how well this decryptor matches the given selection criteria.

fn decrypt<'a>( &'a self, cipher_match: Option<&'a CipherMatch<'a>>, nonce: &'a [u8], ciphertext: &'a [u8], tag: &'a [u8], aad: &'a [u8], ) -> MaybeSendBoxFuture<'a, Result<Vec<u8>, DecryptError>>

Asynchronously decrypts the given ciphertext with the provided nonce, tag, and associated data.

fn try_refresh(&self) -> MaybeSendBoxFuture<'_, bool>

Requests a best-effort refresh of the decryptor’s key material — the cipher analogue of JwsVerifier::try_refresh.

impl<C: AeadEncryptor + 'static> AeadEncryptor for ScheduledRefreshCipher<C>

fn enc_algorithm(&self) -> Cow<'_, str>

Returns the content encryption algorithm identifier (e.g. A256GCM).

fn key_id(&self) -> Option<Cow<'_, str>>

Returns the key ID for this encryptor, if any.

fn encrypt<'a>( &'a self, plaintext: &'a [u8], aad: &'a [u8], ) -> MaybeSendBoxFuture<'a, Result<AeadOutput, Error>>

Asynchronously encrypts the given plaintext with the associated data.

impl<C: AeadEncryptor + 'static> AeadSealerSelector for ScheduledRefreshCipher<C>

fn select_sealer(&self) -> MaybeSendBoxFuture<'_, Arc<dyn AeadSealer>>

Selects the current sealer — a frozen key snapshot — refreshing stale key material first where the implementation supports it.

impl<C: AeadDecryptor + 'static> AeadUnsealer for ScheduledRefreshCipher<C>

fn unseal<'a>( &'a self, cipher_match: Option<&'a CipherMatch<'a>>, bundle: &'a [u8], aad: &'a [u8], ) -> MaybeSendBoxFuture<'a, Result<Vec<u8>, DecryptError>>

Decrypts a versioned bundle produced by AeadSealer::seal.

impl<C> Clone for ScheduledRefreshCipher<C>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: Debug> Debug for ScheduledRefreshCipher<C>

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

Formats the value using the given formatter.