Skip to main content

Module sse_refresh

atd_server_http

Module sse_refresh 

Source
Expand description

SP-token-broker-phase2 §4.7 — SSE long-connection bearer refresh.

For HTTP routes that hold a stream open (Celia’s /chat/stream, healthkit’s bulk-export progress, etc.), the bearer must be re-validated periodically — otherwise consent revocations propagate only at the next request, which on a long-lived stream might be never. This helper spawns a background task that polls TokenBroker::resolve_bearer on a heartbeat and emits RefreshEvents the adopter consumes from their SSE handler.

§Cadence (spec §4.7)

  • Default cadence is 60s — matches the bound under which “consent withdrawals get honoured” the spec contracts for.
  • If BearerIdentity.expires_at is Some(t), the next sleep is min(t - now, cadence) so we never sleep past the advertised TTL.
  • The cadence is recomputed every iteration from the most recent identity (a shrunk expires_at from a revalidation immediately tightens the loop).

§What the helper does NOT do

  • It does not cancel in-flight tool dispatches. Per spec §4.7, a tool call that began authorised must complete with that authority. Adopters propagate the cap change to the next request only.
  • It does not emit SSE bytes. The adopter’s route handler maps RefreshEvent::AuthLost to its own application-level frame (Celia chose event: auth_lost per spec §4.7).
  • It does not auto-reconnect. When the helper emits AuthLost, the loop terminates; the adopter route closes the stream; the client decides whether to reconnect with a fresh bearer.

Enums§

AuthLostReason
Why the bearer was invalidated. Maps 1:1 to the broker error variants per spec §4.4 — adopter UX can surface “session expired” vs “agent revoked” vs “server hiccup” distinctly.
RefreshEvent
Events the refresh task emits to the adopter’s SSE route.

Constants§

DEFAULT_REFRESH_CADENCE
Default heartbeat cadence per spec §4.7 (“matches the typical SSE keep-alive ping cadence; revocation window adopters accept”).

Functions§

spawn_bearer_refresh
Spawn a background task that periodically re-validates bearer via broker and emits RefreshEvents on the returned channel. The task exits after emitting one RefreshEvent::AuthLost; dropping the JoinHandle aborts it sooner.