Line data Source code
1 : /**
2 : * The proactive-refresh owner: an optional piece the session client hands
3 : * its lifecycle to when a host asks for scheduled refresh. It owns its own
4 : * timers, retry count, the expiry fail-close, and (when a cross-tab port is
5 : * given) the lease, leadership and sibling adoption. It never holds session
6 : * state: it reads the client's live credential through the host and commits
7 : * a refreshed, failed, expired or adopted result back through the host, so
8 : * the client stays the single owner of `credential`/`failure`.
9 : *
10 : * Extracted from createSessionClient so the mint/commit core can be reasoned
11 : * about without the scheduling and cross-tab machinery, and so a client with
12 : * no `refreshScheduler` option carries none of it.
13 : */
14 : import type {
15 : AccountCredential,
16 : AccountUser,
17 : MintHandle,
18 : RefreshSchedulerOptions,
19 : SessionFailure
20 : } from './sessionContracts'
21 : import { isPermanentSessionError } from './sessionContracts'
22 :
23 : export const DEFAULT_BUFFER_MS = 5 * 60 * 1000
24 :
25 : /** Guards captured before a scheduled mint, re-checked before its commit. */
26 : interface RefreshGuards {
27 : readonly epoch: number
28 : readonly invalidation: number
29 : }
30 :
31 : export interface RefreshHost {
32 : now: () => number
33 : getCurrentUser: () => AccountUser | null
34 : getCredential: () => AccountCredential | undefined
35 : captureGuards: () => RefreshGuards
36 : /** A scheduled mint's result may commit only if nothing superseded it. */
37 : guardsHold: (
38 : guards: RefreshGuards,
39 : user: AccountUser,
40 : mintId: number
41 : ) => boolean
42 : /** A forced mint for the target that produced the live credential. */
43 : mint: (user: AccountUser) => MintHandle
44 : /** Returns a failure when the refreshed session was rejected (wrong scope). */
45 : commitRefreshed: (
46 : session: AccountCredential,
47 : mintId: number
48 : ) => SessionFailure | undefined
49 : commitPermanentFailure: (failure: SessionFailure) => void
50 : /** Clears iff the live credential is still `expiring`; returns what it committed. */
51 : commitExpired: (expiring: AccountCredential) => SessionFailure | undefined
52 : /** Parse a cross-tab message into a credential, or undefined if malformed. */
53 : parseAdopted: (message: unknown) => AccountCredential | undefined
54 : /** Commit a sibling's credential: supersede any in-flight mint, persist, publish. */
55 : commitAdopted: (session: AccountCredential) => void
56 : }
57 :
58 : export interface RefreshScheduler {
59 : /** A fresh credential committed: cancel the fail-close, arm the next refresh, tell siblings. */
60 : armAfterCommit: (session: AccountCredential, now: number) => void
61 : stop: () => void
62 : }
63 :
64 9412 : function disposeQuietly(
65 : dispose: (() => void) | undefined,
66 : label: string
67 : ): void {
68 9412 : try {
69 9412 : dispose?.()
70 : } catch (error) {
71 0 : console.warn(`Cross-tab refresh ${label} teardown failed:`, error)
72 : }
73 : }
74 :
75 2355 : export function createRefreshScheduler(
76 : options: RefreshSchedulerOptions,
77 : host: RefreshHost
78 : ): RefreshScheduler {
79 2355 : const bufferMs = options.bufferMs ?? DEFAULT_BUFFER_MS
80 2355 : const retryBaseMs = options.retryBaseMs ?? 5000
81 2355 : const maxRetries = options.maxRetries ?? 3
82 2355 : const reportOutcome = options.onScheduledOutcome
83 2355 : const crossTab = options.crossTab
84 2355 : const followerJitterMs = crossTab?.followerJitterMs ?? 15_000
85 :
86 2355 : let scheduledTimer: ReturnType<typeof setTimeout> | undefined
87 : /**
88 : * The hard fail-close for a credential whose refresh chain died. Its own
89 : * timer on purpose: re-arming the refresh (a retry, a promotion) must not
90 : * cancel it; only a committed credential or a teardown does.
91 : */
92 2355 : let expiryTimer: ReturnType<typeof setTimeout> | undefined
93 2355 : let scheduledRetryCount = 0
94 : /** Without coordination every tab is its own leader. */
95 2355 : let isRefreshLeader = crossTab === undefined
96 2355 : let coordinationKey: string | undefined
97 : /**
98 : * Bumped on every coordination teardown. A leadership grant landing on an
99 : * abandoned request carries the generation it was issued under — the key
100 : * string alone cannot distinguish an abandoned request from its same-key
101 : * successor after a sign-out/sign-in round trip.
102 : */
103 2355 : let coordinationGeneration = 0
104 2355 : let armingScheduledRefresh = false
105 2355 : let releaseLeadership: (() => void) | undefined
106 2355 : let stopCredentialFeed: (() => void) | undefined
107 :
108 4706 : function stopScheduledRefresh(): void {
109 4706 : if (scheduledTimer !== undefined) {
110 0 : clearTimeout(scheduledTimer)
111 0 : scheduledTimer = undefined
112 : }
113 : }
114 :
115 4706 : function clearExpiry(): void {
116 4706 : if (expiryTimer !== undefined) {
117 0 : clearTimeout(expiryTimer)
118 0 : expiryTimer = undefined
119 : }
120 : }
121 :
122 4706 : function teardownCoordination(): void {
123 4706 : coordinationGeneration += 1
124 4706 : disposeQuietly(releaseLeadership, 'leadership release')
125 4706 : releaseLeadership = undefined
126 4706 : disposeQuietly(stopCredentialFeed, 'credential feed')
127 4706 : stopCredentialFeed = undefined
128 4706 : coordinationKey = undefined
129 4706 : isRefreshLeader = crossTab === undefined
130 : }
131 :
132 0 : function ensureCoordination(): void {
133 0 : const credential = host.getCredential()
134 0 : if (crossTab === undefined || credential === undefined) return
135 : // Keyed by the SERVER-RESOLVED workspace, never the requested target: a
136 : // personal {} mint resolves to a concrete workspace the target string
137 : // cannot name, and tabs on one workspace must share one lease however
138 : // they reached it.
139 0 : const key = `comfy-account-refresh:${credential.uid}:${credential.workspace.id}`
140 0 : if (key === coordinationKey) return
141 0 : teardownCoordination()
142 0 : coordinationKey = key
143 0 : const generationAtRequest = coordinationGeneration
144 : // Cross-tab coordination is optional: a port that throws during setup
145 : // must never propagate past a committed credential. Tear down whatever
146 : // partial wiring landed and lead this tab on its own schedule.
147 0 : try {
148 0 : stopCredentialFeed = crossTab.port.onCredential(
149 : key,
150 : adoptPublishedCredential
151 : )
152 0 : releaseLeadership = crossTab.port.requestLeadership(key, () => {
153 : // A grant is honored only for the coordination generation that issued
154 : // the request: abandoned requests can still win the grant race in the
155 : // lock manager, and after a same-user round trip their key is
156 : // byte-identical to the live request's.
157 0 : if (generationAtRequest !== coordinationGeneration) return
158 0 : isRefreshLeader = true
159 : // Promotion retakes the schedule unconditionally — the follower timer
160 : // may be jittered, mid-retry, or already dead from exhausted retries.
161 : // The latch skips the redundant re-arm when the grant fires
162 : // synchronously inside armScheduledRefresh itself.
163 0 : const live = host.getCredential()
164 0 : if (live !== undefined && !armingScheduledRefresh) {
165 0 : armScheduledRefresh(live.expiresAt, host.now())
166 : }
167 : })
168 : } catch (error) {
169 0 : console.warn('Cross-tab refresh coordination setup failed:', error)
170 0 : teardownCoordination()
171 0 : isRefreshLeader = true
172 : }
173 : }
174 :
175 : /**
176 : * Every committed mint is published once a coordination key exists —
177 : * leadership gates adoption, never publication — so the reactive 401
178 : * re-mint and a leaderless follower's fallback reach siblings too: those
179 : * are exactly the rotations they must not miss. Adoption itself never
180 : * republishes, and the monotonic-expiry guard makes redelivery a no-op,
181 : * so the channel cannot loop.
182 : */
183 0 : function publishToSiblings(session: AccountCredential): void {
184 0 : if (coordinationKey === undefined) return
185 : // Publication is optional: a throwing port must not unwind a mint that
186 : // already committed and persisted its credential.
187 0 : try {
188 0 : crossTab?.port.publishCredential(coordinationKey, session)
189 : } catch (error) {
190 0 : console.warn('Cross-tab refresh credential publish failed:', error)
191 : }
192 : }
193 :
194 0 : function adoptPublishedCredential(message: unknown): void {
195 : // Any tab adopts a strictly newer credential, the leader included: a
196 : // leader whose own chain died recovers from a sibling's fallback mint,
197 : // and the monotonic-expiry check keeps the channel from looping.
198 0 : const next = host.parseAdopted(message)
199 0 : if (next === undefined) return
200 0 : if (host.getCurrentUser()?.uid !== next.uid) return
201 : // Scope check: the channel key cannot fully encode the workspace (the
202 : // personal target is server-resolved), so a same-user credential minted
203 : // for a DIFFERENT workspace must never switch this tab.
204 0 : const credential = host.getCredential()
205 0 : if (credential === undefined) return
206 0 : if (next.workspace.id !== credential.workspace.id) return
207 0 : if (next.expiresAt <= credential.expiresAt) return
208 0 : clearExpiry()
209 0 : host.commitAdopted(next)
210 0 : armScheduledRefresh(next.expiresAt, host.now())
211 0 : crossTab?.onCredentialAdopted?.(next)
212 : }
213 :
214 0 : function armScheduledRefresh(expiresAt: number, now: number): void {
215 0 : stopScheduledRefresh()
216 0 : scheduledRetryCount = 0
217 0 : armingScheduledRefresh = true
218 0 : try {
219 0 : ensureCoordination()
220 : } finally {
221 0 : armingScheduledRefresh = false
222 : }
223 : // A follower holds past the leader's refresh point by bounded random
224 : // jitter; when no published credential has arrived by then, the leader
225 : // is gone and this tab refreshes for itself. Never tighter than one
226 : // retry interval: a token already inside the buffer (a host buffer at
227 : // or above the TTL, a skewed clock) would otherwise re-mint in a loop.
228 0 : const jitter = isRefreshLeader ? 0 : Math.random() * followerJitterMs
229 0 : scheduledTimer = setTimeout(
230 : () => {
231 0 : scheduledTimer = undefined
232 0 : void runScheduledRefresh()
233 : },
234 : Math.max(retryBaseMs, expiresAt - bufferMs - now) + jitter
235 : )
236 : }
237 :
238 : /**
239 : * Retries are spent and the credential still has time on it: keep serving
240 : * it until its expiry instant, then fail closed and tell the host, as the
241 : * cloud store's clear-at-expiry does. A dead scheduler must never leave an
242 : * expired token in circulation.
243 : */
244 0 : function armClearAtExpiry(expiring: AccountCredential): void {
245 0 : const now = host.now()
246 0 : clearExpiry()
247 0 : expiryTimer = setTimeout(
248 : () => {
249 0 : expiryTimer = undefined
250 0 : const committed = host.commitExpired(expiring)
251 0 : if (!committed) return
252 0 : stopScheduledRefresh()
253 0 : reportOutcome?.({ outcome: 'expired', failure: committed })
254 : },
255 : Math.max(0, expiring.expiresAt - now)
256 : )
257 : }
258 :
259 : /**
260 : * The scheduled re-mint mirrors the cloud store's refresh semantics: a
261 : * transient failure keeps the still-valid credential and retries with
262 : * doubling backoff; a permanent failure commits the error; exhausted
263 : * retries keep the credential until it expires, then fail closed. Every
264 : * commit runs publish() before reporting its outcome — host outcome
265 : * handlers read state the publish just wrote.
266 : */
267 0 : async function runScheduledRefresh(): Promise<void> {
268 0 : const user = host.getCurrentUser()
269 0 : if (!user) return
270 0 : const guards = host.captureGuards()
271 : // Refresh with the target that produced the live credential, so a
272 : // scheduled refresh reproduces the same session AND coalesces with any
273 : // concurrent reactive re-mint for it.
274 0 : const { mintId, response } = host.mint(user)
275 0 : let result
276 0 : try {
277 0 : result = await response
278 : } catch {
279 0 : result = { status: 'error', code: 'TOKEN_EXCHANGE_FAILED' } as const
280 : }
281 0 : if (!host.guardsHold(guards, user, mintId)) return
282 0 : if (result.status === 'ok') {
283 0 : const rejected = host.commitRefreshed(result.session, mintId)
284 0 : if (rejected) {
285 0 : reportOutcome?.({ outcome: 'permanent_failure', failure: rejected })
286 0 : return
287 : }
288 0 : clearExpiry()
289 0 : armScheduledRefresh(result.session.expiresAt, host.now())
290 0 : publishToSiblings(result.session)
291 0 : reportOutcome?.({ outcome: 'succeeded' })
292 0 : return
293 : }
294 0 : if (isPermanentSessionError(result.code)) {
295 0 : host.commitPermanentFailure(result)
296 0 : reportOutcome?.({ outcome: 'permanent_failure', failure: result })
297 0 : return
298 : }
299 0 : if (scheduledRetryCount >= maxRetries) {
300 0 : const live = host.getCredential()
301 0 : if (live !== undefined) armClearAtExpiry(live)
302 : // A leader with a dead chain must not sit on the lease: release it so
303 : // a sibling can lead, and queue again as a follower so this tab can
304 : // adopt what that sibling mints or be promoted back if nobody does.
305 0 : teardownCoordination()
306 0 : ensureCoordination()
307 0 : reportOutcome?.({ outcome: 'retries_exhausted' })
308 0 : return
309 : }
310 0 : const delay = retryBaseMs * 2 ** scheduledRetryCount
311 0 : scheduledRetryCount += 1
312 0 : stopScheduledRefresh()
313 0 : scheduledTimer = setTimeout(() => {
314 0 : scheduledTimer = undefined
315 0 : void runScheduledRefresh()
316 : }, delay)
317 0 : reportOutcome?.({ outcome: 'retry_scheduled' })
318 : }
319 :
320 2355 : return {
321 : armAfterCommit(session, now) {
322 0 : clearExpiry()
323 0 : armScheduledRefresh(session.expiresAt, now)
324 0 : publishToSiblings(session)
325 : },
326 : stop() {
327 4706 : stopScheduledRefresh()
328 4706 : clearExpiry()
329 4706 : teardownCoordination()
330 : }
331 : }
332 : }
|