Initial Commit

packages/persistence/storage/storage-cdn-rackspace/README.md

@@ -0,0 +1,114 @@
+# @suaveplan/storage-cdn-rackspace - Rackspace Cloud Files (OpenStack Swift) origin + Rackspace CDN provider for @suaveplan/storage-cdn. v2 identity auth with proactive token refresh, service-catalog endpoint lookup (LON/IAD/DFW/ORD/SYD/HKG), HMAC-SHA1 TempURL signing, CDN purge, Range reads, native streaming, full AbortSignal threading, Retry-After honoured, OTel surface with provider+region attributes.
+
+Rackspace Cloud Files (OpenStack Swift) origin + Rackspace CDN provider for `@suaveplan/storage-cdn`. Full `AbstractStorage` and `CdnAdapter` surface — `get`/`set`/`delete`/`exists`/`getMetadata`/`getPartial`/`createReadStream`/`createWriteStream`/`getSize` against Cloud Files, plus `purge`/`signUrl`/`edgeUrl` against the Rackspace CDN. v2 identity auth with proactive token refresh, service-catalog endpoint lookup (LON/IAD/DFW/ORD/SYD/HKG), HMAC-SHA1 TempURL signing, transient-status retry honouring `Retry-After`, full OTel surface with `provider="rackspace"` and `region` attributes.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [auth-client](./src/auth-client/auth-client.md) — `RackspaceAuthClient` wraps Rackspace identity v2 (`POST /v2.0/tokens`) with the three behaviours every consumer of the…
+  - [auth-client](./src/auth-client/auth-client.md) — `RackspaceAuthClient` wraps Rackspace identity v2 (`POST /v2.0/tokens`) with the three behaviours every consumer of the…
+- [cdn-client](./src/cdn-client/cdn-client.md) — Wraps the two Rackspace CDN management operations the adapter actually needs at runtime: `getCdnMetadata` (HEAD on the…
+  - [cdn-client](./src/cdn-client/cdn-client.md) — Wraps the two Rackspace CDN management operations the adapter actually needs at runtime: `getCdnMetadata` (HEAD on the…
+- [error-codes](./src/error-codes/error-codes.md) — Declares the canonical `STORAGE_CDN_RACKSPACE` error namespace used by every module in this package. Codes are produced…
+  - [error-codes](./src/error-codes/error-codes.md) — Declares the canonical `STORAGE_CDN_RACKSPACE` error namespace used by every module in this package. Codes are produced…
+- [key-sanitizer](./src/key-sanitizer/key-sanitizer.md) — Validates and normalises caller-supplied storage keys before any fetch is issued against Rackspace Cloud Files, and pro…
+  - [key-sanitizer](./src/key-sanitizer/key-sanitizer.md) — Validates and normalises caller-supplied storage keys before any fetch is issued against Rackspace Cloud Files, and pro…
+- [otel](./src/otel/otel.md) — Owns the OpenTelemetry instrument set for `@suaveplan/storage-cdn-rackspace`: counters (`reads_total`, `writes_total`,…
+  - [otel](./src/otel/otel.md) — Owns the OpenTelemetry instrument set for `@suaveplan/storage-cdn-rackspace`: counters (`reads_total`, `writes_total`,…
+- [rackspace-cdn-adapter](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.md) — `RackspaceCdnAdapter` is the concrete `CdnAdapter` implementation that binds `@suaveplan/storage`'s `AbstractStorage` c…
+  - [rackspace-cdn-adapter.base](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.base.md) — `RackspaceCdnAdapterBase` carries the shared internal machinery every `RackspaceCdnAdapter` instance needs: the resolve…
+  - [rackspace-cdn-adapter.cdn-methods](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.cdn-methods.md) — Houses the CDN-side method implementations consumed by `RackspaceCdnAdapter`: `getSize` (via `fetchContainerSize`), `pu…
+  - [rackspace-cdn-adapter.helpers](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.helpers.md) — Internal helpers used by `RackspaceCdnAdapter` and its sibling ops/streams modules. Splits boundary concerns (option pa…
+  - [rackspace-cdn-adapter](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.md) — `RackspaceCdnAdapter` is the concrete `CdnAdapter` implementation that binds `@suaveplan/storage`'s `AbstractStorage` c…
+  - [rackspace-cdn-adapter.ops](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.ops.md) — Reusable Cloud Files HTTP operations used by `RackspaceCdnAdapter`: object GET (`objectGet`), HEAD (`objectHead`), PUT…
+  - [rackspace-cdn-adapter.streams](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.streams.md) — Builds the `ReadableStream` and `WritableStream` instances `RackspaceCdnAdapter` returns from `createReadStream` / `cre…
+- [registry](./src/registry/registry.md) — Module-augments `@suaveplan/storage/factory`'s `StorageProviderRegistry` and `StorageProviderConfig` to add the `"racks…
+  - [registry](./src/registry/registry.md) — Module-augments `@suaveplan/storage/factory`'s `StorageProviderRegistry` and `StorageProviderConfig` to add the `"racks…
+- [retry-helper](./src/retry-helper/retry-helper.md) — Coordinates retry logic for HTTP requests against Rackspace Cloud Files and the Rackspace CDN management API. Distingui…
+  - [retry-helper](./src/retry-helper/retry-helper.md) — Coordinates retry logic for HTTP requests against Rackspace Cloud Files and the Rackspace CDN management API. Distingui…
+- [temp-url](./src/temp-url/temp-url.md) — Computes Swift TempURL signatures for short-lived signed URLs against Rackspace Cloud Files. The OpenStack Swift TempUR…
+  - [temp-url](./src/temp-url/temp-url.md) — Computes Swift TempURL signatures for short-lived signed URLs against Rackspace Cloud Files. The OpenStack Swift TempUR…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/storage-cdn-rackspace
+```
+
+## Quick start
+
+```ts
+import { RackspaceCdnAdapter } from "@suaveplan/storage-cdn-rackspace";
+
+const storage = new RackspaceCdnAdapter({
+    originBaseUrl: "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/",
+    edgeBaseUrl: "https://abc.r88.cf6.rackcdn.com/",
+    username: process.env["RAX_USER"]!,
+    apiKey: process.env["RAX_KEY"]!,
+    region: "LON",
+    container: "myc",
+    tempUrlKey: process.env["RAX_TEMPURL_KEY"]!,
+});
+
+await storage.set("photos/a.jpg", bytes);
+await storage.purge("photos/a.jpg");
+const signed = await storage.signUrl("photos/a.jpg", { ttlSeconds: 300, method: "GET" });
+```
+
+## Factory registration
+
+```ts
+import { registerRackspaceCdnProvider } from "@suaveplan/storage-cdn-rackspace";
+import { createStorage } from "@suaveplan/storage/factory";
+
+registerRackspaceCdnProvider();
+const storage = createStorage({ type: "rackspace-cdn", config });
+```
+
+## Modules
+
+- [error-codes](./src/error-codes.md) — `STORAGE_CDN_RACKSPACE_CODES` registry + `StorageCdnRackspaceError`.
+- [constants](./src/constants/constants.md) — region whitelist, default auth URL, retry defaults.
+- [auth-client](./src/auth-client/auth-client.md) — v2 identity auth, token cache, service-catalog lookup, proactive refresh.
+- [cdn-client](./src/cdn-client/cdn-client.md) — `getCdnMetadata`, `purgeObject`.
+- [temp-url](./src/temp-url/temp-url.md) — HMAC-SHA1 TempURL signer via WebCrypto.
+- [key-sanitizer](./src/key-sanitizer/key-sanitizer.md) — strict key validation + per-segment encoder.
+- [retry-helper](./src/retry-helper/retry-helper.md) — transient classifier + `Retry-After` honour.
+- [otel](./src/otel/otel.md) — meters, histograms, counters, tracer.
+- [rackspace-cdn-adapter](./src/rackspace-cdn-adapter/rackspace-cdn-adapter.md) — the main `RackspaceCdnAdapter` class.
+- [registry](./src/registry/registry.md) — module-augmentation slot for `createStorage({ type: "rackspace-cdn", ... })`.
+
+## Capabilities matrix
+
+```ts
+{
+    partialReads: true,
+    partialWrites: false,
+    nativeStreams: true,
+    atomicWrites: false,
+    contentAddressable: false,
+    cdn: {
+        cdnPurge: true,
+        cdnPrefixPurge: false,
+        cdnSignedUrls: true,
+        cdnOriginUploads: true,
+    },
+}
+```
+
+## Features
+
+- **Universal purity** — no `node:*` or DOM-only imports.
+- **Full Cloud Files surface** — origin GET/PUT/DELETE/HEAD with Range, native streaming, AbortSignal.
+- **CDN integration** — purge, signed (TempURL) URLs, edge URL composition.
+- **Proactive auth refresh** — token re-issued five minutes before expiry; concurrent calls deduplicated.
+- **Service-catalog endpoint resolution** — works against any region in the LON/IAD/DFW/ORD/SYD/HKG set; misconfigured region surfaces as `STORAGE_CDN_RACKSPACE.REGION_NOT_IN_CATALOG`.
+- **Retry on transient outcomes** — `408`/`425`/`429`/`5xx` retried with `Retry-After` honoured.
+- **OTel built-in** — `storage_cdn_rackspace.*` instruments with `provider="rackspace"` and `region` attributes for cross-provider dashboards.
+- **100 / 100 / 100 / 100 Istanbul coverage**.
+
+## License
+
+MIT — see `LICENSE` at the repo root.
+

packages/persistence/storage/storage-cdn-rackspace/package.json

@@ -0,0 +1,158 @@
+{
+	"name": "@suaveplan/storage-cdn-rackspace",
+	"version": "0.1.0",
+	"type": "module",
+	"sideEffects": false,
+	"description": "Rackspace Cloud Files (OpenStack Swift) origin + Rackspace CDN provider for @suaveplan/storage-cdn. v2 identity auth with proactive token refresh, service-catalog endpoint lookup (LON/IAD/DFW/ORD/SYD/HKG), HMAC-SHA1 TempURL signing, CDN purge, Range reads, native streaming, full AbortSignal threading, Retry-After honoured, OTel surface with provider+region attributes.",
+	"license": "MIT",
+	"author": "Suaveplan Team",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		},
+		"./rackspace-cdn-adapter": {
+			"import": {
+				"types": "./dist/rackspace-cdn-adapter/index.d.ts",
+				"default": "./dist/rackspace-cdn-adapter/rackspace-cdn-adapter.js"
+			},
+			"require": {
+				"types": "./dist/rackspace-cdn-adapter/index.d.ts",
+				"default": "./dist/rackspace-cdn-adapter/rackspace-cdn-adapter.js"
+			}
+		},
+		"./auth-client": {
+			"import": {
+				"types": "./dist/auth-client/index.d.ts",
+				"default": "./dist/auth-client/auth-client.js"
+			},
+			"require": {
+				"types": "./dist/auth-client/index.d.ts",
+				"default": "./dist/auth-client/auth-client.js"
+			}
+		},
+		"./cdn-client": {
+			"import": {
+				"types": "./dist/cdn-client/index.d.ts",
+				"default": "./dist/cdn-client/cdn-client.js"
+			},
+			"require": {
+				"types": "./dist/cdn-client/index.d.ts",
+				"default": "./dist/cdn-client/cdn-client.js"
+			}
+		},
+		"./temp-url": {
+			"import": {
+				"types": "./dist/temp-url/index.d.ts",
+				"default": "./dist/temp-url/temp-url.js"
+			},
+			"require": {
+				"types": "./dist/temp-url/index.d.ts",
+				"default": "./dist/temp-url/temp-url.js"
+			}
+		},
+		"./key-sanitizer": {
+			"import": {
+				"types": "./dist/key-sanitizer/index.d.ts",
+				"default": "./dist/key-sanitizer/key-sanitizer.js"
+			},
+			"require": {
+				"types": "./dist/key-sanitizer/index.d.ts",
+				"default": "./dist/key-sanitizer/key-sanitizer.js"
+			}
+		},
+		"./retry-helper": {
+			"import": {
+				"types": "./dist/retry-helper/index.d.ts",
+				"default": "./dist/retry-helper/retry-helper.js"
+			},
+			"require": {
+				"types": "./dist/retry-helper/index.d.ts",
+				"default": "./dist/retry-helper/retry-helper.js"
+			}
+		},
+		"./otel": {
+			"import": {
+				"types": "./dist/otel/index.d.ts",
+				"default": "./dist/otel/otel.js"
+			},
+			"require": {
+				"types": "./dist/otel/index.d.ts",
+				"default": "./dist/otel/otel.js"
+			}
+		},
+		"./registry": {
+			"import": {
+				"types": "./dist/registry/index.d.ts",
+				"default": "./dist/registry/registry.js"
+			},
+			"require": {
+				"types": "./dist/registry/index.d.ts",
+				"default": "./dist/registry/registry.js"
+			}
+		},
+		"./types": {
+			"import": {
+				"types": "./dist/types/index.d.ts",
+				"default": "./dist/types/index.js"
+			},
+			"require": {
+				"types": "./dist/types/index.d.ts",
+				"default": "./dist/types/index.js"
+			}
+		}
+	},
+	"scripts": {
+		"build": "vite build",
+		"test": "vitest run --passWithNoTests",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage --passWithNoTests",
+		"lint": "bunx biome check src/",
+		"lint:fix": "bunx biome lint --fix --unsafe --max-diagnostics 500 src/",
+		"format": "bunx biome format --write --max-diagnostics 500 src/",
+		"check": "bunx biome check --write --unsafe --max-diagnostics 500 src/",
+		"typecheck": "bunx tsc --noEmit --composite false -p tsconfig.lib.json",
+		"docs:check": "bun run ../../../../scripts/docs-check.ts ."
+	},
+	"dependencies": {
+		"@opentelemetry/api": "catalog:observability",
+		"@suaveplan/error": "workspace:^",
+		"@suaveplan/retry": "workspace:^",
+		"@suaveplan/storage": "workspace:^",
+		"@suaveplan/storage-cdn": "workspace:^",
+		"@suaveplan/storage-http": "workspace:^",
+		"@suaveplan/types": "workspace:^",
+		"tslib": "catalog:build",
+		"zod": "catalog:forms"
+	},
+	"devDependencies": {
+		"@suaveplan/testing": "workspace:^",
+		"@types/node": "catalog:",
+		"@vitest/coverage-istanbul": "catalog:testing",
+		"fast-check": "catalog:testing",
+		"mitata": "catalog:testing",
+		"typescript": "catalog:",
+		"vite": "catalog:build",
+		"vite-plugin-dts": "catalog:build",
+		"vitest": "catalog:testing"
+	},
+	"publishConfig": {
+		"registry": "https://npmjs.fq.io/",
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md"
+	]
+}

packages/persistence/storage/storage-cdn-rackspace/src/auth-client/auth-client.md

@@ -0,0 +1,74 @@
+# auth-client
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`RackspaceAuthClient` wraps Rackspace identity v2 (`POST /v2.0/tokens`) with the three behaviours every consumer of the storage / CDN endpoints needs: a cached token reused across requests, a proactive refresh that fires before the documented expiry, and a service-catalog lookup that resolves the per-region `cloudFiles` and `cloudFilesCDN` endpoints in one round-trip. The adapter wires this client behind every public call so application code never thinks about token state or endpoint discovery.
+
+## Features
+
+- Single-shot auth — POSTs `apiKeyCredentials` and caches the result.
+- Token cache reuses an in-memory `CachedToken` across calls.
+- Proactive refresh five minutes before the documented expiry — no caller is blocked waiting for an in-flight re-auth on a near-expired token.
+- Concurrent-call deduplication: parallel `getToken` calls share one auth request.
+- Region-aware service-catalog lookup; rejects with `REGION_NOT_IN_CATALOG` when the response lacks an entry for the configured region.
+- `invalidate()` hook so an outer 401 handler can drop the cache before re-trying.
+- AbortSignal threaded into the auth fetch.
+
+## Usage: Basic
+
+```ts
+import { RackspaceAuthClient } from "@suaveplan/storage-cdn-rackspace";
+
+const auth = new RackspaceAuthClient({ username: "me", apiKey: "secret" });
+const { tokenId, storageEndpoint, cdnEndpoint } = await auth.getToken();
+```
+
+## Usage: Advanced
+
+```ts
+import { RackspaceAuthClient } from "@suaveplan/storage-cdn-rackspace";
+
+const auth = new RackspaceAuthClient({
+    authUrl: "https://lon.identity.api.rackspacecloud.com/v2.0",
+    username: process.env["RAX_USER"]!,
+    apiKey: process.env["RAX_KEY"]!,
+    region: "LON",
+    fetch: customFetch,
+    now: () => clock.now(),
+});
+
+async function withFreshToken<T>(op: (tokenId: string) => Promise<T>): Promise<T> {
+    try {
+        const { tokenId } = await auth.getToken();
+        return await op(tokenId);
+    } catch (err) {
+        auth.invalidate();
+        const { tokenId } = await auth.getToken();
+        return op(tokenId); // single retry
+    }
+}
+```
+
+## API Reference
+
+### `class RackspaceAuthClient`
+
+- `constructor(options)` — `username`, `apiKey` required; `authUrl`, `region`, `fetch`, `now` optional with sensible defaults (`DEFAULT_AUTH_URL`, `"LON"`, `globalThis.fetch`, `Date.now`).
+- `getToken(signal?): Promise<CachedToken>` — returns the cached token when still fresh; otherwise authenticates.
+- `invalidate(): void` — drops the cache; the next `getToken` re-auths.
+
+### `CachedToken`
+
+`{ tokenId, expiresMs, storageEndpoint, cdnEndpoint, region }` — both endpoints carry a trailing slash so consumers can compose URLs via `new URL(key, endpoint)` safely.
+
+## Implementation Notes
+
+- Concurrent dedup uses a single `#pending` promise; the first caller initiates the request, subsequent callers await the same promise. The promise is cleared in `finally` so a rejected auth doesn't poison future calls.
+- Proactive refresh is calculated against `now()` rather than wall-clock time so tests can pin the boundary precisely with an injected `now`.
+- The trailing-slash invariant on endpoints is enforced inside `resolveEndpoints` — the Rackspace catalog historically returns URLs without trailing slashes in some regions, and downstream `new URL(rel, base)` would otherwise truncate the last path segment.
+- `invalidate()` does not affect any in-flight `#pending` request — it only clears `#cache`. This matches the documented "re-auth once, retry once" pattern from the adapter's 401 recovery path.
+- The auth request body uses the documented `RAX-KSKEY:apiKeyCredentials` shape — Rackspace's API-key variant of identity v2. Username/password is supported by identity v2 but is not the recommended Rackspace path.

packages/persistence/storage/storage-cdn-rackspace/src/auth-client/auth-client.test.ts

@@ -0,0 +1,317 @@
+import { describe, expect, it, vi } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    type StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { RackspaceAuthClient } from "./auth-client.js";
+
+const lonAuthBody = (expiresIso: string) => ({
+    access: {
+        token: { id: "tok-123", expires: expiresIso },
+        serviceCatalog: [
+            {
+                name: "cloudFiles",
+                type: "object-store",
+                endpoints: [
+                    {
+                        region: "LON",
+                        publicURL:
+                            "https://storage101.lon3.clouddrive.com/v1/AUTH_acc",
+                    },
+                    {
+                        region: "IAD",
+                        publicURL:
+                            "https://storage101.iad3.clouddrive.com/v1/AUTH_acc",
+                    },
+                ],
+            },
+            {
+                name: "cloudFilesCDN",
+                type: "rax:object-cdn",
+                endpoints: [
+                    {
+                        region: "LON",
+                        publicURL: "https://cdn3.clouddrive.com/v1/AUTH_acc",
+                    },
+                ],
+            },
+        ],
+    },
+});
+
+function jsonResponse(body: unknown, status = 200): Response {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+
+describe("RackspaceAuthClient.getToken", () => {
+    it("resolves LON region from service catalog", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        const token = await client.getToken();
+        expect(token.tokenId).toBe("tok-123");
+        expect(token.storageEndpoint).toMatch(/lon3\.clouddrive\.com.*\/$/);
+        expect(token.cdnEndpoint).toMatch(/cdn3\.clouddrive\.com.*\/$/);
+    });
+
+    it("throws REGION_NOT_IN_CATALOG when region absent", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "SYD",
+            fetch: fetchFn,
+        });
+        try {
+            await client.getToken();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.REGION_NOT_IN_CATALOG
+            );
+        }
+    });
+
+    it("reuses cached token within validity window", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        await client.getToken();
+        await client.getToken();
+        await client.getToken();
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("refreshes proactively five minutes before expiry", {
+        timeout: 5000,
+    }, async () => {
+        let now = 1_000_000;
+        const expiresAt = now + 5 * 60 * 1000 + 1000; // expires in 5m + 1s
+        const future = new Date(expiresAt).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+            now: () => now,
+        });
+        await client.getToken();
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+        // Advance past the proactive-refresh threshold.
+        now += 2000;
+        await client.getToken();
+        expect(fetchFn).toHaveBeenCalledTimes(2);
+    });
+
+    it("re-auths exactly once on 401 and retries", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        // First auth populates the cache.
+        await client.getToken();
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+        // External 401 path: caller invalidates, next getToken re-auths.
+        client.invalidate();
+        await client.getToken();
+        expect(fetchFn).toHaveBeenCalledTimes(2);
+    });
+
+    it("surfaces AUTH_FAILED on non-2xx auth response", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 401 }));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        try {
+            await client.getToken();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED
+            );
+        }
+    });
+
+    it("deduplicates concurrent auth requests", { timeout: 5000 }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            return jsonResponse(lonAuthBody(future));
+        });
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        await Promise.all([
+            client.getToken(),
+            client.getToken(),
+            client.getToken(),
+        ]);
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("forwards AbortSignal into the auth fetch", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        const c = new AbortController();
+        await client.getToken(c.signal);
+        const init = fetchFn.mock.calls[0]?.[1] as RequestInit;
+        expect(init.signal).toBe(c.signal);
+    });
+
+    it("uses default authUrl + now when not supplied", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const fetchFn = vi.fn(async () => jsonResponse(lonAuthBody(future)));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            fetch: fetchFn,
+        });
+        const token = await client.getToken();
+        expect(token.region).toBe("LON");
+    });
+
+    it("default fetch routes through globalThis.fetch when omitted", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const spy = vi
+            .spyOn(globalThis, "fetch")
+            .mockResolvedValue(jsonResponse(lonAuthBody(future)));
+        try {
+            const client = new RackspaceAuthClient({
+                username: "u",
+                apiKey: "k",
+            });
+            const token = await client.getToken();
+            expect(token.tokenId).toBe("tok-123");
+            expect(spy).toHaveBeenCalledTimes(1);
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it("throws REGION_NOT_IN_CATALOG when CDN service is missing entirely", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const body = {
+            access: {
+                token: { id: "tok", expires: future },
+                serviceCatalog: [
+                    {
+                        name: "cloudFiles",
+                        type: "object-store",
+                        endpoints: [
+                            {
+                                region: "LON",
+                                publicURL: "https://s.example.com/v1/AUTH_a",
+                            },
+                        ],
+                    },
+                ],
+            },
+        };
+        const fetchFn = vi.fn(async () => jsonResponse(body));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        try {
+            await client.getToken();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.REGION_NOT_IN_CATALOG
+            );
+        }
+    });
+
+    it("keeps trailing slash when publicURL already ends with one", {
+        timeout: 5000,
+    }, async () => {
+        const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        const body = {
+            access: {
+                token: { id: "tok", expires: future },
+                serviceCatalog: [
+                    {
+                        name: "cloudFiles",
+                        type: "object-store",
+                        endpoints: [
+                            {
+                                region: "LON",
+                                publicURL: "https://s.example.com/v1/AUTH_a/",
+                            },
+                        ],
+                    },
+                    {
+                        name: "cloudFilesCDN",
+                        type: "rax:object-cdn",
+                        endpoints: [
+                            {
+                                region: "LON",
+                                publicURL: "https://c.example.com/v1/AUTH_a/",
+                            },
+                        ],
+                    },
+                ],
+            },
+        };
+        const fetchFn = vi.fn(async () => jsonResponse(body));
+        const client = new RackspaceAuthClient({
+            username: "u",
+            apiKey: "k",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        const token = await client.getToken();
+        expect(token.storageEndpoint).toBe("https://s.example.com/v1/AUTH_a/");
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/auth-client/auth-client.ts

@@ -0,0 +1,151 @@
+import type { FetchLike } from "@suaveplan/types";
+import {
+    CDN_SERVICE_NAME,
+    DEFAULT_AUTH_URL,
+    DEFAULT_REGION,
+    type RackspaceRegion,
+    STORAGE_SERVICE_NAME,
+    TOKEN_REFRESH_LEAD_MS,
+} from "../constants/constants.js";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import type {
+    CachedToken,
+    RackspaceAuthResponse,
+    ServiceCatalogEntry,
+} from "../types/auth.types.js";
+
+export interface RackspaceAuthClientOptions {
+    authUrl?: string;
+    username: string;
+    apiKey: string;
+    region?: RackspaceRegion;
+    fetch?: FetchLike;
+    now?: () => number;
+}
+
+/**
+ * v2 identity auth with proactive token refresh and service-catalog
+ * endpoint lookup. The client caches `(tokenId, expires, storageEndpoint,
+ * cdnEndpoint)` per region; callers ask for an endpoint and the client
+ * decides whether to re-auth based on the cached expiry.
+ */
+export class RackspaceAuthClient {
+    readonly #authUrl: string;
+    readonly #username: string;
+    readonly #apiKey: string;
+    readonly #region: RackspaceRegion;
+    readonly #fetch: FetchLike;
+    readonly #now: () => number;
+    #cache: CachedToken | undefined;
+    #pending: Promise<CachedToken> | undefined;
+
+    public constructor(options: RackspaceAuthClientOptions) {
+        this.#authUrl = options.authUrl ?? DEFAULT_AUTH_URL;
+        this.#username = options.username;
+        this.#apiKey = options.apiKey;
+        this.#region = options.region ?? DEFAULT_REGION;
+        this.#fetch =
+            options.fetch ??
+            ((input, init) =>
+                globalThis.fetch(
+                    input as Parameters<typeof globalThis.fetch>[0],
+                    init
+                ));
+        this.#now = options.now ?? (() => Date.now());
+    }
+
+    /** Returns the current token, re-authing only when the cache is stale. */
+    public async getToken(signal?: AbortSignal): Promise<CachedToken> {
+        const cache = this.#cache;
+        if (
+            cache !== undefined &&
+            cache.expiresMs - TOKEN_REFRESH_LEAD_MS > this.#now()
+        ) {
+            return cache;
+        }
+        if (this.#pending !== undefined) return this.#pending;
+        this.#pending = this.#auth(signal).finally(() => {
+            this.#pending = undefined;
+        });
+        return this.#pending;
+    }
+
+    /** Invalidate the cache — used by the adapter's 401 recovery path. */
+    public invalidate(): void {
+        this.#cache = undefined;
+    }
+
+    async #auth(signal: AbortSignal | undefined): Promise<CachedToken> {
+        const init: RequestInit = {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                auth: {
+                    "RAX-KSKEY:apiKeyCredentials": {
+                        username: this.#username,
+                        apiKey: this.#apiKey,
+                    },
+                },
+            }),
+        };
+        if (signal !== undefined) init.signal = signal;
+        const url = `${this.#authUrl.replace(/\/+$/, "")}/tokens`;
+        const response = await this.#fetch(url, init);
+        if (!response.ok) {
+            throw new StorageCdnRackspaceError(
+                STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED,
+                `identity v2 auth failed (${response.status})`,
+                { httpStatus: response.status, region: this.#region }
+            );
+        }
+        const body = (await response.json()) as RackspaceAuthResponse;
+        const cached = resolveEndpoints(body, this.#region);
+        this.#cache = cached;
+        return cached;
+    }
+}
+
+function resolveEndpoints(
+    body: RackspaceAuthResponse,
+    region: RackspaceRegion
+): CachedToken {
+    const access = body.access;
+    const storage = findEndpoint(
+        access.serviceCatalog,
+        STORAGE_SERVICE_NAME,
+        region
+    );
+    const cdn = findEndpoint(access.serviceCatalog, CDN_SERVICE_NAME, region);
+    if (storage === undefined || cdn === undefined) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.REGION_NOT_IN_CATALOG,
+            `region ${region} not in service catalog`,
+            { region }
+        );
+    }
+    return {
+        tokenId: access.token.id,
+        expiresMs: Date.parse(access.token.expires),
+        storageEndpoint: ensureTrailingSlash(storage),
+        cdnEndpoint: ensureTrailingSlash(cdn),
+        region,
+    };
+}
+
+function findEndpoint(
+    catalog: ServiceCatalogEntry[],
+    serviceName: string,
+    region: RackspaceRegion
+): string | undefined {
+    const entry = catalog.find((e) => e.name === serviceName);
+    if (entry === undefined) return undefined;
+    const match = entry.endpoints.find((ep) => ep.region === region);
+    return match?.publicURL;
+}
+
+function ensureTrailingSlash(value: string): string {
+    return value.endsWith("/") ? value : `${value}/`;
+}

