Safe Haskell	None
Language	GHC2021

Ecluse.Core.Credential.Refresh.Internal

Contents

Configuration
The refreshing provider
Telemetry reporters
Failure
State and pure/transition helpers (exposed for direct testing)

Description

The implementation behind Ecluse.Core.Credential.Refresh, which documents the policy and re-exports the curated surface. Importing this module opts out of that stability promise, the convention text and bytestring use, so production code imports the public one.

Synopsis

data RefreshConfig = RefreshConfig {
- rcMint :: IO AuthToken
- rcClock :: IO UTCTime
- rcJitter :: IO Double
- rcRefreshAt :: Double
- rcRefreshFloor :: NominalDiffTime
- rcBreakerThreshold :: Int
- rcBreakerCooldown :: NominalDiffTime
- rcReporters :: CredentialReporters
}
defaultRefreshConfig :: RefreshConfig
refreshingProvider :: RefreshConfig -> IO CredentialProvider
refreshingProviderWith :: IO () -> RefreshConfig -> IO CredentialProvider
data RefreshReporter = RefreshReporter {
- onRefreshSucceeded :: Maybe UTCTime -> IO ()
- onRefreshFailed :: Maybe UTCTime -> IO ()
}
noRefreshReporter :: RefreshReporter
data CredentialReporters = CredentialReporters {
- crBreakerReporter :: BreakerReporter
- crRefreshReporter :: RefreshReporter
}
noCredentialReporters :: CredentialReporters
data CredentialError
data CacheState = CacheState {
- csToken :: AuthToken
- csRefreshDue :: Maybe UTCTime
- csRefreshing :: Bool
- csBreaker :: Breaker
}
data ServeAction
- = ServeCached AuthToken
- | ServeAndRefresh AuthToken
- | MintNow
decide :: TVar CacheState -> UTCTime -> STM ServeAction
refreshDueAt :: RefreshConfig -> UTCTime -> AuthToken -> IO (Maybe UTCTime)
onMintSuccess :: AuthToken -> Maybe UTCTime -> CacheState -> CacheState
onMintFailure :: RefreshConfig -> UTCTime -> CacheState -> CacheState
releaseSingleFlight :: TVar CacheState -> IO ()

Configuration

data RefreshConfig Source #

Refresh policy with injected mint, clock, jitter and observers.

Constructors

RefreshConfig

Fields

rcMint :: IO AuthToken
The per-cloud token mint, the only part that touches a network.
rcClock :: IO UTCTime
Injected so a test drives refresh timing without real time passing.
rcJitter :: IO Double
A fraction in [0, 1), sampled once per token, pulling the refresh instant earlier. It desynchronises a cohort of instances.
rcRefreshAt :: Double
The fraction of a token's lifetime to refresh at, before jitter. Clamped to [0, 1].
rcRefreshFloor :: NominalDiffTime
Seconds before expiry the refresh may never be scheduled past, so a short-lived token still refreshes ahead of its deadline.
rcBreakerThreshold :: Int
Consecutive mint failures that trip the circuit breaker.
rcBreakerCooldown :: NominalDiffTime
How long the breaker stays open, fast-failing mints, before one half-open probe tests recovery.
rcReporters :: CredentialReporters
Inert by default. The composition root installs the live pair.

defaultRefreshConfig :: RefreshConfig Source #

Default policy knobs. Unwired rcMint and rcClock throw Unconfigured.

The refreshing provider

refreshingProvider :: RefreshConfig -> IO CredentialProvider Source #

Build a cached provider, minting eagerly so an initial mint failure aborts construction.

refreshingProviderWith :: IO () -> RefreshConfig -> IO CredentialProvider Source #

Add a test hook between the single-flight claim and the mint runner.

Telemetry reporters

data RefreshReporter Source #

Observe refresh outcomes with the active token's absolute expiry, absent for non-expiring tokens.

Constructors

RefreshReporter
Fields onRefreshSucceeded :: Maybe UTCTime -> IO () A mint succeeded, with the new token's absolute expiry. onRefreshFailed :: Maybe UTCTime -> IO () A mint failed, with the still-cached token's absolute expiry.

