@velajs/storage 0.2.0

package/dist/middleware/cache.js

@@ -0,0 +1,101 @@
+import { createStoredFile } from "../internal/stored-file.js";
+import { passthrough } from "./wrap.js";
+/** In-memory, per-isolate cache with lazy TTL + insertion-order eviction (no timers). */ export class MapCacheStore {
+    maxEntries;
+    now;
+    #map = new Map();
+    constructor(maxEntries = 1000, now = Date.now){
+        this.maxEntries = maxEntries;
+        this.now = now;
+    }
+    get(key) {
+        const e = this.#map.get(key);
+        if (!e) return undefined;
+        if (e.expiresAt <= this.now()) {
+            this.#map.delete(key);
+            return undefined;
+        }
+        return e;
+    }
+    set(key, value) {
+        this.#map.delete(key);
+        this.#map.set(key, value);
+        if (this.#map.size > this.maxEntries) {
+            const oldest = this.#map.keys().next().value;
+            if (oldest !== undefined) this.#map.delete(oldest);
+        }
+    }
+    delete(key) {
+        this.#map.delete(key);
+    }
+}
+function toMeta(f) {
+    return {
+        key: f.key,
+        name: f.name,
+        size: f.size,
+        type: f.type,
+        lastModified: f.lastModified,
+        etag: f.etag,
+        metadata: f.metadata
+    };
+}
+/**
+ * Read-through cache for `head` / `exists`. Bodies are never cached (a `head`
+ * hit still lazily fetches on body access), and `list` is not cached
+ * (cross-prefix invalidation is intractable). Writes invalidate the key.
+ */ export function cache(opts = {}) {
+    const now = opts.now ?? Date.now;
+    const store = opts.store ?? new MapCacheStore(1000, now);
+    const ttl = opts.ttlMs ?? 60_000;
+    const doHead = opts.cache?.head ?? true;
+    const doExists = opts.cache?.exists ?? true;
+    const ns = (k)=>`${opts.keyPrefix ?? ''}${k}`;
+    return (inner)=>{
+        const invalidate = async (...keys)=>{
+            await Promise.all(keys.map((k)=>store.delete(ns(k))));
+        };
+        return passthrough(inner, {
+            head: doHead ? async (k, o)=>{
+                const hit = await store.get(ns(k));
+                if (hit?.kind === 'meta' && hit.meta) {
+                    return createStoredFile(hit.meta, {
+                        kind: 'lazy',
+                        fetch: async ()=>new Response((await inner.download(k)).stream())
+                    });
+                }
+                const file = await inner.head(k, o);
+                await store.set(ns(k), {
+                    kind: 'meta',
+                    meta: toMeta(file),
+                    expiresAt: now() + ttl
+                }, ttl);
+                return file;
+            } : undefined,
+            exists: doExists ? async (k, o)=>{
+                const hit = await store.get(ns(k));
+                if (hit?.kind === 'exists' && typeof hit.exists === 'boolean') return hit.exists;
+                const exists = await inner.exists(k, o);
+                await store.set(ns(k), {
+                    kind: 'exists',
+                    exists,
+                    expiresAt: now() + ttl
+                }, ttl);
+                return exists;
+            } : undefined,
+            upload: async (k, b, o)=>{
+                const r = await inner.upload(k, b, o);
+                await invalidate(k);
+                return r;
+            },
+            delete: async (k, o)=>{
+                await inner.delete(k, o);
+                await invalidate(k);
+            },
+            copy: async (f, t, o)=>{
+                await inner.copy(f, t, o);
+                await invalidate(t);
+            }
+        });
+    };
+}

package/dist/middleware/compose.d.ts

@@ -0,0 +1,12 @@
+import type { StorageDriver } from '../storage.types';
+import type { Middleware } from './wrap';
+/**
+ * Compose middlewares over a base driver. Listed innermost → outermost:
+ * `compose(base, a, b, c)` yields `c(b(a(base)))`, so on any call `c` runs
+ * first (outermost) and `base` last. The same wrapper handles read and write,
+ * so the reverse order on download comes for free.
+ *
+ * There is deliberately NO default preset — each middleware is opt-in, so you
+ * never accidentally ship, e.g., compress-then-encrypt (a CRIME/BREACH vector).
+ */
+export declare function compose(base: StorageDriver, ...middlewares: Middleware[]): StorageDriver;