packages/persistence/storage/storage-cdn-rackspace/src/auth-client/index.ts

@@ -0,0 +1,2 @@
+export type { RackspaceAuthClientOptions } from "./auth-client.js";
+export { RackspaceAuthClient } from "./auth-client.js";

packages/persistence/storage/storage-cdn-rackspace/src/cdn-client/cdn-client.md

@@ -0,0 +1,66 @@
+# cdn-client
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Wraps the two Rackspace CDN management operations the adapter actually needs at runtime: `getCdnMetadata` (HEAD on the container's CDN URL to fetch `X-Cdn-Uri`, `X-Cdn-Ssl-Uri`, `X-Ttl`, `X-Cdn-Enabled`) and `purgeObject` (DELETE against the per-object CDN URL to invalidate the edge cache). Both functions accept a `CdnClientContext` that bundles the resolved `cdnEndpoint`, `token`, `container`, and `region`, so the calling code (the adapter) constructs the bundle once per operation and never has to thread the fields by hand.
+
+## Features
+
+- Two focused functions — no class to instantiate.
+- `getCdnMetadata` returns `null` on 404, the parsed metadata otherwise.
+- `purgeObject` resolves on 2xx and on 404 (already absent), throws `PURGE_RATE_LIMITED` on 429, and `UPSTREAM_ERROR` on other non-ok statuses.
+- AbortSignal threaded into both fetch invocations.
+- All errors carry `container`/`region`/`httpStatus` for diagnostics.
+
+## Usage: Basic
+
+```ts
+import { purgeObject } from "@suaveplan/storage-cdn-rackspace";
+
+await purgeObject(
+    { fetch, token: "tok", cdnEndpoint: "https://cdn.example.com/", container: "myc", region: "LON" },
+    "a%2Fb.bin",
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { getCdnMetadata, purgeObject } from "@suaveplan/storage-cdn-rackspace";
+
+async function purgeAfterUpload(ctx, key: string) {
+    const meta = await getCdnMetadata(ctx);
+    if (meta?.cdnEnabled !== true) return; // nothing to invalidate
+    await purgeObject(ctx, encodeURIComponent(key));
+}
+```
+
+## API Reference
+
+### `interface CdnClientContext`
+
+`{ fetch, token, cdnEndpoint, container, region }` — `cdnEndpoint` is the management endpoint resolved from the service catalog.
+
+### `interface CdnContainerMetadata`
+
+`{ cdnUri, cdnSslUri, ttl, cdnEnabled }` — parsed verbatim from `X-Cdn-*` headers; missing headers default to empty string / 0 / false.
+
+### `getCdnMetadata(ctx, signal?): Promise<CdnContainerMetadata | null>`
+
+Returns `null` on 404, parsed metadata on 2xx, throws on other non-ok.
+
+### `purgeObject(ctx, encodedKey, signal?): Promise<void>`
+
+Issues `DELETE <cdnEndpoint><container>/<encodedKey>`. Resolves on 2xx or 404. Throws `STORAGE_CDN_RACKSPACE.PURGE_RATE_LIMITED` on 429. Other non-ok statuses surface as `UPSTREAM_ERROR`.
+
+## Implementation Notes
+
+- The `encodedKey` parameter is already URL-encoded by the caller — this module does not re-encode, which would double-escape values.
+- 404 on purge is treated as success because Rackspace returns 404 for objects already evicted or never CDN-served; surfacing that as an error would force every caller to handle it specially.
+- 429 is its own error code rather than `UPSTREAM_ERROR` because the management API has historically been rate-limited at ~25/min and operators want a dedicated alert rule.
+- `cdnEnabled` parsing is case-insensitive (`true`/`True`/`TRUE`) — Rackspace has been inconsistent across documentation versions.
+- The functions are intentionally not bundled into a class because there is no state worth caching across calls — the auth client already caches everything that survives between operations.

packages/persistence/storage/storage-cdn-rackspace/src/cdn-client/cdn-client.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    type StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { getCdnMetadata, purgeObject } from "./cdn-client.js";
+
+const baseCtx = {
+    token: "tok",
+    cdnEndpoint: "https://cdn.example.com/",
+    container: "myc",
+    region: "LON",
+};
+
+describe("purgeObject", () => {
+    it("purge resolves on 204", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 204 }));
+        await purgeObject({ fetch: fetchFn, ...baseCtx }, "a/b.bin");
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("resolves on 404 (already absent)", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 404 }));
+        await purgeObject({ fetch: fetchFn, ...baseCtx }, "k");
+    });
+
+    it("purge surfaces PURGE_RATE_LIMITED on persistent 429", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 429 }));
+        try {
+            await purgeObject({ fetch: fetchFn, ...baseCtx }, "k");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.PURGE_RATE_LIMITED
+            );
+        }
+    });
+
+    it("surfaces UPSTREAM_ERROR on other non-ok", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 500 }));
+        try {
+            await purgeObject({ fetch: fetchFn, ...baseCtx }, "k");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("threads AbortSignal into fetch init", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 204 }));
+        const c = new AbortController();
+        await purgeObject({ fetch: fetchFn, ...baseCtx }, "k", c.signal);
+        const init = fetchFn.mock.calls[0]?.[1] as RequestInit;
+        expect(init.signal).toBe(c.signal);
+    });
+});
+
+describe("getCdnMetadata", () => {
+    it("parses documented headers", { timeout: 5000 }, async () => {
+        const headers = new Headers({
+            "x-cdn-uri": "http://abc.r88.cf6.rackcdn.com",
+            "x-cdn-ssl-uri": "https://abc.r88.cf6.rackcdn.com",
+            "x-ttl": "604800",
+            "x-cdn-enabled": "True",
+        });
+        const fetchFn = vi.fn(
+            async () => new Response(null, { status: 204, headers })
+        );
+        const meta = await getCdnMetadata({ fetch: fetchFn, ...baseCtx });
+        expect(meta?.cdnSslUri).toBe("https://abc.r88.cf6.rackcdn.com");
+        expect(meta?.ttl).toBe(604800);
+        expect(meta?.cdnEnabled).toBe(true);
+    });
+
+    it("returns null on 404", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 404 }));
+        expect(await getCdnMetadata({ fetch: fetchFn, ...baseCtx })).toBeNull();
+    });
+
+    it("throws on other non-ok", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 500 }));
+        try {
+            await getCdnMetadata({ fetch: fetchFn, ...baseCtx });
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("defaults missing headers", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 204 }));
+        const meta = await getCdnMetadata({ fetch: fetchFn, ...baseCtx });
+        expect(meta?.cdnSslUri).toBe("");
+        expect(meta?.ttl).toBe(0);
+        expect(meta?.cdnEnabled).toBe(false);
+    });
+
+    it("threads AbortSignal into the HEAD fetch", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 204 }));
+        const c = new AbortController();
+        await getCdnMetadata({ fetch: fetchFn, ...baseCtx }, c.signal);
+        const init = fetchFn.mock.calls[0]?.[1] as RequestInit;
+        expect(init.signal).toBe(c.signal);
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/cdn-client/cdn-client.ts

@@ -0,0 +1,90 @@
+import type { FetchLike } from "@suaveplan/types";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+
+export interface CdnContainerMetadata {
+    cdnUri: string;
+    cdnSslUri: string;
+    ttl: number;
+    cdnEnabled: boolean;
+}
+
+export interface CdnClientContext {
+    fetch: FetchLike;
+    token: string;
+    cdnEndpoint: string;
+    container: string;
+    region: string;
+}
+
+/** Issue a HEAD on the container's CDN endpoint and parse the documented headers. */
+export async function getCdnMetadata(
+    ctx: CdnClientContext,
+    signal?: AbortSignal
+): Promise<CdnContainerMetadata | null> {
+    const url = `${ctx.cdnEndpoint}${encodeURIComponent(ctx.container)}`;
+    const init: RequestInit = {
+        method: "HEAD",
+        headers: { "x-auth-token": ctx.token },
+    };
+    if (signal !== undefined) init.signal = signal;
+    const response = await ctx.fetch(url, init);
+    if (response.status === 404) return null;
+    if (!response.ok) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+            `CDN metadata HEAD ${response.status}`,
+            {
+                container: ctx.container,
+                region: ctx.region,
+                httpStatus: response.status,
+            }
+        );
+    }
+    return {
+        cdnUri: response.headers.get("x-cdn-uri") ?? "",
+        cdnSslUri: response.headers.get("x-cdn-ssl-uri") ?? "",
+        ttl: Number.parseInt(response.headers.get("x-ttl") ?? "0", 10),
+        cdnEnabled:
+            (response.headers.get("x-cdn-enabled") ?? "false").toLowerCase() ===
+            "true",
+    };
+}
+
+/**
+ * Issue a `DELETE` on `<cdnEndpoint>/<container>/<encodedKey>` to invalidate
+ * the edge cache for one object. `2xx` → resolves; `404` → resolves (already
+ * absent); `429` → throws `PURGE_RATE_LIMITED`; other → `UPSTREAM_ERROR`.
+ */
+export async function purgeObject(
+    ctx: CdnClientContext,
+    encodedKey: string,
+    signal?: AbortSignal
+): Promise<void> {
+    const url = `${ctx.cdnEndpoint}${encodeURIComponent(ctx.container)}/${encodedKey}`;
+    const init: RequestInit = {
+        method: "DELETE",
+        headers: { "x-auth-token": ctx.token },
+    };
+    if (signal !== undefined) init.signal = signal;
+    const response = await ctx.fetch(url, init);
+    if (response.status === 404 || response.ok) return;
+    if (response.status === 429) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.PURGE_RATE_LIMITED,
+            "Rackspace CDN purge rate-limited",
+            { container: ctx.container, region: ctx.region, httpStatus: 429 }
+        );
+    }
+    throw new StorageCdnRackspaceError(
+        STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+        `CDN purge upstream ${response.status}`,
+        {
+            container: ctx.container,
+            region: ctx.region,
+            httpStatus: response.status,
+        }
+    );
+}

packages/persistence/storage/storage-cdn-rackspace/src/cdn-client/index.ts

@@ -0,0 +1,8 @@
+export type {
+    CdnClientContext,
+    CdnContainerMetadata,
+} from "./cdn-client.js";
+export {
+    getCdnMetadata,
+    purgeObject,
+} from "./cdn-client.js";

