Mint a new session and cache it, collapsing concurrent callers onto one login. Prefer withTokens; call this directly only to warm the cache.
Run one metcap call with a valid session, re-running it once if metcap says the token was revoked mid-flight.
The single entry point for anything that needs tokens. Callers do not
acquire, do not decide when to refresh, and do not write recovery of their
own — all three used to be copy-pasted at each call site, and the Lambda's
copy simply omitted the recovery, which is why a revoked token there failed
a wire outright (WIRE-EMAIL-HANDLER-B).
fn must be re-runnable: it is invoked a second time with fresh tokens on
InvalidToken. Every metcap call behind this today is a read, and a read
that returned nothing but an auth rejection has no effect to undo. Do not
put a non-idempotent write inside it without checking that.
Exactly one extra attempt. Immediately after a refresh we hold the newest token in existence, so the retry all but always wins; losing twice means sustained contention, and a third login would only revoke another peer on the way to the same answer. Anything past that is the caller's retry to own — Temporal's for an activity, SES's for the Lambda.
Holder of the metcap session, and the only place allowed to mint one.
Minting is destructive
A metcap login revokes the tokens previously issued to that credential. Every
refreshTokens()is therefore a side effect on every OTHER holder of the credential, not a private cache-fill — which is why callers reach for withTokens instead of acquiring and recovering by hand. Two things follow from that, and both are load-bearing:SOFT_EXPIRY_BUFFER_MSbelow cannot do this on its own: a buffer moves when the herd arrives, it never serialises it.catch { await refreshTokens(); throw }— which discarded the work, minted a token nobody used, and logged out the peer that had just legitimately logged in. That peer then did the same thing back.withTokensends the ping-pong by making the caller that paid for the login the one that uses it, so each round of contention strictly makes progress.