noRefreshReporter :: RefreshReporter Source #

The inert refresh reporter: records nothing on either outcome.

data CredentialReporters Source #

The telemetry observers a refreshing provider records through, bundled into one value.

Constructors

CredentialReporters
Fields crBreakerReporter :: BreakerReporter Observes the mint breaker's state transitions (`ecluse.rule.breaker.state`). crRefreshReporter :: RefreshReporter Observes each refresh outcome (`ecluse.credential.refresh` / `.token.ttl`).

noCredentialReporters :: CredentialReporters Source #

The inert pair: a provider built with it records nothing on either signal.

Failure

data CredentialError Source #

A failure from credential minting or refresh policy.

Constructors

BreakerOpen	The token expired with the mint breaker open, so no mint was attempted.
Unconfigured Text	An effectful leaf still holds its `defaultRefreshConfig` placeholder.
MintedTokenAlreadyExpired	An already-expired mint is treated as a mint failure.

Instances

Instances details

Exception CredentialError Source #
Instance details Defined in Ecluse.Core.Credential.Refresh.Internal Methods toException :: CredentialError -> SomeException # fromException :: SomeException -> Maybe CredentialError # displayException :: CredentialError -> String # backtraceDesired :: CredentialError -> Bool #
Show CredentialError Source #
Instance details Defined in Ecluse.Core.Credential.Refresh.Internal Methods showsPrec :: Int -> CredentialError -> ShowS # show :: CredentialError -> String # showList :: [CredentialError] -> ShowS #
Eq CredentialError Source #
Instance details Defined in Ecluse.Core.Credential.Refresh.Internal Methods (==) :: CredentialError -> CredentialError -> Bool # (/=) :: CredentialError -> CredentialError -> Bool #

State and pure/transition helpers (exposed for direct testing)

data CacheState Source #

The mutable state of a refreshing provider.

Constructors

CacheState
Fields csToken :: AuthToken The token currently served. csRefreshDue :: Maybe UTCTime When the background refresh fires. `Nothing` for a token with no expiry. csRefreshing :: Bool Whether a mint is in flight (the single-flight flag). csBreaker :: Breaker The circuit-breaker state.

data ServeAction Source #

What a serve/decide decision resolves to.

Constructors

ServeCached AuthToken	The cached token is valid and no refresh is due: serve it.
ServeAndRefresh AuthToken	Valid but past the refresh threshold: serve it, refresh in background.
MintNow	Expired: the caller must mint synchronously (the slow path).

Instances

Instances details

Show ServeAction Source #
Instance details Defined in Ecluse.Core.Credential.Refresh.Internal Methods showsPrec :: Int -> ServeAction -> ShowS # show :: ServeAction -> String # showList :: [ServeAction] -> ShowS #
Eq ServeAction Source #
Instance details Defined in Ecluse.Core.Credential.Refresh.Internal Methods (==) :: ServeAction -> ServeAction -> Bool # (/=) :: ServeAction -> ServeAction -> Bool #

decide :: TVar CacheState -> UTCTime -> STM ServeAction Source #

Claim a mint atomically when one is due, or block until an in-flight refresh frees the flag. The caller must release a claim with releaseSingleFlight.

refreshDueAt :: RefreshConfig -> UTCTime -> AuthToken -> IO (Maybe UTCTime) Source #

When a freshly minted token's refresh should fire. Jitter only pulls the rcRefreshAt fraction of the token's lifetime earlier, never later.

onMintSuccess :: AuthToken -> Maybe UTCTime -> CacheState -> CacheState Source #

Fold a successful mint into the cache. guardInFlight releases the single-flight flag around the mint, not this fold, so the flag clears even on an async exception.

onMintFailure :: RefreshConfig -> UTCTime -> CacheState -> CacheState Source #

Fold a failed mint into the cache. The cached token stays in place and the breaker advances under the configured threshold and cooldown.

releaseSingleFlight :: TVar CacheState -> IO () Source #

Release the single-flight flag. serve runs it under guardInFlight inside the masked scope that claimed it, so the flag clears on every exit, an async cancel included.