LCOV - code coverage report
Current view: top level - packages/account-core/src/core - refreshScheduler.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 25.5 % 137 35
Test Date: 2026-11-17 04:17:53

            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              : }
        

Generated by: LCOV version 2.0-1