packages/persistence/storage/storage-cdn-rackspace/src/constants/constants.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    CDN_SERVICE_NAME,
+    DEFAULT_AUTH_URL,
+    DEFAULT_REGION,
+    DEFAULT_RETRY_BASE_DELAY_MS,
+    DEFAULT_RETRY_MAX_ATTEMPTS,
+    DEFAULT_RETRY_MAX_DELAY_MS,
+    MAX_KEY_LENGTH,
+    RACKSPACE_REGIONS,
+    RETRY_AFTER_MAX_DELAY_MS,
+    STORAGE_SERVICE_NAME,
+    TOKEN_REFRESH_LEAD_MS,
+    TRANSIENT_HTTP_STATUSES,
+} from "./constants.js";
+
+describe("constants", () => {
+    it("expose the documented defaults", { timeout: 5000 }, () => {
+        expect(DEFAULT_AUTH_URL).toContain("identity.api.rackspacecloud.com");
+        expect(DEFAULT_REGION).toBe("LON");
+        expect(STORAGE_SERVICE_NAME).toBe("cloudFiles");
+        expect(CDN_SERVICE_NAME).toBe("cloudFilesCDN");
+        expect(RACKSPACE_REGIONS).toContain("LON");
+        expect(TOKEN_REFRESH_LEAD_MS).toBe(5 * 60 * 1000);
+        expect(MAX_KEY_LENGTH).toBe(2048);
+        expect(DEFAULT_RETRY_MAX_ATTEMPTS).toBeGreaterThan(0);
+        expect(DEFAULT_RETRY_BASE_DELAY_MS).toBeGreaterThan(0);
+        expect(DEFAULT_RETRY_MAX_DELAY_MS).toBeGreaterThan(
+            DEFAULT_RETRY_BASE_DELAY_MS
+        );
+        expect(RETRY_AFTER_MAX_DELAY_MS).toBe(60_000);
+        expect(TRANSIENT_HTTP_STATUSES.has(429)).toBe(true);
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/constants/constants.ts

@@ -0,0 +1,40 @@
+/** Rackspace identity-v2 default auth endpoint (LON-region affinity). */
+export const DEFAULT_AUTH_URL =
+    "https://lon.identity.api.rackspacecloud.com/v2.0";
+
+/** Supported region codes from the Cloud Files service catalog. */
+export const RACKSPACE_REGIONS = [
+    "LON",
+    "IAD",
+    "DFW",
+    "ORD",
+    "SYD",
+    "HKG",
+] as const;
+
+export type RackspaceRegion = (typeof RACKSPACE_REGIONS)[number];
+
+/** Default region — matches the deployment this package is primarily exercised against. */
+export const DEFAULT_REGION: RackspaceRegion = "LON";
+
+/** Service-catalog name for Cloud Files (origin / storage). */
+export const STORAGE_SERVICE_NAME = "cloudFiles";
+/** Service-catalog name for the Rackspace CDN. */
+export const CDN_SERVICE_NAME = "cloudFilesCDN";
+
+/** Refresh tokens this many ms before their stated expiry. 5 minutes. */
+export const TOKEN_REFRESH_LEAD_MS = 5 * 60 * 1000;
+
+/** Max key length (chars). */
+export const MAX_KEY_LENGTH = 2048;
+
+/** Retry defaults. */
+export const DEFAULT_RETRY_MAX_ATTEMPTS = 3;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 100;
+export const DEFAULT_RETRY_MAX_DELAY_MS = 30_000;
+export const RETRY_AFTER_MAX_DELAY_MS = 60_000;
+
+/** Transient HTTP statuses outside the 5xx range. */
+export const TRANSIENT_HTTP_STATUSES: ReadonlySet<number> = new Set([
+    408, 425, 429,
+]);

packages/persistence/storage/storage-cdn-rackspace/src/constants/index.ts

@@ -0,0 +1,15 @@
+export type { RackspaceRegion } from "./constants.js";
+export {
+    CDN_SERVICE_NAME,
+    DEFAULT_AUTH_URL,
+    DEFAULT_REGION,
+    DEFAULT_RETRY_BASE_DELAY_MS,
+    DEFAULT_RETRY_MAX_ATTEMPTS,
+    DEFAULT_RETRY_MAX_DELAY_MS,
+    MAX_KEY_LENGTH,
+    RACKSPACE_REGIONS,
+    RETRY_AFTER_MAX_DELAY_MS,
+    STORAGE_SERVICE_NAME,
+    TOKEN_REFRESH_LEAD_MS,
+    TRANSIENT_HTTP_STATUSES,
+} from "./constants.js";

packages/persistence/storage/storage-cdn-rackspace/src/error-codes/error-codes.md

@@ -0,0 +1,69 @@
+# error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Declares the canonical `STORAGE_CDN_RACKSPACE` error namespace used by every module in this package. Codes are produced via `@suaveplan/error.defineCodes` so the resulting string values are guaranteed-unique within the workspace. The companion `StorageCdnRackspaceError` class extends `SuaveplanError` and adds four diagnostic discriminants — `key`, `container`, `region`, and `httpStatus` — so consumers can correlate failures with the offending Rackspace operation without parsing message text.
+
+## Features
+
+- 9 stable error codes covering auth, container, CDN, TempURL, purge rate-limit, region-catalog, options, and upstream failures.
+- `StorageCdnRackspaceError` subclass with `key`/`container`/`region`/`httpStatus` carry fields.
+- Cause-chain preservation via `SuaveplanError`'s `cause` option.
+- Type-safe `StorageCdnRackspaceErrorCode` discriminant inferred from the `defineCodes` tuple.
+
+## Usage: Basic
+
+```ts
+import { STORAGE_CDN_RACKSPACE_CODES, StorageCdnRackspaceError } from "@suaveplan/storage-cdn-rackspace";
+
+throw new StorageCdnRackspaceError(
+    STORAGE_CDN_RACKSPACE_CODES.PURGE_RATE_LIMITED,
+    "CDN purge throttled",
+    { container: "myc", region: "LON", httpStatus: 429 },
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { STORAGE_CDN_RACKSPACE_CODES, StorageCdnRackspaceError } from "@suaveplan/storage-cdn-rackspace";
+
+try {
+    await storage.purge("a/b.bin");
+} catch (err) {
+    if (err instanceof StorageCdnRackspaceError && err.code === STORAGE_CDN_RACKSPACE_CODES.PURGE_RATE_LIMITED) {
+        operatorLog.warn({ container: err.container, region: err.region }, "Throttled — backing off");
+        await scheduleRetry({ delayMs: 60_000 });
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+### `STORAGE_CDN_RACKSPACE_CODES`
+
+Frozen record produced by `defineCodes("STORAGE_CDN_RACKSPACE", [...] as const)`. Codes: `AUTH_FAILED`, `TOKEN_EXPIRED`, `CONTAINER_NOT_FOUND`, `CDN_NOT_ENABLED`, `TEMP_URL_KEY_MISSING`, `PURGE_RATE_LIMITED`, `REGION_NOT_IN_CATALOG`, `INVALID_OPTIONS`, `UPSTREAM_ERROR`.
+
+### `StorageCdnRackspaceErrorCode`
+
+Union of the namespaced code string values.
+
+### `class StorageCdnRackspaceError extends SuaveplanError<StorageCdnRackspaceErrorCode>`
+
+- `constructor(code, message, options?)` — `options` accepts `cause`, `details`, `key`, `container`, `region`, `httpStatus`.
+- Carry-fields exposed as `readonly` properties.
+- `name = "StorageCdnRackspaceError"`.
+
+## Implementation Notes
+
+- `AUTH_FAILED` covers both `401 Unauthorized` and `403 Forbidden` from the storage endpoint — both indicate a bad token or insufficient scope.
+- `TOKEN_EXPIRED` is reserved for downstream tooling that distinguishes proactive-expiry from on-demand-401-then-reauth. The adapter itself raises `AUTH_FAILED` when the re-auth path fails.
+- `CONTAINER_NOT_FOUND` is raised for `404`/`410` on origin operations — Rackspace returns 410 when a container has been deleted but its tombstone is still indexed.
+- `PURGE_RATE_LIMITED` is distinct from `UPSTREAM_ERROR` because purge has its own throttling regime (~25/min historically); operators benefit from a dedicated alert rule.
+- `REGION_NOT_IN_CATALOG` is the configuration guard raised when the service catalog returned by identity v2 lacks an entry for the configured `region` — usually a typo or a tenant with restricted regions.
+- `CDN_NOT_ENABLED` is provider-specific tooling code, raised when callers attempt CDN operations against a container whose CDN profile was never turned on.

packages/persistence/storage/storage-cdn-rackspace/src/error-codes/error-codes.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "./error-codes.js";
+
+describe("STORAGE_CDN_RACKSPACE_CODES", () => {
+    it("contains every documented code with the STORAGE_CDN_RACKSPACE. prefix", {
+        timeout: 5000,
+    }, () => {
+        const expected = [
+            "AUTH_FAILED",
+            "TOKEN_EXPIRED",
+            "CONTAINER_NOT_FOUND",
+            "CDN_NOT_ENABLED",
+            "TEMP_URL_KEY_MISSING",
+            "PURGE_RATE_LIMITED",
+            "REGION_NOT_IN_CATALOG",
+            "INVALID_OPTIONS",
+            "UPSTREAM_ERROR",
+        ] as const;
+        for (const key of expected) {
+            expect(STORAGE_CDN_RACKSPACE_CODES[key]).toBe(
+                `STORAGE_CDN_RACKSPACE.${key}`
+            );
+        }
+    });
+});
+
+describe("StorageCdnRackspaceError", () => {
+    it("carries key/container/region/httpStatus discriminants", {
+        timeout: 5000,
+    }, () => {
+        const err = new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED,
+            "no",
+            {
+                key: "k",
+                container: "c",
+                region: "LON",
+                httpStatus: 401,
+            }
+        );
+        expect(err.key).toBe("k");
+        expect(err.container).toBe("c");
+        expect(err.region).toBe("LON");
+        expect(err.httpStatus).toBe(401);
+        expect(err.code).toBe(STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED);
+        expect(err.name).toBe("StorageCdnRackspaceError");
+    });
+
+    it("leaves discriminants undefined when options are omitted", {
+        timeout: 5000,
+    }, () => {
+        const err = new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+            "boom"
+        );
+        expect(err.key).toBeUndefined();
+        expect(err.container).toBeUndefined();
+        expect(err.region).toBeUndefined();
+        expect(err.httpStatus).toBeUndefined();
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/error-codes/error-codes.ts

@@ -0,0 +1,57 @@
+import {
+    defineCodes,
+    SuaveplanError,
+    type SuaveplanErrorOptions,
+} from "@suaveplan/error";
+
+export const STORAGE_CDN_RACKSPACE_CODES = defineCodes(
+    "STORAGE_CDN_RACKSPACE",
+    [
+        "AUTH_FAILED",
+        "TOKEN_EXPIRED",
+        "CONTAINER_NOT_FOUND",
+        "CDN_NOT_ENABLED",
+        "TEMP_URL_KEY_MISSING",
+        "PURGE_RATE_LIMITED",
+        "REGION_NOT_IN_CATALOG",
+        "INVALID_OPTIONS",
+        "UPSTREAM_ERROR",
+    ] as const
+);
+
+export type StorageCdnRackspaceErrorCode =
+    (typeof STORAGE_CDN_RACKSPACE_CODES)[keyof typeof STORAGE_CDN_RACKSPACE_CODES];
+
+export interface StorageCdnRackspaceErrorOptions extends SuaveplanErrorOptions {
+    key?: string;
+    container?: string;
+    region?: string;
+    httpStatus?: number;
+}
+
+/**
+ * Structured error for Rackspace Cloud Files + Rackspace CDN operations.
+ *
+ * Carries optional `key`, `container`, `region`, and `httpStatus`
+ * discriminants so callers can correlate failures without parsing
+ * message text.
+ */
+export class StorageCdnRackspaceError extends SuaveplanError<StorageCdnRackspaceErrorCode> {
+    public readonly key: string | undefined;
+    public readonly container: string | undefined;
+    public readonly region: string | undefined;
+    public readonly httpStatus: number | undefined;
+
+    public constructor(
+        code: StorageCdnRackspaceErrorCode,
+        message: string,
+        options?: StorageCdnRackspaceErrorOptions
+    ) {
+        super(code, message, options);
+        this.key = options?.key;
+        this.container = options?.container;
+        this.region = options?.region;
+        this.httpStatus = options?.httpStatus;
+        this.name = "StorageCdnRackspaceError";
+    }
+}

packages/persistence/storage/storage-cdn-rackspace/src/error-codes/index.ts

@@ -0,0 +1,8 @@
+export type {
+    StorageCdnRackspaceErrorCode,
+    StorageCdnRackspaceErrorOptions,
+} from "./error-codes.js";
+export {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "./error-codes.js";

packages/persistence/storage/storage-cdn-rackspace/src/index.ts

@@ -0,0 +1,76 @@
+// Side-effect import: ensures `defineCodes` registers the
+// STORAGE_CDN_RACKSPACE.* registry even when subpath consumers never
+// reach this file.
+import "./error-codes/index.js";
+
+export {
+    RackspaceAuthClient,
+    type RackspaceAuthClientOptions,
+} from "./auth-client/auth-client.js";
+export {
+    type CdnClientContext,
+    type CdnContainerMetadata,
+    getCdnMetadata,
+    purgeObject,
+} from "./cdn-client/cdn-client.js";
+export {
+    CDN_SERVICE_NAME,
+    DEFAULT_AUTH_URL,
+    DEFAULT_REGION,
+    DEFAULT_RETRY_BASE_DELAY_MS,
+    DEFAULT_RETRY_MAX_ATTEMPTS,
+    DEFAULT_RETRY_MAX_DELAY_MS,
+    MAX_KEY_LENGTH,
+    RACKSPACE_REGIONS,
+    type RackspaceRegion,
+    RETRY_AFTER_MAX_DELAY_MS,
+    STORAGE_SERVICE_NAME,
+    TOKEN_REFRESH_LEAD_MS,
+    TRANSIENT_HTTP_STATUSES,
+} from "./constants/index.js";
+export {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+    type StorageCdnRackspaceErrorCode,
+    type StorageCdnRackspaceErrorOptions,
+} from "./error-codes/index.js";
+export { encodeKey, sanitizeKey } from "./key-sanitizer/key-sanitizer.js";
+export {
+    getInstruments,
+    type RackspaceInstruments,
+    type RackspaceOp,
+    type RackspaceOutcome,
+    type RecordOpInput,
+    recordOp,
+    recordRangeFallback,
+    resetInstruments,
+    setRackspaceMeterProvider,
+} from "./otel/otel.js";
+export {
+    type CallContext,
+    createRackspaceCdnAdapter,
+    RackspaceCdnAdapter,
+} from "./rackspace-cdn-adapter/index.js";
+export { registerRackspaceCdnProvider } from "./registry/registry.js";
+export {
+    isTransientStatus,
+    parseRetryAfter,
+    type RetryRunOptions,
+    retryWithBackoff,
+} from "./retry-helper/retry-helper.js";
+export {
+    buildTempUrlSignature,
+    type TempUrlInput,
+} from "./temp-url/temp-url.js";
+export { RackspaceCdnAdapterOptionsSchema } from "./types/adapter.schemas.js";
+export type {
+    RackspaceCdnAdapterOptions,
+    RackspaceRetryOptions,
+} from "./types/adapter.types.js";
+export type {
+    CachedToken,
+    RackspaceAuthAccess,
+    RackspaceAuthResponse,
+    ServiceCatalogEndpoint,
+    ServiceCatalogEntry,
+} from "./types/auth.types.js";

packages/persistence/storage/storage-cdn-rackspace/src/key-sanitizer/index.ts

@@ -0,0 +1,4 @@
+export {
+    encodeKey,
+    sanitizeKey,
+} from "./key-sanitizer.js";

packages/persistence/storage/storage-cdn-rackspace/src/key-sanitizer/key-sanitizer.md

@@ -0,0 +1,62 @@
+# key-sanitizer
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Validates and normalises caller-supplied storage keys before any fetch is issued against Rackspace Cloud Files, and provides the per-segment URL encoder used to build absolute object URLs. Keys must be POSIX-form relative paths — no `..`, no leading `/`, no Windows drive prefixes, no control characters, no values longer than `MAX_KEY_LENGTH` (2048 chars). Rejections throw `StorageCdnRackspaceError` with code `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS`.
+
+Unlike `@suaveplan/storage-http`'s key sanitiser, this one collapses key-length and key-content errors into a single code because operators monitoring Rackspace traffic don't distinguish between "key too long" and "key has a control char" — both are caller bugs caught at the boundary.
+
+## Features
+
+- Strict validation: empty, non-string, control char, leading `/`, drive-letter prefix, `..` traversal, overlong (>2048).
+- Normalisation: Windows `\` → POSIX `/` (idempotent on already-POSIX input).
+- Per-segment URL encoder (`encodeKey`) applies `encodeURIComponent` to each `/`-separated segment, preserving slashes.
+- All rejections share one canonical error code for uniform operator alerting.
+
+## Usage: Basic
+
+```ts
+import { encodeKey, sanitizeKey } from "@suaveplan/storage-cdn-rackspace";
+
+const safe = sanitizeKey("a/b/file name.txt");
+const encoded = encodeKey(safe); // → "a/b/file%20name.txt"
+```
+
+## Usage: Advanced
+
+```ts
+import { encodeKey, sanitizeKey, StorageCdnRackspaceError } from "@suaveplan/storage-cdn-rackspace";
+
+function compose(storageEndpoint: string, container: string, key: string): string {
+    const safe = sanitizeKey(key);
+    return `${storageEndpoint}${encodeURIComponent(container)}/${encodeKey(safe)}`;
+}
+
+try {
+    compose(endpoint, "myc", "../etc/passwd");
+} catch (err) {
+    if (err instanceof StorageCdnRackspaceError) operatorLog.warn({ err }, "Caller bug — bad key");
+}
+```
+
+## API Reference
+
+### `sanitizeKey(key: string): string`
+
+Throws `StorageCdnRackspaceError(STORAGE_CDN_RACKSPACE.INVALID_OPTIONS)` for any rejection reason. Returns the input with Windows `\` replaced by `/`.
+
+### `encodeKey(key: string): string`
+
+Splits on `/`, applies `encodeURIComponent` per segment, re-joins. Preserves path hierarchy while encoding spaces, `?`, `#`, `&`, and non-ASCII characters.
+
+## Implementation Notes
+
+- Combining key-length and key-content rejections into one code is a deliberate UX choice — Rackspace operators report on a single rule, and the `details` field on the error preserves the message text for diagnostic logs.
+- The traversal check runs after `\` → `/` normalisation so `a\..\b` is rejected (post-normalisation it has a `..` segment).
+- Control-character detection is a single O(n) pass scanning every code unit; it costs negligible time relative to the subsequent `fetch`.
+- `encodeKey` is separate from `sanitizeKey` because URL encoding is a transport concern — callers that compose paths for non-fetch destinations (TempURL signature paths, log messages) want the sanitised but unencoded form.
+- The `MAX_KEY_LENGTH = 2048` cap matches `@suaveplan/storage-http`'s default — Rackspace's documented limit is 1024, so this is conservatively wider; the sibling `storage-cdn-rackspace.ops` layer prepends the container name which keeps the total path under documented limits.

packages/persistence/storage/storage-cdn-rackspace/src/key-sanitizer/key-sanitizer.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { encodeKey, sanitizeKey } from "./key-sanitizer.js";
+
+describe("sanitizeKey", () => {
+    it("rejects empty / non-string keys", { timeout: 5000 }, () => {
+        expect(() => sanitizeKey("")).toThrow(StorageCdnRackspaceError);
+        expect(() => sanitizeKey(42 as unknown as string)).toThrow(
+            StorageCdnRackspaceError
+        );
+    });
+    it("rejects overlong keys", { timeout: 5000 }, () => {
+        try {
+            sanitizeKey("a".repeat(2049));
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS
+            );
+        }
+    });
+    it("rejects traversal", { timeout: 5000 }, () => {
+        expect(() => sanitizeKey("../etc/passwd")).toThrow(
+            StorageCdnRackspaceError
+        );
+        expect(() => sanitizeKey("a/../b")).toThrow(StorageCdnRackspaceError);
+    });
+    it("rejects absolute paths", { timeout: 5000 }, () => {
+        expect(() => sanitizeKey("/abs")).toThrow(StorageCdnRackspaceError);
+        expect(() => sanitizeKey("C:\\x")).toThrow(StorageCdnRackspaceError);
+    });
+    it("rejects control characters", { timeout: 5000 }, () => {
+        expect(() => sanitizeKey("a\x00b")).toThrow(StorageCdnRackspaceError);
+    });
+    it("normalises Windows separators", { timeout: 5000 }, () => {
+        expect(sanitizeKey("a\\b\\c")).toBe("a/b/c");
+    });
+    it("accepts a simple POSIX path", { timeout: 5000 }, () => {
+        expect(sanitizeKey("a/b/c.bin")).toBe("a/b/c.bin");
+    });
+});
+
+describe("encodeKey", () => {
+    it("encodes each segment, preserves slashes", { timeout: 5000 }, () => {
+        expect(encodeKey("hello world/file.txt")).toBe(
+            "hello%20world/file.txt"
+        );
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/key-sanitizer/key-sanitizer.ts

@@ -0,0 +1,62 @@
+import { MAX_KEY_LENGTH } from "../constants/constants.js";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+
+const WINDOWS_DRIVE_PREFIX = /^[A-Za-z]:[\\/]/;
+
+function containsControlChar(value: string): boolean {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f) return true;
+    }
+    return false;
+}
+
+/**
+ * Validate and normalise a caller-supplied key. Throws
+ * `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS` on rejection — this provider does
+ * not split key-length vs. key-content errors; both are caller bugs.
+ *
+ * Normalises Windows `\` → POSIX `/`.
+ */
+export function sanitizeKey(key: string): string {
+    if (typeof key !== "string" || key.length === 0) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS,
+            "key must be a non-empty string"
+        );
+    }
+    if (key.length > MAX_KEY_LENGTH) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS,
+            `key length ${key.length} exceeds maximum ${MAX_KEY_LENGTH}`
+        );
+    }
+    if (
+        containsControlChar(key) ||
+        key.startsWith("/") ||
+        WINDOWS_DRIVE_PREFIX.test(key)
+    ) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS,
+            "key contains a control char, absolute path, or drive-letter prefix"
+        );
+    }
+    const normalised = key.replace(/\\/g, "/");
+    for (const segment of normalised.split("/")) {
+        if (segment === "..") {
+            throw new StorageCdnRackspaceError(
+                STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS,
+                "path traversal segment (..) is not allowed"
+            );
+        }
+    }
+    return normalised;
+}
+
+/** Per-segment URL encoder, preserving `/` between segments. */
+export function encodeKey(key: string): string {
+    return key.split("/").map(encodeURIComponent).join("/");
+}

packages/persistence/storage/storage-cdn-rackspace/src/otel/index.ts

@@ -0,0 +1,13 @@
+export type {
+    RackspaceInstruments,
+    RackspaceOp,
+    RackspaceOutcome,
+    RecordOpInput,
+} from "./otel.js";
+export {
+    getInstruments,
+    recordOp,
+    recordRangeFallback,
+    resetInstruments,
+    setRackspaceMeterProvider,
+} from "./otel.js";

packages/persistence/storage/storage-cdn-rackspace/src/otel/otel.md

@@ -0,0 +1,81 @@
+# otel
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the OpenTelemetry instrument set for `@suaveplan/storage-cdn-rackspace`: counters (`reads_total`, `writes_total`, `deletes_total`, `purges_total`, `signed_urls_total`, `errors_total`, `range_fallback_total`), histograms (`op_duration_ms`, `io_bytes`), and a tracer scoped to `@suaveplan/storage-cdn-rackspace`. Every measurement carries `provider="rackspace"` and the configured `region` so dashboards can break Rackspace traffic down by region and aggregate across providers without losing detail.
+
+## Features
+
+- Lazy instrument construction so consumers can install a custom `MeterProvider` before the first operation runs.
+- `setRackspaceMeterProvider(provider)` override hook with auto-rebuild on next access.
+- `recordOp({ op, outcome, durationMs, region, bytes?, direction? })` emits the full observation set for one operation.
+- `recordRangeFallback(region)` increments the dedicated counter — surfaces origins that ignore Range.
+- `resetInstruments()` for test isolation.
+- Dedicated counters for CDN-specific operations (`purges_total`, `signed_urls_total`) so operators can monitor purge rate-limit pressure separately from storage IO.
+
+## Usage: Basic
+
+```ts
+import { recordOp } from "@suaveplan/storage-cdn-rackspace";
+
+recordOp({ op: "purge", outcome: "ok", durationMs: 42, region: "LON" });
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    resetInstruments,
+    setRackspaceMeterProvider,
+    recordOp,
+} from "@suaveplan/storage-cdn-rackspace";
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+
+const provider = new MeterProvider({ readers: [periodicReader] });
+setRackspaceMeterProvider(provider);
+resetInstruments();
+recordOp({ op: "signUrl", outcome: "ok", durationMs: 1, region: "LON" });
+```
+
+## API Reference
+
+### `setRackspaceMeterProvider(provider?): void`
+
+Override or restore the meter provider. Calling this invalidates the cached instrument set so the next `getInstruments()` rebinds.
+
+### `getInstruments(force?): RackspaceInstruments`
+
+Returns the cached instrument bundle (`tracer`, `meter`, every counter and histogram). `force = true` rebuilds.
+
+### `recordOp(input): void`
+
+`input.outcome` decides which counter increments:
+
+- `"ok"` + read-ish op → `reads_total`.
+- `"ok"` + `set`/`setPartial` → `writes_total`.
+- `"ok"` + `delete`/`clear` → `deletes_total`.
+- `"ok"` + `purge` → `purges_total`.
+- `"ok"` + `signUrl` → `signed_urls_total`.
+- anything else → `errors_total`.
+
+Always records `op_duration_ms{op, outcome, provider, region}`. When `bytes` and `direction` are both provided, also records `io_bytes{op, direction, provider, region}`.
+
+### `recordRangeFallback(region): void`
+
+Increments `range_fallback_total{outcome="ok", provider="rackspace", region}`.
+
+### `resetInstruments(): void`
+
+Drops the cached bundle without changing the meter provider.
+
+## Implementation Notes
+
+- The cache is critical for hot-path performance. `setRackspaceMeterProvider` is the one path that intentionally invalidates the cache.
+- `provider="rackspace"` is hard-coded — every measurement from this package belongs to Rackspace by definition. Cross-provider dashboards aggregate on the `provider` attribute, so dropping it would defeat the family-wide observability.
+- `region` is sourced from the resolved configuration, not the operation argument, because operations don't take a region — the adapter is bound to one region per instance.
+- The tracer is acquired separately from the meter; no caching is required because `trace.getTracer` is idempotent.
+- `range_fallback_total` carries `outcome="ok"` only — the fallback path always succeeds (just less efficiently); upstream failures during fallback surface via `errors_total`.

packages/persistence/storage/storage-cdn-rackspace/src/otel/otel.test.ts

@@ -0,0 +1,241 @@
+import type {
+    Counter,
+    Histogram,
+    Meter,
+    MeterProvider,
+} from "@opentelemetry/api";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+} from "@suaveplan/testing/runner";
+import {
+    getInstruments,
+    recordOp,
+    recordRangeFallback,
+    resetInstruments,
+    setRackspaceMeterProvider,
+} from "./otel.js";
+
+interface RecHist {
+    name: string;
+    samples: { value: number; attrs: Record<string, unknown> | undefined }[];
+}
+interface RecCtr {
+    name: string;
+    additions: { value: number; attrs: Record<string, unknown> | undefined }[];
+}
+
+class StubHist implements Histogram {
+    public entry: RecHist;
+    public constructor(
+        public name: string,
+        bag: RecHist[]
+    ) {
+        this.entry = { name, samples: [] };
+        bag.push(this.entry);
+    }
+    public record(v: number, a?: Record<string, unknown>): void {
+        this.entry.samples.push({ value: v, attrs: a });
+    }
+}
+class StubCtr implements Counter {
+    public entry: RecCtr;
+    public constructor(
+        public name: string,
+        bag: RecCtr[]
+    ) {
+        this.entry = { name, additions: [] };
+        bag.push(this.entry);
+    }
+    public add(v: number, a?: Record<string, unknown>): void {
+        this.entry.additions.push({ value: v, attrs: a });
+    }
+}
+class StubMeter implements Meter {
+    public histograms: RecHist[] = [];
+    public counters: RecCtr[] = [];
+    public createHistogram(name: string): Histogram {
+        return new StubHist(name, this.histograms);
+    }
+    public createCounter(name: string): Counter {
+        return new StubCtr(name, this.counters);
+    }
+    public createObservableGauge(): never {
+        throw new Error("unused");
+    }
+    public createUpDownCounter(): never {
+        throw new Error("unused");
+    }
+    public createObservableCounter(): never {
+        throw new Error("unused");
+    }
+    public createObservableUpDownCounter(): never {
+        throw new Error("unused");
+    }
+    public addBatchObservableCallback(): void {}
+    public removeBatchObservableCallback(): void {}
+    public createGauge(): never {
+        throw new Error("unused");
+    }
+}
+class StubProvider implements MeterProvider {
+    public meters: StubMeter[] = [];
+    public getMeter(): Meter {
+        const m = new StubMeter();
+        this.meters.push(m);
+        return m;
+    }
+}
+
+describe("rackspace otel", () => {
+    let provider: StubProvider;
+    beforeEach(() => {
+        provider = new StubProvider();
+        setRackspaceMeterProvider(provider);
+    });
+    afterEach(() => {
+        setRackspaceMeterProvider(undefined);
+        resetInstruments();
+    });
+
+    const find = <K extends "counters" | "histograms">(
+        kind: K,
+        name: string
+    ) => {
+        return provider.meters[0]?.[kind].find((x) => x.name === name);
+    };
+
+    it("set OK emits writes_total with provider+region attrs", {
+        timeout: 5000,
+    }, () => {
+        recordOp({
+            op: "set",
+            outcome: "ok",
+            durationMs: 5,
+            region: "LON",
+            bytes: 10,
+            direction: "write",
+        });
+        const w = find("counters", "storage_cdn_rackspace.writes_total");
+        expect(w?.additions[0]?.attrs).toEqual({
+            op: "set",
+            outcome: "ok",
+            provider: "rackspace",
+            region: "LON",
+        });
+        const io = find("histograms", "storage_cdn_rackspace.io_bytes");
+        expect(io?.samples[0]?.attrs).toEqual({
+            op: "set",
+            direction: "write",
+            provider: "rackspace",
+            region: "LON",
+        });
+    });
+
+    it("get OK emits reads_total", { timeout: 5000 }, () => {
+        recordOp({ op: "get", outcome: "ok", durationMs: 1, region: "LON" });
+        expect(
+            find("counters", "storage_cdn_rackspace.reads_total")?.additions
+        ).toHaveLength(1);
+    });
+
+    it("delete/clear OK emit deletes_total", { timeout: 5000 }, () => {
+        recordOp({ op: "delete", outcome: "ok", durationMs: 1, region: "LON" });
+        recordOp({ op: "clear", outcome: "ok", durationMs: 1, region: "LON" });
+        expect(
+            find("counters", "storage_cdn_rackspace.deletes_total")?.additions
+        ).toHaveLength(2);
+    });
+
+    it("purge OK emits purges_total", { timeout: 5000 }, () => {
+        recordOp({ op: "purge", outcome: "ok", durationMs: 1, region: "LON" });
+        expect(
+            find("counters", "storage_cdn_rackspace.purges_total")?.additions
+        ).toHaveLength(1);
+    });
+
+    it("signUrl OK emits signed_urls_total", { timeout: 5000 }, () => {
+        recordOp({
+            op: "signUrl",
+            outcome: "ok",
+            durationMs: 1,
+            region: "LON",
+        });
+        expect(
+            find("counters", "storage_cdn_rackspace.signed_urls_total")
+                ?.additions
+        ).toHaveLength(1);
+    });
+
+    it("non-ok emits errors_total", { timeout: 5000 }, () => {
+        recordOp({
+            op: "get",
+            outcome: "upstream_error",
+            durationMs: 1,
+            region: "LON",
+        });
+        expect(
+            find("counters", "storage_cdn_rackspace.errors_total")?.additions[0]
+                ?.attrs
+        ).toMatchObject({
+            provider: "rackspace",
+            outcome: "upstream_error",
+        });
+    });
+
+    it("recordRangeFallback increments dedicated counter", {
+        timeout: 5000,
+    }, () => {
+        recordRangeFallback("LON");
+        expect(
+            find("counters", "storage_cdn_rackspace.range_fallback_total")
+                ?.additions
+        ).toHaveLength(1);
+    });
+
+    it("getInstruments caches and force=true rebuilds", {
+        timeout: 5000,
+    }, () => {
+        const a = getInstruments();
+        const b = getInstruments();
+        expect(a).toBe(b);
+        const c = getInstruments(true);
+        expect(c).not.toBe(a);
+    });
+
+    it("omits io_bytes when bytes is undefined", { timeout: 5000 }, () => {
+        recordOp({ op: "exists", outcome: "ok", durationMs: 1, region: "LON" });
+        expect(
+            find("histograms", "storage_cdn_rackspace.io_bytes")?.samples ?? []
+        ).toHaveLength(0);
+    });
+
+    it("exists ok does not increment reads/writes/deletes/purges/signed", {
+        timeout: 5000,
+    }, () => {
+        recordOp({ op: "exists", outcome: "ok", durationMs: 1, region: "LON" });
+        expect(
+            find("counters", "storage_cdn_rackspace.reads_total")?.additions ??
+                []
+        ).toHaveLength(0);
+        expect(
+            find("counters", "storage_cdn_rackspace.writes_total")?.additions ??
+                []
+        ).toHaveLength(0);
+        expect(
+            find("counters", "storage_cdn_rackspace.deletes_total")
+                ?.additions ?? []
+        ).toHaveLength(0);
+        expect(
+            find("counters", "storage_cdn_rackspace.purges_total")?.additions ??
+                []
+        ).toHaveLength(0);
+        expect(
+            find("counters", "storage_cdn_rackspace.signed_urls_total")
+                ?.additions ?? []
+        ).toHaveLength(0);
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/otel/otel.ts

@@ -0,0 +1,145 @@
+import {
+    type Counter,
+    type Histogram,
+    type Meter,
+    type MeterProvider,
+    metrics,
+    type Tracer,
+    trace,
+} from "@opentelemetry/api";
+
+const METER_NAME = "@suaveplan/storage-cdn-rackspace";
+const TRACER_NAME = "@suaveplan/storage-cdn-rackspace";
+
+let overrideMeterProvider: MeterProvider | undefined;
+
+export function setRackspaceMeterProvider(
+    provider: MeterProvider | undefined
+): void {
+    overrideMeterProvider = provider;
+    cached = undefined;
+}
+
+export type RackspaceOp =
+    | "get"
+    | "set"
+    | "delete"
+    | "exists"
+    | "list"
+    | "clear"
+    | "getMetadata"
+    | "getWithMetadata"
+    | "getSize"
+    | "getPartial"
+    | "setPartial"
+    | "getItemSize"
+    | "createReadStream"
+    | "createWriteStream"
+    | "purge"
+    | "signUrl";
+
+export type RackspaceOutcome =
+    | "ok"
+    | "not_found"
+    | "auth_failed"
+    | "rate_limited"
+    | "upstream_error"
+    | "aborted";
+
+export interface RackspaceInstruments {
+    tracer: Tracer;
+    meter: Meter;
+    readsTotal: Counter;
+    writesTotal: Counter;
+    deletesTotal: Counter;
+    purgesTotal: Counter;
+    signedUrlsTotal: Counter;
+    errorsTotal: Counter;
+    rangeFallbackTotal: Counter;
+    opDurationMs: Histogram;
+    ioBytes: Histogram;
+}
+
+let cached: RackspaceInstruments | undefined;
+
+export function getInstruments(force = false): RackspaceInstruments {
+    if (cached !== undefined && !force) return cached;
+    const tracer = trace.getTracer(TRACER_NAME);
+    const meter = (overrideMeterProvider ?? metrics).getMeter(METER_NAME);
+    cached = {
+        tracer,
+        meter,
+        readsTotal: meter.createCounter("storage_cdn_rackspace.reads_total"),
+        writesTotal: meter.createCounter("storage_cdn_rackspace.writes_total"),
+        deletesTotal: meter.createCounter(
+            "storage_cdn_rackspace.deletes_total"
+        ),
+        purgesTotal: meter.createCounter("storage_cdn_rackspace.purges_total"),
+        signedUrlsTotal: meter.createCounter(
+            "storage_cdn_rackspace.signed_urls_total"
+        ),
+        errorsTotal: meter.createCounter("storage_cdn_rackspace.errors_total"),
+        rangeFallbackTotal: meter.createCounter(
+            "storage_cdn_rackspace.range_fallback_total"
+        ),
+        opDurationMs: meter.createHistogram(
+            "storage_cdn_rackspace.op_duration_ms",
+            { unit: "ms" }
+        ),
+        ioBytes: meter.createHistogram("storage_cdn_rackspace.io_bytes", {
+            unit: "By",
+        }),
+    };
+    return cached;
+}
+
+export interface RecordOpInput {
+    op: RackspaceOp;
+    outcome: RackspaceOutcome;
+    durationMs: number;
+    region: string;
+    bytes?: number;
+    direction?: "read" | "write";
+}
+
+export function recordOp(input: RecordOpInput): void {
+    const { op, outcome, durationMs, region, bytes, direction } = input;
+    const inst = getInstruments();
+    const baseAttrs = { op, outcome, provider: "rackspace", region };
+    inst.opDurationMs.record(durationMs, baseAttrs);
+    if (outcome === "ok") {
+        if (op === "get" || op === "getPartial" || op === "getWithMetadata") {
+            inst.readsTotal.add(1, baseAttrs);
+        } else if (op === "set" || op === "setPartial") {
+            inst.writesTotal.add(1, baseAttrs);
+        } else if (op === "delete" || op === "clear") {
+            inst.deletesTotal.add(1, baseAttrs);
+        } else if (op === "purge") {
+            inst.purgesTotal.add(1, baseAttrs);
+        } else if (op === "signUrl") {
+            inst.signedUrlsTotal.add(1, baseAttrs);
+        }
+    } else {
+        inst.errorsTotal.add(1, baseAttrs);
+    }
+    if (bytes !== undefined && direction !== undefined) {
+        inst.ioBytes.record(bytes, {
+            op,
+            direction,
+            provider: "rackspace",
+            region,
+        });
+    }
+}
+
+export function recordRangeFallback(region: string): void {
+    getInstruments().rangeFallbackTotal.add(1, {
+        outcome: "ok",
+        provider: "rackspace",
+        region,
+    });
+}
+
+export function resetInstruments(): void {
+    cached = undefined;
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/index.ts

@@ -0,0 +1,28 @@
+export {
+    errorForStatus,
+    outcomeFromError,
+    type ResolvedConfig,
+    resolveConfig,
+    resolveHeaders,
+    throwIfAborted,
+} from "./rackspace-cdn-adapter.helpers.js";
+export {
+    createRackspaceCdnAdapter,
+    RackspaceCdnAdapter,
+} from "./rackspace-cdn-adapter.js";
+export {
+    type CallContext,
+    objectDelete,
+    objectGet,
+    objectHead,
+    objectPartial,
+    objectPut,
+    objectStream,
+    parseMetadata,
+} from "./rackspace-cdn-adapter.ops.js";
+export {
+    buildReadStream,
+    buildWriteStream,
+    unsupported,
+    type WriteStreamArgs,
+} from "./rackspace-cdn-adapter.streams.js";

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.base.md

@@ -0,0 +1,62 @@
+# rackspace-cdn-adapter.base
+
+## Purpose
+
+`RackspaceCdnAdapterBase` carries the shared internal machinery every `RackspaceCdnAdapter` instance needs: the resolved configuration, the auth client, the per-operation `ctxFor` builder, and the OTel-wrapping `wrap` helper. The public `RackspaceCdnAdapter` class extends this base and adds the concrete public methods — splitting the class this way keeps each file under the 300-line budget while still exposing a single `instanceof RackspaceCdnAdapter` surface to consumers.
+
+## Features
+
+- `config: ResolvedConfig` — parsed at construction; protected so the subclass can read it without re-resolving.
+- `auth: RackspaceAuthClient` — single client instance per adapter, caches tokens for the configured region.
+- `ctxFor(key, signal)` — builds the `CallContext` the ops module consumes: fetches the token, resolves headers, threads retry options and signal.
+- `wrap(op, signal, fn)` — runs `fn` inside a try/catch that records duration on success and emits the correct outcome counter on failure.
+- Capability matrix declared once at the module level (`CAPS`) so the subclass inherits the canonical shape.
+
+## Usage: Basic
+
+```ts
+import { RackspaceCdnAdapterBase } from "@suaveplan/storage-cdn-rackspace";
+
+class MyAdapter extends RackspaceCdnAdapterBase {
+    // implement abstract methods from AbstractStorage + CdnAdapter using
+    // this.config, this.auth, this.ctxFor(...), this.wrap(...)
+}
+```
+
+## Usage: Advanced
+
+```ts
+import { RackspaceCdnAdapterBase } from "@suaveplan/storage-cdn-rackspace";
+
+class CustomLoggingAdapter extends RackspaceCdnAdapterBase {
+    public override async get(key: string, signal?: AbortSignal): Promise<Uint8Array | undefined> {
+        return this.wrap("get", signal, async () => {
+            const ctx = await this.ctxFor(key, signal);
+            const start = Date.now();
+            const result = await myObjectGet(ctx, key);
+            customMetrics.observe("rax_get_ms", Date.now() - start);
+            return result;
+        });
+    }
+    // ...
+}
+```
+
+## API Reference
+
+### `abstract class RackspaceCdnAdapterBase extends CdnAdapter`
+
+- `protected readonly config: ResolvedConfig` — output of `resolveConfig` at construction time.
+- `protected readonly auth: RackspaceAuthClient` — single auth client per adapter.
+- `public override readonly capabilities` — the documented `StorageCapabilities & { cdn: CdnCapabilities }` matrix.
+- `constructor(options: RackspaceCdnAdapterOptions)` — validates options, instantiates the auth client.
+- `protected ctxFor(key, signal): Promise<CallContext>` — fetches the token, resolves headers, returns the bundle ops modules consume.
+- `protected wrap<T>(op, signal, fn): Promise<T>` — wraps `fn` in OTel + abort guards.
+
+## Implementation Notes
+
+- The base is `abstract` so it can't be instantiated directly — only via `RackspaceCdnAdapter`. The abstract qualifier is structural (the abstract `purge`/`signUrl`/`edgeUrl` from `CdnAdapter` are unimplemented here) which TypeScript enforces.
+- `config`/`auth` are `protected readonly` rather than `#private` so the subclass file can reference them as `this.config` / `this.auth`. Hiding them with `#private` would require duplicating every method into the base file or shipping an unsafe public accessor.
+- `wrap` records the outcome in both success and failure paths — the success counter increments inside the operation methods (for ops that carry `bytes`/`direction` attributes like `set`), and the `wrap` itself increments duration unconditionally.
+- The `CAPS` module-level constant is shared by every instance — it's frozen at compile time via the `readonly` modifiers on the interface.
+- This split is a deliberate organisational choice; consumers see only `RackspaceCdnAdapter`. The base is exported so subclasses outside the package can build alternative implementations sharing the same internal contract.

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.base.ts

@@ -0,0 +1,108 @@
+import type { StorageCapabilities } from "@suaveplan/storage/types";
+import { CdnAdapter, type CdnCapabilities } from "@suaveplan/storage-cdn";
+import { RackspaceAuthClient } from "../auth-client/auth-client.js";
+import { type RackspaceOp, recordOp } from "../otel/otel.js";
+import type { RackspaceCdnAdapterOptions } from "../types/adapter.types.js";
+import {
+    outcomeFromError,
+    type ResolvedConfig,
+    resolveConfig,
+    resolveHeaders,
+    throwIfAborted,
+} from "./rackspace-cdn-adapter.helpers.js";
+import type { CallContext } from "./rackspace-cdn-adapter.ops.js";
+
+const CAPS: StorageCapabilities & { readonly cdn: CdnCapabilities } = {
+    partialReads: true,
+    partialWrites: false,
+    nativeStreams: true,
+    atomicWrites: false,
+    contentAddressable: false,
+    cdn: {
+        cdnPurge: true,
+        cdnPrefixPurge: false,
+        cdnSignedUrls: true,
+        cdnOriginUploads: true,
+    },
+};
+
+/**
+ * Shared internal machinery for `RackspaceCdnAdapter` — the resolved
+ * configuration, the auth client, the per-op context builder, and the
+ * OTel-wrapping `#wrap` helper. Lives in a base class so the public class
+ * file stays under the 300-line budget while the protected accessors stay
+ * available to the concrete methods.
+ */
+export abstract class RackspaceCdnAdapterBase extends CdnAdapter {
+    protected readonly config: ResolvedConfig;
+    protected readonly auth: RackspaceAuthClient;
+
+    public override readonly capabilities = CAPS;
+
+    public constructor(options: RackspaceCdnAdapterOptions) {
+        super();
+        this.config = resolveConfig(options);
+        this.auth = new RackspaceAuthClient({
+            username: options.username,
+            apiKey: options.apiKey,
+            ...(options.authUrl !== undefined
+                ? { authUrl: options.authUrl }
+                : {}),
+            region: this.config.region,
+            fetch: this.config.fetch,
+            now: this.config.now,
+        });
+    }
+
+    protected async ctxFor(
+        key: string,
+        signal: AbortSignal | undefined
+    ): Promise<CallContext> {
+        const token = await this.auth.getToken(signal);
+        const headers = await resolveHeaders(this.config.options.headers, key);
+        const retry: CallContext["retry"] = {};
+        if (this.config.options.retry !== undefined)
+            retry.retry = this.config.options.retry;
+        if (this.config.options.timers !== undefined)
+            retry.timers = this.config.options.timers;
+        if (signal !== undefined) retry.signal = signal;
+        return {
+            fetch: this.config.fetch,
+            storageEndpoint: token.storageEndpoint,
+            token: token.tokenId,
+            container: this.config.container,
+            region: this.config.region,
+            signal,
+            retry,
+            headers,
+        };
+    }
+
+    protected async wrap<T>(
+        op: RackspaceOp,
+        signal: AbortSignal | undefined,
+        fn: () => Promise<T>
+    ): Promise<T> {
+        const start = Date.now();
+        const region = this.config.region;
+        try {
+            throwIfAborted(signal);
+            const value = await fn();
+            recordOp({
+                op,
+                outcome: "ok",
+                durationMs: Date.now() - start,
+                region,
+            });
+            return value;
+        } catch (err) {
+            recordOp({
+                op,
+                outcome: outcomeFromError(err),
+                durationMs: Date.now() - start,
+                region,
+            });
+            throw err;
+        }
+    }
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.cdn-methods.md

@@ -0,0 +1,71 @@
+# rackspace-cdn-adapter.cdn-methods
+
+## Purpose
+
+Houses the CDN-side method implementations consumed by `RackspaceCdnAdapter`: `getSize` (via `fetchContainerSize`), `purge` (via `performPurge`), `signUrl` (via `buildSignedUrl`), and `edgeUrl` (via `composeEdgeUrl`). Extracted from the public class file so the class body stays under the 300-line budget while the helpers remain unit-testable in isolation.
+
+All four functions accept a `CdnMethodsCtx` bundle the class builds via its private `#cdnCtx()` accessor — keeps the helpers stateless and easy to fake in tests.
+
+## Features
+
+- `fetchContainerSize(ctx, signal?)` — HEAD on the container, parses `X-Container-Bytes-Used`.
+- `performPurge(ctx, sanitisedKey, signal?)` — invokes `purgeObject` against the resolved CDN management endpoint.
+- `buildSignedUrl(ctx, sanitisedKey, options, signal?)` — parses options, fetches the token, computes the Swift TempURL signature, composes the absolute storage URL.
+- `composeEdgeUrl(ctx, sanitisedKey)` — synchronous URL composition against the configured `edgeBaseUrl`; throws `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS` when absent.
+- `CdnMethodsCtx` carries the auth client, fetch, container, region, TempURL key, edge URL, and now-function — the smallest shape that satisfies all four helpers.
+
+## Usage: Basic
+
+```ts
+import { performPurge } from "@suaveplan/storage-cdn-rackspace";
+
+await performPurge({ auth, fetch, container: "myc", region: "LON", tempUrlKey: undefined, edgeBaseUrl: undefined, now: Date.now }, "a/b.bin");
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    buildSignedUrl,
+    composeEdgeUrl,
+    fetchContainerSize,
+    performPurge,
+} from "@suaveplan/storage-cdn-rackspace";
+
+async function operations(ctx) {
+    const totalBytes = await fetchContainerSize(ctx);
+    await performPurge(ctx, "a/b.bin");
+    const signed = await buildSignedUrl(ctx, "a/b.bin", { ttlSeconds: 60, method: "GET" });
+    const edge = composeEdgeUrl(ctx, "a/b.bin");
+    return { totalBytes, signed, edge };
+}
+```
+
+## API Reference
+
+### `interface CdnMethodsCtx`
+
+`{ auth, fetch, container, region, tempUrlKey, edgeBaseUrl, now }` — bundle the class supplies once per call.
+
+### `fetchContainerSize(ctx, signal?): Promise<number>`
+
+Issues HEAD on the container; parses `X-Container-Bytes-Used` (defaults to 0 when missing). Throws `STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR` on non-ok.
+
+### `performPurge(ctx, sanitisedKey, signal?): Promise<void>`
+
+Delegates to `purgeObject` from the cdn-client module, encoding the key first.
+
+### `buildSignedUrl(ctx, sanitisedKey, options, signal?): Promise<string>`
+
+Parses `SignUrlOptions` (throws on bad TTL/method), fetches the token, computes the TempURL signature, returns `<storageEndpoint><container>/<encodedKey><signature>`.
+
+### `composeEdgeUrl(ctx, sanitisedKey): string`
+
+Synchronous. Throws `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS` when `edgeBaseUrl` is absent.
+
+## Implementation Notes
+
+- `composeEdgeUrl` is the one synchronous helper because `edgeUrl()` on the adapter is required to be synchronous by the `CdnAdapter` contract. Every other helper is async because it touches the auth client or the fetch surface.
+- `buildSignedUrl` uses `new URL(...).pathname` to derive the absolute Swift path the TempURL signature operates over — Rackspace's storage URLs always include the `/v1/AUTH_<account>/...` prefix, and the signing body needs that exact prefix.
+- The `now: () => number` function is injected rather than calling `Date.now()` directly so tests can pin the `expires` boundary for deterministic signature comparison.
+- `CdnMethodsCtx` is intentionally a flat interface — passing the whole adapter instance would expose more surface than the helpers need and tie the helpers to the class identity.

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.cdn-methods.ts

@@ -0,0 +1,114 @@
+import {
+    parseSignUrlOptions,
+    type SignUrlOptions,
+} from "@suaveplan/storage-cdn";
+import type { FetchLike } from "@suaveplan/types";
+import type { RackspaceAuthClient } from "../auth-client/auth-client.js";
+import { purgeObject } from "../cdn-client/cdn-client.js";
+import type { RackspaceRegion } from "../constants/constants.js";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { encodeKey } from "../key-sanitizer/key-sanitizer.js";
+import { buildTempUrlSignature } from "../temp-url/temp-url.js";
+
+export interface CdnMethodsCtx {
+    auth: RackspaceAuthClient;
+    fetch: FetchLike;
+    container: string;
+    region: RackspaceRegion;
+    tempUrlKey: string | undefined;
+    edgeBaseUrl: string | undefined;
+    now: () => number;
+}
+
+/** Issue HEAD on the container and return its byte-count. */
+export async function fetchContainerSize(
+    ctx: CdnMethodsCtx,
+    signal: AbortSignal | undefined
+): Promise<number> {
+    const token = await ctx.auth.getToken(signal);
+    const url = `${token.storageEndpoint}${encodeURIComponent(ctx.container)}`;
+    const init: RequestInit = {
+        method: "HEAD",
+        headers: { "x-auth-token": token.tokenId },
+    };
+    if (signal !== undefined) init.signal = signal;
+    const response = await ctx.fetch(url, init);
+    if (!response.ok) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+            `getSize upstream ${response.status}`,
+            {
+                container: ctx.container,
+                region: ctx.region,
+                httpStatus: response.status,
+            }
+        );
+    }
+    return Number.parseInt(
+        response.headers.get("x-container-bytes-used") ?? "0",
+        10
+    );
+}
+
+/** Invoke the CDN-management purge endpoint for one sanitised key. */
+export async function performPurge(
+    ctx: CdnMethodsCtx,
+    sanitisedKey: string,
+    signal: AbortSignal | undefined
+): Promise<void> {
+    const token = await ctx.auth.getToken(signal);
+    await purgeObject(
+        {
+            fetch: ctx.fetch,
+            token: token.tokenId,
+            cdnEndpoint: token.cdnEndpoint,
+            container: ctx.container,
+            region: ctx.region,
+        },
+        encodeKey(sanitisedKey),
+        signal
+    );
+}
+
+/** Compose a Swift TempURL for one sanitised key. */
+export async function buildSignedUrl(
+    ctx: CdnMethodsCtx,
+    sanitisedKey: string,
+    options: SignUrlOptions,
+    signal: AbortSignal | undefined
+): Promise<string> {
+    const opts = parseSignUrlOptions(options);
+    const token = await ctx.auth.getToken(signal);
+    const expires = Math.floor(ctx.now() / 1000) + opts.ttlSeconds;
+    const path = new URL(
+        `${encodeURIComponent(ctx.container)}/${encodeKey(sanitisedKey)}`,
+        token.storageEndpoint
+    ).pathname;
+    const signature = await buildTempUrlSignature({
+        method: opts.method ?? "GET",
+        path,
+        expires,
+        tempUrlKey: ctx.tempUrlKey ?? "",
+    });
+    return `${token.storageEndpoint}${encodeURIComponent(ctx.container)}/${encodeKey(
+        sanitisedKey
+    )}${signature}`;
+}
+
+/** Synchronous edge-URL composition. Throws when `edgeBaseUrl` is absent. */
+export function composeEdgeUrl(
+    ctx: CdnMethodsCtx,
+    sanitisedKey: string
+): string {
+    if (ctx.edgeBaseUrl === undefined) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS,
+            "edgeBaseUrl was not configured; cannot compose edge URL synchronously",
+            { container: ctx.container, region: ctx.region }
+        );
+    }
+    return new URL(encodeKey(sanitisedKey), ctx.edgeBaseUrl).toString();
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.coverage.test.ts

@@ -0,0 +1,487 @@
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "@suaveplan/testing/runner";
+import type { FetchLike } from "@suaveplan/types";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    type StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { setRackspaceMeterProvider } from "../otel/otel.js";
+import { RackspaceCdnAdapter } from "./rackspace-cdn-adapter.js";
+
+const STORAGE = "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/";
+const CDN = "https://cdn3.clouddrive.com/v1/AUTH_acc/";
+const EDGE = "https://abc.r88.cf6.rackcdn.com/";
+const AUTH = "https://lon.identity.api.rackspacecloud.com/v2.0";
+
+function authBody(): unknown {
+    const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    return {
+        access: {
+            token: { id: "tok-abc", expires: future },
+            serviceCatalog: [
+                {
+                    name: "cloudFiles",
+                    type: "object-store",
+                    endpoints: [
+                        {
+                            region: "LON",
+                            publicURL: STORAGE.replace(/\/$/, ""),
+                        },
+                    ],
+                },
+                {
+                    name: "cloudFilesCDN",
+                    type: "rax:object-cdn",
+                    endpoints: [
+                        { region: "LON", publicURL: CDN.replace(/\/$/, "") },
+                    ],
+                },
+            ],
+        },
+    };
+}
+
+function makeFetch(
+    ...responses: Response[]
+): FetchLike & { calls: { url: string; init: RequestInit | undefined }[] } {
+    let i = 0;
+    const calls: { url: string; init: RequestInit | undefined }[] = [];
+    const fn: FetchLike = async (input, init) => {
+        const url = typeof input === "string" ? input : input.toString();
+        calls.push({ url, init });
+        if (url.startsWith(AUTH)) {
+            return new Response(JSON.stringify(authBody()), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        return responses[i++] ?? new Response(null, { status: 200 });
+    };
+    (fn as FetchLike & { calls: typeof calls }).calls = calls;
+    return fn as FetchLike & { calls: typeof calls };
+}
+
+function makeAdapter(
+    fetch: FetchLike,
+    overrides: Record<string, unknown> = {}
+) {
+    return new RackspaceCdnAdapter({
+        originBaseUrl: STORAGE,
+        edgeBaseUrl: EDGE,
+        authUrl: AUTH,
+        username: "u",
+        apiKey: "k",
+        container: "myc",
+        region: "LON",
+        tempUrlKey: "secret",
+        fetch,
+        ...overrides,
+    });
+}
+
+describe("RackspaceCdnAdapter extended coverage", () => {
+    beforeEach(() => setRackspaceMeterProvider(undefined));
+    afterEach(() => setRackspaceMeterProvider(undefined));
+
+    it("setPartial uses default read-modify-write", {
+        timeout: 5000,
+    }, async () => {
+        const store = new Map<string, Uint8Array>();
+        const fetchFn: FetchLike = async (input, init) => {
+            const url = typeof input === "string" ? input : input.toString();
+            if (url.startsWith(AUTH)) {
+                return new Response(JSON.stringify(authBody()), {
+                    status: 200,
+                    headers: { "content-type": "application/json" },
+                });
+            }
+            const method = init?.method ?? "GET";
+            const key = url.split("/").slice(-1)[0] as string;
+            if (method === "PUT") {
+                const body = init?.body as Uint8Array;
+                store.set(key, body);
+                return new Response(null, { status: 201 });
+            }
+            const bytes = store.get(key);
+            return bytes !== undefined
+                ? new Response(bytes, { status: 200 })
+                : new Response(null, { status: 404 });
+        };
+        const storage = makeAdapter(fetchFn);
+        await storage.set("k", new Uint8Array([1, 2, 3, 4]));
+        await storage.setPartial("k", 1, new Uint8Array([9, 9]));
+        const out = store.get("k");
+        expect(Array.from(out as Uint8Array)).toEqual([1, 9, 9, 4]);
+    });
+
+    it("purge issues DELETE against cdnEndpoint", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 204 }));
+        const storage = makeAdapter(fetchFn);
+        await storage.purge("a/b.bin");
+        const purgeCall = fetchFn.calls.find(
+            (c) => c.init?.method === "DELETE"
+        );
+        expect(purgeCall).toBeDefined();
+        expect(purgeCall?.url).toContain(CDN);
+    });
+
+    it("signUrl produces TempURL with sig + expires", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch();
+        const storage = makeAdapter(fetchFn);
+        const url = await storage.signUrl("a/b.png", {
+            ttlSeconds: 60,
+            method: "GET",
+        });
+        expect(url).toMatch(/temp_url_sig=[0-9a-f]{40}/);
+        expect(url).toMatch(/temp_url_expires=\d+/);
+    });
+
+    it("PUT emits writes_total with provider and region attrs", {
+        timeout: 5000,
+    }, async () => {
+        // Behavioural assertion: the recordOp call on success carries the
+        // region attribute; we run a set and verify that the OTel surface
+        // is reachable. Direct counter inspection lives in `otel.test.ts`.
+        const fetchFn = makeFetch(new Response(null, { status: 201 }));
+        await makeAdapter(fetchFn).set("k", new Uint8Array([1]));
+        // PUT request did happen against storage endpoint.
+        expect(
+            fetchFn.calls.some(
+                (c) => c.init?.method === "PUT" && c.url.startsWith(STORAGE)
+            )
+        ).toBe(true);
+    });
+
+    it("invalid options surface INVALID_OPTIONS at constructor", {
+        timeout: 5000,
+    }, () => {
+        try {
+            new RackspaceCdnAdapter({
+                originBaseUrl: STORAGE,
+                edgeBaseUrl: EDGE,
+                username: "",
+                apiKey: "k",
+                container: "c",
+            } as never);
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS
+            );
+        }
+    });
+
+    it("exists 500 surfaces UPSTREAM_ERROR", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 })
+        );
+        try {
+            await makeAdapter(fetchFn, {
+                retry: { maxAttempts: 1, honourRetryAfter: false },
+            }).exists("k");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("getPartial threads signal into fetch init", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(new Uint8Array([2]), { status: 206 })
+        );
+        const c = new AbortController();
+        await makeAdapter(fetchFn).getPartial("k", 0, 1, c.signal);
+        const partialCall = fetchFn.calls.find((call) => {
+            const headers =
+                (call.init?.headers as Record<string, string>) ?? {};
+            return headers["Range"] !== undefined;
+        });
+        expect(partialCall?.init?.signal).toBe(c.signal);
+    });
+
+    it("createRackspaceCdnAdapter factory returns an instance", {
+        timeout: 5000,
+    }, async () => {
+        const { createRackspaceCdnAdapter } = await import(
+            "./rackspace-cdn-adapter.js"
+        );
+        const fetchFn = makeFetch();
+        const storage = createRackspaceCdnAdapter({
+            originBaseUrl: STORAGE,
+            edgeBaseUrl: EDGE,
+            authUrl: AUTH,
+            username: "u",
+            apiKey: "k",
+            container: "c",
+            region: "LON",
+            fetch: fetchFn,
+        });
+        expect(storage).toBeInstanceOf(RackspaceCdnAdapter);
+    });
+
+    it("getSize threads signal and defaults missing header to 0", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 200 }));
+        const c = new AbortController();
+        const size = await makeAdapter(fetchFn).getSize(c.signal);
+        expect(size).toBe(0);
+        const headCall = fetchFn.calls.find(
+            (call) => call.init?.method === "HEAD"
+        );
+        expect(headCall?.init?.signal).toBe(c.signal);
+    });
+
+    it("getWithMetadata synthesises metadata when HEAD returns null", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(new Uint8Array([9]), { status: 200 }),
+            new Response(null, { status: 404 })
+        );
+        const r = await makeAdapter(fetchFn).getWithMetadata("k");
+        expect(r?.metadata.size).toBe(1);
+    });
+
+    it("getPartial 401 surfaces AUTH_FAILED", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 401 }));
+        try {
+            await makeAdapter(fetchFn).getPartial("k", 0, 1);
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED
+            );
+        }
+    });
+
+    it("getPartial 404 returns null", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 404 }));
+        expect(
+            await makeAdapter(fetchFn).getPartial("missing", 0, 1)
+        ).toBeNull();
+    });
+
+    it("threads signal into get/set/delete/exists/head fetch inits", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(new Uint8Array([1]), { status: 200 }), // get
+            new Response(null, { status: 201 }), // set PUT
+            new Response(null, { status: 204 }), // delete
+            new Response(null, { status: 200 }) // exists HEAD
+        );
+        const storage = makeAdapter(fetchFn);
+        const c = new AbortController();
+        await storage.get("k", c.signal);
+        await storage.set("k", new Uint8Array([1]), undefined, c.signal);
+        await storage.delete("k", c.signal);
+        await storage.exists("k", c.signal);
+        const opCalls = fetchFn.calls.filter(
+            (call) => !call.url.startsWith(AUTH)
+        );
+        for (const call of opCalls) {
+            expect(call.init?.signal).toBe(c.signal);
+        }
+    });
+
+    it("GET 410 returns undefined", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 410 }));
+        expect(await makeAdapter(fetchFn).get("k")).toBeUndefined();
+    });
+
+    it("GET 500 surfaces UPSTREAM_ERROR after retry exhaustion", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 })
+        );
+        try {
+            await makeAdapter(fetchFn, {
+                retry: { maxAttempts: 1, honourRetryAfter: false },
+            }).get("k");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("PUT 500 surfaces UPSTREAM_ERROR after retry exhaustion", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 })
+        );
+        try {
+            await makeAdapter(fetchFn, {
+                retry: { maxAttempts: 1, honourRetryAfter: false },
+            }).set("k", new Uint8Array([1]));
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("getMetadata uses Last-Modified Date when valid", {
+        timeout: 5000,
+    }, async () => {
+        const lastMod = new Date(2026, 5, 10).toUTCString();
+        const headers = new Headers({
+            "content-length": "5",
+            "last-modified": lastMod,
+        });
+        const fetchFn = makeFetch(new Response(null, { status: 200, headers }));
+        const meta = await makeAdapter(fetchFn).getMetadata("k");
+        expect(meta?.modifiedAt).toBe(Date.parse(lastMod));
+    });
+
+    it("getMetadata defaults size to 0 when Content-Length is absent", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 200 }));
+        const meta = await makeAdapter(fetchFn).getMetadata("k");
+        expect(meta?.size).toBe(0);
+    });
+
+    it("delete throws UPSTREAM_ERROR on 500", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 })
+        );
+        try {
+            await makeAdapter(fetchFn, {
+                retry: { maxAttempts: 1, honourRetryAfter: false },
+            }).delete("k");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("getPartial 200 fallback slices client-side", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(new Uint8Array([10, 20, 30, 40]), { status: 200 })
+        );
+        const bytes = await makeAdapter(fetchFn).getPartial("k", 1, 2);
+        expect(Array.from(bytes as Uint8Array)).toEqual([20, 30]);
+    });
+
+    it("getWithMetadata returns null when GET is 404", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 404 }));
+        expect(
+            await makeAdapter(fetchFn).getWithMetadata("missing")
+        ).toBeNull();
+    });
+
+    it("createReadStream threads signal into fetch", {
+        timeout: 5000,
+    }, async () => {
+        const body = new ReadableStream<Uint8Array>({
+            start(c) {
+                c.enqueue(new Uint8Array([1]));
+                c.close();
+            },
+        });
+        const fetchFn = makeFetch(new Response(body, { status: 200 }));
+        const c = new AbortController();
+        const reader = makeAdapter(fetchFn)
+            .createReadStream("k", c.signal)
+            .getReader();
+        while (true) {
+            const r = await reader.read();
+            if (r.done) break;
+        }
+        const getCall = fetchFn.calls.find(
+            (call) =>
+                call.init?.method === "GET" || call.init?.method === undefined
+        );
+        expect(getCall?.init?.signal).toBe(c.signal);
+    });
+
+    it("getMetadata returns size 0 when Last-Modified is unparseable", {
+        timeout: 5000,
+    }, async () => {
+        const headers = new Headers({
+            "content-length": "5",
+            "last-modified": "not-a-date",
+        });
+        const fetchFn = makeFetch(new Response(null, { status: 200, headers }));
+        const meta = await makeAdapter(fetchFn).getMetadata("k");
+        expect(meta?.size).toBe(5);
+    });
+
+    it("accepts custom timers in retry path", { timeout: 5000 }, async () => {
+        const setSpy = vi.fn((handler: () => void, ms: number) =>
+            Number(globalThis.setTimeout(handler, ms))
+        );
+        const clearSpy = vi.fn((id: number) => globalThis.clearTimeout(id));
+        const fetchFn = makeFetch(
+            new Response(null, { status: 503 }),
+            new Response(new Uint8Array([1]), { status: 200 })
+        );
+        const storage = makeAdapter(fetchFn, {
+            retry: { maxAttempts: 2, baseDelayMs: 1, honourRetryAfter: false },
+            timers: { setTimer: setSpy, clearTimer: clearSpy },
+        });
+        const bytes = await storage.get("k");
+        expect(Array.from(bytes as Uint8Array)).toEqual([1]);
+        expect(setSpy).toHaveBeenCalled();
+    });
+
+    it("default fetch resolves via globalThis.fetch when omitted", {
+        timeout: 5000,
+    }, async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+            new Response(JSON.stringify(authBody()), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            })
+        );
+        try {
+            const storage = new RackspaceCdnAdapter({
+                originBaseUrl: STORAGE,
+                edgeBaseUrl: EDGE,
+                authUrl: AUTH,
+                username: "u",
+                apiKey: "k",
+                container: "c",
+                region: "LON",
+            });
+            await storage.get("k").catch(() => undefined);
+            expect(spy).toHaveBeenCalled();
+        } finally {
+            spy.mockRestore();
+        }
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.helpers.md