package/dist/middleware/compose.js

@@ -0,0 +1,11 @@
+/**
+ * Compose middlewares over a base driver. Listed innermost → outermost:
+ * `compose(base, a, b, c)` yields `c(b(a(base)))`, so on any call `c` runs
+ * first (outermost) and `base` last. The same wrapper handles read and write,
+ * so the reverse order on download comes for free.
+ *
+ * There is deliberately NO default preset — each middleware is opt-in, so you
+ * never accidentally ship, e.g., compress-then-encrypt (a CRIME/BREACH vector).
+ */ export function compose(base, ...middlewares) {
+    return middlewares.reduce((driver, wrap)=>wrap(driver), base);
+}

package/dist/middleware/compression.d.ts

@@ -0,0 +1,16 @@
+import { type Middleware } from './wrap';
+export type CompressionFormat = 'gzip' | 'deflate' | 'deflate-raw';
+export interface CompressionOptions {
+    /** Stream format. Default `gzip`. */
+    format?: CompressionFormat;
+    /** What to do when `CompressionStream` is unavailable. Default `throw`. */
+    onUnavailable?: 'throw' | 'passthrough';
+}
+/**
+ * Transparent gzip/deflate via Web Streams `CompressionStream` — fully
+ * streaming, opaque mode (v1). The stored object is compressed and tagged
+ * `vela-zip`; reads detect the tag and decompress, so pre-existing (untagged)
+ * objects pass through unharmed. Range reads / presigned URLs are disabled
+ * (the byte stream is not seekable and a direct URL would serve gzip).
+ */
+export declare function compression(opts?: CompressionOptions): Middleware;

package/dist/middleware/compression.js

@@ -0,0 +1,101 @@
+import { byteLengthOf, toStream } from "../internal/body.js";
+import { createStoredFile } from "../internal/stored-file.js";
+import { StorageError } from "../storage.error.js";
+import { passthrough } from "./wrap.js";
+function stripVela(meta) {
+    if (!meta) return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(meta))if (!k.startsWith('vela-')) out[k] = v;
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * Transparent gzip/deflate via Web Streams `CompressionStream` — fully
+ * streaming, opaque mode (v1). The stored object is compressed and tagged
+ * `vela-zip`; reads detect the tag and decompress, so pre-existing (untagged)
+ * objects pass through unharmed. Range reads / presigned URLs are disabled
+ * (the byte stream is not seekable and a direct URL would serve gzip).
+ */ export function compression(opts = {}) {
+    const format = opts.format ?? 'gzip';
+    const available = typeof CompressionStream !== 'undefined' && typeof DecompressionStream !== 'undefined';
+    if (!available && (opts.onUnavailable ?? 'throw') === 'throw') {
+        throw new StorageError('Unsupported', 'CompressionStream is not available in this runtime');
+    }
+    return (inner)=>{
+        if (!available) return inner; // passthrough mode
+        const decompressDownload = async (k, _o)=>{
+            const file = await inner.download(k);
+            const zip = file.metadata?.['vela-zip'];
+            if (!zip) return file; // untagged / legacy object
+            const plain = file.stream().pipeThrough(new DecompressionStream(zip));
+            const size = file.metadata?.['vela-size'] ? Number(file.metadata['vela-size']) : file.size;
+            return createStoredFile({
+                key: k,
+                name: file.name,
+                size,
+                type: file.metadata?.['vela-ct'] ?? file.type,
+                lastModified: file.lastModified,
+                etag: file.etag,
+                metadata: stripVela(file.metadata)
+            }, {
+                kind: 'stream',
+                stream: plain
+            });
+        };
+        return passthrough(inner, {
+            reportsUploadProgress: false,
+            supportsRange: false,
+            signedUrl: {
+                supported: false,
+                upload: false
+            },
+            async upload (k, body, o) {
+                const zipped = toStream(body).pipeThrough(new CompressionStream(format));
+                const metadata = {
+                    ...o?.metadata,
+                    'vela-zip': format
+                };
+                if (o?.contentType) metadata['vela-ct'] = o.contentType;
+                const known = byteLengthOf(body);
+                if (known != null) metadata['vela-size'] = String(known);
+                const r = await inner.upload(k, zipped, {
+                    ...o,
+                    metadata: inner.supportsMetadata ? metadata : undefined,
+                    contentType: 'application/octet-stream'
+                });
+                return {
+                    ...r,
+                    size: known ?? r.size,
+                    contentType: o?.contentType ?? 'application/octet-stream'
+                };
+            },
+            download: decompressDownload,
+            async head (k, o) {
+                const file = await inner.head(k, o);
+                if (!file.metadata?.['vela-zip']) return file;
+                const size = file.metadata['vela-size'] ? Number(file.metadata['vela-size']) : file.size;
+                return createStoredFile({
+                    key: k,
+                    name: file.name,
+                    size,
+                    type: file.metadata['vela-ct'] ?? file.type,
+                    lastModified: file.lastModified,
+                    etag: file.etag,
+                    metadata: stripVela(file.metadata)
+                }, {
+                    kind: 'lazy',
+                    fetch: async ()=>new Response((await decompressDownload(k)).stream())
+                });
+            },
+            url () {
+                throw new StorageError('Unsupported', 'compression: url() would serve compressed bytes');
+            },
+            signedUploadUrl () {
+                throw new StorageError('Unsupported', 'compression: signed uploads would store uncompressed');
+            }
+        }, [
+            'createMultipartUpload',
+            'resumeMultipartUpload',
+            'signedMultipart'
+        ]);
+    };
+}

