@veryfront/ext-blob-s3 0.1.1184

package/esm/multipart-upload.js

@@ -0,0 +1,159 @@
+import { Upload } from "@aws-sdk/lib-storage";
+import { Readable } from "node:stream";
+import { API_ERROR, INVALID_ARGUMENT } from "veryfront/errors";
+export const MIN_MULTIPART_PART_SIZE = 5 * 1024 * 1024;
+export const DEFAULT_MULTIPART_PART_SIZE = 8 * 1024 * 1024;
+export const MAX_MULTIPART_PART_SIZE = 512 * 1024 * 1024;
+export const DEFAULT_MULTIPART_QUEUE_SIZE = 2;
+export const MAX_MULTIPART_QUEUE_SIZE = 16;
+function invalidByteStream(detail, cause) {
+    return INVALID_ARGUMENT.create({ detail, cause });
+}
+async function cancelReader(reader, reason) {
+    try {
+        await reader.cancel(reason);
+    }
+    catch {
+        // The failure that stopped the upload remains authoritative.
+    }
+}
+async function uploadStream(client, input) {
+    input.signal?.throwIfAborted();
+    let reader;
+    try {
+        reader = input.stream.getReader();
+    }
+    catch (cause) {
+        throw invalidByteStream("S3BlobStorage: upload stream must be unlocked", cause);
+    }
+    let bytesRead = 0;
+    let readerFinished = false;
+    let readerCancelled = false;
+    let cancellationReason;
+    const cancelSource = async (reason) => {
+        if (readerFinished || readerCancelled)
+            return;
+        readerCancelled = true;
+        await cancelReader(reader, reason);
+    };
+    async function* bytes() {
+        try {
+            while (true) {
+                input.signal?.throwIfAborted();
+                const result = await reader.read();
+                input.signal?.throwIfAborted();
+                if (result.done) {
+                    readerFinished = true;
+                    return;
+                }
+                if (!(result.value instanceof Uint8Array)) {
+                    throw invalidByteStream("S3BlobStorage: ReadableStream chunks must be Uint8Array values");
+                }
+                bytesRead += result.value.byteLength;
+                if (!Number.isSafeInteger(bytesRead)) {
+                    throw invalidByteStream("S3BlobStorage: upload stream exceeds the supported size range");
+                }
+                yield result.value;
+            }
+        }
+        catch (error) {
+            cancellationReason = error;
+            await cancelSource(error);
+            throw error;
+        }
+        finally {
+            await cancelSource(cancellationReason);
+            reader.releaseLock();
+        }
+    }
+    const body = Readable.from(bytes(), { objectMode: false });
+    const abortController = new AbortController();
+    let upload;
+    let uploadAbortPromise;
+    let uploadAbortFailed = false;
+    let uploadAbortFailure;
+    const requestUploadAbort = () => {
+        if (!upload || uploadAbortPromise)
+            return;
+        const currentUpload = upload;
+        uploadAbortPromise = Promise.resolve()
+            .then(() => currentUpload.abort())
+            .catch((error) => {
+            uploadAbortFailed = true;
+            uploadAbortFailure = error;
+        });
+    };
+    let abortCancellation;
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const onAbort = () => {
+        const reason = input.signal?.reason;
+        cancellationReason = reason;
+        abortController.abort(reason);
+        abortCancellation ??= cancelSource(reason);
+        body.destroy();
+        requestUploadAbort();
+        rejectAbort?.(reason);
+    };
+    if (input.signal?.aborted)
+        onAbort();
+    else
+        input.signal?.addEventListener("abort", onAbort, { once: true });
+    let completed = false;
+    let done;
+    try {
+        const params = {
+            Bucket: input.bucket,
+            Key: input.key,
+            Body: body,
+            ContentType: input.mimeType,
+            Expires: input.expiresAt,
+            Metadata: input.metadata,
+        };
+        upload = new Upload({
+            client,
+            params,
+            abortController,
+            leavePartsOnError: false,
+            partSize: input.partSize,
+            queueSize: input.queueSize,
+        });
+        done = upload.done();
+        await Promise.race([done, aborted]);
+        if (!readerFinished) {
+            throw API_ERROR.create({
+                detail: "S3BlobStorage: multipart uploader did not consume the source stream",
+            });
+        }
+        completed = true;
+        return bytesRead;
+    }
+    catch (error) {
+        cancellationReason = error;
+        abortController.abort(error);
+        await cancelSource(error);
+        body.destroy();
+        requestUploadAbort();
+        await uploadAbortPromise;
+        if (uploadAbortFailed) {
+            throw new AggregateError([error, uploadAbortFailure], "S3BlobStorage: upload failed and multipart cleanup also failed");
+        }
+        throw error;
+    }
+    finally {
+        input.signal?.removeEventListener("abort", onAbort);
+        rejectAbort = undefined;
+        await abortCancellation;
+        await uploadAbortPromise;
+        if (!completed)
+            void done?.catch(() => undefined);
+    }
+}
+/** Create the official AWS multipart adapter for unknown-length Web streams. */
+export function createS3BlobStorageStreamUploader(client) {
+    return {
+        upload: (input) => uploadStream(client, input),
+    };
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/s3-storage.d.ts

@@ -0,0 +1,82 @@
+import { CreateBucketCommand, DeleteObjectCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+import { type BlobRef, type BlobStorage, type StoreBlobOptions } from "veryfront/workflow/blob";
+import { type S3BlobStorageStreamUploader } from "./multipart-upload.js";
+/** AWS commands issued through the injectable client boundary. */
+export type S3BlobStorageCommand = CreateBucketCommand | DeleteObjectCommand | GetObjectCommand | HeadBucketCommand | HeadObjectCommand | PutObjectCommand;
+/** Provider request options required by the storage implementation. */
+export interface S3BlobStorageSendOptions {
+    abortSignal?: AbortSignal;
+}
+/** Minimal client boundary used by the storage implementation and deterministic tests. */
+export interface S3BlobStorageClient {
+    send(command: S3BlobStorageCommand, options?: S3BlobStorageSendOptions): Promise<unknown>;
+    destroy?(): void;
+}
+/** Injectable provider seams for deterministic tests and custom transports. */
+export interface S3BlobStorageDependencies {
+    /** S3-compatible command client. */
+    client?: S3BlobStorageClient;
+    /** Required for stream uploads when a custom client is supplied. */
+    streamUploader?: S3BlobStorageStreamUploader;
+}
+/** Explicit S3 connection, transport, and object-layout configuration. */
+export interface S3BlobStorageConfig {
+    /** AWS region used by the client and bucket creation. */
+    region: string;
+    /** S3 bucket name. */
+    bucket: string;
+    /** AWS access-key id. */
+    accessKeyId: string;
+    /** AWS secret access key. */
+    secretAccessKey: string;
+    /** Optional temporary-credential session token. */
+    sessionToken?: string;
+    /** Optional S3-compatible endpoint. */
+    endpoint?: string;
+    /** Force path-style requests for S3-compatible services. */
+    forcePathStyle?: boolean;
+    /** Maximum attempts, including the initial request. Defaults to three. */
+    maxAttempts?: number;
+    /** Explicit SDK retry algorithm. Defaults to standard. */
+    retryMode?: "standard" | "adaptive";
+    /** Use AWS dual-stack endpoints. Defaults to false. */
+    useDualstackEndpoint?: boolean;
+    /** Use AWS FIPS endpoints. Defaults to false. */
+    useFipsEndpoint?: boolean;
+    /** Resolve an ARN's region instead of the configured region. Defaults to false. */
+    useArnRegion?: boolean;
+    /** Request-checksum policy. Defaults to the SDK's deterministic supported policy. */
+    requestChecksumCalculation?: "WHEN_SUPPORTED" | "WHEN_REQUIRED";
+    /** Response-checksum policy. Defaults to the SDK's deterministic supported policy. */
+    responseChecksumValidation?: "WHEN_SUPPORTED" | "WHEN_REQUIRED";
+    /** Disable S3 Express session authentication. Defaults to false. */
+    disableS3ExpressSessionAuth?: boolean;
+    /** Multipart part size for unknown-length streams. Defaults to 8 MiB. */
+    multipartPartSize?: number;
+    /** Concurrent multipart requests for unknown-length streams. Defaults to two. */
+    multipartQueueSize?: number;
+    /** Object-key prefix applied verbatim before each blob id. */
+    prefix?: string;
+    /** Public base URL used only to populate `BlobRef.url`. */
+    baseUrl?: string;
+    /** Default TTL in seconds. Zero means no expiry. */
+    defaultTtl?: number;
+    /** Check for and create a missing bucket before the first upload. */
+    autoCreateBucket?: boolean;
+    /** Cancellation signal applied to provider requests. */
+    signal?: AbortSignal;
+}
+/** AWS S3 implementation of the framework-owned `BlobStorage` interface. */
+export declare class S3BlobStorage implements BlobStorage {
+    #private;
+    constructor(config: S3BlobStorageConfig, dependencies?: S3BlobStorageDependencies);
+    close(): void;
+    put(data: string | Uint8Array | Blob | ReadableStream, options?: StoreBlobOptions): Promise<BlobRef>;
+    getStream(id: string): Promise<ReadableStream | null>;
+    getText(id: string): Promise<string | null>;
+    getBytes(id: string): Promise<Uint8Array | null>;
+    delete(id: string): Promise<void>;
+    exists(id: string): Promise<boolean>;
+    stat(id: string): Promise<BlobRef | null>;
+}
+//# sourceMappingURL=s3-storage.d.ts.map

package/esm/s3-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-storage.d.ts","sourceRoot":"","sources":["../src/s3-storage.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAEhB,iBAAiB,EACjB,iBAAiB,EAEjB,gBAAgB,EAGjB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAOL,KAAK,2BAA2B,EACjC,MAAM,uBAAuB,CAAC;AAO/B,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB,uEAAuE;AACvE,MAAM,WAAW,wBAAwB;IACvC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,IAAI,CACF,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,+EAA+E;AAC/E,MAAM,WAAW,yBAAyB;IACxC,oCAAoC;IACpC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,oEAAoE;IACpE,cAAc,CAAC,EAAE,2BAA2B,CAAC;CAC9C;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iDAAiD;IACjD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mFAAmF;IACnF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,0BAA0B,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAC;IAChE,sFAAsF;IACtF,0BAA0B,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAC;IAChE,oEAAoE;IACpE,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAsdD,4EAA4E;AAC5E,qBAAa,aAAc,YAAW,WAAW;;gBAUnC,MAAM,EAAE,mBAAmB,EAAE,YAAY,GAAE,yBAA8B;IA8BrF,KAAK,IAAI,IAAI;IAwFP,GAAG,CACP,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,GAAG,cAAc,EACjD,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,OAAO,CAAC;IAoFb,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA+BrD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK3C,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMhD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAepC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;CAkDhD"}