Initial Commit

packages/persistence/storage/storage-cdn-rackspace/src/retry-helper/retry-helper.md

@@ -0,0 +1,71 @@
+# retry-helper
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Coordinates retry logic for HTTP requests against Rackspace Cloud Files and the Rackspace CDN management API. Distinguishes transient outcomes (`408`/`425`/`429`/`5xx`) from fatal ones, honours `Retry-After` when the server provides it, and falls back to exponential backoff with a configurable cap. AbortSignal is plumbed through every wait so cancellation lands within milliseconds.
+
+This is structurally similar to `@suaveplan/storage-http`'s retry helper but lives in this package so the adapter can use Rackspace-specific error codes for exhausted retries — a `STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR` surfaces with `container` and `region` context that the generic helper cannot carry.
+
+## Features
+
+- `isTransientStatus(status)` — `408`, `425`, `429`, or any `5xx`.
+- `parseRetryAfter(value, now)` — delta-seconds and HTTP-date forms; capped at `RETRY_AFTER_MAX_DELAY_MS` (60s).
+- `retryWithBackoff(fn, options?)` — runs `fn` up to `maxAttempts`, sleeps between transient outcomes, supports cancellation.
+- Injectable `TimersLike` so tests pin behaviour without real timers.
+- Exhausted retries surface as `STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR`.
+
+## Usage: Basic
+
+```ts
+import { retryWithBackoff } from "@suaveplan/storage-cdn-rackspace";
+
+const response = await retryWithBackoff(() => fetch("https://cdn.example.com/file.bin"));
+```
+
+## Usage: Advanced
+
+```ts
+import { retryWithBackoff } from "@suaveplan/storage-cdn-rackspace";
+
+const response = await retryWithBackoff(
+    () => fetch(url, { signal, headers: { "x-auth-token": token } }),
+    {
+        retry: { maxAttempts: 5, baseDelayMs: 200, maxDelayMs: 10_000, honourRetryAfter: true },
+        timers: fakeTimers,
+        signal,
+    },
+);
+```
+
+## API Reference
+
+### `retryWithBackoff(fn, options?): Promise<Response>`
+
+- `fn: () => Promise<Response>` — attempts the request.
+- `options.retry?` — `maxAttempts`, `baseDelayMs`, `maxDelayMs`, `honourRetryAfter`.
+- `options.timers?` — defaults to `globalThis.setTimeout`/`clearTimeout`.
+- `options.signal?` — cancels the wait between attempts; pre-aborted signal short-circuits with `STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR`.
+
+Returns the last response after exhaustion (caller decides how to surface a final transient status) or throws on synthesised exhaustion (no response, no error captured) / abort.
+
+### `isTransientStatus(status: number): boolean`
+
+True for `408`, `425`, `429`, or any value in `[500, 599]`.
+
+### `parseRetryAfter(value: string | null, now: number): number | undefined`
+
+- Numeric value → delta-seconds × 1000 (capped at `RETRY_AFTER_MAX_DELAY_MS`).
+- HTTP-date → `parseDate − now` (clamped to 0 if in the past, capped on the high side).
+- Missing / empty / unparseable → `undefined`.
+
+## Implementation Notes
+
+- The Retry-After ceiling is **distinct from** `maxDelayMs`; the latter governs exponential backoff, the former specifically defends against the "stall 1 hour" abuse pattern.
+- `sleep` listens to the abort event with `{ once: true }` and tears down both the abort listener and the underlying timer on either resolution path — no listener leaks.
+- The helper is `fetch`-shaped (returns a `Response`) rather than generic; HTTP semantics drive every retry decision, and a generic helper would duplicate the classifier.
+- Synthesised exhaustion (no response, no error) is only reachable when `maxAttempts === 0`; the schema validates `> 0` at the boundary so the path is defensive.
+- Mid-wait abort throws `UPSTREAM_ERROR` (with `cause = signal.reason`) rather than a separate `ABORTED` code because the Rackspace error registry deliberately keeps abort under the upstream umbrella — operators monitoring "request canceled" already filter on `cause`-shape, not a separate code.