Process-wide credential health of model providers.
Owns the forced-refresh circuit breaker, the post-refresh propagation marker, the escalating authentication cooldown and the single-flight interactive re-authentication. The iteration loop decides how a turn recovers from a rejected credential; this namespace records what happened to each provider and answers whether its credential may be refreshed or routed to.
The state is process-wide on purpose: router builds, every session's turns and
the gateway /metrics endpoint share one breaker and one cooldown, and
concurrent turns share one interactive authentication per provider.
Process-wide credential health of model providers. Owns the forced-refresh circuit breaker, the post-refresh propagation marker, the escalating authentication cooldown and the single-flight interactive re-authentication. The iteration loop decides how a turn recovers from a rejected credential; this namespace records what happened to each provider and answers whether its credential may be refreshed or routed to. The state is process-wide on purpose: router builds, every session's turns and the gateway `/metrics` endpoint share one breaker and one cooldown, and concurrent turns share one interactive authentication per provider.
BASE window (ms) a provider stays EXCLUDED from routing after its credentials were rejected and the turn had to rescue itself on another provider.
The rescue route itself is per-ITERATION state, so without a process-wide cooldown the very next iteration re-probes the dead credential: every single iteration then pays a 401 round-trip, a fallback log line and a visible progress chunk until the user re-authenticates.
BASE window (ms) a provider stays EXCLUDED from routing after its credentials were rejected and the turn had to rescue itself on another provider. The rescue route itself is per-ITERATION state, so without a process-wide cooldown the very next iteration re-probes the dead credential: every single iteration then pays a 401 round-trip, a fallback log line and a visible progress chunk until the user re-authenticates.
Max forced OAuth refreshes for one provider inside AUTH_REFRESH_WINDOW_MS
before the breaker trips. Legitimate rotation refreshes at most a handful of
times a minute; more than this is a flap, not real rotation.
Max forced OAuth refreshes for one provider inside `AUTH_REFRESH_WINDOW_MS` before the breaker trips. Legitimate rotation refreshes at most a handful of times a minute; more than this is a flap, not real rotation.
Rolling window (ms) for the forced-OAuth-refresh circuit breaker.
Rolling window (ms) for the forced-OAuth-refresh circuit breaker.
(cooldown-metrics)Observability snapshot of the per-provider auth cooldown: the BASE window, the ceiling it escalates to, and the providers still excluded — each with the epoch-ms the exclusion lifts, how many fallbacks landed inside the window and how many unbroken strikes set its length.
Observability snapshot of the per-provider auth cooldown: the BASE window, the ceiling it escalates to, and the providers still excluded — each with the epoch-ms the exclusion lifts, how many fallbacks landed inside the window and how many unbroken strikes set its length.
(cooled)Set of providers whose credentials are still inside their auth cooldown. Prunes records whose window lapsed more than [[AUTH_COOLDOWN_MAX_MS]] ago on the way, so the map cannot grow without bound while a recent streak still outlives its own window and keeps the escalation honest.
Set of providers whose credentials are still inside their auth cooldown. Prunes records whose window lapsed more than [[AUTH_COOLDOWN_MAX_MS]] ago on the way, so the map cannot grow without bound while a recent streak still outlives its own window and keeps the escalation honest.
(ensure-authenticated! pid)Resolve pid immediately before a real provider request. A managed provider with
an auth function authenticates only when its token lookup has no usable credential;
startup, status probes, and picker rendering never call this function.
Resolve `pid` immediately before a real provider request. A managed provider with an auth function authenticates only when its token lookup has no usable credential; startup, status probes, and picker rendering never call this function.
(forget-refresh! pid)Drop the propagation marker of pid, so a rejection during interactive
re-authentication is not read as lag of an earlier refresh.
Drop the propagation marker of `pid`, so a rejection during interactive re-authentication is not read as lag of an earlier refresh.
(managed? provider)True when provider is managed and can both sign in interactively and read its token.
True when `provider` is managed and can both sign in interactively and read its token.
(note-failure! pid)Open (or extend) the auth cooldown for pid after a fallback. Returns true only
for the FIRST trip of a cooldown window so the caller can log the escape once at
:warn and keep the repeats at :debug.
Open (or extend) the auth cooldown for `pid` after a fallback. Returns true only for the FIRST trip of a cooldown window so the caller can log the escape once at :warn and keep the repeats at :debug.
(note-ok! pid)Record that pid ACCEPTED a request: close its propagation window and its auth
cooldown, so a later rotation is a fresh rejection and a re-authenticated
provider re-enters routing at once. Returns true when a cooldown was cleared.
Record that `pid` ACCEPTED a request: close its propagation window and its auth cooldown, so a later rotation is a fresh rejection and a re-authenticated provider re-enters routing at once. Returns true when a cooldown was cleared.
(note-refreshed! pid)Stamp a FORCED refresh of pid now, opening its propagation window.
Stamp a FORCED refresh of `pid` now, opening its propagation window.
(propagation-lag? pid)True while the last FORCED refresh of pid is younger than
[[AUTH_PROPAGATION_WINDOW_MS]]: a new authentication rejection then reads as
propagation lag of the freshly minted token, not as a dead credential.
True while the last FORCED refresh of `pid` is younger than [[AUTH_PROPAGATION_WINDOW_MS]]: a new authentication rejection then reads as propagation lag of the freshly minted token, not as a dead credential.
(reauthenticate! pid provider rejected)Run at most one interactive authentication for pid; concurrent turns await the
same result. Re-read storage inside the flight to adopt a peer credential, but
never accept the token rejected by the request that triggered recovery.
Run at most one interactive authentication for `pid`; concurrent turns await the same result. Re-read storage inside the flight to adopt a peer credential, but never accept the token rejected by the request that triggered recovery.
(refresh-allowed? pid)Circuit breaker for forced OAuth refreshes. Atomically prunes timestamps older
than the rolling window for pid, records this attempt ONLY when it is
GRANTED, and returns true while the provider is still under the per-window
budget. When it returns false the breaker is OPEN: the caller must NOT refresh
and must recover without touching the token endpoint, so the user
re-authenticates once instead of the daemon flapping it.
Recording only GRANTED refreshes is what lets the breaker CLOSE again. An earlier version stamped every call, denials included, so a fleet of tabs still retrying inside the window kept re-arming the breaker they had just tripped: the window never drained and the process stayed in permanent auth fallback until restart, even once the on-file token was healthy again.
Circuit breaker for forced OAuth refreshes. Atomically prunes timestamps older than the rolling window for `pid`, records this attempt ONLY when it is GRANTED, and returns true while the provider is still under the per-window budget. When it returns false the breaker is OPEN: the caller must NOT refresh and must recover without touching the token endpoint, so the user re-authenticates once instead of the daemon flapping it. Recording only GRANTED refreshes is what lets the breaker CLOSE again. An earlier version stamped every call, denials included, so a fleet of tabs still retrying inside the window kept re-arming the breaker they had just tripped: the window never drained and the process stayed in permanent auth fallback until restart, even once the on-file token was healthy again.
(refresh-metrics)Observability snapshot of the OAuth-refresh circuit breaker. Returns the
rolling window, the trip threshold, the per-provider count of forced
refreshes still inside the window, and the set of providers at the refresh
limit (breaker OPEN). Surfaced by the gateway /metrics endpoint so an
auth-refresh flap is visible at a glance instead of needing a vis.log
grep.
Observability snapshot of the OAuth-refresh circuit breaker. Returns the rolling window, the trip threshold, the per-provider count of forced refreshes still inside the window, and the set of providers at the refresh limit (breaker OPEN). Surfaced by the gateway `/metrics` endpoint so an auth-refresh flap is visible at a glance instead of needing a `vis.log` grep.
(usable-token? envelope rejected)True when envelope carries a non-blank token other than the rejected one.
True when `envelope` carries a non-blank token other than the `rejected` one.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |