@suaveplan/storage-cdn-bunnycdn - BunnyCDN Storage Zone + Pull Zone provider for @suaveplan/storage-cdn. AccessKey-header CRUD against regional Storage Zones (de/ny/la/sg/syd/uk), single + prefix purge via the Bunny.net management API, HMAC-SHA256 Token Authentication signed URLs, Range reads, native streaming, full AbortSignal threading, Retry-After honoured, OTel surface with provider+storage_region attributes.

BunnyCDN Storage Zone + Pull Zone provider for @suaveplan/storage-cdn. Full AbstractStorage and CdnAdapter surface — get/set/delete/exists/getMetadata/getPartial/createReadStream/createWriteStream against the regional Storage Zone with AccessKey header auth, plus purge/purgePrefix/signUrl/edgeUrl against the public Pull Zone. HMAC-SHA256 Token Authentication (URL-safe base64, no padding) for signed URLs. Single + wildcard prefix purge via the Bunny.net management API. Transient-status retry honouring Retry-After. Full OTel surface with provider="bunnycdn" and storage_region attributes.

Documentation tree

bunny-cdn-adapter — BunnyCdnAdapter binds @suaveplan/storage's AbstractStorage contract to BunnyCDN Storage Zones for storage operati…
- bunny-cdn-adapter.base — BunnyCdnAdapterBase carries the shared internal machinery every BunnyCdnAdapter instance needs: the resolved config…
- bunny-cdn-adapter.helpers — Internal helpers used by BunnyCdnAdapter and its sibling streams module. Splits boundary concerns (option parsing, he…
- bunny-cdn-adapter — BunnyCdnAdapter binds @suaveplan/storage's AbstractStorage contract to BunnyCDN Storage Zones for storage operati…
- bunny-cdn-adapter.streams — Builds the ReadableStream and WritableStream instances BunnyCdnAdapter returns from createReadStream / `createW…
error-codes — Declares the canonical STORAGE_CDN_BUNNYCDN error namespace used by every module in this package. Codes are produced…
- error-codes — Declares the canonical STORAGE_CDN_BUNNYCDN error namespace used by every module in this package. Codes are produced…
key-sanitizer — Validates and normalises caller-supplied storage keys before any fetch is issued against BunnyCDN Storage, and provides…
- key-sanitizer — Validates and normalises caller-supplied storage keys before any fetch is issued against BunnyCDN Storage, and provides…
otel — Owns the OpenTelemetry instrument set for @suaveplan/storage-cdn-bunnycdn: counters (reads_total, writes_total, `…
- otel — Owns the OpenTelemetry instrument set for @suaveplan/storage-cdn-bunnycdn: counters (reads_total, writes_total, `…
pull-zone-client — Owns the Bunny.net management-API purge operation. purgeUrl(ctx, edgeUrl, signal?) issues `POST…
- pull-zone-client — Owns the Bunny.net management-API purge operation. purgeUrl(ctx, edgeUrl, signal?) issues `POST…
registry — Module-augments @suaveplan/storage/factory's StorageProviderRegistry and StorageProviderConfig to add the `"bunny…
- registry — Module-augments @suaveplan/storage/factory's StorageProviderRegistry and StorageProviderConfig to add the `"bunny…
retry-helper — Coordinates retry logic for HTTP requests against BunnyCDN Storage Zones and the Bunny.net management API. Distinguishe…
- retry-helper — Coordinates retry logic for HTTP requests against BunnyCDN Storage Zones and the Bunny.net management API. Distinguishe…
storage-client — Owns every Storage Zone HTTP operation BunnyCdnAdapter needs: PUT, GET, HEAD, DELETE, Range read, and streaming GET.…
- storage-client — Owns every Storage Zone HTTP operation BunnyCdnAdapter needs: PUT, GET, HEAD, DELETE, Range read, and streaming GET.…
token-auth — Computes BunnyCDN Pull Zone Token Authentication query strings — `?token=<urlSafeBase64(sha256(key + path + expires))>&…
- token-auth — Computes BunnyCDN Pull Zone Token Authentication query strings — `?token=<urlSafeBase64(sha256(key + path + expires))>&…

Install

bun add @suaveplan/storage-cdn-bunnycdn

Quick start

import { BunnyCdnAdapter } from "@suaveplan/storage-cdn-bunnycdn";

const storage = new BunnyCdnAdapter({
    storageZone: "myz",
    storageAccessKey: process.env["BUNNY_STORAGE_KEY"]!,
    pullZoneHostname: "mycdn.b-cdn.net",
    storageRegion: "de",
    tokenAuthKey: process.env["BUNNY_TOKEN_KEY"]!,
    purgeApiKey: process.env["BUNNY_PURGE_KEY"]!,
});

await storage.set("photos/a.jpg", bytes);
await storage.purge("photos/a.jpg");
await storage.purgePrefix("photos/");
const signed = await storage.signUrl("photos/a.jpg", { ttlSeconds: 300 });

Factory registration

import { registerBunnyCdnProvider } from "@suaveplan/storage-cdn-bunnycdn";
import { createStorage } from "@suaveplan/storage/factory";

registerBunnyCdnProvider();
const storage = createStorage({ type: "bunnycdn", config });

Modules

error-codes — STORAGE_CDN_BUNNYCDN_CODES registry + StorageCdnBunnycdnError.
constants — region whitelist, default hosts, retry defaults, storageHostFor helper.
storage-client — PUT/GET/DELETE/HEAD/Range/streaming against the regional Storage Zone.
pull-zone-client — purgeUrl for single + wildcard purge via api.bunny.net/purge.
token-auth — HMAC-SHA256 Token Authentication query builder.
key-sanitizer — strict key validation + per-segment encoder.
retry-helper — transient classifier + Retry-After honour.
otel — meters, histograms, counters, tracer.
bunny-cdn-adapter — main BunnyCdnAdapter class.
registry — module-augmentation slot for createStorage({ type: "bunnycdn", ... }).

Capabilities matrix

{
    partialReads: true,
    partialWrites: false,
    nativeStreams: true,
    atomicWrites: false,
    contentAddressable: false,
    cdn: {
        cdnPurge: true,
        cdnPrefixPurge: true,
        cdnSignedUrls: true,
        cdnOriginUploads: true,
    },
}

Features

Universal purity — no node:* or DOM-only imports.
Full Storage Zone surface — origin PUT/GET/DELETE/HEAD with Range, native streaming, AbortSignal.
CDN integration — single + prefix purge, signed (Token Authentication) URLs, edge URL composition.
Region-aware host selection — de uses the unprefixed host (storage.bunnycdn.com); other regions prepend the code (ny.storage.bunnycdn.com, …).
Two-key model — per-zone storageAccessKey for CRUD vs. account-level purgeApiKey for invalidation; rotated independently.
Retry on transient outcomes — 408/425/429/5xx retried with Retry-After honoured.
OTel built-in — storage_cdn_bunnycdn.* instruments with provider="bunnycdn" and storage_region attributes for cross-provider dashboards.
100 / 100 / 100 / 100 Istanbul coverage.

License

MIT — see LICENSE at the repo root.

8.0 KiB Raw Blame History