LCOV - code coverage report
Current view: top level - packages/api-client/src - retryPolicy.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 18.8 % 69 13
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : export interface RetryPolicy {
       2              :   readonly maxAttempts: number
       3              :   readonly baseDelayMs: number
       4              :   readonly maxDelayMs: number
       5              :   readonly retryNonIdempotent: boolean
       6              :   /** Send a write once more after {@link isSignInCheckRefusal}; cloud only. */
       7              :   readonly retrySignInRefusal: boolean
       8              : }
       9              : 
      10         2356 : export const DEFAULT_RETRY_POLICY: RetryPolicy = {
      11              :   maxAttempts: 3,
      12              :   baseDelayMs: 500,
      13              :   maxDelayMs: 10_000,
      14              :   retryNonIdempotent: false,
      15              :   retrySignInRefusal: false
      16              : }
      17              : 
      18              : /** Sends once: for callers that already retry on their own backoff. */
      19         2356 : export const NO_RETRY_POLICY: RetryPolicy = {
      20              :   ...DEFAULT_RETRY_POLICY,
      21              :   maxAttempts: 1
      22              : }
      23              : 
      24         2356 : const RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 502, 503, 504])
      25         2356 : const IDEMPOTENT_METHODS: ReadonlySet<string> = new Set([
      26              :   'GET',
      27              :   'HEAD',
      28              :   'OPTIONS'
      29              : ])
      30              : 
      31            0 : function isRetryableStatus(status: number): boolean {
      32            0 :   return RETRYABLE_STATUSES.has(status)
      33              : }
      34              : 
      35            1 : function isIdempotentMethod(method: string): boolean {
      36            1 :   return IDEMPOTENT_METHODS.has(method.toUpperCase())
      37              : }
      38              : 
      39            1 : export function canRetryMethod(
      40              :   method: string,
      41              :   policy: RetryPolicy = DEFAULT_RETRY_POLICY
      42              : ): boolean {
      43            1 :   return policy.retryNonIdempotent || isIdempotentMethod(method)
      44              : }
      45              : 
      46              : /** `policy`, also sending a write once more after a sign-in check refusal. */
      47            0 : export function withSignInRefusalRetry(
      48              :   policy: RetryPolicy = DEFAULT_RETRY_POLICY
      49              : ): RetryPolicy {
      50            0 :   return { ...policy, retrySignInRefusal: true }
      51              : }
      52              : 
      53              : /** Whether a sign-in check refusal is the only answer that can resend `method`. */
      54          111 : export function canRetrySignInRefusal(
      55              :   method: string,
      56              :   policy: RetryPolicy = DEFAULT_RETRY_POLICY
      57              : ): boolean {
      58          111 :   return policy.retrySignInRefusal && !canRetryMethod(method, policy)
      59              : }
      60              : 
      61              : /** Milliseconds a `Retry-After` header asks for (delta-seconds or HTTP-date). */
      62            0 : export function parseRetryAfterMs(
      63              :   value: string | null | undefined,
      64              :   now: number = Date.now()
      65              : ): number | undefined {
      66            0 :   const trimmed = value?.trim()
      67            0 :   if (!trimmed) return undefined
      68            0 :   if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1000
      69            0 :   if (!/[a-z]/i.test(trimmed)) return undefined
      70            0 :   const at = Date.parse(trimmed)
      71            0 :   return Number.isNaN(at) ? undefined : Math.max(0, at - now)
      72              : }
      73              : 
      74         2356 : const SIGN_IN_REFUSAL_MAX_SENDS = 2
      75         2356 : const SIGN_IN_REFUSAL_BODY_READ_MAX_MS = 1_000
      76              : 
      77              : interface SignInRefusalInput {
      78              :   readonly status: number
      79              :   readonly readRetryAfter: () => string | null | undefined
      80              :   readonly readBody: (signal: AbortSignal) => unknown
      81              : }
      82              : 
      83            0 : async function readBodyWithinCap(
      84              :   readBody: SignInRefusalInput['readBody']
      85              : ): Promise<unknown> {
      86            0 :   const reading = new AbortController()
      87            0 :   try {
      88            0 :     return await Promise.race([
      89              :       readBody(reading.signal),
      90              :       sleep(SIGN_IN_REFUSAL_BODY_READ_MAX_MS, reading.signal)
      91              :     ])
      92              :   } finally {
      93            0 :     reading.abort()
      94              :   }
      95              : }
      96              : 
      97         2356 : const SIGN_IN_CHECK_UNAVAILABLE_MESSAGE = 'authentication service unavailable'
      98              : 
      99              : /**
     100              :  * Whether a 503 is cloud's sign-in check refusing a request before any handler ran.
     101              :  * The message match is temporary: BE-24676 replaces it with a marker from ingest.
     102              :  */
     103            0 : export async function isSignInCheckRefusal({
     104              :   status,
     105              :   readRetryAfter,
     106              :   readBody
     107              : }: SignInRefusalInput): Promise<boolean> {
     108            0 :   if (status !== 503) return false
     109            0 :   try {
     110            0 :     if (parseRetryAfterMs(readRetryAfter()) === undefined) return false
     111            0 :     const body = await readBodyWithinCap(readBody)
     112            0 :     const parsed: unknown = typeof body === 'string' ? JSON.parse(body) : body
     113            0 :     return (
     114              :       typeof parsed === 'object' &&
     115              :       parsed !== null &&
     116              :       'message' in parsed &&
     117              :       parsed.message === SIGN_IN_CHECK_UNAVAILABLE_MESSAGE
     118              :     )
     119              :   } catch {
     120            0 :     return false
     121              :   }
     122              : }
     123              : 
     124              : interface RetryDecisionInput {
     125              :   readonly method: string
     126              :   readonly status: number
     127              :   readonly readRetryAfter: () => string | null | undefined
     128              :   readonly attempt: number
     129              :   readonly policy?: RetryPolicy
     130              :   readonly random?: () => number
     131              :   readonly now?: () => number
     132              :   readonly signInRefusal?: boolean
     133              : }
     134              : 
     135              : /** Why {@link nextRetry} stopped instead of scheduling another attempt. */
     136              : export type RetryStopReason =
     137              :   | 'not_retryable'
     138              :   | 'attempts_spent'
     139              :   | 'retry_after_too_long'
     140              : 
     141              : export type RetryDecision =
     142              :   | { readonly retry: true; readonly delayMs: number }
     143              :   | { readonly retry: false; readonly reason: RetryStopReason }
     144              : 
     145              : /** Whether to send another attempt, and after how long. */
     146            0 : export function nextRetry({
     147              :   method,
     148              :   status,
     149              :   readRetryAfter,
     150              :   attempt,
     151              :   policy = DEFAULT_RETRY_POLICY,
     152              :   random = Math.random,
     153              :   now = Date.now,
     154              :   signInRefusal = false
     155              : }: RetryDecisionInput): RetryDecision {
     156            0 :   const methodRetries = canRetryMethod(method, policy)
     157            0 :   const refusalRetries = signInRefusal && policy.retrySignInRefusal
     158            0 :   if (!isRetryableStatus(status) || !(methodRetries || refusalRetries)) {
     159            0 :     return { retry: false, reason: 'not_retryable' }
     160              :   }
     161              :   const maxAttempts = methodRetries
     162              :     ? policy.maxAttempts
     163              :     : Math.min(policy.maxAttempts, SIGN_IN_REFUSAL_MAX_SENDS)
     164            0 :   if (attempt >= maxAttempts) {
     165            0 :     return { retry: false, reason: 'attempts_spent' }
     166              :   }
     167              : 
     168            0 :   const retryAfterMs = parseRetryAfterMs(readRetryAfter(), now())
     169            0 :   if (retryAfterMs !== undefined && retryAfterMs > policy.maxDelayMs) {
     170            0 :     return { retry: false, reason: 'retry_after_too_long' }
     171              :   }
     172              : 
     173            0 :   const ceiling = Math.min(
     174              :     policy.maxDelayMs,
     175              :     policy.baseDelayMs * 2 ** (attempt - 1)
     176              :   )
     177            0 :   const jittered = ceiling / 2 + (random() * ceiling) / 2
     178            0 :   if (retryAfterMs === undefined) return { retry: true, delayMs: jittered }
     179            0 :   const spread = (random() * ceiling) / 2
     180            0 :   return {
     181              :     retry: true,
     182              :     delayMs: Math.min(
     183              :       policy.maxDelayMs,
     184              :       Math.max(jittered, retryAfterMs + spread)
     185              :     )
     186              :   }
     187              : }
     188              : 
     189              : interface RefusedWriteInput extends SignInRefusalInput {
     190              :   readonly method: string
     191              :   readonly policy?: RetryPolicy
     192              :   readonly random?: () => number
     193              : }
     194              : 
     195              : /** The wait before resending a refused write, or `undefined` to send nothing more. */
     196            0 : export async function signInRefusalDelayMs({
     197              :   method,
     198              :   policy = DEFAULT_RETRY_POLICY,
     199              :   random,
     200              :   ...answer
     201              : }: RefusedWriteInput): Promise<number | undefined> {
     202            0 :   if (!canRetrySignInRefusal(method, policy)) return undefined
     203            0 :   const decision = nextRetry({
     204              :     method,
     205              :     status: answer.status,
     206              :     readRetryAfter: answer.readRetryAfter,
     207              :     attempt: 1,
     208              :     policy,
     209              :     random,
     210              :     signInRefusal: true
     211              :   })
     212            0 :   if (!decision.retry) return undefined
     213            0 :   return (await isSignInCheckRefusal(answer)) ? decision.delayMs : undefined
     214              : }
     215              : 
     216            0 : export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
     217            0 :   return new Promise((resolve, reject) => {
     218            0 :     if (signal?.aborted) {
     219            0 :       reject(signal.reason)
     220            0 :       return
     221              :     }
     222            0 :     const onAbort = () => {
     223            0 :       clearTimeout(timer)
     224            0 :       reject(signal?.reason)
     225              :     }
     226            0 :     const timer = setTimeout(() => {
     227            0 :       signal?.removeEventListener('abort', onAbort)
     228            0 :       resolve()
     229              :     }, ms)
     230            0 :     signal?.addEventListener('abort', onAbort, { once: true })
     231              :   })
     232              : }
        

Generated by: LCOV version 2.0-1