package/dist/middleware/encryption.d.ts

@@ -0,0 +1,14 @@
+import { type Middleware } from './wrap';
+export interface EncryptionOptions {
+    /** A 256-bit AES-GCM key: a `CryptoKey` or 32 raw bytes. */
+    key: CryptoKey | Uint8Array;
+    /** How to treat objects that aren't valid ciphertext (legacy data). Default `throw`. */
+    onInvalid?: 'throw' | 'passthrough';
+}
+/**
+ * Transparent client-side encryption via Web Crypto AES-GCM. v1 encrypts the
+ * WHOLE object (buffered); the stored object is `IV(12) || ciphertext+tag`.
+ * Range reads, presigned URLs, and multipart are disabled (a signed URL would
+ * hand out ciphertext / accept plaintext, defeating the invariant).
+ */
+export declare function encryption(opts: EncryptionOptions): Middleware;

package/dist/middleware/encryption.js

@@ -0,0 +1,134 @@
+import { toBytes } from "../internal/body.js";
+import { createStoredFile } from "../internal/stored-file.js";
+import { StorageError } from "../storage.error.js";
+import { passthrough } from "./wrap.js";
+const IV_BYTES = 12;
+// The Web Crypto typings pin BufferSource to ArrayBuffer-backed views; our byte
+// views are ArrayBufferLike-typed. They are ArrayBuffer-backed at runtime, so a
+// narrowing cast is safe and confined to this helper.
+const asBuf = (u)=>u;
+function stripVela(meta) {
+    if (!meta) return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(meta))if (!k.startsWith('vela-')) out[k] = v;
+    return Object.keys(out).length ? out : undefined;
+}
+async function importKey(key) {
+    if (key instanceof Uint8Array) {
+        return crypto.subtle.importKey('raw', key, {
+            name: 'AES-GCM'
+        }, false, [
+            'encrypt',
+            'decrypt'
+        ]);
+    }
+    return key;
+}
+/**
+ * Transparent client-side encryption via Web Crypto AES-GCM. v1 encrypts the
+ * WHOLE object (buffered); the stored object is `IV(12) || ciphertext+tag`.
+ * Range reads, presigned URLs, and multipart are disabled (a signed URL would
+ * hand out ciphertext / accept plaintext, defeating the invariant).
+ */ export function encryption(opts) {
+    const keyPromise = importKey(opts.key);
+    return (inner)=>{
+        const decryptDownload = async (k, _o)=>{
+            const file = await inner.download(k);
+            const framed = new Uint8Array(await file.arrayBuffer());
+            if (framed.byteLength < IV_BYTES) {
+                if (opts.onInvalid === 'passthrough') return file;
+                throw new StorageError('Parse', `object too small to be encrypted: ${k}`);
+            }
+            const iv = framed.subarray(0, IV_BYTES);
+            const ciphertext = framed.subarray(IV_BYTES);
+            const key = await keyPromise;
+            let plain;
+            try {
+                plain = new Uint8Array(await crypto.subtle.decrypt({
+                    name: 'AES-GCM',
+                    iv: asBuf(iv)
+                }, key, asBuf(ciphertext)));
+            } catch (e) {
+                if (opts.onInvalid === 'passthrough') return file;
+                throw new StorageError('Provider', `decryption failed: ${k}`, {
+                    cause: e
+                });
+            }
+            return createStoredFile({
+                key: k,
+                name: file.name,
+                size: plain.byteLength,
+                type: file.metadata?.['vela-ct'] ?? file.type,
+                lastModified: file.lastModified,
+                etag: file.etag,
+                metadata: stripVela(file.metadata)
+            }, {
+                kind: 'bytes',
+                bytes: plain
+            });
+        };
+        return passthrough(inner, {
+            reportsUploadProgress: false,
+            supportsRange: false,
+            signedUrl: {
+                supported: false,
+                upload: false
+            },
+            async upload (k, body, o) {
+                const plaintext = await toBytes(body);
+                const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+                const key = await keyPromise;
+                const ct = new Uint8Array(await crypto.subtle.encrypt({
+                    name: 'AES-GCM',
+                    iv
+                }, key, asBuf(plaintext)));
+                const framed = new Uint8Array(IV_BYTES + ct.byteLength);
+                framed.set(iv, 0);
+                framed.set(ct, IV_BYTES);
+                const metadata = {
+                    ...o?.metadata,
+                    'vela-enc': 'AES-GCM'
+                };
+                if (o?.contentType) metadata['vela-ct'] = o.contentType;
+                metadata['vela-size'] = String(plaintext.byteLength);
+                const r = await inner.upload(k, framed, {
+                    ...o,
+                    metadata: inner.supportsMetadata ? metadata : undefined,
+                    contentType: 'application/octet-stream'
+                });
+                return {
+                    ...r,
+                    size: plaintext.byteLength,
+                    contentType: o?.contentType ?? 'application/octet-stream'
+                };
+            },
+            download: decryptDownload,
+            async head (k, o) {
+                const file = await inner.head(k, o);
+                const size = file.metadata?.['vela-size'] ? Number(file.metadata['vela-size']) : file.size;
+                return createStoredFile({
+                    key: k,
+                    name: file.name,
+                    size,
+                    type: file.metadata?.['vela-ct'] ?? file.type,
+                    lastModified: file.lastModified,
+                    etag: file.etag,
+                    metadata: stripVela(file.metadata)
+                }, {
+                    kind: 'lazy',
+                    fetch: async ()=>new Response((await decryptDownload(k)).stream())
+                });
+            },
+            url () {
+                throw new StorageError('Unsupported', 'encryption: url() would expose ciphertext');
+            },
+            signedUploadUrl () {
+                throw new StorageError('Unsupported', 'encryption: signed uploads would store plaintext');
+            }
+        }, [
+            'createMultipartUpload',
+            'resumeMultipartUpload',
+            'signedMultipart'
+        ]);
+    };
+}

