create-monolayer-app 0.2.2 → 0.3.0

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

@@ -0,0 +1,544 @@
+import { createHash } from "node:crypto";
+import { Readable, addAbortSignal } from "node:stream";
+
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  ListObjectsV2Command,
+  CreateMultipartUploadCommand,
+  UploadPartCommand,
+  CompleteMultipartUploadCommand,
+  AbortMultipartUploadCommand,
+} from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+import type { FileBucket } from "./index.js";
+import { createMultipartUploadClient, multipartPartSize } from "./multipart.js";
+import { uploadSignedUrl } from "./transfers.js";
+import type {
+  FileUploadBody,
+  MultipartUploadOptions,
+  FileMultipartUploadClient,
+  PutOptions,
+  GetUrlOptions,
+  PutUrlOptions,
+  ScanOptions,
+  FileContent,
+  FileInfo,
+  FileDownloadClient,
+  FileUploadClient,
+} from "./types.js";
+
+// Re-export public types
+export { FileBucketErrors } from "./errors.js";
+export type {
+  FileUploadBody,
+  MultipartUploadOptions,
+  FileMultipartUploadClient,
+  FileMultipartUploadDescriptor,
+  UploadOptions,
+  UploadProgress,
+  PutOptions,
+  GetUrlOptions,
+  PutUrlOptions,
+  ScanOptions,
+  FileContent,
+  FileInfo,
+  FileDownloadClient,
+  FileUploadClient,
+  FileDownloadDescriptor,
+  FileUploadDescriptor,
+} from "./types.js";
+
+function uploadBodySize(body: FileUploadBody): number | undefined {
+  // The public body union includes strings, byte arrays, blobs, and streams.
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof
+  if (typeof body === "string") return Buffer.byteLength(body);
+  if (body instanceof Uint8Array) return body.byteLength;
+  if (body instanceof Blob) return body.size;
+  return undefined;
+}
+
+function cancellableBody(
+  body: FileUploadBody,
+  signal?: AbortSignal
+): FileUploadBody {
+  if (!signal) return body;
+  if (body instanceof Readable) return addAbortSignal(signal, body);
+  if (body instanceof ReadableStream) {
+    return body.pipeThrough(new TransformStream<Uint8Array, Uint8Array>(), {
+      signal,
+    });
+  }
+  return body;
+}
+
+async function abortFailedUpload(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  uploadId: string
+): Promise<void> {
+  try {
+    await client.send(
+      new AbortMultipartUploadCommand({
+        Bucket: bucket,
+        Key: key,
+        UploadId: uploadId,
+      })
+    );
+  } catch (error) {
+    if (!(error instanceof Error && error.name === "NoSuchUpload")) throw error;
+  }
+}
+
+const clients = new WeakMap<FileBucket, S3Client>();
+function getClient(bucket: FileBucket): S3Client {
+  const client =
+    clients.get(bucket) ??
+    new S3Client(
+      process.env.NODE_ENV === "production"
+        ? { requestChecksumCalculation: "WHEN_REQUIRED" }
+        : {
+            requestChecksumCalculation: "WHEN_REQUIRED",
+            endpoint:
+              process.env.S3_EMULATOR_ENDPOINT || "http://127.0.0.1:4566",
+            region: "us-east-1",
+            forcePathStyle: true,
+            credentials: {
+              accessKeyId: "test",
+              secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || "test",
+            },
+          }
+    );
+  clients.set(bucket, client);
+  return client;
+}
+/**
+ * Upload an object from the server, managing multipart transfers automatically.
+ *
+ * Reusing a key overwrites its object. Cancellation or failure attempts multipart
+ * cleanup. Progress reports transferred bytes; total size can be unknown for streams.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Destination object key.
+ * @param body - String, byte array, Blob, Node stream, or Web stream to upload.
+ * @param options - Object metadata, content headers, cancellation, and progress callback.
+ * @returns A promise that resolves after S3 confirms completion.
+ */
+export async function put(
+  bucket: FileBucket,
+  path: string,
+  body: FileUploadBody,
+  options?: PutOptions
+): Promise<void> {
+  const bucketName = resolveBucketName(bucket);
+  options?.signal?.throwIfAborted();
+  const client = getClient(bucket);
+  const size = uploadBodySize(body);
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  const upload = new Upload({
+    client,
+    params: {
+      Bucket: bucketName,
+      Key: path,
+      Body: cancellableBody(body, options?.signal),
+      ContentType: options?.contentType,
+      Metadata: options?.metadata,
+      CacheControl: options?.cacheControl,
+    },
+    partSize: multipartPartSize(size),
+    queueSize: 4,
+    leavePartsOnError: false,
+    abortController: controller,
+  });
+  options?.signal?.addEventListener("abort", abort, { once: true });
+  if (options?.onProgress) {
+    upload.on("httpUploadProgress", (progress) => {
+      options.onProgress?.({
+        uploadedBytes: progress.loaded ?? 0,
+        totalBytes: progress.total,
+      });
+    });
+  }
+  try {
+    await upload.done();
+  } catch (error) {
+    // lib-storage cleans up failed parts; also cover completion failures.
+    if (upload.uploadId) {
+      try {
+        await abortFailedUpload(client, bucketName, path, upload.uploadId);
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          "Upload failed and its multipart session could not be cleaned up.",
+          { cause: cleanupError }
+        );
+      }
+    }
+    throw error;
+  } finally {
+    options?.signal?.removeEventListener("abort", abort);
+  }
+}
+
+/**
+ * Read an entire object into memory on the server.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Object key to read.
+ * @returns Buffered content and metadata, or `null` for a missing key. Other S3 errors reject the promise.
+ */
+export async function get(
+  bucket: FileBucket,
+  path: string
+): Promise<FileContent | null> {
+  const bucketName = resolveBucketName(bucket);
+  const client = getClient(bucket);
+  try {
+    const result = await client.send(
+      new GetObjectCommand({
+        Bucket: bucketName,
+        Key: path,
+      })
+    );
+    if (!result.Body) throw new Error("S3 returned an empty response body");
+    const bytes = await result.Body.transformToByteArray();
+    return {
+      body: Buffer.from(bytes),
+      contentType: result.ContentType ?? "application/octet-stream",
+      metadata: result.Metadata ?? {},
+      size: result.ContentLength ?? bytes.length,
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "NoSuchKey") return null;
+    throw error;
+  }
+}
+
+/**
+ * Delete an object through S3. Deleting a missing key succeeds.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Object key to delete.
+ * @returns A promise that resolves after S3 confirms deletion.
+ */
+async function deleteFile(bucket: FileBucket, path: string): Promise<void> {
+  const bucketName = resolveBucketName(bucket);
+  const client = getClient(bucket);
+  await client.send(
+    new DeleteObjectCommand({
+      Bucket: bucketName,
+      Key: path,
+    })
+  );
+}
+
+/**
+ * Delete objects in sequential batches of up to 1,000 keys.
+ *
+ * An empty list sends no S3 request. Deletion is not atomic: a rejected batch may
+ * already have deleted some objects, and later batches are not attempted.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param paths - Object keys to delete.
+ * @returns A promise that resolves after all batches complete.
+ * @throws {AggregateError} If S3 reports per-object deletion errors.
+ */
+export async function deleteBatch(
+  bucket: FileBucket,
+  paths: string[]
+): Promise<void> {
+  if (paths.length === 0) return;
+  const bucketName = resolveBucketName(bucket);
+  const client = getClient(bucket);
+  const CHUNK_SIZE = 1000;
+  for (let i = 0; i < paths.length; i += CHUNK_SIZE) {
+    const chunk = paths.slice(i, i + CHUNK_SIZE);
+    // oxlint-disable-next-line no-await-in-loop
+    const result = await client.send(
+      new DeleteObjectsCommand({
+        Bucket: bucketName,
+        Delete: { Objects: chunk.map((Key) => ({ Key })), Quiet: true },
+      })
+    );
+    if (result.Errors?.length) {
+      throw new AggregateError(
+        result.Errors.map(
+          (error) =>
+            new Error(
+              `Failed to delete ${error.Key}: ${error.Code} ${error.Message ?? ""}`
+            )
+        ),
+        "Some files could not be deleted."
+      );
+    }
+  }
+}
+
+/**
+ * Sign a GET URL on the server without reading the object or checking that it exists.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Object key to access.
+ * @param options - URL lifetime in seconds (default 3600) and optional response content disposition.
+ * @returns A signed URL; requesting it performs the download.
+ */
+export function getUrl(
+  bucket: FileBucket,
+  path: string,
+  options?: GetUrlOptions
+): Promise<string> {
+  const bucketName = resolveBucketName(bucket);
+  return getSignedUrl(
+    getClient(bucket),
+    new GetObjectCommand({
+      Bucket: bucketName,
+      Key: path,
+      ResponseContentDisposition: options?.contentDisposition,
+    }),
+    {
+      expiresIn: options?.expiresIn ?? 3600,
+    }
+  );
+}
+
+/**
+ * Sign a URL for one PUT without uploading bytes or creating a multipart session.
+ *
+ * Send the raw body with the content-type and cache-control headers used when
+ * signing. Metadata is carried in the signed query. Uploading replaces an existing key.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Destination object key.
+ * @param options - Object metadata, content headers, and URL lifetime in seconds (default 3600).
+ * @returns A signed URL for a single PUT.
+ */
+export function putUrl(
+  bucket: FileBucket,
+  path: string,
+  options?: PutUrlOptions
+): Promise<string> {
+  const bucketName = resolveBucketName(bucket);
+  return getSignedUrl(
+    getClient(bucket),
+    new PutObjectCommand({
+      Bucket: bucketName,
+      Key: path,
+      ContentType: options?.contentType,
+      Metadata: options?.metadata,
+      CacheControl: options?.cacheControl,
+    }),
+    { expiresIn: options?.expiresIn ?? 3600 }
+  );
+}
+
+/**
+ * Create an S3 multipart session and sign its part, completion, and abort URLs.
+ *
+ * The returned handle uploads once, supports cancellation and progress, and can
+ * abort an unused session. Serialize with `toJSON()` and hydrate in the browser
+ * with `createMultipartUploadClient`. Creation sends no file bytes.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Destination object key.
+ * @param options - Expected byte size, object metadata, content headers, and URL lifetime (default 3600 seconds).
+ * @returns A multipart handle tied to the newly created session.
+ * @throws {RangeError} For an unsupported size or URL lifetime.
+ */
+export async function createMultipartUploadHandle(
+  bucket: FileBucket,
+  path: string,
+  options: MultipartUploadOptions
+): Promise<FileMultipartUploadClient> {
+  const bucketName = resolveBucketName(bucket);
+  const partSize = multipartPartSize(options.size);
+  const expiresIn = options.expiresIn ?? 3600;
+  if (!Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > 604_800) {
+    throw new RangeError("URL lifetime must be between 1 and 604800 seconds.");
+  }
+  const client = getClient(bucket);
+  const target = { Bucket: bucketName, Key: path };
+  const { UploadId } = await client.send(
+    new CreateMultipartUploadCommand({
+      ...target,
+      ContentType: options.contentType,
+      Metadata: options.metadata,
+      CacheControl: options.cacheControl,
+    })
+  );
+  if (!UploadId) throw new Error("S3 did not return an upload ID.");
+  const session = { ...target, UploadId };
+  // SigV4 timestamps have one-second precision; expire conservatively.
+  const expiresAt = Math.floor(Date.now() / 1000) * 1000 + expiresIn * 1000;
+  try {
+    const partUrls: string[] = [];
+    const count = Math.max(1, Math.ceil(options.size / partSize));
+    for (let partNumber = 1; partNumber <= count; partNumber += 1) {
+      partUrls.push(
+        // oxlint-disable-next-line no-await-in-loop
+        await getSignedUrl(
+          client,
+          new UploadPartCommand({
+            ...session,
+            PartNumber: partNumber,
+          }),
+          { expiresIn }
+        )
+      );
+    }
+    const completeUrl = await getSignedUrl(
+      client,
+      new CompleteMultipartUploadCommand({
+        ...session,
+        MultipartUpload: { Parts: [] },
+      }),
+      { expiresIn, unsignableHeaders: new Set(["content-length"]) }
+    );
+    const abortUrl = await getSignedUrl(
+      client,
+      new AbortMultipartUploadCommand(session),
+      { expiresIn }
+    );
+    return createMultipartUploadClient({
+      __blocks: "file-bucket/multipart-upload",
+      uploadId: UploadId,
+      size: options.size,
+      partSize,
+      expiresAt,
+      partUrls,
+      completeUrl,
+      abortUrl,
+    });
+  } catch (error) {
+    try {
+      await client.send(new AbortMultipartUploadCommand(session));
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        "Failed to create and clean up multipart upload.",
+        { cause: cleanupError }
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Create a signed download handle on the server without fetching the object.
+ *
+ * Its `download()` method buffers the response as a Blob and rejects HTTP errors;
+ * it does not trigger a native browser download. `toJSON()` returns descriptor
+ * data without methods. The signed URL is not refreshed automatically.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Object key to access.
+ * @param options - URL lifetime in seconds (default 3600) and response content disposition.
+ * @returns A handle with `download()`, `getUrl()`, and `toJSON()`.
+ */
+export async function getFileHandle(
+  bucket: FileBucket,
+  path: string,
+  options?: GetUrlOptions
+): Promise<FileDownloadClient> {
+  const url = await getUrl(bucket, path, options);
+  return {
+    download: async () => {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+      return res.blob();
+    },
+    getUrl: () => url,
+    toJSON: () => ({ __blocks: "file-bucket/download" as const, url }),
+  };
+}
+
+/**
+ * Create a signed single-PUT handle on the server without uploading bytes.
+ *
+ * Call `upload(body, { signal, onProgress })` with a Blob, File, or ArrayBuffer.
+ * The handle supplies signed content headers, omits browser credentials, rejects
+ * HTTP errors, and reports progress after completion. `toJSON()` returns data
+ * without methods. The signed URL is not refreshed automatically.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param path - Destination object key; uploading replaces any existing object.
+ * @param options - Object metadata, content headers, and URL lifetime in seconds (default 3600).
+ * @returns A handle with `upload()`, `getUrl()`, and `toJSON()`.
+ */
+export async function createUploadHandle(
+  bucket: FileBucket,
+  path: string,
+  options?: PutUrlOptions
+): Promise<FileUploadClient> {
+  const url = await putUrl(bucket, path, options);
+  const contentType = options?.contentType;
+  const cacheControl = options?.cacheControl;
+  return {
+    upload: async (body, uploadOptions) => {
+      const headers: Record<string, string> = {};
+      if (contentType) headers["Content-Type"] = contentType;
+      if (cacheControl) headers["Cache-Control"] = cacheControl;
+      await uploadSignedUrl(url, body, headers, uploadOptions);
+    },
+    getUrl: () => url,
+    toJSON: () => ({
+      __blocks: "file-bucket/upload" as const,
+      url,
+      contentType,
+      cacheControl,
+    }),
+  };
+}
+
+/**
+ * Iterate object metadata on the server, fetching S3 pages as needed.
+ *
+ * The physical bucket is resolved when iteration starts. File bodies are not read.
+ *
+ * @param bucket - Shared definition whose ID is resolved to the configured physical bucket.
+ * @param options - Optional object-key prefix filter.
+ * @returns An async iterable of object keys, sizes, and modification dates.
+ * @yields {FileInfo} Metadata for each matching object.
+ */
+export async function* scan(
+  bucket: FileBucket,
+  options?: ScanOptions
+): AsyncIterable<FileInfo> {
+  const bucketName = resolveBucketName(bucket);
+  const client = getClient(bucket);
+  let continuationToken: string | undefined;
+  do {
+    // oxlint-disable-next-line no-await-in-loop
+    const result = await client.send(
+      new ListObjectsV2Command({
+        Bucket: bucketName,
+        Prefix: options?.prefix,
+        ContinuationToken: continuationToken,
+      })
+    );
+    for (const obj of result.Contents ?? []) {
+      if (obj.Key === undefined) continue;
+      yield {
+        path: obj.Key,
+        size: obj.Size ?? 0,
+        lastModified: obj.LastModified ?? new Date(),
+      };
+    }
+    continuationToken = result.NextContinuationToken;
+  } while (continuationToken);
+}
+export { deleteFile as delete };
+
+function resolveBucketName(bucket: FileBucket): string {
+  const hash = createHash("sha256")
+    .update(bucket.name)
+    .digest("hex")
+    .slice(0, 8);
+  return process.env[`FILE_BUCKET_${hash}`] || bucket.name;
+}

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

@@ -0,0 +1,23 @@
+import type { UploadOptions } from "./types.js";
+
+/** Execute a signed PUT without forwarding application credentials. */
+export async function uploadSignedUrl(
+  url: string,
+  body: Blob | ArrayBuffer | Uint8Array,
+  headers: Record<string, string>,
+  options: UploadOptions = {}
+): Promise<void> {
+  options.signal?.throwIfAborted();
+  const requestBody: BodyInit =
+    body instanceof Uint8Array ? new Uint8Array(body).buffer : body;
+  const response = await fetch(url, {
+    method: "PUT",
+    credentials: "omit",
+    headers,
+    body: requestBody,
+    signal: options.signal,
+  });
+  if (!response.ok) throw new Error(`Upload failed (${response.status}).`);
+  const size = body instanceof Blob ? body.size : body.byteLength;
+  options.onProgress?.({ uploadedBytes: size, totalBytes: size });
+}

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

@@ -0,0 +1,37 @@
+import type {
+  FileBucketOperation,
+  FileBucketRequest,
+  FileBucketResponses,
+} from "./protocol.js";
+import { parseFileBucketResponse } from "./protocol.js";
+
+const FAILURE_LABELS: Record<FileBucketOperation, string> = {
+  put: "Upload signing",
+  get: "Download signing",
+  getUrl: "URL signing",
+  putUrl: "URL signing",
+  delete: "Deletion",
+  deleteBatch: "Deletion",
+};
+
+export async function request<O extends FileBucketOperation>(
+  payload: Extract<FileBucketRequest, { operation: O }>,
+  signal?: AbortSignal
+): Promise<FileBucketResponses[O]> {
+  signal?.throwIfAborted();
+  const response = await fetch("/resources/files", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+    signal,
+  });
+  if (!response.ok)
+    throw new Error(
+      `${FAILURE_LABELS[payload.operation]} failed (${response.status}).`
+    );
+  const value: unknown =
+    response.status === 204 ? undefined : await response.json();
+  signal?.throwIfAborted();
+  return parseFileBucketResponse(payload.operation, value);
+}