create-monolayer-app 0.2.2 → 0.4.0

package/template/vendor/file-bucket/multipart.ts

@@ -0,0 +1,304 @@
+import type {
+  FileMultipartUploadClient,
+  FileMultipartUploadDescriptor,
+  UploadOptions,
+} from "./types.js";
+// Parts and retries deliberately run in bounded, sequential worker loops.
+/* oxlint-disable no-await-in-loop */
+import { escapeXml, parseXml } from "./xml.js";
+
+export type {
+  FileMultipartUploadClient,
+  FileMultipartUploadDescriptor,
+  UploadOptions,
+  UploadProgress,
+} from "./types.js";
+
+function uploadError(name: string, message: string, cause?: unknown): Error {
+  return Object.assign(new Error(message, { cause }), { name });
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  // oxlint-disable-next-line promise/avoid-new
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+async function responseError(response: Response): Promise<Error> {
+  let code = "UploadFailed";
+  try {
+    const error = parseXml(await response.text());
+    code = error.findText("Code") || code;
+    if (
+      code === "AccessDenied" &&
+      /expired/iu.test(error.findText("Message") || "")
+    )
+      code = "UploadExpired";
+  } catch {
+    // HTTP status remains available when a proxy returns a non-XML error.
+  }
+  if (code === "RequestExpired" || code === "ExpiredToken")
+    code = "UploadExpired";
+  return uploadError(
+    code,
+    `S3 upload request failed (${response.status}, ${code}).`
+  );
+}
+
+/** Hydrate the wire descriptor without Node.js or AWS SDK runtime dependencies. */
+export function createMultipartUploadClient(
+  descriptor: FileMultipartUploadDescriptor
+): FileMultipartUploadClient {
+  const controller = new AbortController();
+  let state:
+    | "ready"
+    | "uploading"
+    | "completed"
+    | "aborted"
+    | "failed"
+    | "unknown" = "ready";
+  let active: Promise<void> | undefined;
+  let cleaned = false;
+  let cleaning: Promise<void> | undefined;
+
+  function checkExpiry(): void {
+    if (Date.now() >= descriptor.expiresAt) {
+      throw uploadError(
+        "UploadExpired",
+        "The multipart upload URLs have expired. Create a new handle."
+      );
+    }
+  }
+
+  async function sendPart(
+    url: string,
+    body: Blob,
+    signal: AbortSignal
+  ): Promise<string> {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      signal.throwIfAborted();
+      checkExpiry();
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: "PUT",
+          body,
+          signal: AbortSignal.any([signal, AbortSignal.timeout(120_000)]),
+        });
+      } catch (error) {
+        signal.throwIfAborted();
+        if (attempt === 2) throw error;
+        await delay(200 * 2 ** attempt, signal);
+        continue;
+      }
+      if (response.ok) {
+        const etag = response.headers.get("etag");
+        await response.arrayBuffer();
+        if (!etag)
+          throw uploadError(
+            "MissingETag",
+            "S3 did not expose the part ETag. Check the bucket CORS configuration."
+          );
+        return etag;
+      }
+      const error = await responseError(response);
+      if (attempt === 2 || (response.status !== 429 && response.status < 500))
+        throw error;
+      await delay(200 * 2 ** attempt, signal);
+    }
+    throw new Error("Part upload retry limit reached.");
+  }
+
+  async function cleanUp(): Promise<void> {
+    if (cleaned) return;
+    if (cleaning) return cleaning;
+    cleaning = (async () => {
+      const response = await fetch(descriptor.abortUrl, {
+        method: "DELETE",
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (!response.ok && response.status !== 404)
+        throw await responseError(response);
+      await response.arrayBuffer();
+      cleaned = true;
+    })();
+    try {
+      await cleaning;
+    } finally {
+      cleaning = undefined;
+    }
+  }
+
+  async function execute(
+    body: Blob | File | ArrayBuffer | Uint8Array,
+    options: UploadOptions
+  ): Promise<void> {
+    const signal = options.signal
+      ? AbortSignal.any([controller.signal, options.signal])
+      : controller.signal;
+    try {
+      signal.throwIfAborted();
+      checkExpiry();
+      const file =
+        body instanceof Blob
+          ? body
+          : new Blob([
+              body instanceof Uint8Array ? new Uint8Array(body).buffer : body,
+            ]);
+      if (file.size !== descriptor.size)
+        throw new RangeError(
+          "File size does not match the multipart upload handle."
+        );
+      let nextPart = 0;
+      let uploadedBytes = 0;
+      const etags = Array.from(
+        { length: descriptor.partUrls.length },
+        () => ""
+      );
+      const worker = async () => {
+        try {
+          while (nextPart < descriptor.partUrls.length) {
+            signal.throwIfAborted();
+            const index = nextPart;
+            nextPart += 1;
+            const start = index * descriptor.partSize;
+            const part = file.slice(
+              start,
+              Math.min(file.size, start + descriptor.partSize)
+            );
+            etags[index] = await sendPart(
+              descriptor.partUrls[index],
+              part,
+              signal
+            );
+            uploadedBytes += part.size;
+            options.onProgress?.({
+              uploadedBytes,
+              totalBytes: descriptor.size,
+            });
+          }
+        } catch (error) {
+          controller.abort(error);
+          throw error;
+        }
+      };
+      const workers = await Promise.allSettled(
+        Array.from({ length: Math.min(4, etags.length) }, worker)
+      );
+      const failure = workers.find((result) => result.status === "rejected");
+      if (failure?.status === "rejected") throw failure.reason;
+      signal.throwIfAborted();
+      checkExpiry();
+      const xml = `<CompleteMultipartUpload>${etags.map((etag, index) => `<Part><PartNumber>${index + 1}</PartNumber><ETag>${escapeXml(etag)}</ETag></Part>`).join("")}</CompleteMultipartUpload>`;
+      // Once completion is sent, a lost response cannot prove whether S3 committed.
+      let response: Response;
+      let result;
+      try {
+        response = await fetch(descriptor.completeUrl, {
+          method: "POST",
+          body: xml,
+          headers: { "Content-Type": "application/xml" },
+          signal: AbortSignal.any([signal, AbortSignal.timeout(300_000)]),
+        });
+        result = parseXml(await response.text());
+      } catch (error) {
+        state = "unknown";
+        throw uploadError(
+          "UploadCompletionUnknown",
+          "The completion result is unknown. Check the object before retrying.",
+          error
+        );
+      }
+      if (result.localName() === "Error") {
+        throw uploadError(
+          result.findText("Code") || "UploadFailed",
+          result.findText("Message") || "S3 rejected multipart completion."
+        );
+      }
+      if (
+        !response.ok ||
+        result.localName() !== "CompleteMultipartUploadResult" ||
+        !result.findText("ETag")
+      ) {
+        state = "unknown";
+        throw uploadError(
+          "UploadCompletionUnknown",
+          "S3 did not return a valid completion result. Check the object before retrying."
+        );
+      }
+      state = "completed";
+    } catch (error) {
+      controller.abort(error);
+      if (state !== "unknown") {
+        state = signal.aborted ? "aborted" : "failed";
+        try {
+          await cleanUp();
+        } catch (cleanupError) {
+          throw uploadError(
+            error instanceof Error ? error.name : "UploadFailed",
+            "Upload failed and its session could not be cleaned up.",
+            new AggregateError(
+              [error, cleanupError],
+              "Upload and cleanup failed."
+            )
+          );
+        }
+      }
+      throw error;
+    }
+  }
+
+  const isCompleted = () => state === "completed";
+  return {
+    async upload(body, options = {}) {
+      if (state !== "ready")
+        throw uploadError(
+          "InvalidUploadState",
+          "This multipart upload handle has already been used."
+        );
+      state = "uploading";
+      active = execute(body, options);
+      await active;
+    },
+    async abort() {
+      if (isCompleted()) return;
+      controller.abort(new DOMException("Upload aborted.", "AbortError"));
+      if (active) {
+        try {
+          await active;
+        } catch {
+          /* The upload caller receives the original error. */
+        }
+      }
+      if (isCompleted()) return;
+      await cleanUp();
+      state = "aborted";
+    },
+    toJSON: () => descriptor,
+  };
+}
+
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+const MAX_PARTS = 10_000;
+const MAX_PART_SIZE = 5 * 1024 * 1024 * 1024;
+
+export function multipartPartSize(size?: number): number {
+  if (size === undefined) return DEFAULT_PART_SIZE;
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new RangeError("Upload size must be a nonnegative safe integer.");
+  }
+  const partSize = Math.max(DEFAULT_PART_SIZE, Math.ceil(size / MAX_PARTS));
+  if (partSize > MAX_PART_SIZE)
+    throw new RangeError("Upload exceeds the multipart size limit.");
+  return partSize;
+}

