@veryfront/ext-blob-gcs 0.1.1184

package/esm/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Google Cloud Storage implementation of Veryfront's first-party
+ * `BlobStorage` contract.
+ *
+ * @module extensions/ext-blob-gcs
+ */
+import "./_dnt.polyfills.js";
+import { type Extension } from "veryfront/extensions";
+import { type GCSBlobStorageConfig } from "./gcs-storage.js";
+/** Create an explicitly configured GCS blob-storage extension. */
+export declare const extBlobGCS: (config: GCSBlobStorageConfig) => Extension;
+export default extBlobGCS;
+export { GCSBlobStorage } from "./gcs-storage.js";
+export type { GCSBlobStorageConfig, GCSBlobStorageDependencies, GCSFetch } from "./gcs-storage.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,qBAAqB,CAAC;AAG7B,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,kEAAkE;AAClE,eAAO,MAAM,UAAU,GAAI,QAAQ,oBAAoB,KAAG,SAgEzD,CAAC;AAEF,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/esm/index.js

@@ -0,0 +1,75 @@
+/**
+ * Google Cloud Storage implementation of Veryfront's first-party
+ * `BlobStorage` contract.
+ *
+ * @module extensions/ext-blob-gcs
+ */
+import "./_dnt.polyfills.js";
+import { composeAbortSignals } from "veryfront/extensions";
+import { BlobStorageContractName } from "veryfront/workflow/blob";
+import { GCSBlobStorage } from "./gcs-storage.js";
+/** Create an explicitly configured GCS blob-storage extension. */
+export const extBlobGCS = (config) => {
+    const selectedConfig = { ...config };
+    let activeGeneration;
+    return {
+        name: "ext-blob-gcs",
+        version: "0.1.0",
+        contracts: {
+            provides: ["BlobStorage"],
+        },
+        capabilities: [
+            {
+                type: "net:outbound",
+                hosts: ["oauth2.googleapis.com", "storage.googleapis.com"],
+            },
+        ],
+        setup(ctx) {
+            if (activeGeneration)
+                throw new Error("ext-blob-gcs is already set up");
+            selectedConfig.signal?.throwIfAborted();
+            ctx.signal?.throwIfAborted();
+            const controller = new AbortController();
+            const signal = composeAbortSignals([
+                controller.signal,
+                ...(selectedConfig.signal ? [selectedConfig.signal] : []),
+                ...(ctx.signal ? [ctx.signal] : []),
+            ]);
+            const generation = {
+                controller,
+                storage: new GCSBlobStorage({ ...selectedConfig, signal }),
+            };
+            try {
+                signal.throwIfAborted();
+                ctx.provide(BlobStorageContractName, generation.storage);
+                signal.throwIfAborted();
+                activeGeneration = generation;
+            }
+            catch (error) {
+                if (!controller.signal.aborted) {
+                    controller.abort(new DOMException("GCS blob extension setup failed.", "AbortError"));
+                }
+                generation.storage.close();
+                throw error;
+            }
+            try {
+                ctx.logger.debug("[ext-blob-gcs] BlobStorage registered");
+            }
+            catch {
+                // Diagnostics must not invalidate a successfully registered provider.
+            }
+        },
+        teardown() {
+            const generation = activeGeneration;
+            if (!generation)
+                return;
+            activeGeneration = undefined;
+            if (!generation.controller.signal.aborted) {
+                generation.controller.abort(new DOMException("GCS blob extension is shutting down.", "AbortError"));
+            }
+            generation.storage.close();
+        },
+    };
+};
+export default extBlobGCS;
+export { GCSBlobStorage } from "./gcs-storage.js";

package/esm/package.json

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

package/esm/resumable-upload.d.ts

@@ -0,0 +1,19 @@
+export declare const MIN_RESUMABLE_CHUNK_SIZE: number;
+export declare const DEFAULT_RESUMABLE_CHUNK_SIZE: number;
+export declare const MAX_RESUMABLE_CHUNK_SIZE: number;
+export interface ResumableStreamUploadOptions {
+    readonly stream: ReadableStream;
+    readonly sessionUrl: URL;
+    readonly contentType: string;
+    readonly chunkSize: number;
+    readonly signal?: AbortSignal;
+    readonly request: (input: URL, init: RequestInit) => Promise<Response>;
+    readonly createHttpError: (response: Response) => Promise<Error>;
+}
+export interface ResumableStreamUploadResult {
+    readonly response: Response;
+    readonly size: number;
+}
+/** Upload an unknown-length byte stream using the GCS resumable protocol. */
+export declare function uploadUnknownLengthStream(options: ResumableStreamUploadOptions): Promise<ResumableStreamUploadResult>;
+//# sourceMappingURL=resumable-upload.d.ts.map

