@trokky/trokky 3.4.1 → 3.5.0

package/dist/adapters/s3-media/s3-media-adapter.d.ts

@@ -0,0 +1,118 @@
+/**
+ * S3-compatible media storage adapter.
+ *
+ * Talks SigV4 over HTTP, so it reaches R2 from a Node process, and MinIO, Backblaze B2, Spaces,
+ * Ceph or AWS from anywhere. `CloudflareR2Adapter` is the better choice *inside* a Worker — a
+ * binding is faster and needs no credentials — and the two share a key layout on purpose, so
+ * one bucket can be handed from a Worker to a Node server and back.
+ *
+ * The layout, identical to the R2 adapter's:
+ *
+ *   files/<id>              the bytes
+ *   meta/<id>.json          the record — the only authority for existence
+ *   variants/<id>/<name>    variant bytes, format in user metadata
+ *   index/...               the listing cache, see index-key.ts
+ *
+ * What differs, and why:
+ *
+ *  - **The listing is a join, not a sweep.** R2's `list()` can return `customMetadata`;
+ *    `ListObjectsV2` cannot return user metadata at all. So the sortable fields are encoded into
+ *    keys under `index/`, and `listMedia` enumerates ids from `meta/`, reads fields from the
+ *    index, and falls back to reading the record for any id the index does not cover.
+ *  - **The index must never be the enumeration.** Writes go bytes → record → index and deletes
+ *    reverse that, so an interrupted operation leaves a record with no index entry. If the index
+ *    were authoritative that file would exist and never be listed — a ghost. Enumerating from
+ *    `meta/` makes a missing entry cost one GET instead of hiding a file, and `cleanup()`
+ *    rebuilds it.
+ *  - **`listVariants` HEADs each variant.** The format lives in user metadata and a listing does
+ *    not carry it. A file has a handful of variants, so this is a handful of requests, and it
+ *    keeps the R2 invariant that variant keys carry no format — re-encoding a variant to another
+ *    format overwrites it instead of leaving both behind.
+ */
+import type { MediaFile, MediaMetadata } from '../../core/types/index.js';
+import type { MediaListOptions, MediaListResult, MediaStorageAdapter, MediaVariant } from '../../core/types/storage-adapters.js';
+import type { S3MediaAdapterConfig } from './types.js';
+export declare class S3MediaAdapter implements MediaStorageAdapter {
+    private readonly s3;
+    private readonly prefix;
+    private readonly publicBaseUrl?;
+    private readonly urlExpiry;
+    private readonly maxFileSize;
+    private readonly silent;
+    private readonly logger;
+    constructor(config: S3MediaAdapterConfig);
+    private fileKey;
+    private recordKey;
+    private variantKey;
+    private variantPrefix;
+    private recordPrefix;
+    uploadFile(file: File, metadata: MediaMetadata): Promise<MediaFile>;
+    getFile(id: string): Promise<MediaFile | null>;
+    updateFile(id: string, metadata: Record<string, any>): Promise<MediaFile>;
+    getFileContent(id: string): Promise<ArrayBuffer | null>;
+    getFileUrl(id: string, options?: {
+        expiresIn?: number;
+    }): Promise<string | null>;
+    fileExists(id: string): Promise<boolean>;
+    getFileSize(id: string): Promise<number | null>;
+    deleteFile(id: string): Promise<void>;
+    listMedia(options?: MediaListOptions): Promise<MediaListResult>;
+    saveVariantFile(parentId: string, variantName: string, buffer: Buffer, format: string): Promise<string>;
+    getVariantContent(parentId: string, variantName: string): Promise<ArrayBuffer | null>;
+    getVariantUrl(parentId: string, variantName: string, options?: {
+        expiresIn?: number;
+    }): Promise<string | null>;
+    listVariants(parentId: string): Promise<MediaVariant[]>;
+    deleteVariantFiles(parentId: string): Promise<void>;
+    deleteVariant(parentId: string, variantName: string): Promise<void>;
+    healthCheck(): Promise<boolean>;
+    getStorageInfo(): Promise<{
+        totalFiles: number;
+        totalSize: number;
+        availableSpace?: number;
+        usedSpace?: number;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Reconcile the bucket against its records, which are the only authority.
+     *
+     * Three jobs, and the order they are listed in is the order of how much they matter:
+     *
+     *  1. **Rebuild missing index entries.** An upload interrupted after the record but before the
+     *     index — or a delete interrupted the other way — leaves a file that `getFile` serves and
+     *     no listing shows. `listMedia` already heals the symptom by reading the record; this
+     *     removes the cost.
+     *  2. **Drop orphaned bytes.** Anything under `files/` or `variants/` whose id has no record.
+     *  3. **Drop stale index entries.** Unreachable by an interruption under these write orders,
+     *     but reachable by a partial restore or by a re-upload whose old-entry delete failed.
+     *
+     * Returns the number of objects written or deleted.
+     */
+    cleanup(): Promise<number>;
+    private writeRecord;
+    private readRecord;
+    private writeIndexEntry;
+    /**
+     * Every index key for an id, whatever epoch it carries.
+     *
+     * One prefix listing rather than a sweep of the whole index — which is the entire reason the
+     * key puts the id before the timestamp. This runs on every upload.
+     */
+    private deleteIndexEntries;
+    private listRecordIds;
+    /**
+     * Every record in the bucket, with its listable fields.
+     *
+     * Two key-only listings — `meta/` for the ids, `index/` for the fields — joined by id. The
+     * records are the authority for *which* files exist; the index only saves reading them. An id
+     * the index does not cover (a bucket written by the R2 adapter, a hand-copied object, an
+     * interrupted upload) falls back to a real read, so it is never silently invisible.
+     */
+    private listIndex;
+    /** Every request here is a network round trip, so fan out — but not without a ceiling. */
+    private mapWithConcurrency;
+    private sortIndex;
+    private toMediaFile;
+    private validateMediaMetadata;
+}
+//# sourceMappingURL=s3-media-adapter.d.ts.map

package/dist/adapters/s3-media/s3-media-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-media-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/s3-media/s3-media-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzE,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,YAAY,EACb,MAAM,sCAAsC,CAAA;AAS7C,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,YAAY,CAAA;AAiBrE,qBAAa,cAAe,YAAW,mBAAmB;IACxD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAU;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;gBAEvD,MAAM,EAAE,oBAAoB;IA+CxC,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,YAAY;IAQP,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IA4CnE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAO9C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;IAiDzE,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAOvD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUpF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAO/C,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBrC,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAgDnE,eAAe,CAC1B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC;IA0BL,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQrF,aAAa,CACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUZ,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqBvD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAanD,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAa/B,cAAc,IAAI,OAAO,CAAC;QACrC,UAAU,EAAE,MAAM,CAAA;QAClB,SAAS,EAAE,MAAM,CAAA;QACjB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAC;IAYF;;;;;;;;;;;;;;OAcG;IACU,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;YAoEzB,WAAW;YAMX,UAAU;YAcV,eAAe;IAI7B;;;;;OAKG;YACW,kBAAkB;YAKlB,aAAa;IAQ3B;;;;;;;OAOG;YACW,SAAS;IA+BvB,0FAA0F;YAC5E,kBAAkB;IAWhC,OAAO,CAAC,SAAS;IA6BjB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,qBAAqB;CA4B9B"}