package/template/vendor/file-bucket/protocol.ts

@@ -0,0 +1,222 @@
+// Validate JSON at the client/server boundary before using it as a protocol value.
+/* oxlint-disable anti-slop/no-runtime-typeof, anti-slop/no-unsafe-dictionary-type, anti-slop/no-unknown-parameters */
+import type {
+  FileMultipartUploadDescriptor,
+  GetUrlOptions,
+  PutOptions,
+  PutUrlOptions,
+} from "./types.js";
+
+type UploadMetadata = Pick<
+  PutOptions,
+  "contentType" | "metadata" | "cacheControl"
+>;
+export type FileBucketRequest = { bucketId: string } & (
+  | ({ operation: "put"; path: string; size: number } & UploadMetadata)
+  | { operation: "get"; path: string }
+  | ({ operation: "getUrl"; path: string } & GetUrlOptions)
+  | ({ operation: "putUrl"; path: string } & PutUrlOptions)
+  | { operation: "delete"; path: string }
+  | { operation: "deleteBatch"; paths: string[] }
+);
+export type FileBucketOperation = FileBucketRequest["operation"];
+export type UploadGrant =
+  | { type: "single"; url: string; headers: Record<string, string> }
+  | { type: "multipart"; descriptor: FileMultipartUploadDescriptor };
+export interface SignedUrl {
+  url: string;
+}
+export interface FileBucketResponses {
+  put: UploadGrant;
+  get: SignedUrl;
+  getUrl: SignedUrl;
+  putUrl: SignedUrl;
+  delete: undefined;
+  deleteBatch: undefined;
+}
+
+export interface ParseRequestOptions {
+  maxBatchKeys?: number;
+}
+
+const MAX_KEY_BYTES = 1024;
+const MAX_METADATA_ENTRIES = 50;
+const MAX_METADATA_KEY_LENGTH = 128;
+const MAX_METADATA_VALUE_LENGTH = 2048;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function textByteLength(value: string): number {
+  return new TextEncoder().encode(value).length;
+}
+
+function isKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    textByteLength(value) <= MAX_KEY_BYTES
+  );
+}
+function isText(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function isOptionalText(
+  value: unknown,
+  maxLen = 1024
+): value is string | undefined {
+  return (
+    value === undefined ||
+    (typeof value === "string" && textByteLength(value) <= maxLen)
+  );
+}
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (!isRecord(value)) return false;
+  const entries = Object.entries(value);
+  if (entries.length > MAX_METADATA_ENTRIES) return false;
+  return entries.every(
+    ([k, v]) =>
+      typeof v === "string" &&
+      k.length <= MAX_METADATA_KEY_LENGTH &&
+      v.length <= MAX_METADATA_VALUE_LENGTH
+  );
+}
+function isSize(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isMetadata(input: Record<string, unknown>): boolean {
+  return (
+    isOptionalText(input.contentType, 512) &&
+    isOptionalText(input.cacheControl, 512) &&
+    (input.metadata === undefined || isStringRecord(input.metadata))
+  );
+}
+function isSigningOptions(input: Record<string, unknown>): boolean {
+  return (
+    isMetadata(input) &&
+    isOptionalText(input.contentDisposition, 512) &&
+    (input.expiresIn === undefined ||
+      (isSize(input.expiresIn) &&
+        input.expiresIn >= 1 &&
+        input.expiresIn <= 604_800))
+  );
+}
+
+export function deepFreeze<T>(object: T): Readonly<T> {
+  if (object === null || typeof object !== "object") return object;
+  Object.freeze(object);
+  for (const key of Object.keys(object)) {
+    // SAFETY: The object has been verified as a non-null object.
+    const val = (object as Record<string, unknown>)[key];
+    if (val !== null && typeof val === "object" && !Object.isFrozen(val)) {
+      deepFreeze(val);
+    }
+  }
+  return object;
+}
+
+function isRequest(
+  input: Record<string, unknown>,
+  maxBatchKeys = 1000
+): input is Record<string, unknown> & FileBucketRequest {
+  if (!isKey(input.bucketId)) return false;
+  if (input.operation === "deleteBatch") {
+    return (
+      Array.isArray(input.paths) &&
+      input.paths.length > 0 &&
+      input.paths.length <= maxBatchKeys &&
+      input.paths.every(isKey)
+    );
+  }
+  if (!isKey(input.path)) return false;
+  switch (input.operation) {
+    case "get":
+    case "delete": {
+      return true;
+    }
+    case "getUrl":
+    case "putUrl": {
+      return isSigningOptions(input);
+    }
+    case "put": {
+      return isSize(input.size) && isMetadata(input);
+    }
+    default: {
+      return false;
+    }
+  }
+}
+
+export function parseFileBucketRequest(
+  value: unknown,
+  options?: ParseRequestOptions
+): Readonly<FileBucketRequest> {
+  if (!isRecord(value)) throw new Error("Invalid file request");
+  // Preserve the original upload protocol, which allowed operation to be omitted.
+  const input = {
+    ...value,
+    operation: value.operation === undefined ? "put" : value.operation,
+  };
+  if (!isRequest(input, options?.maxBatchKeys))
+    throw new Error("Invalid file request");
+  return deepFreeze(input);
+}
+
+function isHttpUrl(value: unknown): value is string {
+  if (!isText(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function isMultipart(value: unknown): value is FileMultipartUploadDescriptor {
+  if (!isRecord(value)) return false;
+  return (
+    value.__blocks === "file-bucket/multipart-upload" &&
+    isText(value.uploadId) &&
+    isSize(value.size) &&
+    isSize(value.partSize) &&
+    value.partSize >= 5 * 1024 * 1024 &&
+    isSize(value.expiresAt) &&
+    Array.isArray(value.partUrls) &&
+    value.partUrls.length ===
+      Math.max(1, Math.ceil(value.size / value.partSize)) &&
+    value.partUrls.length <= 10_000 &&
+    value.partUrls.every(isHttpUrl) &&
+    isHttpUrl(value.completeUrl) &&
+    isHttpUrl(value.abortUrl)
+  );
+}
+function isUploadGrant(value: unknown): value is UploadGrant {
+  if (!isRecord(value)) return false;
+  return value.type === "single"
+    ? isHttpUrl(value.url) && isStringRecord(value.headers)
+    : value.type === "multipart" && isMultipart(value.descriptor);
+}
+
+export function parseFileBucketResponse<O extends FileBucketOperation>(
+  operation: O,
+  value: unknown
+): FileBucketResponses[O] {
+  let valid: boolean;
+  switch (operation) {
+    case "delete":
+    case "deleteBatch": {
+      valid = value === undefined;
+      break;
+    }
+    case "put": {
+      valid = isUploadGrant(value);
+      break;
+    }
+    default: {
+      valid = isRecord(value) && isHttpUrl(value.url);
+    }
+  }
+  if (!valid) throw new Error("Invalid file response.");
+  // SAFETY: The operation-specific validation above verifies its corresponding response shape.
+  return value as FileBucketResponses[O];
+}