Safe Haskell	None
Language	GHC2021

Ecluse.Core.Credential.Refresh

Contents

Configuration
The refreshing provider
Telemetry reporters
Failure

Description

The refresh, cache, expiry, and concurrency policy behind a CredentialProvider.

The policy is identical for every cloud, so it lives here once, parameterised over a per-cloud rcMint leaf and an injected rcClock. Only rcMint touches a network. Ecluse.Core.Credential.Refresh.Internal implements it.

What reaches a caller

It serves a cached token, refreshes it in the background under a single-flight claim before expiry, and keeps serving a valid one through a mint outage behind a circuit breaker, so only an expired token with a still-failing mint reaches a caller as an exception (docs/architecture/cloud-backends.md).

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
data RefreshReporter = RefreshReporter {
- onRefreshSucceeded :: Maybe UTCTime -> IO ()
- onRefreshFailed :: Maybe UTCTime -> IO ()
}
noRefreshReporter :: RefreshReporter
data CredentialReporters = CredentialReporters {
- crBreakerReporter :: BreakerReporter
- crRefreshReporter :: RefreshReporter
}
noCredentialReporters :: CredentialReporters
data CredentialError

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.

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 #