Initial Commit
This commit is contained in:
114
packages/persistence/storage/storage-cdn-rackspace/README.md
Normal file
114
packages/persistence/storage/storage-cdn-rackspace/README.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user