create-monolayer-app 0.2.2 → 0.3.0

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

package/template/vendor/file-bucket/react-router.ts

@@ -0,0 +1,222 @@
+/* oxlint-disable no-await-in-loop, anti-slop/no-unknown-returns, anti-slop/no-runtime-typeof */
+import { FileBucket } from "./index.js";
+import { parseFileBucketRequest } from "./protocol.js";
+import type {
+  FileBucketRequest,
+  FileBucketResponses,
+  UploadGrant,
+} from "./protocol.js";
+import {
+  getUrl,
+  putUrl,
+  delete as deleteFile,
+  deleteBatch,
+  createMultipartUploadHandle,
+} from "./server.js";
+
+const MULTIPART_THRESHOLD = 8 * 1024 * 1024;
+export const MAX_REQUEST_BYTES = 64 * 1024;
+export const MAX_BATCH_KEYS = 1000;
+
+export type {
+  FileBucketRequest,
+  FileBucketOperation,
+  UploadGrant,
+  SignedUrl,
+  FileBucketResponses,
+} from "./protocol.js";
+
+export async function readLimitedJson(
+  request: Request,
+  maxBytes: number,
+): Promise<unknown> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new RangeError("maxBytes must be a positive safe integer.");
+  }
+  const reader = request.body?.getReader();
+  if (!reader) throw new Response("Invalid JSON", { status: 400 });
+
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {
+          // Preserve 413 if canceling fails
+        }
+        throw new Response("Request too large", { status: 413 });
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new Response("Invalid JSON", { status: 400 });
+  }
+}
+
+async function uploadGrant(
+  bucket: FileBucket,
+  input: Extract<FileBucketRequest, { operation: "put" }>,
+): Promise<UploadGrant> {
+  const options = {
+    contentType: input.contentType,
+    cacheControl: input.cacheControl,
+    metadata: input.metadata,
+  };
+  if (input.size >= MULTIPART_THRESHOLD) {
+    const handle = await createMultipartUploadHandle(bucket, input.path, {
+      ...options,
+      size: input.size,
+    });
+    return { type: "multipart", descriptor: handle.toJSON() };
+  }
+  const url = await putUrl(bucket, input.path, options);
+  const headers: Record<string, string> = {};
+  if (options.contentType) headers["Content-Type"] = options.contentType;
+  if (options.cacheControl) headers["Cache-Control"] = options.cacheControl;
+  return { type: "single", url, headers };
+}
+
+export async function dispatch(
+  bucket: FileBucket,
+  input: FileBucketRequest,
+): Promise<FileBucketResponses[FileBucketRequest["operation"]]> {
+  switch (input.operation) {
+    case "delete": {
+      await deleteFile(bucket, input.path);
+      return undefined;
+    }
+    case "deleteBatch": {
+      await deleteBatch(bucket, input.paths);
+      return undefined;
+    }
+    case "get": {
+      return {
+        url: await getUrl(bucket, input.path, {
+          contentDisposition: "attachment",
+        }),
+      };
+    }
+    case "getUrl": {
+      return {
+        url: await getUrl(bucket, input.path, {
+          expiresIn: input.expiresIn,
+          contentDisposition: input.contentDisposition,
+        }),
+      };
+    }
+    case "putUrl": {
+      return {
+        url: await putUrl(bucket, input.path, {
+          expiresIn: input.expiresIn,
+          contentType: input.contentType,
+          metadata: input.metadata,
+          cacheControl: input.cacheControl,
+        }),
+      };
+    }
+    case "put": {
+      return uploadGrant(bucket, input);
+    }
+    default: {
+      throw new Error("Unsupported file operation");
+    }
+  }
+}
+
+/**
+ * Creates a React Router server action for handling browser FileBucket operations.
+ *
+ * Register the returned action at `/resources/files`. It handles JSON POST requests for:
+ * - Direct upload signing (`put`)
+ * - Attachment download signing (`get`)
+ * - Presigned URL generation (`getUrl`, `putUrl`)
+ * - Server-side deletion (`delete`, `deleteBatch`)
+ *
+ * Resolves the `FileBucket` instance directly from the request's bucket ID.
+ * Limits request bodies to 64 KiB and batch deletions to 1,000 keys.
+ *
+ * Returns JSON for signing, an empty 204 response for successful deletion,
+ * 400 for malformed requests, 405 for methods other than POST, 413 for oversized requests,
+ * and 415 for non-JSON content types.
+ * Storage failures propagate to React Router. Route registration is the caller's responsibility.
+ *
+ * @returns A React Router action function `({ request }: { request: Request }) => Promise<Response>`.
+ *
+ * @example
+ * ```ts
+ * // app/routes/files.ts
+ * import { createFileBucketAction } from "@monolayer/file-bucket/react-router";
+ *
+ * export const action = createFileBucketAction();
+ * ```
+ */
+export function createFileBucketAction(): (args: {
+  request: Request;
+}) => Promise<Response> {
+  return 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" },
+    });
+  };
+}