115 lines
8.4 KiB
Markdown
115 lines
8.4 KiB
Markdown
# @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.
|
|
|