package/esm/resumable-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumable-upload.d.ts","sourceRoot":"","sources":["../src/resumable-upload.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,QAAa,CAAC;AACnD,eAAO,MAAM,4BAA4B,QAAkB,CAAC;AAC5D,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AASzD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,QAAQ,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAkID,6EAA6E;AAC7E,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAyHtC"}

package/esm/resumable-upload.js

@@ -0,0 +1,219 @@
+import { API_ERROR, INVALID_ARGUMENT } from "veryfront/errors";
+export const MIN_RESUMABLE_CHUNK_SIZE = 256 * 1024;
+export const DEFAULT_RESUMABLE_CHUNK_SIZE = 8 * 1024 * 1024;
+export const MAX_RESUMABLE_CHUNK_SIZE = 64 * 1024 * 1024;
+const MAX_CONSECUTIVE_NO_PROGRESS_RESPONSES = 3;
+function invalidByteStream(detail, cause) {
+    return INVALID_ARGUMENT.create({ detail, cause });
+}
+function protocolError(detail) {
+    return API_ERROR.create({ detail });
+}
+async function cancelReader(reader, reason) {
+    try {
+        await reader.cancel(reason);
+    }
+    catch {
+        // The failure that stopped the upload remains authoritative.
+    }
+}
+async function* readByteChunks(stream, chunkSize, signal, cancellationReason) {
+    let reader;
+    try {
+        reader = stream.getReader();
+    }
+    catch (cause) {
+        throw invalidByteStream("GCSBlobStorage: upload stream must be unlocked", cause);
+    }
+    let readerFinished = false;
+    let readerCancelled = false;
+    let pending;
+    let pendingOffset = 0;
+    const cancel = async (reason) => {
+        if (readerFinished || readerCancelled)
+            return;
+        readerCancelled = true;
+        await cancelReader(reader, reason);
+    };
+    let abortCancellation;
+    const onAbort = () => {
+        abortCancellation ??= cancel(signal?.reason);
+    };
+    if (signal?.aborted)
+        onAbort();
+    else
+        signal?.addEventListener("abort", onAbort, { once: true });
+    const loadPendingBytes = async () => {
+        while (!readerFinished && (!pending || pendingOffset === pending.byteLength)) {
+            signal?.throwIfAborted();
+            const result = await reader.read();
+            if (result.done) {
+                readerFinished = true;
+                pending = undefined;
+                pendingOffset = 0;
+                return false;
+            }
+            if (!(result.value instanceof Uint8Array)) {
+                throw invalidByteStream("GCSBlobStorage: ReadableStream chunks must be Uint8Array values");
+            }
+            if (result.value.byteLength === 0)
+                continue;
+            pending = result.value;
+            pendingOffset = 0;
+        }
+        return pending !== undefined && pendingOffset < pending.byteLength;
+    };
+    try {
+        if (!(await loadPendingBytes())) {
+            yield { bytes: new Uint8Array(), final: true };
+            return;
+        }
+        while (true) {
+            const buffer = new Uint8Array(chunkSize);
+            let length = 0;
+            while (length < chunkSize && await loadPendingBytes()) {
+                const available = pending.byteLength - pendingOffset;
+                const copied = Math.min(chunkSize - length, available);
+                buffer.set(pending.subarray(pendingOffset, pendingOffset + copied), length);
+                length += copied;
+                pendingOffset += copied;
+            }
+            const final = !(await loadPendingBytes());
+            yield {
+                bytes: length === chunkSize ? buffer : buffer.slice(0, length),
+                final,
+            };
+            if (final)
+                return;
+        }
+    }
+    catch (error) {
+        await cancel(error);
+        throw error;
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+        await abortCancellation;
+        await cancel(cancellationReason());
+        reader.releaseLock();
+    }
+}
+function acknowledgedByteCount(response) {
+    const value = response.headers.get("range");
+    if (value === null)
+        return 0;
+    const match = /^bytes=0-(0|[1-9][0-9]*)$/.exec(value);
+    if (!match) {
+        throw protocolError("GCSBlobStorage: resumable upload returned an invalid Range header");
+    }
+    const lastByte = Number(match[1]);
+    if (!Number.isSafeInteger(lastByte)) {
+        throw protocolError("GCSBlobStorage: resumable upload returned an unsafe byte range");
+    }
+    return lastByte + 1;
+}
+async function discardResponseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // A valid acknowledgement remains authoritative over body cleanup.
+    }
+}
+/** Upload an unknown-length byte stream using the GCS resumable protocol. */
+export async function uploadUnknownLengthStream(options) {
+    let acknowledged = 0;
+    let cancellationReason;
+    for await (const chunk of readByteChunks(options.stream, options.chunkSize, options.signal, () => cancellationReason)) {
+        const chunkStart = acknowledged;
+        const chunkEndExclusive = chunkStart + chunk.bytes.byteLength;
+        if (!Number.isSafeInteger(chunkEndExclusive)) {
+            const error = protocolError("GCSBlobStorage: upload stream exceeds the supported size range");
+            cancellationReason = error;
+            throw error;
+        }
+        const totalSize = chunk.final ? chunkEndExclusive : undefined;
+        let chunkOffset = 0;
+        let noProgressResponses = 0;
+        while (true) {
+            const requestStart = chunkStart + chunkOffset;
+            const requestBytes = chunk.bytes.subarray(chunkOffset);
+            const headers = new Headers({
+                "content-length": String(requestBytes.byteLength),
+                "content-type": options.contentType,
+            });
+            headers.set("content-range", requestBytes.byteLength === 0
+                ? `bytes */${totalSize}`
+                : `bytes ${requestStart}-${chunkEndExclusive - 1}/${totalSize ?? "*"}`);
+            let response;
+            try {
+                options.signal?.throwIfAborted();
+                response = await options.request(options.sessionUrl, {
+                    method: "PUT",
+                    headers,
+                    body: requestBytes,
+                });
+            }
+            catch (error) {
+                cancellationReason = error;
+                throw error;
+            }
+            if (response.status === 200 || response.status === 201) {
+                if (!chunk.final) {
+                    await discardResponseBody(response);
+                    const error = protocolError("GCSBlobStorage: resumable upload finalized before the source stream ended");
+                    cancellationReason = error;
+                    throw error;
+                }
+                return { response, size: totalSize };
+            }
+            if (response.status !== 308) {
+                const error = await options.createHttpError(response);
+                cancellationReason = error;
+                throw error;
+            }
+            let nextByte;
+            try {
+                nextByte = acknowledgedByteCount(response);
+            }
+            catch (error) {
+                cancellationReason = error;
+                throw error;
+            }
+            finally {
+                await discardResponseBody(response);
+            }
+            if (nextByte < requestStart || nextByte > chunkEndExclusive) {
+                const error = protocolError("GCSBlobStorage: resumable upload acknowledged bytes outside the request range");
+                cancellationReason = error;
+                throw error;
+            }
+            if (!chunk.final && nextByte % MIN_RESUMABLE_CHUNK_SIZE !== 0) {
+                const error = protocolError("GCSBlobStorage: resumable upload acknowledged an unaligned intermediate range");
+                cancellationReason = error;
+                throw error;
+            }
+            if (nextByte === requestStart) {
+                noProgressResponses += 1;
+                if (noProgressResponses >= MAX_CONSECUTIVE_NO_PROGRESS_RESPONSES) {
+                    const error = protocolError("GCSBlobStorage: resumable upload repeatedly made no progress");
+                    cancellationReason = error;
+                    throw error;
+                }
+                continue;
+            }
+            noProgressResponses = 0;
+            acknowledged = nextByte;
+            chunkOffset = nextByte - chunkStart;
+            if (chunkOffset === chunk.bytes.byteLength) {
+                if (chunk.final) {
+                    const error = protocolError("GCSBlobStorage: resumable upload accepted the final range without finalizing");
+                    cancellationReason = error;
+                    throw error;
+                }
+                break;
+            }
+        }
+    }
+    throw protocolError("GCSBlobStorage: upload stream ended without a final response");
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@veryfront/ext-blob-gcs",
+  "version": "0.1.1184",
+  "description": "Veryfront first-party extension package for ext-blob-gcs",
+  "keywords": [
+    "veryfront",
+    "extension",
+    "ext-blob-gcs"
+  ],
+  "author": "Veryfront",
+  "homepage": "https://github.com/veryfront/veryfront-code/tree/main/extensions/ext-blob-gcs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veryfront/veryfront-code.git",
+    "directory": "extensions/ext-blob-gcs"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/veryfront/veryfront-code/issues"
+  },
+  "module": "./esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js",
+      "types": "./esm/index.d.ts"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "veryfront": {
+    "extension": true,
+    "activation": "explicit",
+    "contracts": {
+      "provides": [
+        "BlobStorage"
+      ]
+    },
+    "capabilities": [
+      {
+        "type": "net:outbound",
+        "hosts": [
+          "oauth2.googleapis.com",
+          "storage.googleapis.com"
+        ]
+      }
+    ]
+  },
+  "dependencies": {
+    "@deno/shim-deno": "~0.18.0",
+    "@deno/shim-crypto": "~0.3.1",
+    "@deno/shim-timers": "~0.1.0"
+  },
+  "peerDependencies": {
+    "veryfront": "^0.1.1184"
+  },
+  "type": "module",
+  "types": "./esm/index.d.ts",
+  "files": [
+    "esm",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ]
+}