basalt / drives/src / DriveRetryPolicy

Interface: DriveRetryPolicy

Defined in: drives/src/retry.ts:24

Retry with exponential backoff and full jitter, honouring the provider's own Retry-After when it gave one.

This lives here rather than in each adapter because rate limiting is the one thing every file API does and every adapter would get subtly wrong. Three decisions are worth stating:

• Retry-After wins over our own schedule. A provider that says "wait 42 seconds" has told us what its limiter will accept; retrying at our own pace just burns the remaining quota.
• Full jitter, not fixed backoff. A sync that fans out across a tenant's folders hits the limiter with a herd; identical backoff reconverges the herd on the same instant. random() * delay spreads it.
• Only transient failures retry. A 401 that survived a refresh, a 403, a 404 and every DriveCredentialsInvalidError are terminal — retrying them is how an app turns one broken connection into a sustained attack on the provider and gets the whole application throttled, not just one tenant.

Properties

attempts?

> optional attempts?: number

Defined in: drives/src/retry.ts:26

Total attempts including the first. Default 3.

---

baseDelayMs?

> optional baseDelayMs?: number

Defined in: drives/src/retry.ts:28

First backoff step. Doubles each attempt. Default 500 ms.

---

maxDelayMs?

> optional maxDelayMs?: number

Defined in: drives/src/retry.ts:30

Ceiling for one wait. Default 30 s.

---

maxRetryAfterMs?

> optional maxRetryAfterMs?: number

Defined in: drives/src/retry.ts:39

Longest a provider-supplied Retry-After may hold a worker.

Providers occasionally answer with hours. Blocking a queue worker for an hour is worse than failing the job and letting the queue's own backoff re-run it later, so anything above this gives up instead of sleeping. Default 60 s.

---

onRetry?

> optional onRetry?: (info) => void

Defined in: drives/src/retry.ts:45

Observer for each retry — for metrics and logs. Never receives credentials.

Parameters

info

attempt

number

delayMs

number

error

unknown

Returns

void

---

random?

> optional random?: () => number

Defined in: drives/src/retry.ts:43

Injected randomness (tests). Must return [0, 1).

Returns

number

---

sleep?

> optional sleep?: (ms) => Promise<void>

Defined in: drives/src/retry.ts:41

Injected sleep (tests).

Parameters

ms

number

Returns

Promise<void>