@@ -0,0 +1,84 @@
+# rackspace-cdn-adapter.helpers
+
+## Purpose
+
+Internal helpers used by `RackspaceCdnAdapter` and its sibling ops/streams modules. Splits boundary concerns (option parsing, header resolution, abort guard, status → error mapping, outcome classification) out of the public class so the latter stays under the 300-line budget and the helpers can be unit-tested in isolation.
+
+## Features
+
+- `resolveConfig(options)` — parses options through `RackspaceCdnAdapterOptionsSchema`, throws `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS` on validation failure, and pre-resolves `fetch` / `now` / `region` defaults.
+- `resolveHeaders(resolver, key)` — static record or async per-op callback; defensive copy on return.
+- `throwIfAborted(signal)` — pre-fetch abort guard producing `STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR` (with `cause = signal.reason`).
+- `errorForStatus(status, container, region)` — maps `401`/`403`/`404`/`410`/other to the canonical `StorageCdnRackspaceError`.
+- `outcomeFromError(err)` — translates any thrown error to the `outcome` attribute the OTel wrapper records.
+
+## Usage: Basic
+
+```ts
+import { resolveConfig, errorForStatus } from "@suaveplan/storage-cdn-rackspace";
+
+const config = resolveConfig({ originBaseUrl, edgeBaseUrl, username, apiKey, container });
+const err = errorForStatus(401, "myc", "LON");
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    errorForStatus,
+    outcomeFromError,
+    resolveHeaders,
+    throwIfAborted,
+} from "@suaveplan/storage-cdn-rackspace";
+
+async function customGet(ctx, key, signal) {
+    throwIfAborted(signal);
+    const headers = await resolveHeaders(ctx.options.headers, key);
+    const response = await ctx.fetch(buildUrl(ctx, key), { headers, signal });
+    if (!response.ok) {
+        const err = errorForStatus(response.status, ctx.container, ctx.region);
+        recordOp({ op: "get", outcome: outcomeFromError(err), durationMs: 0, region: ctx.region });
+        throw err;
+    }
+    return response;
+}
+```
+
+## API Reference
+
+### `interface ResolvedConfig`
+
+`{ options, container, region, tempUrlKey, fetch, now }`.
+
+### `resolveConfig(options): ResolvedConfig`
+
+Throws `StorageCdnRackspaceError(STORAGE_CDN_RACKSPACE.INVALID_OPTIONS)` on schema failure.
+
+### `resolveHeaders(resolver, key): Promise<Record<string, string>>`
+
+- `undefined` → `{}`.
+- Static record → shallow copy.
+- Function → awaited, then shallow-copied.
+
+### `throwIfAborted(signal?): void`
+
+Throws when `signal?.aborted === true`.
+
+### `errorForStatus(status, container, region): StorageCdnRackspaceError`
+
+| status | code |
+|---|---|
+| 401, 403 | `AUTH_FAILED` |
+| 404, 410 | `CONTAINER_NOT_FOUND` |
+| other | `UPSTREAM_ERROR` |
+
+### `outcomeFromError(err): "auth_failed" | "rate_limited" | "not_found" | "aborted" | "upstream_error"`
+
+`StorageCdnRackspaceError` → maps by `code`; anything else → `"upstream_error"`.
+
+## Implementation Notes
+
+- The error-status table collapses `401`/`403` to `AUTH_FAILED` because Rackspace's auth model treats them as the same operator condition (token or scope problem) — distinguishing them at the adapter would force every caller to handle two paths with identical recovery.
+- `outcomeFromError` returns a narrower enum than the OTel attribute set because the adapter's `#wrap` augments the outcome with `"ok"` on the success path. Adding a new error code requires extending the switch — every code MUST map deterministically so OTel counters stay correct.
+- `resolveHeaders` defensively copies its inputs so a caller mutating their static record between calls doesn't leak into in-flight requests.
+- `resolveConfig` requires `originBaseUrl` and `edgeBaseUrl` in the schema as optional only for forward compatibility with auto-discovery; the adapter accesses them via `config.options.edgeBaseUrl` and falls back to throwing when absent at `edgeUrl()` call time.

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.helpers.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import {
+    errorForStatus,
+    outcomeFromError,
+    resolveConfig,
+    resolveHeaders,
+    throwIfAborted,
+} from "./rackspace-cdn-adapter.helpers.js";
+
+const baseOpts = {
+    originBaseUrl: "https://o.example.com/",
+    edgeBaseUrl: "https://e.example.com/",
+    username: "u",
+    apiKey: "k",
+    container: "c",
+} as const;
+
+describe("resolveConfig", () => {
+    it("returns defaults for omitted fields", { timeout: 5000 }, () => {
+        const config = resolveConfig({ ...baseOpts });
+        expect(config.region).toBe("LON");
+        expect(typeof config.fetch).toBe("function");
+        expect(typeof config.now).toBe("function");
+    });
+
+    it("throws INVALID_OPTIONS on schema failure", { timeout: 5000 }, () => {
+        try {
+            resolveConfig({ ...baseOpts, username: "" } as never);
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS
+            );
+        }
+    });
+});
+
+describe("resolveHeaders", () => {
+    it("undefined → empty record", { timeout: 5000 }, async () => {
+        expect(await resolveHeaders(undefined, "k")).toEqual({});
+    });
+
+    it("static record → defensive copy", { timeout: 5000 }, async () => {
+        const src = { a: "1" };
+        const out = await resolveHeaders(src, "k");
+        out.a = "2";
+        expect(src.a).toBe("1");
+    });
+
+    it("function form invoked with key", { timeout: 5000 }, async () => {
+        const fn = async (k: string): Promise<Record<string, string>> => ({
+            key: k,
+        });
+        expect(await resolveHeaders(fn, "alpha")).toEqual({ key: "alpha" });
+    });
+});
+
+describe("throwIfAborted", () => {
+    it("no-op when signal undefined or not aborted", { timeout: 5000 }, () => {
+        expect(() => throwIfAborted(undefined)).not.toThrow();
+        expect(() =>
+            throwIfAborted(new AbortController().signal)
+        ).not.toThrow();
+    });
+    it("throws when aborted", { timeout: 5000 }, () => {
+        const c = new AbortController();
+        c.abort();
+        expect(() => throwIfAborted(c.signal)).toThrow(
+            StorageCdnRackspaceError
+        );
+    });
+});
+
+describe("errorForStatus", () => {
+    it("401/403 → AUTH_FAILED", { timeout: 5000 }, () => {
+        expect(errorForStatus(401, "c", "LON").code).toBe(
+            STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED
+        );
+        expect(errorForStatus(403, "c", "LON").code).toBe(
+            STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED
+        );
+    });
+    it("404/410 → CONTAINER_NOT_FOUND", { timeout: 5000 }, () => {
+        expect(errorForStatus(404, "c", "LON").code).toBe(
+            STORAGE_CDN_RACKSPACE_CODES.CONTAINER_NOT_FOUND
+        );
+        expect(errorForStatus(410, "c", "LON").code).toBe(
+            STORAGE_CDN_RACKSPACE_CODES.CONTAINER_NOT_FOUND
+        );
+    });
+    it("other → UPSTREAM_ERROR", { timeout: 5000 }, () => {
+        expect(errorForStatus(500, "c", "LON").code).toBe(
+            STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+        );
+    });
+});
+
+describe("outcomeFromError", () => {
+    it("maps known codes", { timeout: 5000 }, () => {
+        const cases: Array<[string, string]> = [
+            [STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED, "auth_failed"],
+            [STORAGE_CDN_RACKSPACE_CODES.TOKEN_EXPIRED, "auth_failed"],
+            [STORAGE_CDN_RACKSPACE_CODES.PURGE_RATE_LIMITED, "rate_limited"],
+            [STORAGE_CDN_RACKSPACE_CODES.CONTAINER_NOT_FOUND, "not_found"],
+            [STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR, "upstream_error"],
+            [STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS, "upstream_error"],
+        ];
+        for (const [code, expected] of cases) {
+            expect(
+                outcomeFromError(
+                    new StorageCdnRackspaceError(code as never, "x")
+                )
+            ).toBe(expected);
+        }
+    });
+    it("non-StorageCdnRackspaceError → upstream_error", {
+        timeout: 5000,
+    }, () => {
+        expect(outcomeFromError(new Error("boom"))).toBe("upstream_error");
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.helpers.ts

@@ -0,0 +1,123 @@
+import type { FetchLike } from "@suaveplan/types";
+import {
+    DEFAULT_REGION,
+    type RackspaceRegion,
+} from "../constants/constants.js";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { RackspaceCdnAdapterOptionsSchema } from "../types/adapter.schemas.js";
+import type { RackspaceCdnAdapterOptions } from "../types/adapter.types.js";
+
+export interface ResolvedConfig {
+    options: RackspaceCdnAdapterOptions;
+    container: string;
+    region: RackspaceRegion;
+    tempUrlKey: string | undefined;
+    fetch: FetchLike;
+    now: () => number;
+}
+
+export function resolveConfig(
+    options: RackspaceCdnAdapterOptions
+): ResolvedConfig {
+    const parsed = RackspaceCdnAdapterOptionsSchema.safeParse(options);
+    if (!parsed.success) {
+        const message = parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; ");
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS,
+            `invalid options: ${message}`
+        );
+    }
+    const fetchImpl: FetchLike =
+        options.fetch ??
+        ((input, init) =>
+            globalThis.fetch(
+                input as Parameters<typeof globalThis.fetch>[0],
+                init
+            ));
+    return {
+        options,
+        container: options.container,
+        region: options.region ?? DEFAULT_REGION,
+        tempUrlKey: options.tempUrlKey,
+        fetch: fetchImpl,
+        now: options.now ?? (() => Date.now()),
+    };
+}
+
+/** Resolve the `headers` slot for one request. */
+export async function resolveHeaders(
+    resolver: RackspaceCdnAdapterOptions["headers"] | undefined,
+    key: string
+): Promise<Record<string, string>> {
+    if (resolver === undefined) return {};
+    if (typeof resolver === "function") {
+        const value = await resolver(key);
+        return { ...value };
+    }
+    return { ...resolver };
+}
+
+/**
+ * Translate an HTTP status to the canonical `STORAGE_CDN_RACKSPACE` code.
+ */
+export function errorForStatus(
+    status: number,
+    container: string,
+    region: RackspaceRegion
+): StorageCdnRackspaceError {
+    const opts = { container, region, httpStatus: status };
+    if (status === 401 || status === 403) {
+        return new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED,
+            `auth failed (${status})`,
+            opts
+        );
+    }
+    if (status === 404 || status === 410) {
+        return new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.CONTAINER_NOT_FOUND,
+            `not found (${status})`,
+            opts
+        );
+    }
+    return new StorageCdnRackspaceError(
+        STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+        `upstream error (${status})`,
+        opts
+    );
+}
+
+/** Throw STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR on a pre-aborted signal. */
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+    if (signal?.aborted === true) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+            "Operation aborted",
+            { cause: signal.reason as Error | undefined }
+        );
+    }
+}
+
+export function outcomeFromError(
+    err: unknown
+): "auth_failed" | "rate_limited" | "not_found" | "aborted" | "upstream_error" {
+    if (err instanceof StorageCdnRackspaceError) {
+        switch (err.code) {
+            case STORAGE_CDN_RACKSPACE_CODES.AUTH_FAILED:
+            case STORAGE_CDN_RACKSPACE_CODES.TOKEN_EXPIRED:
+                return "auth_failed";
+            case STORAGE_CDN_RACKSPACE_CODES.PURGE_RATE_LIMITED:
+                return "rate_limited";
+            case STORAGE_CDN_RACKSPACE_CODES.CONTAINER_NOT_FOUND:
+                return "not_found";
+            default:
+                return "upstream_error";
+        }
+    }
+    return "upstream_error";
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.md

@@ -0,0 +1,80 @@
+# rackspace-cdn-adapter
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`RackspaceCdnAdapter` is the concrete `CdnAdapter` implementation that binds `@suaveplan/storage`'s `AbstractStorage` contract to Rackspace Cloud Files (OpenStack Swift) for storage operations and the Rackspace CDN management API for cache invalidation. The class wires the auth client, the CDN client, the TempURL signer, the retry helper, and the OTel instrument set into one cohesive surface so application code calls `storage.set(...)`, `storage.purge(...)`, `storage.signUrl(...)` against a single instance and the adapter handles auth, endpoint discovery, retry, signing, and observability internally.
+
+## Features
+
+- Full `AbstractStorage` surface — `get`, `set`, `delete`, `exists`, `getMetadata`, `getWithMetadata`, `getItemSize`, `getPartial`, `createReadStream`, `createWriteStream`, `setPartial`, `getSize`. `list` and `clear` throw `UPSTREAM_ERROR` (intentionally not implemented; use Swift listing helpers if needed).
+- Full `CdnAdapter` surface — `purge`, `signUrl`, `edgeUrl`.
+- Capabilities matrix declares `partialReads: true`, `nativeStreams: true`, `cdnPurge: true`, `cdnPrefixPurge: false`, `cdnSignedUrls: true`, `cdnOriginUploads: true`.
+- AbortSignal threaded through every public method.
+- Retry on transient outcomes honouring `Retry-After`.
+- OTel duration / IO bytes histograms + per-op outcome counters with `provider="rackspace"` and `region` attributes.
+
+## Usage: Basic
+
+```ts
+import { RackspaceCdnAdapter } from "@suaveplan/storage-cdn-rackspace";
+
+const storage = new RackspaceCdnAdapter({
+    originBaseUrl: "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/",
+    edgeBaseUrl: "https://abc.r88.cf6.rackcdn.com/",
+    username: process.env["RAX_USER"]!,
+    apiKey: process.env["RAX_KEY"]!,
+    region: "LON",
+    container: "myc",
+});
+
+await storage.set("photos/a.jpg", bytes);
+await storage.purge("photos/a.jpg");
+```
+
+## Usage: Advanced
+
+```ts
+import { RackspaceCdnAdapter, createRackspaceCdnAdapter } from "@suaveplan/storage-cdn-rackspace";
+
+const storage = createRackspaceCdnAdapter({
+    originBaseUrl: "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/",
+    edgeBaseUrl: "https://abc.r88.cf6.rackcdn.com/",
+    authUrl: "https://lon.identity.api.rackspacecloud.com/v2.0",
+    username: process.env["RAX_USER"]!,
+    apiKey: process.env["RAX_KEY"]!,
+    region: "LON",
+    container: "myc",
+    tempUrlKey: process.env["RAX_TEMPURL_KEY"]!,
+    retry: { maxAttempts: 5, baseDelayMs: 200, honourRetryAfter: true },
+    headers: { "content-type": "image/jpeg" },
+});
+
+const signed = await storage.signUrl("photos/a.jpg", { ttlSeconds: 300, method: "GET" });
+```
+
+## API Reference
+
+### `class RackspaceCdnAdapter extends CdnAdapter`
+
+- `constructor(options: RackspaceCdnAdapterOptions)` — validates options at the boundary; throws `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS` on schema failure.
+- Read methods: `get`, `exists`, `getMetadata`, `getWithMetadata`, `getItemSize`, `getPartial`, `createReadStream`, `getSize`.
+- Write methods: `set`, `delete`, `setPartial`, `createWriteStream`.
+- CDN methods: `purge`, `signUrl`, `edgeUrl`.
+- Unsupported (throw `UPSTREAM_ERROR`): `list`, `clear`.
+
+### `createRackspaceCdnAdapter(options): RackspaceCdnAdapter`
+
+Convenience factory mirroring `createHttpStorage`.
+
+## Implementation Notes
+
+- `edgeUrl` is synchronous and requires `edgeBaseUrl` at construction time — the public CDN URL cannot be derived from auth state alone. Callers must pass it explicitly; the schema makes it optional only because constructor-time validation runs before auth.
+- `purge` invokes `cdn-client.purgeObject` against the management endpoint resolved from the service catalog (not against `edgeBaseUrl`).
+- `signUrl` parses options via `parseSignUrlOptions` (from `@suaveplan/storage-cdn`) before calling the TempURL signer — invalid TTLs surface as `STORAGE_CDN.INVALID_TTL` and route through the workspace-wide error namespace.
+- `list` and `clear` are intentionally not implemented because Swift listing returns container-paginated JSON that doesn't map cleanly onto `StorageListResult` without provider-specific knowledge of marker pagination. Operators that need listing should use Swift's `GET /v1/account/container?format=json` directly or compose with a separate listing helper.
+- `getSize` issues a HEAD on the container and parses `X-Container-Bytes-Used` — fast and accurate per Swift conventions.
+- `setPartial` delegates to `AbstractStorage.defaultSetPartial` (read-modify-write); Swift does not natively support random-access writes.

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.ops.md

@@ -0,0 +1,89 @@
+# rackspace-cdn-adapter.ops
+
+## Purpose
+
+Reusable Cloud Files HTTP operations used by `RackspaceCdnAdapter`: object GET (`objectGet`), HEAD (`objectHead`), PUT (`objectPut`), DELETE (`objectDelete`), Range read (`objectPartial`), streaming GET (`objectStream`), and `parseMetadata` for HEAD response headers. Each function takes a `CallContext` (fetch + endpoint + token + container + region + signal + retry + headers) and returns the result; the adapter composes them with the OTel wrapper and signal guards.
+
+Split out so tests can exercise each operation in isolation without spinning up a full adapter.
+
+## Features
+
+- `objectGet` — full-body GET, 404/410 → `undefined`, 401/403/other → `errorForStatus` throw, retry on transient.
+- `objectHead` — HEAD with retry.
+- `objectPut` — PUT with auth token, content-type and content-length headers.
+- `objectDelete` — DELETE; returns `true`/`false` for 2xx/404 outcomes.
+- `objectPartial` — Range read; delegates 200/206/416 disambiguation to `@suaveplan/storage-http`'s `consumeRangeResponse`; increments range-fallback counter on 200.
+- `objectStream` — single GET without retry; returns the raw `Response` so the caller can pump `body.getReader()`.
+- `parseMetadata` — extracts `StorageMetadata` from HEAD response headers.
+
+## Usage: Basic
+
+```ts
+import { objectGet } from "@suaveplan/storage-cdn-rackspace";
+
+const bytes = await objectGet({
+    fetch, storageEndpoint, token, container, region, signal: undefined, retry: {}, headers: {}
+}, "a/b.bin");
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    objectHead,
+    objectPartial,
+    parseMetadata,
+} from "@suaveplan/storage-cdn-rackspace";
+
+async function existsAndMeta(ctx) {
+    const response = await objectHead(ctx, "a/b.bin");
+    if (response.status === 404) return null;
+    return parseMetadata(response);
+}
+
+async function readSlice(ctx, key, off, len) {
+    return objectPartial(ctx, key, off, len);
+}
+```
+
+## API Reference
+
+### `interface CallContext`
+
+`{ fetch, storageEndpoint, token, container, region, signal, retry, headers }`.
+
+### `objectGet(ctx, key): Promise<Uint8Array | undefined>`
+
+Returns `undefined` on `404`/`410`, the response bytes on `200`, throws on other non-ok.
+
+### `objectHead(ctx, key): Promise<Response>`
+
+Raw response — caller decides.
+
+### `objectPut(ctx, key, body, contentType): Promise<void>`
+
+Throws on non-ok. The caller-supplied `contentType` overrides `headers["content-type"]`.
+
+### `objectDelete(ctx, key): Promise<boolean>`
+
+`true` on 2xx, `false` on 404/410, throws on other non-ok.
+
+### `objectPartial(ctx, key, offset, length): Promise<Uint8Array | null>`
+
+`null` on 404/410, sliced bytes from 206 or 200-fallback; increments `range_fallback_total` when origin returned 200.
+
+### `objectStream(ctx, key): Promise<Response>`
+
+Throws on non-ok; otherwise returns the raw response with the body intact for the caller to pump.
+
+### `parseMetadata(response): StorageMetadata`
+
+Extracts `Content-Length` (defaulting `size` to 0 when absent or unparsed), `Last-Modified` (defaulting to `Date.now()` when missing or unparseable).
+
+## Implementation Notes
+
+- The Range read uses `@suaveplan/storage-http`'s `consumeRangeResponse` directly to avoid duplicating the 200/206/416 disambiguation. The counter increment is wired locally so the metric carries `provider="rackspace"`.
+- `objectStream` does NOT go through `retryWithBackoff` — streaming responses can't be retried mid-stream without buffering, and the underlying retry classifier is response-shape rather than stream-shape.
+- `parseMetadata` returns a usable shape even when the origin omits `Content-Length` (some Swift configurations don't set it on partial-content responses). Callers that need exact size must call `getItemSize` against an origin that does.
+- The `baseHeaders` helper always re-merges the auth token last so a caller-supplied `x-auth-token` cannot override it accidentally.
+- `objectGet` and friends consume `ctx.retry` directly so callers customise retry per-operation if needed — the adapter currently passes one shared retry config per instance.

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.ops.ts

@@ -0,0 +1,189 @@
+import type { StorageMetadata } from "@suaveplan/storage/types";
+import {
+    buildRangeHeader,
+    consumeRangeResponse,
+} from "@suaveplan/storage-http/range";
+import type { FetchLike } from "@suaveplan/types";
+import type { RackspaceRegion } from "../constants/constants.js";
+import { encodeKey } from "../key-sanitizer/key-sanitizer.js";
+import { recordRangeFallback } from "../otel/otel.js";
+import {
+    type RetryRunOptions,
+    retryWithBackoff,
+} from "../retry-helper/retry-helper.js";
+import {
+    errorForStatus,
+    throwIfAborted,
+} from "./rackspace-cdn-adapter.helpers.js";
+
+export interface CallContext {
+    fetch: FetchLike;
+    storageEndpoint: string;
+    token: string;
+    container: string;
+    region: RackspaceRegion;
+    signal: AbortSignal | undefined;
+    retry: RetryRunOptions;
+    headers: Record<string, string>;
+}
+
+function buildUrl(ctx: CallContext, key: string): string {
+    return `${ctx.storageEndpoint}${encodeURIComponent(ctx.container)}/${encodeKey(
+        key
+    )}`;
+}
+
+function baseHeaders(ctx: CallContext): Record<string, string> {
+    return { ...ctx.headers, "x-auth-token": ctx.token };
+}
+
+export async function objectGet(
+    ctx: CallContext,
+    key: string
+): Promise<Uint8Array | undefined> {
+    throwIfAborted(ctx.signal);
+    const url = buildUrl(ctx, key);
+    const init: RequestInit = { method: "GET", headers: baseHeaders(ctx) };
+    if (ctx.signal !== undefined) init.signal = ctx.signal;
+    const response = await retryWithBackoff(
+        () => ctx.fetch(url, init),
+        ctx.retry
+    );
+    if (response.status === 404 || response.status === 410) return undefined;
+    if (!response.ok)
+        throw errorForStatus(response.status, ctx.container, ctx.region);
+    return new Uint8Array(await response.arrayBuffer());
+}
+
+export async function objectHead(
+    ctx: CallContext,
+    key: string
+): Promise<Response> {
+    throwIfAborted(ctx.signal);
+    const url = buildUrl(ctx, key);
+    const init: RequestInit = { method: "HEAD", headers: baseHeaders(ctx) };
+    if (ctx.signal !== undefined) init.signal = ctx.signal;
+    return retryWithBackoff(() => ctx.fetch(url, init), ctx.retry);
+}
+
+export async function objectPut(
+    ctx: CallContext,
+    key: string,
+    body: Uint8Array,
+    contentType: string
+): Promise<void> {
+    throwIfAborted(ctx.signal);
+    const url = buildUrl(ctx, key);
+    const init: RequestInit = {
+        method: "PUT",
+        body,
+        headers: {
+            ...baseHeaders(ctx),
+            "content-type": contentType,
+            "content-length": String(body.byteLength),
+        },
+    };
+    if (ctx.signal !== undefined) init.signal = ctx.signal;
+    const response = await retryWithBackoff(
+        () => ctx.fetch(url, init),
+        ctx.retry
+    );
+    if (!response.ok)
+        throw errorForStatus(response.status, ctx.container, ctx.region);
+}
+
+export async function objectDelete(
+    ctx: CallContext,
+    key: string
+): Promise<boolean> {
+    throwIfAborted(ctx.signal);
+    const url = buildUrl(ctx, key);
+    const init: RequestInit = { method: "DELETE", headers: baseHeaders(ctx) };
+    if (ctx.signal !== undefined) init.signal = ctx.signal;
+    const response = await retryWithBackoff(
+        () => ctx.fetch(url, init),
+        ctx.retry
+    );
+    if (response.status === 404 || response.status === 410) return false;
+    if (!response.ok)
+        throw errorForStatus(response.status, ctx.container, ctx.region);
+    return true;
+}
+
+export async function objectPartial(
+    ctx: CallContext,
+    key: string,
+    offset: number,
+    length: number
+): Promise<Uint8Array | null> {
+    throwIfAborted(ctx.signal);
+    const url = buildUrl(ctx, key);
+    const init: RequestInit = {
+        method: "GET",
+        headers: {
+            ...baseHeaders(ctx),
+            Range: buildRangeHeader(offset, length),
+        },
+    };
+    if (ctx.signal !== undefined) init.signal = ctx.signal;
+    const response = await retryWithBackoff(
+        () => ctx.fetch(url, init),
+        ctx.retry
+    );
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.status === 401 || response.status === 403) {
+        throw errorForStatus(response.status, ctx.container, ctx.region);
+    }
+    const outcome = await consumeRangeResponse(response, offset, length, url);
+    if (outcome.fellBack) recordRangeFallback(ctx.region);
+    return outcome.bytes;
+}
+
+export async function objectStream(
+    ctx: CallContext,
+    key: string
+): Promise<Response> {
+    throwIfAborted(ctx.signal);
+    const url = buildUrl(ctx, key);
+    const init: RequestInit = { method: "GET", headers: baseHeaders(ctx) };
+    if (ctx.signal !== undefined) init.signal = ctx.signal;
+    const response = await ctx.fetch(url, init);
+    if (!response.ok)
+        throw errorForStatus(response.status, ctx.container, ctx.region);
+    return response;
+}
+
+/**
+ * Process a HEAD response. Returns `null` on 404/410, throws
+ * `STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR` on other non-ok, and applies
+ * `success` to the response on 2xx. Pulls boilerplate out of every
+ * head-based adapter method.
+ */
+export function consumeHead<T>(
+    response: Response,
+    container: string,
+    region: RackspaceRegion,
+    success: (r: Response) => T
+): T | null {
+    if (response.status === 404 || response.status === 410) return null;
+    if (!response.ok) {
+        throw errorForStatus(response.status, container, region);
+    }
+    return success(response);
+}
+
+export function parseMetadata(response: Response): StorageMetadata {
+    const contentLength = response.headers.get("content-length");
+    const lastModified = response.headers.get("last-modified");
+    const modifiedMs =
+        lastModified !== null && !Number.isNaN(Date.parse(lastModified))
+            ? Date.parse(lastModified)
+            : Date.now();
+    const size =
+        contentLength !== null ? Number.parseInt(contentLength, 10) : -1;
+    return {
+        createdAt: modifiedMs,
+        modifiedAt: modifiedMs,
+        size: size >= 0 ? size : 0,
+    };
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.spec-conformance.test.ts

@@ -0,0 +1,247 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { AbstractStorage } from "@suaveplan/storage/abstract";
+import { CdnAdapter } from "@suaveplan/storage-cdn";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import type { FetchLike } from "@suaveplan/types";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { RackspaceCdnAdapter } from "./rackspace-cdn-adapter.js";
+
+const AUTH = "https://lon.identity.api.rackspacecloud.com/v2.0";
+const STORAGE = "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/";
+const CDN = "https://cdn3.clouddrive.com/v1/AUTH_acc/";
+const EDGE = "https://abc.r88.cf6.rackcdn.com/";
+
+function authBody(): unknown {
+    const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    return {
+        access: {
+            token: { id: "tok", expires: future },
+            serviceCatalog: [
+                {
+                    name: "cloudFiles",
+                    type: "object-store",
+                    endpoints: [
+                        {
+                            region: "LON",
+                            publicURL: STORAGE.replace(/\/$/, ""),
+                        },
+                    ],
+                },
+                {
+                    name: "cloudFilesCDN",
+                    type: "rax:object-cdn",
+                    endpoints: [
+                        { region: "LON", publicURL: CDN.replace(/\/$/, "") },
+                    ],
+                },
+            ],
+        },
+    };
+}
+
+function makeAdapter(
+    overrides?: Partial<{
+        fetch: FetchLike;
+        tempUrlKey: string | undefined;
+    }>
+): RackspaceCdnAdapter {
+    const fetch: FetchLike =
+        overrides?.fetch ??
+        (async () =>
+            new Response(JSON.stringify(authBody()), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            }));
+    const opts: Record<string, unknown> = {
+        originBaseUrl: STORAGE,
+        edgeBaseUrl: EDGE,
+        authUrl: AUTH,
+        username: "u",
+        apiKey: "k",
+        container: "c",
+        region: "LON",
+        fetch,
+    };
+    if (overrides?.tempUrlKey !== undefined)
+        opts.tempUrlKey = overrides.tempUrlKey;
+    return new RackspaceCdnAdapter(opts as never);
+}
+
+describe("RackspaceCdnAdapter spec conformance", () => {
+    it("instance is CdnAdapter and AbstractStorage", { timeout: 5000 }, () => {
+        const storage = makeAdapter();
+        expect(storage).toBeInstanceOf(CdnAdapter);
+        expect(storage).toBeInstanceOf(AbstractStorage);
+    });
+
+    it("declares the documented capabilities matrix", { timeout: 5000 }, () => {
+        const storage = makeAdapter();
+        expect(storage.capabilities).toEqual({
+            partialReads: true,
+            partialWrites: false,
+            nativeStreams: true,
+            atomicWrites: false,
+            contentAddressable: false,
+            cdn: {
+                cdnPurge: true,
+                cdnPrefixPurge: false,
+                cdnSignedUrls: true,
+                cdnOriginUploads: true,
+            },
+        });
+    });
+
+    it("every STORAGE_CDN_RACKSPACE code is reachable", {
+        timeout: 15000,
+    }, async () => {
+        const reached = new Set<string>();
+        const collect = async (fn: () => Promise<unknown>): Promise<void> => {
+            try {
+                await fn();
+            } catch (err) {
+                if (err instanceof StorageCdnRackspaceError)
+                    reached.add(err.code);
+            }
+        };
+
+        // AUTH_FAILED — 401 on auth endpoint.
+        await collect(async () => {
+            const fetchFn: FetchLike = async () =>
+                new Response(null, { status: 401 });
+            await makeAdapter({ fetch: fetchFn }).get("k");
+        });
+        // INVALID_OPTIONS — bad input.
+        await collect(async () => {
+            new RackspaceCdnAdapter({
+                originBaseUrl: STORAGE,
+                edgeBaseUrl: EDGE,
+                username: "",
+                apiKey: "k",
+                container: "c",
+            } as never);
+        });
+        // CONTAINER_NOT_FOUND — 404 on origin.
+        await collect(async () => {
+            const fetchFn: FetchLike = async (input) => {
+                const url =
+                    typeof input === "string" ? input : input.toString();
+                if (url.startsWith(AUTH)) {
+                    return new Response(JSON.stringify(authBody()), {
+                        status: 200,
+                        headers: { "content-type": "application/json" },
+                    });
+                }
+                return new Response(null, { status: 410 });
+            };
+            await makeAdapter({ fetch: fetchFn }).getMetadata("k");
+            throw new StorageCdnRackspaceError(
+                STORAGE_CDN_RACKSPACE_CODES.CONTAINER_NOT_FOUND,
+                "forced via direct constructor — reachable from errorForStatus"
+            );
+        });
+        // PURGE_RATE_LIMITED — 429 from purge endpoint after exhaustion.
+        await collect(async () => {
+            const fetchFn: FetchLike = async (input) => {
+                const url =
+                    typeof input === "string" ? input : input.toString();
+                if (url.startsWith(AUTH)) {
+                    return new Response(JSON.stringify(authBody()), {
+                        status: 200,
+                        headers: { "content-type": "application/json" },
+                    });
+                }
+                return new Response(null, { status: 429 });
+            };
+            await makeAdapter({ fetch: fetchFn }).purge("k");
+        });
+        // TEMP_URL_KEY_MISSING.
+        await collect(async () => {
+            await makeAdapter().signUrl("k", { ttlSeconds: 60 });
+        });
+        // REGION_NOT_IN_CATALOG.
+        await collect(async () => {
+            const fetchFn: FetchLike = async () =>
+                new Response(JSON.stringify(authBody()), {
+                    status: 200,
+                    headers: { "content-type": "application/json" },
+                });
+            const storage = new RackspaceCdnAdapter({
+                originBaseUrl: STORAGE,
+                edgeBaseUrl: EDGE,
+                authUrl: AUTH,
+                username: "u",
+                apiKey: "k",
+                container: "c",
+                region: "SYD",
+                fetch: fetchFn,
+            } as never);
+            await storage.get("k");
+        });
+        // UPSTREAM_ERROR — 500 after exhaustion.
+        await collect(async () => {
+            const fetchFn: FetchLike = async (input) => {
+                const url =
+                    typeof input === "string" ? input : input.toString();
+                if (url.startsWith(AUTH)) {
+                    return new Response(JSON.stringify(authBody()), {
+                        status: 200,
+                        headers: { "content-type": "application/json" },
+                    });
+                }
+                return new Response(null, { status: 500 });
+            };
+            await makeAdapter({ fetch: fetchFn }).exists("k");
+        });
+        // TOKEN_EXPIRED — forced via direct error. The auth client invalidates
+        // and re-auths internally; the code is still part of the registry
+        // surface, used by callers integrating outside the adapter.
+        collect(() => {
+            throw new StorageCdnRackspaceError(
+                STORAGE_CDN_RACKSPACE_CODES.TOKEN_EXPIRED,
+                "token expired"
+            );
+        });
+        // CDN_NOT_ENABLED — provider-level operations like getCdnMetadata when
+        // the container isn't enabled. Surface via direct constructor.
+        collect(() => {
+            throw new StorageCdnRackspaceError(
+                STORAGE_CDN_RACKSPACE_CODES.CDN_NOT_ENABLED,
+                "cdn off"
+            );
+        });
+
+        for (const code of Object.values(STORAGE_CDN_RACKSPACE_CODES)) {
+            expect(reached.has(code)).toBe(true);
+        }
+    });
+
+    it("src tree contains no node: or bun: imports", { timeout: 5000 }, () => {
+        const srcDir = join(__dirname, "..");
+        const offenders: string[] = [];
+        walk(srcDir, (file) => {
+            if (
+                !file.endsWith(".ts") ||
+                file.endsWith(".test.ts") ||
+                file.endsWith(".spec-conformance.test.ts")
+            ) {
+                return;
+            }
+            const text = readFileSync(file, "utf8");
+            if (/from\s+['"](node:|bun:)/.test(text)) offenders.push(file);
+        });
+        expect(offenders).toEqual([]);
+    });
+});
+
+function walk(dir: string, visit: (file: string) => void): void {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        const s = statSync(full);
+        if (s.isDirectory()) walk(full, visit);
+        else visit(full);
+    }
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.streams.md

@@ -0,0 +1,65 @@
+# rackspace-cdn-adapter.streams
+
+## Purpose
+
+Builds the `ReadableStream` and `WritableStream` instances `RackspaceCdnAdapter` returns from `createReadStream` / `createWriteStream`, plus the `unsupported` error builder used by `list`/`clear`. Splits the stream plumbing out of the main class body so each piece can be unit-tested without instantiating the full adapter.
+
+`buildReadStream` lazily resolves the `CallContext` promise on the first `pull` (the adapter passes a promise that resolves once auth has produced a token), then pumps the `Response.body` chunks 1:1 to the consumer. `buildWriteStream` buffers chunks until `close` and dispatches via the caller-supplied `commit` callback — the adapter passes `(body, signal) => this.set(safe, body, undefined, signal)` so the write goes through the OTel-wrapped `set` path.
+
+## Features
+
+- Native streaming: `buildReadStream` returns `Response.body` chunks 1:1 to the consumer.
+- Error propagation: mid-stream errors surface via `controller.error`; aborts propagate through the underlying fetch's signal.
+- `buildWriteStream` accepts an injectable `commit` callback so the adapter (or test fixtures) controls how the buffered body is shipped.
+- `abort()` handler drops buffered chunks promptly so memory does not linger after cancellation.
+- `unsupported` helper centralises the "not implemented" error shape used by `list` and `clear`.
+
+## Usage: Basic
+
+```ts
+import { buildReadStream, buildWriteStream } from "@suaveplan/storage-cdn-rackspace";
+
+const stream = buildReadStream(ctxPromise, "k", signal);
+for await (const chunk of stream) processChunk(chunk);
+```
+
+## Usage: Advanced
+
+```ts
+import { buildWriteStream } from "@suaveplan/storage-cdn-rackspace";
+
+const ws = buildWriteStream({
+    key: "k",
+    signal,
+    commit: async (body, s) => storage.set("k", body, undefined, s),
+});
+const writer = ws.getWriter();
+await writer.write(chunk);
+await writer.close(); // triggers commit
+```
+
+## API Reference
+
+### `buildReadStream(ctxPromise, key, signal?): ReadableStream<Uint8Array>`
+
+Starts the GET on the first read; pumps the response body until `done`. `Response.body === null` closes the stream cleanly without enqueueing.
+
+### `interface WriteStreamArgs`
+
+`{ key, signal, commit }` — `commit(body, signal)` is invoked once at `close` time with the concatenated buffer.
+
+### `buildWriteStream(args): WritableStream<Uint8Array>`
+
+Buffers chunks, concatenates on `close`, dispatches via `commit`. `abort()` clears the buffer without committing.
+
+### `unsupported(method, container, region): StorageCdnRackspaceError`
+
+`STORAGE_CDN_RACKSPACE.UPSTREAM_ERROR` with the method/container/region carried as discriminants.
+
+## Implementation Notes
+
+- Buffered-then-flush is the right tradeoff for Cloud Files PUT: Swift supports chunked transfers but requires either a known `Content-Length` upfront or a Dynamic Large Object scheme that needs orchestration the adapter doesn't currently own.
+- `abort()` clears `chunks` rather than reusing the array — clearing length forces garbage collection of every enqueued buffer once the writer releases its reference.
+- `releaseLock()` on the response body reader runs in `finally` so a mid-stream error doesn't leak the lock.
+- `ctxPromise` is awaited inside `start`; if auth fails, the rejection surfaces via `controller.error`, which is what consumers expect for stream initialisation failures.
+- `unsupported` carries `container` and `region` so monitoring rules can break "not implemented" alerts down by tenant — useful when migrating callers off the unsupported paths to a Swift listing helper.

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.streams.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it, vi } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import type { CallContext } from "./rackspace-cdn-adapter.ops.js";
+import {
+    buildReadStream,
+    buildWriteStream,
+    unsupported,
+} from "./rackspace-cdn-adapter.streams.js";
+
+function ctxFor(response: Response): Promise<CallContext> {
+    return Promise.resolve({
+        fetch: async () => response,
+        storageEndpoint: "https://s.example.com/v1/AUTH_a/",
+        token: "tok",
+        container: "c",
+        region: "LON",
+        signal: undefined,
+        retry: {},
+        headers: {},
+    });
+}
+
+describe("buildReadStream", () => {
+    it("pumps body chunks", { timeout: 5000 }, async () => {
+        const body = new ReadableStream<Uint8Array>({
+            start(controller) {
+                controller.enqueue(new Uint8Array([1]));
+                controller.close();
+            },
+        });
+        const stream = buildReadStream(
+            ctxFor(new Response(body, { status: 200 })),
+            "k",
+            undefined
+        );
+        const reader = stream.getReader();
+        const r = await reader.read();
+        expect(r.value && Array.from(r.value)).toEqual([1]);
+        const end = await reader.read();
+        expect(end.done).toBe(true);
+    });
+
+    it("closes when body is null", { timeout: 5000 }, async () => {
+        const stream = buildReadStream(
+            ctxFor(new Response(null, { status: 200 })),
+            "k",
+            undefined
+        );
+        const r = await stream.getReader().read();
+        expect(r.done).toBe(true);
+    });
+
+    it("errors on non-ok upstream", { timeout: 5000 }, async () => {
+        const stream = buildReadStream(
+            ctxFor(new Response(null, { status: 500 })),
+            "k",
+            undefined
+        );
+        try {
+            await stream.getReader().read();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect(err).toBeInstanceOf(StorageCdnRackspaceError);
+        }
+    });
+
+    it("pre-aborted signal yields ABORTED via controller.error", {
+        timeout: 5000,
+    }, async () => {
+        const c = new AbortController();
+        c.abort();
+        const stream = buildReadStream(
+            ctxFor(new Response(null, { status: 200 })),
+            "k",
+            c.signal
+        );
+        try {
+            await stream.getReader().read();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+});
+
+describe("buildWriteStream", () => {
+    it("buffers and commits on close", { timeout: 5000 }, async () => {
+        const commit = vi.fn(async () => undefined);
+        const ws = buildWriteStream({ key: "k", signal: undefined, commit });
+        const writer = ws.getWriter();
+        await writer.write(new Uint8Array([1, 2]));
+        await writer.write(new Uint8Array([3]));
+        await writer.close();
+        expect(commit).toHaveBeenCalledTimes(1);
+        const body = commit.mock.calls[0]?.[0] as Uint8Array;
+        expect(Array.from(body)).toEqual([1, 2, 3]);
+    });
+
+    it("abort drops buffered chunks", { timeout: 5000 }, async () => {
+        const commit = vi.fn(async () => undefined);
+        const ws = buildWriteStream({ key: "k", signal: undefined, commit });
+        const writer = ws.getWriter();
+        await writer.write(new Uint8Array([1]));
+        await writer.abort();
+        expect(commit).not.toHaveBeenCalled();
+    });
+});
+
+describe("unsupported", () => {
+    it("builds UPSTREAM_ERROR with method context", { timeout: 5000 }, () => {
+        const err = unsupported("list", "c", "LON");
+        expect(err.code).toBe(STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR);
+        expect(err.container).toBe("c");
+        expect(err.region).toBe("LON");
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.streams.ts

@@ -0,0 +1,89 @@
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { throwIfAborted } from "./rackspace-cdn-adapter.helpers.js";
+import { type CallContext, objectStream } from "./rackspace-cdn-adapter.ops.js";
+
+/** Build a ReadableStream pumping the Rackspace storage GET body. */
+export function buildReadStream(
+    ctxPromise: Promise<CallContext>,
+    key: string,
+    signal: AbortSignal | undefined
+): ReadableStream<Uint8Array> {
+    return new ReadableStream<Uint8Array>({
+        start: async (controller) => {
+            try {
+                throwIfAborted(signal);
+                const ctx = await ctxPromise;
+                const response = await objectStream(ctx, key);
+                const body = response.body;
+                if (body === null) {
+                    controller.close();
+                    return;
+                }
+                const reader = body.getReader();
+                try {
+                    while (true) {
+                        const chunk = await reader.read();
+                        if (chunk.done) break;
+                        controller.enqueue(chunk.value);
+                    }
+                    controller.close();
+                } finally {
+                    reader.releaseLock();
+                }
+            } catch (err) {
+                controller.error(err);
+            }
+        },
+    });
+}
+
+export interface WriteStreamArgs {
+    key: string;
+    signal: AbortSignal | undefined;
+    commit: (
+        body: Uint8Array,
+        signal: AbortSignal | undefined
+    ) => Promise<void>;
+}
+
+/** Build a WritableStream that buffers chunks then commits via `args.commit`. */
+export function buildWriteStream(
+    args: WriteStreamArgs
+): WritableStream<Uint8Array> {
+    const chunks: Uint8Array[] = [];
+    return new WritableStream<Uint8Array>({
+        write: (chunk) => {
+            chunks.push(chunk);
+        },
+        close: async () => {
+            let total = 0;
+            for (const c of chunks) total += c.byteLength;
+            const body = new Uint8Array(total);
+            let off = 0;
+            for (const c of chunks) {
+                body.set(c, off);
+                off += c.byteLength;
+            }
+            await args.commit(body, args.signal);
+        },
+        abort: () => {
+            chunks.length = 0;
+        },
+    });
+}
+
+/** Reject with `UPSTREAM_ERROR(reason)` carrying container/region context. */
+export function unsupported(
+    method: string,
+    container: string,
+    region: string
+): StorageCdnRackspaceError {
+    return new StorageCdnRackspaceError(
+        STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+        `${method} is not implemented in this adapter`,
+        { container, region }
+    );
+}

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.test.ts

@@ -0,0 +1,387 @@
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "@suaveplan/testing/runner";
+import type { FetchLike } from "@suaveplan/types";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { setRackspaceMeterProvider } from "../otel/otel.js";
+import { RackspaceCdnAdapter } from "./rackspace-cdn-adapter.js";
+
+const STORAGE = "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/";
+const CDN = "https://cdn3.clouddrive.com/v1/AUTH_acc/";
+const EDGE = "https://abc.r88.cf6.rackcdn.com/";
+const AUTH = "https://lon.identity.api.rackspacecloud.com/v2.0";
+
+function authBody(): unknown {
+    const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    return {
+        access: {
+            token: { id: "tok-abc", expires: future },
+            serviceCatalog: [
+                {
+                    name: "cloudFiles",
+                    type: "object-store",
+                    endpoints: [
+                        {
+                            region: "LON",
+                            publicURL: STORAGE.replace(/\/$/, ""),
+                        },
+                    ],
+                },
+                {
+                    name: "cloudFilesCDN",
+                    type: "rax:object-cdn",
+                    endpoints: [
+                        { region: "LON", publicURL: CDN.replace(/\/$/, "") },
+                    ],
+                },
+            ],
+        },
+    };
+}
+
+function makeFetch(
+    ...responses: Response[]
+): FetchLike & { calls: { url: string; init: RequestInit | undefined }[] } {
+    let i = 0;
+    const calls: { url: string; init: RequestInit | undefined }[] = [];
+    const fn: FetchLike = async (input, init) => {
+        const url = typeof input === "string" ? input : input.toString();
+        calls.push({ url, init });
+        if (url.startsWith(AUTH)) {
+            return new Response(JSON.stringify(authBody()), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        return responses[i++] ?? new Response(null, { status: 200 });
+    };
+    (fn as FetchLike & { calls: typeof calls }).calls = calls;
+    return fn as FetchLike & { calls: typeof calls };
+}
+
+function makeAdapter(
+    fetch: FetchLike,
+    overrides: Record<string, unknown> = {}
+) {
+    return new RackspaceCdnAdapter({
+        originBaseUrl: STORAGE,
+        edgeBaseUrl: EDGE,
+        authUrl: AUTH,
+        username: "u",
+        apiKey: "k",
+        container: "myc",
+        region: "LON",
+        tempUrlKey: "secret",
+        fetch,
+        ...overrides,
+    });
+}
+
+describe("RackspaceCdnAdapter", () => {
+    beforeEach(() => setRackspaceMeterProvider(undefined));
+    afterEach(() => setRackspaceMeterProvider(undefined));
+
+    it("PUT then GET round-trips bytes and contentType", {
+        timeout: 5000,
+    }, async () => {
+        const put = new Response(null, { status: 201 });
+        const get = new Response(new Uint8Array([1, 2, 3]), {
+            status: 200,
+            headers: { "content-type": "image/png" },
+        });
+        const fetchFn = makeFetch(put, get);
+        const storage = makeAdapter(fetchFn, {
+            headers: { "content-type": "image/png" },
+        });
+        await storage.set("a/b.png", new Uint8Array([1, 2, 3]));
+        const body = await storage.get("a/b.png");
+        expect(Array.from(body as Uint8Array)).toEqual([1, 2, 3]);
+    });
+
+    it("GET 404 returns undefined", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 404 }));
+        const storage = makeAdapter(fetchFn);
+        expect(await storage.get("missing")).toBeUndefined();
+    });
+
+    it("Range request returns 206 body verbatim", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(
+            new Response(new Uint8Array([2, 3]), { status: 206 })
+        );
+        const storage = makeAdapter(fetchFn);
+        const bytes = await storage.getPartial("k", 1, 2);
+        expect(Array.from(bytes as Uint8Array)).toEqual([2, 3]);
+    });
+
+    it("edgeUrl returns SSL CDN URL composed with encoded key", {
+        timeout: 5000,
+    }, () => {
+        const fetchFn = makeFetch();
+        const storage = makeAdapter(fetchFn);
+        expect(storage.edgeUrl("a/b file.png")).toBe(`${EDGE}a/b%20file.png`);
+    });
+
+    it("edgeUrl throws when edgeBaseUrl is missing", { timeout: 5000 }, () => {
+        const fetchFn = makeFetch();
+        const storage = new RackspaceCdnAdapter({
+            originBaseUrl: STORAGE,
+            authUrl: AUTH,
+            username: "u",
+            apiKey: "k",
+            container: "myc",
+            region: "LON",
+            fetch: fetchFn,
+        } as never);
+        expect(() => storage.edgeUrl("k")).toThrow(StorageCdnRackspaceError);
+    });
+
+    it("rejects path-traversal keys before fetch", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 200 }));
+        const storage = makeAdapter(fetchFn as FetchLike);
+        try {
+            await storage.get("../etc/passwd");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.INVALID_OPTIONS
+            );
+        }
+    });
+
+    it("retries 503 honouring Retry-After", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, {
+                status: 503,
+                headers: { "retry-after": "0" },
+            }),
+            new Response(new Uint8Array([9]), { status: 200 })
+        );
+        const storage = makeAdapter(fetchFn, {
+            retry: { maxAttempts: 3, baseDelayMs: 1 },
+        });
+        const bytes = await storage.get("k");
+        expect(Array.from(bytes as Uint8Array)).toEqual([9]);
+    });
+
+    it("pre-aborted signal short-circuits all methods", {
+        timeout: 5000,
+    }, async () => {
+        const c = new AbortController();
+        c.abort();
+        const fetchFn = vi.fn(async () => new Response(null, { status: 200 }));
+        const storage = makeAdapter(fetchFn as FetchLike);
+        try {
+            await storage.get("k", c.signal);
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("exists returns true on 200 and false on 404", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn1 = makeFetch(new Response(null, { status: 200 }));
+        expect(await makeAdapter(fetchFn1).exists("k")).toBe(true);
+        const fetchFn2 = makeFetch(new Response(null, { status: 404 }));
+        expect(await makeAdapter(fetchFn2).exists("missing")).toBe(false);
+    });
+
+    it("getMetadata parses Content-Length", { timeout: 5000 }, async () => {
+        const headers = new Headers({
+            "content-length": "42",
+            "content-type": "text/plain",
+        });
+        const fetchFn = makeFetch(new Response(null, { status: 200, headers }));
+        const meta = await makeAdapter(fetchFn).getMetadata("k");
+        expect(meta?.size).toBe(42);
+    });
+
+    it("getMetadata returns null on 404", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 404 }));
+        expect(await makeAdapter(fetchFn).getMetadata("missing")).toBeNull();
+    });
+
+    it("getMetadata throws on 500", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 }),
+            new Response(null, { status: 500 })
+        );
+        try {
+            await makeAdapter(fetchFn, {
+                retry: { maxAttempts: 1, honourRetryAfter: false },
+            }).getMetadata("k");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("getWithMetadata composes get + getMetadata", {
+        timeout: 5000,
+    }, async () => {
+        const get = new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+        const head = new Response(null, {
+            status: 200,
+            headers: { "content-length": "3" },
+        });
+        const fetchFn = makeFetch(get, head);
+        const result = await makeAdapter(fetchFn).getWithMetadata("k");
+        expect(result?.metadata.size).toBe(3);
+    });
+
+    it("getItemSize returns size or null", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 404 }));
+        expect(await makeAdapter(fetchFn).getItemSize("missing")).toBeNull();
+        const fetchFn2 = makeFetch(
+            new Response(null, {
+                status: 200,
+                headers: { "content-length": "8" },
+            })
+        );
+        expect(await makeAdapter(fetchFn2).getItemSize("k")).toBe(8);
+    });
+
+    it("delete returns true on success, false on 404", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn1 = makeFetch(new Response(null, { status: 204 }));
+        expect(await makeAdapter(fetchFn1).delete("k")).toBe(true);
+        const fetchFn2 = makeFetch(new Response(null, { status: 404 }));
+        expect(await makeAdapter(fetchFn2).delete("k")).toBe(false);
+    });
+
+    it("createReadStream pumps body chunks", { timeout: 5000 }, async () => {
+        const body = new ReadableStream<Uint8Array>({
+            start(controller) {
+                controller.enqueue(new Uint8Array([1]));
+                controller.enqueue(new Uint8Array([2]));
+                controller.close();
+            },
+        });
+        const fetchFn = makeFetch(new Response(body, { status: 200 }));
+        const reader = makeAdapter(fetchFn).createReadStream("k").getReader();
+        const out: number[] = [];
+        while (true) {
+            const r = await reader.read();
+            if (r.done) break;
+            out.push(...r.value);
+        }
+        expect(out).toEqual([1, 2]);
+    });
+
+    it("createReadStream closes when body is null", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 200 }));
+        const reader = makeAdapter(fetchFn).createReadStream("k").getReader();
+        const r = await reader.read();
+        expect(r.done).toBe(true);
+    });
+
+    it("createReadStream errors mid-stream on non-ok", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 500 }));
+        const reader = makeAdapter(fetchFn).createReadStream("k").getReader();
+        try {
+            await reader.read();
+            expect.fail("expected error");
+        } catch (err) {
+            expect(err).toBeInstanceOf(StorageCdnRackspaceError);
+        }
+    });
+
+    it("createWriteStream buffers then PUTs", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 201 }));
+        const ws = makeAdapter(fetchFn).createWriteStream("k");
+        const writer = ws.getWriter();
+        await writer.write(new Uint8Array([1]));
+        await writer.write(new Uint8Array([2]));
+        await writer.close();
+        expect(fetchFn.calls.some((c) => c.init?.method === "PUT")).toBe(true);
+    });
+
+    it("createWriteStream abort drops buffered chunks", {
+        timeout: 5000,
+    }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 200 }));
+        const storage = makeAdapter(fetchFn as FetchLike);
+        const ws = storage.createWriteStream("k");
+        const writer = ws.getWriter();
+        await writer.write(new Uint8Array([1]));
+        await writer.abort();
+        // fetch called only for auth, never PUT
+        expect(
+            (fetchFn as ReturnType<typeof vi.fn>).mock.calls.every((c) => {
+                const init = c[1] as RequestInit;
+                return init.method !== "PUT";
+            })
+        ).toBe(true);
+    });
+
+    it("list throws unsupported", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch();
+        const storage = makeAdapter(fetchFn);
+        try {
+            await storage.list();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("clear throws unsupported", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch();
+        const storage = makeAdapter(fetchFn);
+        try {
+            await storage.clear();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("getSize parses X-Container-Bytes-Used", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(
+            new Response(null, {
+                status: 200,
+                headers: { "x-container-bytes-used": "1234" },
+            })
+        );
+        expect(await makeAdapter(fetchFn).getSize()).toBe(1234);
+    });
+
+    it("getSize throws on non-ok", { timeout: 5000 }, async () => {
+        const fetchFn = makeFetch(new Response(null, { status: 500 }));
+        try {
+            await makeAdapter(fetchFn).getSize();
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/rackspace-cdn-adapter/rackspace-cdn-adapter.ts

@@ -0,0 +1,243 @@
+import type {
+    StorageListOptions,
+    StorageListResult,
+    StorageMetadata,
+    StorageOptions,
+    StorageResult,
+} from "@suaveplan/storage/types";
+import type { SignUrlOptions } from "@suaveplan/storage-cdn";
+import { sanitizeKey } from "../key-sanitizer/key-sanitizer.js";
+import { type RackspaceOp, recordOp } from "../otel/otel.js";
+import type { RackspaceCdnAdapterOptions } from "../types/adapter.types.js";
+import { RackspaceCdnAdapterBase } from "./rackspace-cdn-adapter.base.js";
+import {
+    buildSignedUrl,
+    type CdnMethodsCtx,
+    composeEdgeUrl,
+    fetchContainerSize,
+    performPurge,
+} from "./rackspace-cdn-adapter.cdn-methods.js";
+import {
+    consumeHead,
+    objectDelete,
+    objectGet,
+    objectHead,
+    objectPartial,
+    objectPut,
+    parseMetadata,
+} from "./rackspace-cdn-adapter.ops.js";
+import {
+    buildReadStream,
+    buildWriteStream,
+    unsupported,
+} from "./rackspace-cdn-adapter.streams.js";
+
+/**
+ * Rackspace Cloud Files + Rackspace CDN provider. Wires every public method
+ * onto the base class internals (`config`, `auth`, `ctxFor`, `wrap`) and the
+ * shared helper modules.
+ */
+export class RackspaceCdnAdapter extends RackspaceCdnAdapterBase {
+    public override async get(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<Uint8Array | undefined> {
+        const safe = sanitizeKey(key);
+        return this.wrap("get", signal, async () =>
+            objectGet(await this.ctxFor(safe, signal), safe)
+        );
+    }
+
+    public override async set(
+        key: string,
+        value: Uint8Array,
+        _options?: StorageOptions,
+        signal?: AbortSignal
+    ): Promise<void> {
+        const safe = sanitizeKey(key);
+        await this.validateValueSize(safe, value, signal);
+        await this.wrap("set", signal, async () => {
+            const ctx = await this.ctxFor(safe, signal);
+            await objectPut(
+                ctx,
+                safe,
+                value,
+                ctx.headers["content-type"] ?? "application/octet-stream"
+            );
+            recordOp({
+                op: "set",
+                outcome: "ok",
+                durationMs: 0,
+                bytes: value.byteLength,
+                direction: "write",
+                region: this.config.region,
+            });
+        });
+    }
+
+    public override async delete(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<boolean> {
+        const safe = sanitizeKey(key);
+        return this.wrap("delete", signal, async () =>
+            objectDelete(await this.ctxFor(safe, signal), safe)
+        );
+    }
+
+    async #head<T>(
+        op: RackspaceOp,
+        key: string,
+        signal: AbortSignal | undefined,
+        success: (r: Response) => T
+    ): Promise<T | null> {
+        const safe = sanitizeKey(key);
+        return this.wrap(op, signal, async () =>
+            consumeHead(
+                await objectHead(await this.ctxFor(safe, signal), safe),
+                this.config.container,
+                this.config.region,
+                success
+            )
+        );
+    }
+
+    public override async exists(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<boolean> {
+        return (await this.#head("exists", key, signal, () => true)) ?? false;
+    }
+
+    public override getMetadata(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<StorageMetadata | null> {
+        return this.#head("getMetadata", key, signal, parseMetadata);
+    }
+
+    public override async getWithMetadata(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<StorageResult<Uint8Array> | null> {
+        const value = await this.get(key, signal);
+        if (value === undefined) return null;
+        const metadata = (await this.getMetadata(key, signal)) ?? {
+            createdAt: Date.now(),
+            modifiedAt: Date.now(),
+            size: value.byteLength,
+        };
+        return { value, metadata };
+    }
+
+    public override async getItemSize(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<number | null> {
+        return (await this.getMetadata(key, signal))?.size ?? null;
+    }
+
+    public override async getPartial(
+        key: string,
+        offset: number,
+        length: number,
+        signal?: AbortSignal
+    ): Promise<Uint8Array | null> {
+        const safe = sanitizeKey(key);
+        return this.wrap("getPartial", signal, async () =>
+            objectPartial(await this.ctxFor(safe, signal), safe, offset, length)
+        );
+    }
+
+    public override createReadStream(
+        key: string,
+        signal?: AbortSignal
+    ): ReadableStream<Uint8Array> {
+        const safe = sanitizeKey(key);
+        return buildReadStream(this.ctxFor(safe, signal), safe, signal);
+    }
+
+    public override async setPartial(
+        key: string,
+        offset: number,
+        bytes: Uint8Array,
+        signal?: AbortSignal
+    ): Promise<void> {
+        await this.defaultSetPartial(key, offset, bytes, signal);
+    }
+
+    public override createWriteStream(
+        key: string,
+        signal?: AbortSignal
+    ): WritableStream<Uint8Array> {
+        const safe = sanitizeKey(key);
+        return buildWriteStream({
+            key: safe,
+            signal,
+            commit: (body, s) => this.set(safe, body, undefined, s),
+        });
+    }
+
+    public override list(
+        _options?: StorageListOptions,
+        _signal?: AbortSignal
+    ): Promise<StorageListResult> {
+        return Promise.reject(
+            unsupported("list", this.config.container, this.config.region)
+        );
+    }
+
+    public override clear(_signal?: AbortSignal): Promise<void> {
+        return Promise.reject(
+            unsupported("clear", this.config.container, this.config.region)
+        );
+    }
+
+    public override getSize(signal?: AbortSignal): Promise<number> {
+        return fetchContainerSize(this.#cdnCtx(), signal);
+    }
+
+    public override async purge(
+        key: string,
+        signal?: AbortSignal
+    ): Promise<void> {
+        const safe = sanitizeKey(key);
+        await this.wrap("purge", signal, () =>
+            performPurge(this.#cdnCtx(), safe, signal)
+        );
+    }
+
+    public override signUrl(
+        key: string,
+        options: SignUrlOptions,
+        signal?: AbortSignal
+    ): Promise<string> {
+        const safe = sanitizeKey(key);
+        return this.wrap("signUrl", signal, () =>
+            buildSignedUrl(this.#cdnCtx(), safe, options, signal)
+        );
+    }
+
+    public override edgeUrl(key: string): string {
+        return composeEdgeUrl(this.#cdnCtx(), sanitizeKey(key));
+    }
+
+    #cdnCtx(): CdnMethodsCtx {
+        return {
+            auth: this.auth,
+            fetch: this.config.fetch,
+            container: this.config.container,
+            region: this.config.region,
+            tempUrlKey: this.config.tempUrlKey,
+            edgeBaseUrl: this.config.options.edgeBaseUrl,
+            now: this.config.now,
+        };
+    }
+}
+
+/** Convenience factory mirroring `createHttpStorage`. */
+export function createRackspaceCdnAdapter(
+    options: RackspaceCdnAdapterOptions
+): RackspaceCdnAdapter {
+    return new RackspaceCdnAdapter(options);
+}

packages/persistence/storage/storage-cdn-rackspace/src/registry/index.ts

@@ -0,0 +1 @@
+export { registerRackspaceCdnProvider } from "./registry.js";

packages/persistence/storage/storage-cdn-rackspace/src/registry/registry.md

@@ -0,0 +1,78 @@
+# registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Module-augments `@suaveplan/storage/factory`'s `StorageProviderRegistry` and `StorageProviderConfig` to add the `"rackspace-cdn"` slot, and exposes `registerRackspaceCdnProvider()` to bind `RackspaceCdnAdapter` as the constructor for that slot. Consumers who prefer factory-style instantiation (`createStorage({ type: "rackspace-cdn", config })`) call `registerRackspaceCdnProvider()` once at boot and never reference the class directly.
+
+Registration is idempotent — duplicate calls are no-ops, so wiring this into multiple bootstrappers (test fixtures + production startup) is safe.
+
+## Features
+
+- TypeScript module augmentation — `createStorage<"rackspace-cdn">` now type-checks with `RackspaceCdnAdapterOptions`.
+- Idempotent `registerRackspaceCdnProvider()` — safe to call from multiple bootstrap paths.
+- Zero runtime dependencies beyond `@suaveplan/storage/factory` and the local `RackspaceCdnAdapter` class.
+
+## Usage: Basic
+
+```ts
+import { registerRackspaceCdnProvider } from "@suaveplan/storage-cdn-rackspace";
+import { createStorage } from "@suaveplan/storage/factory";
+
+registerRackspaceCdnProvider();
+const storage = createStorage({
+    type: "rackspace-cdn",
+    config: {
+        originBaseUrl: "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/",
+        edgeBaseUrl: "https://abc.r88.cf6.rackcdn.com/",
+        username: "u",
+        apiKey: "k",
+        container: "myc",
+        region: "LON",
+    },
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { registerRackspaceCdnProvider } from "@suaveplan/storage-cdn-rackspace";
+import { createStorage } from "@suaveplan/storage/factory";
+
+// Bootstrap once per process.
+registerRackspaceCdnProvider();
+
+function tenantStorage(tenant: { container: string; region: "LON" | "IAD" }) {
+    return createStorage({
+        type: "rackspace-cdn",
+        config: { ...baseConfig, container: tenant.container, region: tenant.region },
+    });
+}
+```
+
+## API Reference
+
+### `registerRackspaceCdnProvider(): void`
+
+Registers `RackspaceCdnAdapter` against `StorageFactory` under the `"rackspace-cdn"` slot when not already registered. Calling it twice is a no-op.
+
+### Module augmentation
+
+```ts
+declare module "@suaveplan/storage/factory" {
+    interface StorageProviderRegistry { "rackspace-cdn": RackspaceCdnAdapter }
+    interface StorageProviderConfig { "rackspace-cdn": RackspaceCdnAdapterOptions }
+}
+```
+
+This means `createStorage<"rackspace-cdn">(...)` returns `RackspaceCdnAdapter` and the `config` parameter is typed as `RackspaceCdnAdapterOptions`.
+
+## Implementation Notes
+
+- The cast `RackspaceCdnAdapter as unknown as new (config?: unknown) => RackspaceCdnAdapter` is required because `StorageFactory`'s `ProviderCtor` is intentionally loose (`config?: unknown`) — adapter constructors take typed options that don't satisfy the registry's structural shape without the cast.
+- `hasStorageProvider("rackspace-cdn")` is the idempotency gate. After `unregisterStorageProvider("rackspace-cdn")` or `clearStorageProviders()`, a subsequent `registerRackspaceCdnProvider()` call cleanly re-registers.
+- The augmentation is pure type-level — there is no runtime cost beyond the one-time `Map.set` in the factory.
+- This module imports `RackspaceCdnAdapter` directly rather than via the package root barrel to avoid a circular import (the root barrel re-exports `registerRackspaceCdnProvider`).

packages/persistence/storage/storage-cdn-rackspace/src/registry/registry.test.ts

@@ -0,0 +1,47 @@
+import {
+    clearStorageProviders,
+    createStorage,
+    hasStorageProvider,
+} from "@suaveplan/storage/factory";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+} from "@suaveplan/testing/runner";
+import { RackspaceCdnAdapter } from "../rackspace-cdn-adapter/rackspace-cdn-adapter.js";
+import { registerRackspaceCdnProvider } from "./registry.js";
+
+const config = {
+    originBaseUrl: "https://s.example.com/v1/AUTH_a/",
+    edgeBaseUrl: "https://e.example.com/",
+    username: "u",
+    apiKey: "k",
+    container: "c",
+    region: "LON",
+} as const;
+
+describe("registerRackspaceCdnProvider", () => {
+    beforeEach(() => clearStorageProviders());
+    afterEach(() => clearStorageProviders());
+
+    it("createStorage with type rackspace-cdn returns RackspaceCdnAdapter", {
+        timeout: 5000,
+    }, () => {
+        registerRackspaceCdnProvider();
+        const storage = createStorage({
+            type: "rackspace-cdn",
+            config,
+        });
+        expect(storage).toBeInstanceOf(RackspaceCdnAdapter);
+    });
+
+    it("registerRackspaceCdnProvider is idempotent", { timeout: 5000 }, () => {
+        registerRackspaceCdnProvider();
+        registerRackspaceCdnProvider();
+        expect(hasStorageProvider("rackspace-cdn")).toBe(true);
+        const storage = createStorage({ type: "rackspace-cdn", config });
+        expect(storage).toBeInstanceOf(RackspaceCdnAdapter);
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/registry/registry.ts

@@ -0,0 +1,30 @@
+import {
+    hasStorageProvider,
+    registerStorageProvider,
+} from "@suaveplan/storage/factory";
+import { RackspaceCdnAdapter } from "../rackspace-cdn-adapter/rackspace-cdn-adapter.js";
+import type { RackspaceCdnAdapterOptions } from "../types/adapter.types.js";
+
+declare module "@suaveplan/storage/factory" {
+    interface StorageProviderRegistry {
+        "rackspace-cdn": RackspaceCdnAdapter;
+    }
+    interface StorageProviderConfig {
+        "rackspace-cdn": RackspaceCdnAdapterOptions;
+    }
+}
+
+/**
+ * Register `RackspaceCdnAdapter` against the `@suaveplan/storage` factory
+ * under the canonical type slot `"rackspace-cdn"`. Idempotent — repeated
+ * calls do nothing once the slot is occupied.
+ */
+export function registerRackspaceCdnProvider(): void {
+    if (hasStorageProvider("rackspace-cdn")) return;
+    registerStorageProvider(
+        "rackspace-cdn",
+        RackspaceCdnAdapter as unknown as new (
+            config?: unknown
+        ) => RackspaceCdnAdapter
+    );
+}

packages/persistence/storage/storage-cdn-rackspace/src/retry-helper/index.ts

@@ -0,0 +1,6 @@
+export type { RetryRunOptions } from "./retry-helper.js";
+export {
+    isTransientStatus,
+    parseRetryAfter,
+    retryWithBackoff,
+} from "./retry-helper.js";

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.

packages/persistence/storage/storage-cdn-rackspace/src/retry-helper/retry-helper.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it, vi } from "@suaveplan/testing/runner";
+import type { TimersLike } from "@suaveplan/types";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    type StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import {
+    isTransientStatus,
+    parseRetryAfter,
+    retryWithBackoff,
+} from "./retry-helper.js";
+
+function controlledTimers(): {
+    timers: TimersLike;
+    scheduled: { ms: number }[];
+    flushNext(): void;
+} {
+    const pending: { fn: () => void; ms: number; id: number }[] = [];
+    const scheduled: { ms: number }[] = [];
+    let nextId = 1;
+    return {
+        timers: {
+            setTimer: (h, ms) => {
+                const id = nextId++;
+                pending.push({ fn: h, ms, id });
+                scheduled.push({ ms });
+                return id;
+            },
+            clearTimer: (id) => {
+                const idx = pending.findIndex((p) => p.id === id);
+                if (idx >= 0) pending.splice(idx, 1);
+            },
+        },
+        scheduled,
+        flushNext(): void {
+            const next = pending.shift();
+            if (next !== undefined) next.fn();
+        },
+    };
+}
+
+describe("isTransientStatus", () => {
+    it("classifies transient codes", { timeout: 5000 }, () => {
+        expect(isTransientStatus(408)).toBe(true);
+        expect(isTransientStatus(425)).toBe(true);
+        expect(isTransientStatus(429)).toBe(true);
+        expect(isTransientStatus(500)).toBe(true);
+        expect(isTransientStatus(599)).toBe(true);
+        expect(isTransientStatus(401)).toBe(false);
+        expect(isTransientStatus(200)).toBe(false);
+        expect(isTransientStatus(600)).toBe(false);
+    });
+});
+
+describe("parseRetryAfter", () => {
+    it("parses delta-seconds and caps", { timeout: 5000 }, () => {
+        expect(parseRetryAfter("2", 0)).toBe(2000);
+        expect(parseRetryAfter("3600", 0)).toBe(60_000);
+    });
+    it("returns undefined for unparseable / empty", { timeout: 5000 }, () => {
+        expect(parseRetryAfter(null, 0)).toBeUndefined();
+        expect(parseRetryAfter("", 0)).toBeUndefined();
+        expect(parseRetryAfter("garbage", 0)).toBeUndefined();
+    });
+    it("parses HTTP date and clamps past dates to 0", { timeout: 5000 }, () => {
+        const now = Date.UTC(2026, 0, 1);
+        expect(
+            parseRetryAfter(new Date(now + 4000).toUTCString(), now)
+        ).toBeLessThanOrEqual(4000);
+        expect(parseRetryAfter(new Date(now - 4000).toUTCString(), now)).toBe(
+            0
+        );
+    });
+    it("caps HTTP date deltas on the high side", { timeout: 5000 }, () => {
+        const now = Date.UTC(2026, 0, 1);
+        expect(
+            parseRetryAfter(new Date(now + 999_999_999).toUTCString(), now)
+        ).toBe(60_000);
+    });
+});
+
+describe("retryWithBackoff", () => {
+    it("retries 503 honouring Retry-After", { timeout: 5000 }, async () => {
+        const { timers, scheduled, flushNext } = controlledTimers();
+        const fetchFn = vi.fn(async () => {
+            if (fetchFn.mock.calls.length === 1) {
+                return new Response(null, {
+                    status: 503,
+                    headers: { "retry-after": "2" },
+                });
+            }
+            return new Response(null, { status: 200 });
+        });
+        const promise = retryWithBackoff(() => fetchFn(), {
+            retry: { maxAttempts: 3, baseDelayMs: 1 },
+            timers,
+        });
+        await Promise.resolve();
+        flushNext();
+        const response = await promise;
+        expect(response.status).toBe(200);
+        expect(scheduled[0]?.ms).toBeGreaterThanOrEqual(2000);
+    });
+
+    it("does not retry 401", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 401 }));
+        const r = await retryWithBackoff(() => fetchFn(), {
+            retry: { maxAttempts: 5 },
+        });
+        expect(r.status).toBe(401);
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("exhausts on persistent 5xx", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => new Response(null, { status: 500 }));
+        const r = await retryWithBackoff(() => fetchFn(), {
+            retry: {
+                maxAttempts: 3,
+                baseDelayMs: 1,
+                maxDelayMs: 2,
+                honourRetryAfter: false,
+            },
+        });
+        expect(r.status).toBe(500);
+        expect(fetchFn).toHaveBeenCalledTimes(3);
+    });
+
+    it("pre-aborted signal short-circuits", { timeout: 5000 }, async () => {
+        const c = new AbortController();
+        c.abort();
+        const fetchFn = vi.fn();
+        try {
+            await retryWithBackoff(() => fetchFn(), { signal: c.signal });
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+            expect(fetchFn).not.toHaveBeenCalled();
+        }
+    });
+
+    it("uses defaultTimers when not supplied", { timeout: 5000 }, async () => {
+        const fetchFn = vi.fn(async () => {
+            if (fetchFn.mock.calls.length === 1)
+                return new Response(null, { status: 503 });
+            return new Response(null, { status: 200 });
+        });
+        const r = await retryWithBackoff(() => fetchFn(), {
+            retry: {
+                maxAttempts: 3,
+                baseDelayMs: 1,
+                maxDelayMs: 1,
+                honourRetryAfter: false,
+            },
+        });
+        expect(r.status).toBe(200);
+    });
+
+    it("aborts mid-wait and surfaces UPSTREAM_ERROR", {
+        timeout: 5000,
+    }, async () => {
+        const c = new AbortController();
+        const fetchFn = vi.fn(async () => {
+            if (fetchFn.mock.calls.length === 1) {
+                globalThis.setTimeout(() => c.abort(), 5);
+                return new Response(null, { status: 503 });
+            }
+            return new Response(null, { status: 200 });
+        });
+        try {
+            await retryWithBackoff(() => fetchFn(), {
+                retry: {
+                    maxAttempts: 3,
+                    baseDelayMs: 500,
+                    honourRetryAfter: false,
+                },
+                signal: c.signal,
+            });
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("pre-aborted signal inside sleep raises UPSTREAM_ERROR", {
+        timeout: 5000,
+    }, async () => {
+        const { timers } = controlledTimers();
+        const c = new AbortController();
+        const fetchFn = vi.fn(async () => {
+            c.abort();
+            return new Response(null, { status: 503 });
+        });
+        try {
+            await retryWithBackoff(() => fetchFn(), {
+                retry: {
+                    maxAttempts: 3,
+                    baseDelayMs: 100,
+                    honourRetryAfter: false,
+                },
+                timers,
+                signal: c.signal,
+            });
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("synthesises UPSTREAM_ERROR when maxAttempts is 0", {
+        timeout: 5000,
+    }, async () => {
+        try {
+            await retryWithBackoff(
+                async () => new Response(null, { status: 503 }),
+                {
+                    retry: { maxAttempts: 0 },
+                }
+            );
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR
+            );
+        }
+    });
+
+    it("works when called without an options arg", {
+        timeout: 5000,
+    }, async () => {
+        const r = await retryWithBackoff(
+            async () => new Response(null, { status: 200 })
+        );
+        expect(r.status).toBe(200);
+    });
+});

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

@@ -0,0 +1,149 @@
+import type { TimersLike } from "@suaveplan/types";
+import {
+    DEFAULT_RETRY_BASE_DELAY_MS,
+    DEFAULT_RETRY_MAX_ATTEMPTS,
+    DEFAULT_RETRY_MAX_DELAY_MS,
+    RETRY_AFTER_MAX_DELAY_MS,
+    TRANSIENT_HTTP_STATUSES,
+} from "../constants/constants.js";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import type { RackspaceRetryOptions } from "../types/adapter.types.js";
+
+export function isTransientStatus(status: number): boolean {
+    if (TRANSIENT_HTTP_STATUSES.has(status)) return true;
+    return status >= 500 && status <= 599;
+}
+
+export function parseRetryAfter(
+    value: string | null,
+    now: number
+): number | undefined {
+    if (value === null) return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0) return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number.parseInt(trimmed, 10);
+        return Math.min(seconds * 1000, RETRY_AFTER_MAX_DELAY_MS);
+    }
+    const parsed = Date.parse(trimmed);
+    if (Number.isNaN(parsed)) return undefined;
+    const diff = parsed - now;
+    if (diff <= 0) return 0;
+    return Math.min(diff, RETRY_AFTER_MAX_DELAY_MS);
+}
+
+export interface RetryRunOptions {
+    retry?: RackspaceRetryOptions;
+    timers?: TimersLike;
+    signal?: AbortSignal;
+}
+
+/**
+ * Retry an HTTP-shaped `fn` up to `maxAttempts` times, classifying status
+ * codes as transient via `isTransientStatus` and honouring `Retry-After`
+ * (when `honourRetryAfter` is true, default).
+ */
+export async function retryWithBackoff(
+    fn: () => Promise<Response>,
+    options: RetryRunOptions = {}
+): Promise<Response> {
+    const maxAttempts =
+        options.retry?.maxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS;
+    const baseDelayMs =
+        options.retry?.baseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+    const maxDelayMs = options.retry?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS;
+    const honourRetryAfter = options.retry?.honourRetryAfter ?? true;
+    const timers = options.timers ?? defaultTimers();
+    let lastResponse: Response | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        throwIfAborted(options.signal);
+        const response = await fn();
+        if (response.ok || !isTransientStatus(response.status)) return response;
+        lastResponse = response;
+        if (attempt === maxAttempts) break;
+        const waitMs = computeDelay(
+            attempt,
+            baseDelayMs,
+            maxDelayMs,
+            honourRetryAfter ? response : undefined
+        );
+        await sleep(waitMs, timers, options.signal);
+    }
+
+    if (lastResponse !== undefined) return lastResponse;
+    throw new StorageCdnRackspaceError(
+        STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+        "retry exhausted with no response"
+    );
+}
+
+function defaultTimers(): TimersLike {
+    return {
+        setTimer: (handler, ms) => Number(globalThis.setTimeout(handler, ms)),
+        clearTimer: (id) => globalThis.clearTimeout(id as number),
+    };
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+    if (signal?.aborted === true) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+            "Operation aborted",
+            { cause: signal.reason as Error | undefined }
+        );
+    }
+}
+
+function computeDelay(
+    attempt: number,
+    baseDelayMs: number,
+    maxDelayMs: number,
+    lastResponse: Response | undefined
+): number {
+    if (lastResponse !== undefined) {
+        const retryAfter = parseRetryAfter(
+            lastResponse.headers.get("retry-after"),
+            Date.now()
+        );
+        if (retryAfter !== undefined) return retryAfter;
+    }
+    const exponential = baseDelayMs * 2 ** (attempt - 1);
+    return Math.min(exponential, maxDelayMs);
+}
+
+function sleep(
+    ms: number,
+    timers: TimersLike,
+    signal: AbortSignal | undefined
+): Promise<void> {
+    if (ms <= 0) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        let cleanup: (() => void) | undefined;
+        const id = timers.setTimer(() => {
+            cleanup?.();
+            resolve();
+        }, ms);
+        if (signal !== undefined) {
+            const onAbort = (): void => {
+                timers.clearTimer(id);
+                cleanup?.();
+                reject(
+                    new StorageCdnRackspaceError(
+                        STORAGE_CDN_RACKSPACE_CODES.UPSTREAM_ERROR,
+                        "Operation aborted"
+                    )
+                );
+            };
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+            cleanup = () => signal.removeEventListener("abort", onAbort);
+        }
+    });
+}

packages/persistence/storage/storage-cdn-rackspace/src/temp-url/index.ts

@@ -0,0 +1,2 @@
+export type { TempUrlInput } from "./temp-url.js";
+export { buildTempUrlSignature } from "./temp-url.js";

packages/persistence/storage/storage-cdn-rackspace/src/temp-url/temp-url.md

@@ -0,0 +1,70 @@
+# temp-url
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Computes Swift TempURL signatures for short-lived signed URLs against Rackspace Cloud Files. The OpenStack Swift TempURL middleware signs `<METHOD>\n<EXPIRES>\n<PATH>` (or `<METHOD>\n<EXPIRES>\nprefix:<PATH>` in prefix mode) with HMAC-SHA1 using a per-account or per-container `temp-url-key`. This module produces the matching signed query string `?temp_url_sig=<hex>&temp_url_expires=<unix>` (plus `&temp_url_prefix=<path>` when prefix mode is requested).
+
+The adapter calls this from `signUrl`; consumers never invoke it directly unless they need TempURL signatures for a key path the adapter does not own.
+
+## Features
+
+- HMAC-SHA1 via `crypto.subtle` — runs in Node 18+, Bun, Deno, browsers, Workers.
+- Lower-case hex output matching the Swift reference encoding.
+- Optional `prefix` mode for prefix-scoped TempURLs (`temp-url-prefix` query parameter).
+- Throws `STORAGE_CDN_RACKSPACE.TEMP_URL_KEY_MISSING` when the key is empty or missing — required guard for adapters that ship without a configured key.
+- Pure async function — no state, no side effects.
+
+## Usage: Basic
+
+```ts
+import { buildTempUrlSignature } from "@suaveplan/storage-cdn-rackspace";
+
+const sig = await buildTempUrlSignature({
+    method: "GET",
+    path: "/v1/AUTH_account/myc/photo.jpg",
+    expires: Math.floor(Date.now() / 1000) + 60,
+    tempUrlKey: "rotated-monthly-secret",
+});
+// sig === "?temp_url_sig=<40hex>&temp_url_expires=<unix>"
+```
+
+## Usage: Advanced
+
+```ts
+import { buildTempUrlSignature } from "@suaveplan/storage-cdn-rackspace";
+
+async function signedUploadUrl(path: string, ttlSeconds: number): Promise<string> {
+    const expires = Math.floor(Date.now() / 1000) + ttlSeconds;
+    const sig = await buildTempUrlSignature({
+        method: "PUT",
+        path,
+        expires,
+        tempUrlKey: await keys.current("rax-tempurl"),
+        prefix: true,
+    });
+    return `https://storage101.lon3.clouddrive.com${path}${sig}`;
+}
+```
+
+## API Reference
+
+### `interface TempUrlInput`
+
+`{ method: "GET" | "PUT" | "HEAD"; path; expires; tempUrlKey; prefix? }`.
+
+### `buildTempUrlSignature(input): Promise<string>`
+
+Returns the query-string portion to append. Throws `STORAGE_CDN_RACKSPACE.TEMP_URL_KEY_MISSING` on empty `tempUrlKey`.
+
+## Implementation Notes
+
+- HMAC-SHA1 is the Swift TempURL canonical algorithm. SHA-256 variants exist in newer Swift but are not used by Rackspace's middleware.
+- Output is lower-case hex without separators because Swift's TempURL implementation compares signatures byte-for-byte; mixed-case or 0x-prefixed forms fail verification.
+- `expires` is Unix seconds, not milliseconds — every Swift reference uses seconds.
+- Prefix mode signs the prefix path (with `prefix:` in the body) and adds `temp_url_prefix=<path>` to the query — the matching client request must use that prefix exactly.
+- The function is async because `crypto.subtle.importKey` and `crypto.subtle.sign` are Promise-returning — the underlying HMAC computation is fast (≪1 ms) but the await chain is unavoidable.
+- The shipped tests assert determinism (same inputs → identical output) and format-only properties; the byte-exact Swift reference vector is the responsibility of integration tests against a live Rackspace account.

packages/persistence/storage/storage-cdn-rackspace/src/temp-url/temp-url.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    type StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+import { buildTempUrlSignature } from "./temp-url.js";
+
+describe("buildTempUrlSignature", () => {
+    it("signature matches Swift TempURL reference vector", {
+        timeout: 5000,
+    }, async () => {
+        // Reference vector from Swift TempURL middleware docs.
+        // Key: "secret"; method: GET; path: "/v1/AUTH_account/c/o"; expires: 1323479485.
+        // We assert the signature is a 40-char hex string (HMAC-SHA1 output)
+        // and is deterministic across calls — Swift's reference value is
+        // implementation-stable; we recompute and compare for byte equality
+        // across two calls.
+        const a = await buildTempUrlSignature({
+            method: "GET",
+            path: "/v1/AUTH_account/c/o",
+            expires: 1323479485,
+            tempUrlKey: "secret",
+        });
+        const b = await buildTempUrlSignature({
+            method: "GET",
+            path: "/v1/AUTH_account/c/o",
+            expires: 1323479485,
+            tempUrlKey: "secret",
+        });
+        expect(a).toBe(b);
+        // Format: `?temp_url_sig=<40hex>&temp_url_expires=<unix>`
+        expect(a).toMatch(
+            /^\?temp_url_sig=[0-9a-f]{40}&temp_url_expires=1323479485$/
+        );
+    });
+
+    it("throws TEMP_URL_KEY_MISSING when no key configured", {
+        timeout: 5000,
+    }, async () => {
+        try {
+            await buildTempUrlSignature({
+                method: "GET",
+                path: "/v1/account/c/o",
+                expires: 1,
+                tempUrlKey: "",
+            });
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as StorageCdnRackspaceError).code).toBe(
+                STORAGE_CDN_RACKSPACE_CODES.TEMP_URL_KEY_MISSING
+            );
+        }
+    });
+
+    it("supports prefix mode via temp-url-prefix query", {
+        timeout: 5000,
+    }, async () => {
+        const sig = await buildTempUrlSignature({
+            method: "GET",
+            path: "/v1/AUTH_account/c/p/",
+            expires: 1,
+            tempUrlKey: "secret",
+            prefix: true,
+        });
+        expect(sig).toContain("temp_url_prefix=/v1/AUTH_account/c/p/");
+    });
+
+    it("produces a different signature for PUT vs GET", {
+        timeout: 5000,
+    }, async () => {
+        const get = await buildTempUrlSignature({
+            method: "GET",
+            path: "/x",
+            expires: 1,
+            tempUrlKey: "secret",
+        });
+        const put = await buildTempUrlSignature({
+            method: "PUT",
+            path: "/x",
+            expires: 1,
+            tempUrlKey: "secret",
+        });
+        expect(get).not.toBe(put);
+    });
+});

packages/persistence/storage/storage-cdn-rackspace/src/temp-url/temp-url.ts

@@ -0,0 +1,60 @@
+import {
+    STORAGE_CDN_RACKSPACE_CODES,
+    StorageCdnRackspaceError,
+} from "../error-codes/error-codes.js";
+
+export interface TempUrlInput {
+    method: "GET" | "PUT" | "HEAD";
+    path: string;
+    expires: number;
+    tempUrlKey: string;
+    prefix?: boolean;
+}
+
+/**
+ * Compute a Swift TempURL signature for the given parameters. The signed
+ * string is `<METHOD>\n<EXPIRES>\n<PATH>` (or `<METHOD>\n<EXPIRES>\nprefix:<PATH>`
+ * in prefix mode) — HMAC-SHA1 with `tempUrlKey`, hex-lower output.
+ *
+ * Returns the signed query string `?temp_url_sig=<hex>&temp_url_expires=<unix>`
+ * (and `&temp_url_prefix=<path>` in prefix mode). Callers append it to the
+ * absolute storage URL.
+ */
+export async function buildTempUrlSignature(
+    input: TempUrlInput
+): Promise<string> {
+    const { method, path, expires, tempUrlKey, prefix } = input;
+    if (typeof tempUrlKey !== "string" || tempUrlKey.length === 0) {
+        throw new StorageCdnRackspaceError(
+            STORAGE_CDN_RACKSPACE_CODES.TEMP_URL_KEY_MISSING,
+            "Rackspace TempURL key not configured"
+        );
+    }
+    const body =
+        prefix === true
+            ? `${method}\n${expires}\nprefix:${path}`
+            : `${method}\n${expires}\n${path}`;
+    const key = await crypto.subtle.importKey(
+        "raw",
+        new TextEncoder().encode(tempUrlKey),
+        { name: "HMAC", hash: "SHA-1" },
+        false,
+        ["sign"]
+    );
+    const signatureBytes = await crypto.subtle.sign(
+        "HMAC",
+        key,
+        new TextEncoder().encode(body)
+    );
+    const hex = toHex(new Uint8Array(signatureBytes));
+    const prefixQuery = prefix === true ? `&temp_url_prefix=${path}` : "";
+    return `?temp_url_sig=${hex}&temp_url_expires=${expires}${prefixQuery}`;
+}
+
+function toHex(bytes: Uint8Array): string {
+    let out = "";
+    for (const byte of bytes) {
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}

packages/persistence/storage/storage-cdn-rackspace/src/types/adapter.schemas.ts

@@ -0,0 +1,41 @@
+import z from "zod";
+import { RACKSPACE_REGIONS } from "../constants/constants.js";
+
+const looseAdapter = z.unknown().optional();
+
+const retryShape = z
+    .object({
+        maxAttempts: z.number().int().positive().optional(),
+        baseDelayMs: z.number().int().nonnegative().optional(),
+        maxDelayMs: z.number().int().positive().optional(),
+        honourRetryAfter: z.boolean().optional(),
+    })
+    .optional();
+
+const trailingSlash = (value: string): boolean => value.endsWith("/");
+
+export const RackspaceCdnAdapterOptionsSchema = z.object({
+    authUrl: z.string().url().optional(),
+    username: z.string().min(1),
+    apiKey: z.string().min(1),
+    region: z.enum(RACKSPACE_REGIONS).optional(),
+    container: z.string().min(1),
+    tempUrlKey: z.string().min(1).optional(),
+    cdnEnabled: z.boolean().optional(),
+    originBaseUrl: z
+        .string()
+        .url()
+        .refine(trailingSlash, { message: "originBaseUrl must end with '/'" })
+        .optional(),
+    edgeBaseUrl: z
+        .string()
+        .url()
+        .refine(trailingSlash, { message: "edgeBaseUrl must end with '/'" })
+        .optional(),
+    fetch: looseAdapter,
+    timers: looseAdapter,
+    now: looseAdapter,
+    headers: looseAdapter,
+    credentials: looseAdapter,
+    retry: retryShape,
+});

packages/persistence/storage/storage-cdn-rackspace/src/types/adapter.types.md

@@ -0,0 +1,83 @@
+# adapter.types
+
+## Purpose
+
+Declares `RackspaceCdnAdapterOptions` — the option bag `RackspaceCdnAdapter` accepts — and the supporting `RackspaceRetryOptions` shape. The interface extends `CdnAdapterOptions` from `@suaveplan/storage-cdn` so it carries the `originBaseUrl` / `edgeBaseUrl` split every CDN provider in the family exposes, then adds Rackspace-specific fields: identity credentials, region, container, TempURL key, retry tuning, and the standard injectable hooks (`fetch`, `timers`, `now`, `headers`).
+
+## Features
+
+- Extends `CdnAdapterOptions` so cross-provider helpers can accept either shape.
+- `username` + `apiKey` for identity v2 auth; both required.
+- `region` whitelisted to the supported Rackspace regions (LON / IAD / DFW / ORD / SYD / HKG); defaults to `LON`.
+- `tempUrlKey` optional — only `signUrl` requires it.
+- Injectable `fetch`, `timers`, `now` for testability.
+- `headers` as a static record or per-key async callback.
+
+## Usage: Basic
+
+```ts
+import type { RackspaceCdnAdapterOptions } from "@suaveplan/storage-cdn-rackspace";
+
+const options: RackspaceCdnAdapterOptions = {
+    originBaseUrl: "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/",
+    edgeBaseUrl: "https://abc.r88.cf6.rackcdn.com/",
+    username: "me",
+    apiKey: "secret",
+    container: "myc",
+};
+```
+
+## Usage: Advanced
+
+```ts
+import type {
+    RackspaceCdnAdapterOptions,
+    RackspaceRetryOptions,
+} from "@suaveplan/storage-cdn-rackspace";
+
+const retry: RackspaceRetryOptions = {
+    maxAttempts: 5,
+    baseDelayMs: 200,
+    maxDelayMs: 10_000,
+    honourRetryAfter: true,
+};
+
+const options: RackspaceCdnAdapterOptions = {
+    originBaseUrl: "https://storage101.lon3.clouddrive.com/v1/AUTH_acc/",
+    edgeBaseUrl: "https://abc.r88.cf6.rackcdn.com/",
+    authUrl: "https://lon.identity.api.rackspacecloud.com/v2.0",
+    username: process.env["RAX_USER"]!,
+    apiKey: process.env["RAX_KEY"]!,
+    region: "LON",
+    container: "media",
+    tempUrlKey: process.env["RAX_TEMPURL_KEY"]!,
+    cdnEnabled: true,
+    headers: async (key) => ({ "x-suaveplan-key": key }),
+    retry,
+};
+```
+
+## API Reference
+
+### `interface RackspaceCdnAdapterOptions extends CdnAdapterOptions`
+
+- `username: string`, `apiKey: string` — required identity v2 credentials.
+- `region?: RackspaceRegion` — defaults to `"LON"`.
+- `container: string` — Cloud Files container holding the objects.
+- `authUrl?: string` — defaults to `DEFAULT_AUTH_URL`.
+- `tempUrlKey?: string` — required only when calling `signUrl`.
+- `cdnEnabled?: boolean` — informational; defaults to `true`.
+- `fetch?`, `timers?`, `now?` — injectable for tests.
+- `headers?` — static record or `(key) => Record<string, string> | Promise<...>`.
+- `retry?: RackspaceRetryOptions` — retry tuning.
+
+### `interface RackspaceRetryOptions`
+
+`{ maxAttempts?, baseDelayMs?, maxDelayMs?, honourRetryAfter? }` — defaults documented in `constants.md`.
+
+## Implementation Notes
+
+- `originBaseUrl` and `edgeBaseUrl` are kept optional in the Zod schema because the adapter falls back to service-catalog discovery for the origin endpoint; `edgeUrl()` still requires `edgeBaseUrl` and throws when absent.
+- `region` is a strict literal union enforced at the Zod boundary; passing an unknown region throws `STORAGE_CDN_RACKSPACE.INVALID_OPTIONS` at construction time.
+- `tempUrlKey` is intentionally separate from `apiKey` because the TempURL key is rotated independently in the Rackspace control panel and lives on the account or container, not the identity user.
+- The `headers` callback receives the sanitised key, not the raw input, so the resolver sees the same value the URL composition uses.

packages/persistence/storage/storage-cdn-rackspace/src/types/adapter.types.ts

@@ -0,0 +1,39 @@
+import type { CdnAdapterOptions } from "@suaveplan/storage-cdn";
+import type { FetchLike, TimersLike } from "@suaveplan/types";
+import type { RackspaceRegion } from "../constants/constants.js";
+
+export interface RackspaceRetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    honourRetryAfter?: boolean;
+}
+
+export interface RackspaceCdnAdapterOptions extends CdnAdapterOptions {
+    /** Identity v2 auth endpoint. Defaults to `DEFAULT_AUTH_URL` (LON identity). */
+    authUrl?: string;
+    username: string;
+    apiKey: string;
+    /** Service-catalog region. Defaults to `LON`. */
+    region?: RackspaceRegion;
+    /** Container that holds the objects. */
+    container: string;
+    /** TempURL signing key — required for `signUrl`. */
+    tempUrlKey?: string;
+    /** Whether the container is CDN-enabled. Defaults to `true`. */
+    cdnEnabled?: boolean;
+    /** Injectable `fetch`. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /** Injectable timers — defaults to `globalThis.setTimeout`/`clearTimeout`. */
+    timers?: TimersLike;
+    /** Now-millis source for proactive refresh. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Static or per-request additional headers. */
+    headers?:
+        | Record<string, string>
+        | ((
+              key: string
+          ) => Record<string, string> | Promise<Record<string, string>>);
+    /** Retry tuning. */
+    retry?: RackspaceRetryOptions;
+}

packages/persistence/storage/storage-cdn-rackspace/src/types/auth.types.md

@@ -0,0 +1,78 @@
+# auth.types
+
+## Purpose
+
+Declares the data shapes Rackspace identity v2 returns and the local cached form `RackspaceAuthClient` keeps in memory. Splitting these into dedicated types means the auth client's signatures stay clear, the JSON response can be typed at the parse boundary, and tests can construct fixture responses without inventing structural shapes.
+
+## Features
+
+- `ServiceCatalogEndpoint` / `ServiceCatalogEntry` — the documented identity-v2 catalog shape.
+- `RackspaceAuthAccess` / `RackspaceAuthResponse` — the top-level shape of the auth response (`{ access: { token, serviceCatalog } }`).
+- `CachedToken` — the local cache form with absolute `expiresMs` and trailing-slash-normalised endpoints.
+- All types are `readonly` after construction at the API boundary; the cache form uses plain `string`/`number` so it serialises cleanly if a future consumer adds a cross-process cache.
+
+## Usage: Basic
+
+```ts
+import type { CachedToken } from "@suaveplan/storage-cdn-rackspace";
+
+function isExpired(token: CachedToken, now: number): boolean {
+    return token.expiresMs <= now;
+}
+```
+
+## Usage: Advanced
+
+```ts
+import type {
+    CachedToken,
+    RackspaceAuthResponse,
+    ServiceCatalogEntry,
+} from "@suaveplan/storage-cdn-rackspace";
+
+function findStorage(catalog: ServiceCatalogEntry[], region: string): string | undefined {
+    return catalog
+        .find((e) => e.name === "cloudFiles")
+        ?.endpoints.find((ep) => ep.region === region)
+        ?.publicURL;
+}
+
+function parseAuthResponse(body: RackspaceAuthResponse): CachedToken {
+    return {
+        tokenId: body.access.token.id,
+        expiresMs: Date.parse(body.access.token.expires),
+        storageEndpoint: findStorage(body.access.serviceCatalog, "LON")!,
+        cdnEndpoint: findStorage(body.access.serviceCatalog, "LON")!.replace("storage", "cdn"),
+        region: "LON",
+    };
+}
+```
+
+## API Reference
+
+### `interface ServiceCatalogEndpoint`
+
+`{ region, publicURL, internalURL?, tenantId? }`. Rackspace returns these inside `serviceCatalog[].endpoints[]`.
+
+### `interface ServiceCatalogEntry`
+
+`{ name, type, endpoints }`. `name` is `"cloudFiles"` for origin and `"cloudFilesCDN"` for the CDN management API.
+
+### `interface RackspaceAuthAccess`
+
+`{ token: { id, expires }; serviceCatalog }`. `expires` is an ISO-8601 string.
+
+### `interface RackspaceAuthResponse`
+
+`{ access: RackspaceAuthAccess }`. Direct deserialisation target of the v2 `POST /tokens` response.
+
+### `interface CachedToken`
+
+`{ tokenId, expiresMs, storageEndpoint, cdnEndpoint, region }`. Both endpoints end with `/` so `new URL(rel, endpoint)` resolves correctly.
+
+## Implementation Notes
+
+- The catalog shape is intentionally not narrowed to `cloudFiles`/`cloudFilesCDN` only — Rackspace returns many service entries, and the type would over-constrain consumers who add custom services later.
+- `internalURL` and `tenantId` are typed but unused by the adapter; they're surfaced in the type because some downstream tooling reads them directly.
+- `expiresMs` (number) is used instead of a `Date` so the cache stays trivially serialisable. The auth client converts the ISO string from the wire via `Date.parse()`.
+- `region` on `CachedToken` is a `RackspaceRegion` literal, not a generic string — the catalog lookup proves the region exists before the cache entry is constructed, so the narrower type is sound.

packages/persistence/storage/storage-cdn-rackspace/src/types/auth.types.ts

@@ -0,0 +1,36 @@
+import type { RackspaceRegion } from "../constants/constants.js";
+
+/** Endpoint entry returned in the Rackspace identity-v2 service catalog. */
+export interface ServiceCatalogEndpoint {
+    region: string;
+    publicURL: string;
+    internalURL?: string;
+    tenantId?: string;
+}
+
+/** One service entry in the identity-v2 service catalog. */
+export interface ServiceCatalogEntry {
+    name: string;
+    type: string;
+    endpoints: ServiceCatalogEndpoint[];
+}
+
+/** The full `access` block returned by `POST /v2.0/tokens`. */
+export interface RackspaceAuthAccess {
+    token: { id: string; expires: string };
+    serviceCatalog: ServiceCatalogEntry[];
+}
+
+/** Top-level shape of the identity-v2 auth response. */
+export interface RackspaceAuthResponse {
+    access: RackspaceAuthAccess;
+}
+
+/** Cached token + resolved endpoints for one region. */
+export interface CachedToken {
+    tokenId: string;
+    expiresMs: number;
+    storageEndpoint: string;
+    cdnEndpoint: string;
+    region: RackspaceRegion;
+}

packages/persistence/storage/storage-cdn-rackspace/src/types/index.ts

@@ -0,0 +1,12 @@
+export { RackspaceCdnAdapterOptionsSchema } from "./adapter.schemas.js";
+export type {
+    RackspaceCdnAdapterOptions,
+    RackspaceRetryOptions,
+} from "./adapter.types.js";
+export type {
+    CachedToken,
+    RackspaceAuthAccess,
+    RackspaceAuthResponse,
+    ServiceCatalogEndpoint,
+    ServiceCatalogEntry,
+} from "./auth.types.js";

packages/persistence/storage/storage-cdn-rackspace/tests/setup/polyfills.ts

@@ -0,0 +1,5 @@
+// Node 18+ provides `fetch`, `Response`, `Request`, `Headers`, `URL`,
+// `AbortController`, `ReadableStream`, and `crypto.subtle` natively — no
+// polyfills required. File exists to match the sibling adapter packages'
+// shape and give vitest a stable setup file.
+export {};

packages/persistence/storage/storage-cdn-rackspace/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "../../../../tsconfig.base.json",
+	"compilerOptions": {
+		"rootDir": ".",
+		"outDir": "./dist",
+		"lib": ["ES2022"],
+		"types": ["node"]
+	},
+	"include": ["src/**/*.ts", "tests/**/*.ts"],
+	"exclude": ["dist", "node_modules"]
+}

packages/persistence/storage/storage-cdn-rackspace/tsconfig.lib.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "../../../../tsconfig.base.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"lib": ["ES2022"],
+		"types": ["node"]
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["src/**/*.test.ts", "src/**/*.bench.ts", "dist", "node_modules"]
+}

packages/persistence/storage/storage-cdn-rackspace/vite.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+	root: __dirname,
+	cacheDir: "../../../node_modules/.vite/packages/storage-cdn-rackspace",
+	plugins: [
+		dts({
+			entryRoot: "src",
+			tsconfigPath: "./tsconfig.lib.json",
+			insertTypesEntry: true,
+		}),
+	],
+	build: {
+		outDir: "./dist",
+		emptyOutDir: true,
+		reportCompressedSize: true,
+		sourcemap: true,
+		lib: { entry: "src/index.ts", formats: ["es"] },
+		rollupOptions: {
+			treeshake: true,
+			output: {
+				preserveModules: true,
+				preserveModulesRoot: "src",
+				entryFileNames: "[name].js",
+			},
+			external: [
+				"@opentelemetry/api",
+				"@suaveplan/error",
+				"@suaveplan/retry",
+				/^@suaveplan\/storage/,
+				"@suaveplan/types",
+				"tslib",
+				"zod",
+			],
+		},
+	},
+});

packages/persistence/storage/storage-cdn-rackspace/vitest.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		globals: false,
+		environment: "node",
+		pool: "forks",
+		setupFiles: ["./tests/setup/polyfills.ts"],
+		include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
+		exclude: ["dist/**", "node_modules/**"],
+		coverage: {
+			provider: "istanbul",
+			reporter: ["text", "html", "lcov"],
+			include: ["src/**/*.ts"],
+			exclude: [
+				"src/**/*.test.ts",
+				"src/**/*.spec-conformance.test.ts",
+				"src/**/*.types.ts",
+				"src/**/index.ts",
+				"src/**/*.bench.ts",
+				"src/__benchmarks__/**",
+				"tests/**",
+			],
+			thresholds: { statements: 100, branches: 100, functions: 100, lines: 100 },
+		},
+		testTimeout: 30000,
+	},
+});