package/dist/middleware/failover.d.ts

@@ -0,0 +1,18 @@
+import type { StorageDriver } from '../storage.types';
+import { type Middleware } from './wrap';
+export interface FailoverOptions {
+    /** Decide whether an error should trigger failover. Default: transient errors. */
+    shouldFailover?: (error: unknown) => boolean;
+    onFailover?: (info: {
+        from: number;
+        to: number;
+        error: unknown;
+    }) => void;
+}
+/**
+ * Read-failover across a primary + fallbacks. Reads try each driver in order
+ * until one succeeds; writes and presigning go to the primary only (avoids
+ * partial/divergent writes). Capabilities are the intersection so the facade
+ * never routes a feature to a driver that can't serve it.
+ */
+export declare function failover(fallbacks: StorageDriver[], opts?: FailoverOptions): Middleware;

package/dist/middleware/failover.js

@@ -0,0 +1,52 @@
+import { StorageError } from "../storage.error.js";
+import { passthrough } from "./wrap.js";
+function isTransient(error) {
+    return error instanceof StorageError ? error.retryable : true;
+}
+function intersectCapabilities(chain) {
+    return {
+        supportsRange: chain.every((d)=>!!d.supportsRange),
+        supportsDelimiter: chain.every((d)=>!!d.supportsDelimiter),
+        supportsMetadata: chain.every((d)=>!!d.supportsMetadata),
+        supportsCacheControl: chain.every((d)=>!!d.supportsCacheControl),
+        supportsServerSideCopy: chain.every((d)=>!!d.supportsServerSideCopy)
+    };
+}
+/**
+ * Read-failover across a primary + fallbacks. Reads try each driver in order
+ * until one succeeds; writes and presigning go to the primary only (avoids
+ * partial/divergent writes). Capabilities are the intersection so the facade
+ * never routes a feature to a driver that can't serve it.
+ */ export function failover(fallbacks, opts = {}) {
+    const should = opts.shouldFailover ?? isTransient;
+    return (primary)=>{
+        const chain = [
+            primary,
+            ...fallbacks
+        ];
+        const read = async (fn)=>{
+            let lastError;
+            for(let i = 0; i < chain.length; i++){
+                try {
+                    return await fn(chain[i]);
+                } catch (e) {
+                    lastError = e;
+                    if (!should(e) || i === chain.length - 1) throw e;
+                    opts.onFailover?.({
+                        from: i,
+                        to: i + 1,
+                        error: e
+                    });
+                }
+            }
+            throw lastError;
+        };
+        return passthrough(primary, {
+            ...intersectCapabilities(chain),
+            download: (k, o)=>read((d)=>d.download(k, o)),
+            head: (k, o)=>read((d)=>d.head(k, o)),
+            exists: (k, o)=>read((d)=>d.exists(k, o)),
+            list: (o)=>read((d)=>d.list(o))
+        });
+    };
+}

