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