create-monolayer-app 0.2.2 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-monolayer-app",
-  "version": "0.2.2",
-  "description": "CLI to scaffold a new Monolayer application",
+  "version": "0.3.0",
+  "description": "CLI to scaffold a new monolayer application",
   "type": "module",
   "bin": {
     "create-monolayer-app": "./bin/index.js"

package/template/app/routes/files.ts

@@ -0,0 +1,63 @@
+import { FileBucket } from "../../vendor/file-bucket";
+import { parseFileBucketRequest } from "../../vendor/file-bucket/protocol";
+import {
+  dispatch,
+  MAX_BATCH_KEYS,
+  MAX_REQUEST_BYTES,
+  readLimitedJson,
+  type FileBucketRequest,
+} from "../../vendor/file-bucket/react-router";
+
+export const action = async ({
+  request,
+}: {
+  request: Request;
+}): Promise<Response> => {
+  if (request.method !== "POST") {
+    return new Response("Method not allowed", {
+      status: 405,
+      headers: { Allow: "POST" },
+    });
+  }
+
+  const contentTypeHeader = request.headers.get("content-type");
+  const mediaType = contentTypeHeader?.toLowerCase().split(";")[0]?.trim();
+  if (mediaType !== "application/json") {
+    return new Response("Unsupported Media Type", { status: 415 });
+  }
+
+  const contentLengthHeader = request.headers.get("content-length");
+  if (contentLengthHeader !== null) {
+    const declaredLength = Number(contentLengthHeader);
+    if (!Number.isNaN(declaredLength) && declaredLength > MAX_REQUEST_BYTES) {
+      return new Response("Request too large", { status: 413 });
+    }
+  }
+
+  let value: unknown;
+  try {
+    value = await readLimitedJson(request, MAX_REQUEST_BYTES);
+  } catch (error) {
+    if (error instanceof Response) return error;
+    return new Response("Invalid JSON", { status: 400 });
+  }
+
+  let input: Readonly<FileBucketRequest>;
+  try {
+    input = parseFileBucketRequest(value, { maxBatchKeys: MAX_BATCH_KEYS });
+  } catch {
+    return new Response("Invalid file request", { status: 400 });
+  }
+
+  const bucket = new FileBucket(input.bucketId);
+  const result = await dispatch(bucket, input);
+  if (result === undefined) {
+    return new Response(null, {
+      status: 204,
+      headers: { "Cache-Control": "no-store" },
+    });
+  }
+  return Response.json(result, {
+    headers: { "Cache-Control": "private, no-store" },
+  });
+};

package/template/app/routes.ts

@@ -1,3 +1,6 @@
-import { type RouteConfig, index } from "@react-router/dev/routes";
+import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
-export default [index("routes/home.tsx")] satisfies RouteConfig;
+export default [
+  index("routes/home.tsx"),
+  route("resources/files", "routes/files.ts"),
+] satisfies RouteConfig;

package/template/oxfmt.config.ts

@@ -3,5 +3,10 @@ import ultracite from "ultracite/oxfmt";
 
 export default defineConfig({
   ...ultracite,
-  ignorePatterns: [".agents/**"],
+  ignorePatterns: [
+    ".agents/**",
+    ".emulator/**",
+    "vendor/file-bucket/vite.js",
+    "vendor/file-bucket/vite.d.ts",
+  ],
 });

package/template/oxlint.config.ts

@@ -1,16 +1,12 @@
 import { defineConfig } from "oxlint";
 import antiSlop from "ultracite/oxlint/anti-slop";
 import core from "ultracite/oxlint/core";
-import { jsPluginSettings, selectJsPlugins } from "ultracite/oxlint/js-plugins";
 import react from "ultracite/oxlint/react";
 import remix from "ultracite/oxlint/remix";
 
-const jsPlugins = selectJsPlugins(["react-doctor"]);
-
 export default defineConfig({
-  extends: [core, react, remix, antiSlop, jsPlugins],
-  ignorePatterns: core.ignorePatterns,
-  jsPlugins: jsPlugins.jsPlugins,
+  extends: [core, react, remix, antiSlop],
+  ignorePatterns: [...(core.ignorePatterns ?? []), "vendor/file-bucket/**"],
   rules: {
     "react/function-component-definition": [
       "error",
@@ -28,8 +24,8 @@ export default defineConfig({
     ],
     "no-use-before-define": "off",
     "no-empty-pattern": "off",
-    "react-doctor/rendering-svg-precision": "off",
     "arrow-body-style": "off",
+    curly: "off",
   },
   overrides: [
     {
@@ -41,5 +37,4 @@ export default defineConfig({
       },
     },
   ],
-  settings: jsPluginSettings,
 });

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

@@ -0,0 +1,196 @@
+import type { FileBucket } from "./index.js";
+import { createMultipartUploadClient } from "./multipart.js";
+import { uploadSignedUrl } from "./transfers.js";
+import { request } from "./transport.js";
+import type { GetUrlOptions, PutOptions, PutUrlOptions } from "./types.js";
+
+export { createMultipartUploadClient } from "./multipart.js";
+export type { UploadGrant } from "./protocol.js";
+export type {
+  FileMultipartUploadDescriptor,
+  FileMultipartUploadClient,
+  UploadOptions,
+  UploadProgress,
+  GetUrlOptions,
+  PutOptions,
+  PutUrlOptions,
+} from "./types.js";
+export type BrowserUploadBody =
+  | Blob
+  | string
+  | Uint8Array<ArrayBuffer>
+  | ArrayBuffer;
+
+/**
+ * Delete a single object from storage via the signing resource endpoint.
+ *
+ * Deleting a missing key succeeds. Cancellation stops waiting but cannot undo
+ * server-side deletion. Endpoint failures reject the promise.
+ *
+ * @param bucket - The `FileBucket` target definition.
+ * @param path - Key of the object to delete.
+ * @param options - Optional settings including an `AbortSignal`.
+ * @returns A promise that resolves when the deletion is completed by the server.
+ */
+function deleteFile(
+  bucket: FileBucket,
+  path: string,
+  options: { signal?: AbortSignal } = {}
+): Promise<void> {
+  return request(
+    { operation: "delete", bucketId: bucket.name, path },
+    options.signal
+  );
+}
+
+/**
+ * Delete multiple objects from storage in batch via the signing resource endpoint.
+ *
+ * An empty list sends no request unless cancellation has already been requested,
+ * in which case the promise rejects. Batches are not atomic: some keys may be
+ * deleted before an error. Cancellation cannot undo completed deletions.
+ *
+ * @param bucket - The `FileBucket` target definition.
+ * @param paths - Array of object keys to delete.
+ * @param options - Optional settings including an `AbortSignal`.
+ * @returns A promise that resolves when batch deletion is completed by the server.
+ */
+export async function deleteBatch(
+  bucket: FileBucket,
+  paths: string[],
+  options: { signal?: AbortSignal } = {}
+): Promise<void> {
+  options.signal?.throwIfAborted();
+  if (!paths.length) return;
+  await request(
+    { operation: "deleteBatch", bucketId: bucket.name, paths },
+    options.signal
+  );
+}
+
+/**
+ * Request a presigned GET URL for an object from the server without initiating a download.
+ *
+ * Signing does not check object existence. Content disposition is unchanged by
+ * default; URL lifetime defaults to 3600 seconds. Cancellation applies to signing.
+ *
+ * @param bucket - The `FileBucket` target definition.
+ * @param path - Key of the object to access.
+ * @param options - Optional URL configuration such as `expiresIn`, `contentDisposition`, and `signal`.
+ * @returns A promise resolving to the presigned GET URL string.
+ */
+export async function getUrl(
+  bucket: FileBucket,
+  path: string,
+  options: GetUrlOptions & { signal?: AbortSignal } = {}
+): Promise<string> {
+  const { signal, ...signingOptions } = options;
+  const result = await request(
+    { ...signingOptions, operation: "getUrl", bucketId: bucket.name, path },
+    signal
+  );
+  return result.url;
+}
+
+/**
+ * Request a presigned single-PUT upload URL from the server without sending file bytes.
+ *
+ * Send the raw body with the same content-type and cache-control headers used
+ * when signing. Metadata is carried in the signed query. No multipart session
+ * is created. URL lifetime defaults to 3600 seconds; cancellation applies to signing.
+ *
+ * @param bucket - The `FileBucket` target definition.
+ * @param path - Target key for the uploaded object.
+ * @param options - Optional URL configuration such as `expiresIn`, `contentType`, `metadata`, `cacheControl`, and `signal`.
+ * @returns A promise resolving to the presigned PUT URL string.
+ */
+export async function putUrl(
+  bucket: FileBucket,
+  path: string,
+  options: PutUrlOptions & { signal?: AbortSignal } = {}
+): Promise<string> {
+  const { signal, ...signingOptions } = options;
+  const result = await request(
+    { ...signingOptions, operation: "putUrl", bucketId: bucket.name, path },
+    signal
+  );
+  return result.url;
+}
+
+/**
+ * Request an attachment download URL from the server and trigger native browser download navigation.
+ *
+ * Resolves as soon as the browser initiates the download link; does not buffer file bytes in memory.
+ * It cannot confirm saving or report subsequent storage errors. Cancellation
+ * applies before handoff and cannot stop the native download afterward.
+ *
+ * @param bucket - The `FileBucket` target definition.
+ * @param path - Key of the object to download.
+ * @param options - Optional settings including an `AbortSignal`.
+ * @returns A promise that resolves once the download has been triggered in the browser.
+ */
+export async function get(
+  bucket: FileBucket,
+  path: string,
+  options: { signal?: AbortSignal } = {}
+): Promise<void> {
+  const grant = await request(
+    { operation: "get", bucketId: bucket.name, path },
+    options.signal
+  );
+  const link = document.createElement("a");
+  link.href = grant.url;
+  link.download = "";
+  link.hidden = true;
+  document.body.append(link);
+  try {
+    link.click();
+  } finally {
+    link.remove();
+  }
+}
+
+/**
+ * Upload a file or data directly to S3 from the browser using a server-issued grant.
+ *
+ * Uses `/resources/files` for signing, then sends bytes directly to storage.
+ * The standard resource action selects a single PUT below 8 MiB and multipart
+ * at or above 8 MiB. Reusing a key overwrites its object.
+ *
+ * Single PUT reports progress after completion; multipart reports completed part
+ * bytes and attempts cleanup on cancellation or failure. A Blob's content type
+ * is used unless overridden. Endpoint or storage failures reject the promise.
+ *
+ * @param bucket - The `FileBucket` target definition.
+ * @param path - Key of the destination object.
+ * @param body - The payload to upload (`Blob`, `File`, `string`, `Uint8Array`, or `ArrayBuffer`).
+ * @param options - Optional upload settings including `contentType`, `metadata`, `cacheControl`, `onProgress`, and `signal`.
+ * @returns A promise that resolves when the upload is confirmed complete.
+ */
+export async function put(
+  bucket: FileBucket,
+  path: string,
+  body: BrowserUploadBody,
+  options: PutOptions = {}
+): Promise<void> {
+  options.signal?.throwIfAborted();
+  const file = body instanceof Blob ? body : new Blob([body]);
+  const grant = await request(
+    {
+      operation: "put",
+      bucketId: bucket.name,
+      path,
+      size: file.size,
+      contentType: options.contentType ?? (file.type || undefined),
+      metadata: options.metadata,
+      cacheControl: options.cacheControl,
+    },
+    options.signal
+  );
+  if (grant.type === "multipart") {
+    await createMultipartUploadClient(grant.descriptor).upload(file, options);
+    return;
+  }
+  await uploadSignedUrl(grant.url, file, grant.headers, options);
+}
+export { deleteFile as delete };

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

@@ -0,0 +1,26 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Modified
+
+/**
+ * Error names returned by FileBucket actions.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await put(bucket, 'report.txt', body);
+ * } catch (e: unknown) {
+ *   if (e instanceof Error && e.name === FileBucketErrors.FileTooLarge) {
+ *     // handle an oversized file
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const FileBucketErrors = {
+  FileNotFound: "NoSuchKey",
+  FileTooLarge: "EntityTooLarge",
+  UploadExpired: "UploadExpired",
+  UploadCompletionUnknown: "UploadCompletionUnknown",
+  InvalidUploadState: "InvalidUploadState",
+} as const;

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

@@ -0,0 +1,7 @@
+/** Shared file bucket definition. Safe to import on the server and in the browser. */
+export class FileBucket {
+  readonly name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}

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;
+}