package/dist/middleware/index.d.ts

@@ -0,0 +1,15 @@
+export { compose } from './compose';
+export { passthrough } from './wrap';
+export type { Middleware } from './wrap';
+export { retry } from './retry';
+export type { RetryMiddlewareOptions } from './retry';
+export { failover } from './failover';
+export type { FailoverOptions } from './failover';
+export { cache, MapCacheStore } from './cache';
+export type { CacheOptions, CacheStore, CacheEntry, CachedMeta } from './cache';
+export { encryption } from './encryption';
+export type { EncryptionOptions } from './encryption';
+export { compression } from './compression';
+export type { CompressionOptions, CompressionFormat } from './compression';
+export { versioning, unwrapVersioning, VERSIONED } from './versioning';
+export type { VersioningOptions, Versioned, VersionInfo } from './versioning';

package/dist/middleware/index.js

@@ -0,0 +1,8 @@
+export { compose } from "./compose.js";
+export { passthrough } from "./wrap.js";
+export { retry } from "./retry.js";
+export { failover } from "./failover.js";
+export { cache, MapCacheStore } from "./cache.js";
+export { encryption } from "./encryption.js";
+export { compression } from "./compression.js";
+export { versioning, unwrapVersioning, VERSIONED } from "./versioning.js";

package/dist/middleware/retry.d.ts

@@ -0,0 +1,14 @@
+import type { RetryOptions } from '../storage.types';
+import { type Middleware } from './wrap';
+export interface RetryMiddlewareOptions {
+    /** Default retry policy for driver operations. Per-call `opts.retries` wins. */
+    retries?: RetryOptions;
+}
+/**
+ * Retry transient failures at the driver level. Reads and idempotent ops
+ * always retry; an upload retries only when its body is replayable (not a
+ * one-shot stream). Note: the `Storage` facade also retries per
+ * `OperationOptions.retries` — use this middleware when driving a driver
+ * directly, or set the facade's retries to 0 to avoid compounding.
+ */
+export declare function retry(opts?: RetryMiddlewareOptions): Middleware;

package/dist/middleware/retry.js

@@ -0,0 +1,47 @@
+import { isStream } from "../internal/body.js";
+import { runWithRetry } from "../internal/retry.js";
+import { passthrough } from "./wrap.js";
+/**
+ * Retry transient failures at the driver level. Reads and idempotent ops
+ * always retry; an upload retries only when its body is replayable (not a
+ * one-shot stream). Note: the `Storage` facade also retries per
+ * `OperationOptions.retries` — use this middleware when driving a driver
+ * directly, or set the facade's retries to 0 to avoid compounding.
+ */ export function retry(opts = {}) {
+    const base = opts.retries ?? 3;
+    const run = (o, fn)=>runWithRetry(fn, {
+            retries: o?.retries ?? base,
+            timeout: o?.timeout,
+            signal: o?.signal
+        });
+    return (inner)=>passthrough(inner, {
+            download: (k, o)=>run(o, (s)=>inner.download(k, {
+                        ...o,
+                        signal: s
+                    })),
+            head: (k, o)=>run(o, (s)=>inner.head(k, {
+                        ...o,
+                        signal: s
+                    })),
+            exists: (k, o)=>run(o, (s)=>inner.exists(k, {
+                        ...o,
+                        signal: s
+                    })),
+            list: (o)=>run(o, (s)=>inner.list({
+                        ...o,
+                        signal: s
+                    })),
+            delete: (k, o)=>run(o, (s)=>inner.delete(k, {
+                        ...o,
+                        signal: s
+                    })),
+            copy: (f, t, o)=>run(o, (s)=>inner.copy(f, t, {
+                        ...o,
+                        signal: s
+                    })),
+            upload: (k, b, o)=>isStream(b) ? inner.upload(k, b, o) : run(o, (s)=>inner.upload(k, b, {
+                        ...o,
+                        signal: s
+                    }))
+        });
+}

package/dist/middleware/versioning.d.ts

@@ -0,0 +1,36 @@
+import type { StorageDriver } from '../storage.types';
+import { type Middleware } from './wrap';
+export interface VersionInfo {
+    versionId: string;
+    key: string;
+    size: number;
+    lastModified?: number;
+}
+/** Extra surface a versioning-wrapped driver exposes (reached via {@link unwrapVersioning}). */
+export interface Versioned {
+    listVersions(key: string): Promise<VersionInfo[]>;
+    restore(key: string, versionId: string): Promise<void>;
+    deleteVersion(key: string, versionId: string): Promise<void>;
+}
+export declare const VERSIONED: unique symbol;
+export interface VersioningOptions {
+    /** Prefix under which prior versions are stored. Default `.vela-versions/`. */
+    prefix?: string;
+    versionId?: () => string;
+    /** Keep at most this many versions per key (prunes oldest). */
+    maxVersions?: number;
+    /** Hide the version prefix from `list()`. Default true. */
+    hideFromList?: boolean;
+    /** On delete: snapshot first (default) or purge all versions. */
+    onDelete?: 'snapshot' | 'purge';
+}
+/**
+ * Keeps prior versions on overwrite via key-suffixing (no external manifest →
+ * no read-modify-write race). Snapshots are cheap when the base driver
+ * `supportsServerSideCopy`. Direct presigned uploads bypass snapshotting, so
+ * `signedUploadUrl` throws. Reach `listVersions`/`restore`/`deleteVersion` via
+ * {@link unwrapVersioning}.
+ */
+export declare function versioning(opts?: VersioningOptions): Middleware;
+/** Retrieve the {@link Versioned} surface from a versioning-wrapped driver (or `undefined`). */
+export declare function unwrapVersioning(driver: StorageDriver): Versioned | undefined;