@minhvuong/pirate-storage-server 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @minhvuong/pirate-storage-server
+
+Fetch-standard route builder and authenticated upload handler for `@minhvuong/pirate-storage`.
+
+The handler supports direct streamed uploads and resumable multipart sessions. Multipart parts are
+normal authenticated requests to the consumer's server or Worker; provider secrets are never sent
+to the browser.
+
+Applications provide the journal implementation and persist completed receipts in
+`onUploadComplete` using any database or ORM.
+
+The journal stores temporary coordination metadata (file identity, provider session state,
+completed part locators/hashes, status, and expiry), never file bytes. During cancellation the
+handler marks the session aborted, waits for in-flight uploads, deletes late provider parts, and
+only then removes the journal record.
+
+Concurrent requests for the same session part share one provider operation. This prevents a quick
+pause/resume from creating duplicate Discord attachment messages while the first request is still
+finishing server-side.

package/dist/handler.d.ts

@@ -0,0 +1,15 @@
+import { Storage, type UploadJournal } from "@minhvuong/pirate-storage";
+import type { FileRouter } from "./router";
+export interface FetchHandlerOptions<Router extends FileRouter> {
+    storage: Storage<any>;
+    router: Router;
+    journal: UploadJournal;
+    basePath?: string;
+    sessionTtlMs?: number;
+    corsOrigin?: string | ((request: Request) => string | undefined);
+}
+export interface StorageFetchHandler {
+    (request: Request): Promise<Response>;
+    fetch(request: Request): Promise<Response>;
+}
+export declare function createFetchHandler<const Router extends FileRouter>(options: FetchHandlerOptions<Router>): StorageFetchHandler;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./handler";
+export * from "./router";

package/dist/index.js

@@ -0,0 +1,485 @@
+// src/handler.ts
+import {
+  StorageError
+} from "@minhvuong/pirate-storage";
+function createFetchHandler(options) {
+  const basePath = normalizeBasePath(options.basePath ?? "/api/storage");
+  const sessionTtlMs = options.sessionTtlMs ?? 24 * 60 * 60 * 1000;
+  const inFlightParts = new Map;
+  const inFlightPartRequests = new Map;
+  const handle = async (request) => {
+    try {
+      if (request.method === "OPTIONS")
+        return withCors(new Response(null, { status: 204 }), request, options);
+      const url = new URL(request.url);
+      if (!url.pathname.startsWith(`${basePath}/`))
+        return json({ error: "Not found" }, 404);
+      const segments = url.pathname.slice(basePath.length + 1).split("/").map(decodeURIComponent);
+      const routeName = segments[0];
+      const route = routeName ? options.router[routeName] : undefined;
+      if (!route || !routeName)
+        return json({ error: "Storage route not found" }, 404);
+      let response;
+      if (segments.length === 1 && request.method === "POST") {
+        response = await directUpload(request, routeName, route, options.storage);
+      } else if (segments[1] === "multipart" && segments.length === 2 && request.method === "POST") {
+        response = await beginMultipart(request, routeName, route, options, sessionTtlMs);
+      } else if (segments[1] === "multipart" && segments[2] && segments[3] && segments.length === 4 && request.method === "PUT") {
+        response = await uploadMultipartPart(request, routeName, route, segments[2], segments[3], options, inFlightParts, inFlightPartRequests);
+      } else if (segments[1] === "multipart" && segments[2] && segments[3] === "complete" && request.method === "POST") {
+        response = await completeMultipart(request, routeName, route, segments[2], options);
+      } else if (segments[1] === "multipart" && segments[2] && segments.length === 3 && request.method === "GET") {
+        response = await inspectMultipart(request, routeName, route, segments[2], options);
+      } else if (segments[1] === "multipart" && segments[2] && segments.length === 3 && request.method === "DELETE") {
+        response = await abortMultipart(request, routeName, route, segments[2], options, inFlightParts);
+      } else {
+        response = json({ error: "Method not allowed" }, 405);
+      }
+      return withCors(response, request, options);
+    } catch (error) {
+      const status = error instanceof StorageError ? error.status ?? 500 : 500;
+      return withCors(json({
+        error: error instanceof Error ? error.message : "Unknown storage server error",
+        code: error instanceof StorageError ? error.code : "INTERNAL_ERROR"
+      }, status), request, options);
+    }
+  };
+  const handler = handle;
+  handler.fetch = handle;
+  return handler;
+}
+async function directUpload(request, routeName, route, storage) {
+  if (!request.body)
+    throw new StorageError("INVALID_INPUT", "A binary request body is required", { status: 400 });
+  const name = decodedHeader(request, "x-storage-file-name");
+  const size = positiveHeader(request, "x-storage-file-size");
+  const input = await parseRouteInput(request, route);
+  const metadata = await route.authorize({ request, input, route: routeName });
+  validateRouteFile(route, name, request.headers.get("content-type") ?? "application/octet-stream", size);
+  try {
+    const receipt = await storage.upload({
+      name,
+      size,
+      contentType: request.headers.get("content-type") ?? "application/octet-stream",
+      body: request.body
+    }, {
+      provider: route.config.provider,
+      metadata: asMetadata(metadata),
+      signal: request.signal
+    });
+    const serverData = await route.onComplete?.({
+      request,
+      input,
+      metadata,
+      receipt,
+      route: routeName
+    });
+    return json({ receipt, serverData }, 201);
+  } catch (error) {
+    await route.onError?.({ request, route: routeName, error });
+    throw error;
+  }
+}
+async function beginMultipart(request, routeName, route, options, sessionTtlMs) {
+  const body = await request.json();
+  const file = parseFileDescriptor(body.file);
+  const fileSha256 = parseSha256(body.file?.sha256, "file.sha256");
+  validateRouteFile(route, file.name, file.contentType, file.size);
+  const input = await route.parseInput(body.input);
+  const metadata = await route.authorize({ request, input, route: routeName });
+  const provider = getMultipartProvider(options.storage, route.config.provider);
+  const providerSession = await provider.beginMultipart(file, {
+    signal: request.signal,
+    metadata: asMetadata(metadata)
+  });
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  const session = {
+    id,
+    provider: route.config.provider,
+    route: routeName,
+    file: { ...file, sha256: fileSha256 },
+    providerState: providerSession.state,
+    partSize: providerSession.partSize,
+    parts: {},
+    status: "active",
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + sessionTtlMs).toISOString()
+  };
+  await options.journal.create(session);
+  return json({
+    sessionId: id,
+    partSize: session.partSize,
+    maxConcurrency: providerSession.maxConcurrency,
+    completedParts: [],
+    expiresAt: session.expiresAt
+  }, 201);
+}
+async function inspectMultipart(request, routeName, route, sessionId, options) {
+  await authorizeExistingSession(request, routeName, route);
+  const session = await requiredSession(options.journal, sessionId, routeName);
+  assertSessionFileHash(request, session);
+  return json({
+    sessionId,
+    status: session.status,
+    partSize: session.partSize,
+    completedParts: Object.values(session.parts).map((part) => part.index).toSorted((a, b) => a - b),
+    expiresAt: session.expiresAt,
+    result: session.result
+  });
+}
+async function uploadMultipartPart(request, routeName, route, sessionId, rawIndex, options, inFlightParts, inFlightPartRequests) {
+  await authorizeExistingSession(request, routeName, route);
+  const session = await requiredSession(options.journal, sessionId, routeName);
+  if (session.status !== "active") {
+    throw new StorageError("INVALID_INPUT", `Upload session is ${session.status}`, { status: 409 });
+  }
+  const index = Number(rawIndex);
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new StorageError("INVALID_INPUT", "Part index must be a non-negative integer", {
+      status: 400
+    });
+  }
+  const existing = session.parts[String(index)];
+  if (existing)
+    return json({ part: existing, reused: true });
+  const operationKey = `${sessionId}:${index}`;
+  const existingOperation = inFlightPartRequests.get(operationKey);
+  if (existingOperation) {
+    return json({ part: await existingOperation, reused: true });
+  }
+  const provider = getMultipartProvider(options.storage, session.provider);
+  const operation = (async () => {
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    if (bytes.byteLength > session.partSize) {
+      throw new StorageError("FILE_TOO_LARGE", "Multipart request exceeds the session part size", {
+        status: 413
+      });
+    }
+    const part2 = await provider.uploadPart(providerSession(session), {
+      index,
+      bytes
+    });
+    try {
+      await options.journal.putPart(sessionId, part2);
+    } catch (error) {
+      await provider.abortMultipart?.(providerSession(session), [part2]);
+      throw error;
+    }
+    return part2;
+  })();
+  inFlightPartRequests.set(operationKey, operation);
+  trackInFlight(inFlightParts, sessionId, operation);
+  operation.finally(() => {
+    if (inFlightPartRequests.get(operationKey) === operation) {
+      inFlightPartRequests.delete(operationKey);
+    }
+  }).catch(() => {
+    return;
+  });
+  const part = await operation;
+  return json({ part, reused: false }, 201);
+}
+async function completeMultipart(request, routeName, route, sessionId, options) {
+  const { input, metadata } = await authorizeExistingSession(request, routeName, route);
+  let session = await requiredSession(options.journal, sessionId, routeName);
+  if (session.status === "complete")
+    return json(session.result);
+  if (session.status !== "active") {
+    throw new StorageError("INVALID_INPUT", `Upload session is ${session.status}`, { status: 409 });
+  }
+  const sha256 = requiredHeader(request, "x-storage-file-sha256");
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw new StorageError("INVALID_INPUT", "x-storage-file-sha256 must be a SHA-256 hex digest", {
+      status: 400
+    });
+  }
+  if (session.file.sha256 && sha256 !== session.file.sha256) {
+    throw new StorageError("INTEGRITY_FAILED", "The selected file does not match the file that started this upload session", { status: 409 });
+  }
+  const expectedParts = Math.ceil(session.file.size / session.partSize);
+  const parts = Object.values(session.parts).toSorted((left, right) => left.index - right.index);
+  if (parts.length !== expectedParts) {
+    throw new StorageError("INVALID_INPUT", `Upload is missing ${expectedParts - parts.length} parts`, { status: 409 });
+  }
+  const preview = await parseOptionalPreview(request, session.partSize);
+  session = await options.journal.setStatus(sessionId, "completing");
+  const provider = getMultipartProvider(options.storage, session.provider);
+  try {
+    const receipt = await provider.completeMultipart(providerSession(session), parts, {
+      name: session.file.name,
+      contentType: session.file.contentType,
+      size: session.file.size,
+      sha256
+    }, { signal: request.signal, preview, metadata: asMetadata(metadata) });
+    const serverData = await route.onComplete?.({
+      request,
+      input,
+      metadata,
+      receipt,
+      route: routeName
+    });
+    const result = { receipt, serverData };
+    await options.journal.setResult(sessionId, result);
+    return json(result, 201);
+  } catch (error) {
+    await options.journal.setStatus(sessionId, "active").catch(() => {
+      return;
+    });
+    await route.onError?.({ request, route: routeName, error });
+    throw error;
+  }
+}
+async function abortMultipart(request, routeName, route, sessionId, options, inFlightParts) {
+  await authorizeExistingSession(request, routeName, route);
+  let session = await requiredSession(options.journal, sessionId, routeName);
+  if (session.status === "complete") {
+    throw new StorageError("INVALID_INPUT", "A completed upload cannot be aborted", { status: 409 });
+  }
+  if (session.status !== "aborted") {
+    session = await options.journal.setStatus(sessionId, "aborted");
+  }
+  await Promise.allSettled(inFlightParts.get(sessionId) ?? []);
+  session = await options.journal.get(sessionId) ?? session;
+  const provider = getMultipartProvider(options.storage, session.provider);
+  await provider.abortMultipart?.(providerSession(session), Object.values(session.parts));
+  await options.journal.remove(sessionId);
+  return new Response(null, { status: 204 });
+}
+function trackInFlight(registry, sessionId, operation) {
+  const operations = registry.get(sessionId) ?? new Set;
+  operations.add(operation);
+  registry.set(sessionId, operations);
+  operation.finally(() => {
+    operations.delete(operation);
+    if (operations.size === 0)
+      registry.delete(sessionId);
+  }).catch(() => {
+    return;
+  });
+}
+function assertSessionFileHash(request, session) {
+  const supplied = requiredHeader(request, "x-storage-file-sha256");
+  if (!/^[a-f0-9]{64}$/.test(supplied)) {
+    throw new StorageError("INVALID_INPUT", "x-storage-file-sha256 must be a SHA-256 hex digest", {
+      status: 400
+    });
+  }
+  if (!session.file.sha256) {
+    throw new StorageError("INTEGRITY_FAILED", "This upload session predates safe resume and must be restarted", { status: 409 });
+  }
+  if (supplied !== session.file.sha256) {
+    throw new StorageError("INTEGRITY_FAILED", "The selected file does not match the file that started this upload session", { status: 409 });
+  }
+}
+function parseSha256(value, name) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new StorageError("INVALID_INPUT", `${name} must be a SHA-256 hex digest`, {
+      status: 400
+    });
+  }
+  return value;
+}
+function getMultipartProvider(storage, name) {
+  const provider = storage.provider(name);
+  if (!provider.beginMultipart || !provider.uploadPart || !provider.completeMultipart) {
+    throw new StorageError("CAPABILITY_UNSUPPORTED", `Provider '${name}' does not support multipart uploads`, { status: 501 });
+  }
+  return provider;
+}
+function providerSession(session) {
+  return { state: session.providerState, partSize: session.partSize };
+}
+async function authorizeExistingSession(request, routeName, route) {
+  const input = await parseRouteInput(request, route);
+  const metadata = await route.authorize({ request, input, route: routeName });
+  return { input, metadata };
+}
+async function parseRouteInput(request, route) {
+  const encoded = request.headers.get("x-storage-input");
+  if (!encoded)
+    return route.parseInput(undefined);
+  try {
+    return route.parseInput(JSON.parse(decodeURIComponent(encoded)));
+  } catch (error) {
+    throw new StorageError("INVALID_INPUT", "x-storage-input must contain valid JSON", {
+      status: 400,
+      cause: error
+    });
+  }
+}
+async function parseOptionalPreview(request, maxSize) {
+  const widthValue = request.headers.get("x-storage-preview-width");
+  const heightValue = request.headers.get("x-storage-preview-height");
+  if (!widthValue && !heightValue)
+    return;
+  if (!widthValue || !heightValue) {
+    throw new StorageError("INVALID_INPUT", "Preview width and height are required together", {
+      status: 400
+    });
+  }
+  const width = Number(widthValue);
+  const height = Number(heightValue);
+  if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+    throw new StorageError("INVALID_INPUT", "Preview dimensions must be positive integers", {
+      status: 400
+    });
+  }
+  const bytes = await request.arrayBuffer();
+  if (bytes.byteLength <= 0 || bytes.byteLength > maxSize) {
+    throw new StorageError("FILE_TOO_LARGE", "Preview exceeds the provider part size", {
+      status: 413
+    });
+  }
+  const contentType = request.headers.get("content-type") ?? "image/jpeg";
+  return {
+    file: new File([bytes], `${requiredHeader(request, "x-storage-file-name")}.preview`, {
+      type: contentType
+    }),
+    width,
+    height
+  };
+}
+function parseFileDescriptor(value) {
+  if (!value || typeof value !== "object") {
+    throw new StorageError("INVALID_INPUT", "A file descriptor is required", {
+      status: 400
+    });
+  }
+  const file = value;
+  if (typeof file.name !== "string" || !file.name || typeof file.size !== "number" || !Number.isSafeInteger(file.size) || file.size <= 0 || typeof file.contentType !== "string" || !file.contentType) {
+    throw new StorageError("INVALID_INPUT", "The file descriptor is invalid", {
+      status: 400
+    });
+  }
+  return { name: file.name, size: file.size, contentType: file.contentType };
+}
+function validateRouteFile(route, name, contentType, size) {
+  if (!name || name.length > 255 || size <= 0) {
+    throw new StorageError("INVALID_INPUT", "File name or size is invalid", {
+      status: 400
+    });
+  }
+  if (route.config.maxFileSize && size > route.config.maxFileSize) {
+    throw new StorageError("FILE_TOO_LARGE", "File exceeds the route limit", {
+      status: 413
+    });
+  }
+  if (route.config.accept?.length && !route.config.accept.some((pattern) => matchesContentType(contentType, pattern))) {
+    throw new StorageError("INVALID_INPUT", `Content type '${contentType}' is not accepted`, {
+      status: 415
+    });
+  }
+}
+function matchesContentType(contentType, pattern) {
+  return pattern.endsWith("/*") ? contentType.startsWith(pattern.slice(0, -1)) : contentType === pattern;
+}
+async function requiredSession(journal, id, route) {
+  const session = await journal.get(id);
+  if (!session || session.route !== route) {
+    throw new StorageError("SESSION_NOT_FOUND", "Upload session was not found", { status: 404 });
+  }
+  if (Date.parse(session.expiresAt) <= Date.now()) {
+    throw new StorageError("SESSION_EXPIRED", "Upload session has expired", {
+      status: 410
+    });
+  }
+  return session;
+}
+function requiredHeader(request, name) {
+  const value = request.headers.get(name);
+  if (!value)
+    throw new StorageError("INVALID_INPUT", `${name} header is required`, {
+      status: 400
+    });
+  return value;
+}
+function decodedHeader(request, name) {
+  const value = requiredHeader(request, name);
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    throw new StorageError("INVALID_INPUT", `${name} is not valid URI-encoded text`, {
+      status: 400,
+      cause: error
+    });
+  }
+}
+function positiveHeader(request, name) {
+  const value = Number(requiredHeader(request, name));
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new StorageError("INVALID_INPUT", `${name} must be a positive integer`, { status: 400 });
+  }
+  return value;
+}
+function asMetadata(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function normalizeBasePath(value) {
+  const withSlash = value.startsWith("/") ? value : `/${value}`;
+  return withSlash.replace(/\/$/, "");
+}
+function json(value, status = 200) {
+  return Response.json(value, { status });
+}
+function withCors(response, request, options) {
+  const origin = typeof options.corsOrigin === "function" ? options.corsOrigin(request) : options.corsOrigin;
+  if (!origin)
+    return response;
+  response.headers.set("Access-Control-Allow-Origin", origin);
+  response.headers.set("Access-Control-Allow-Headers", "Authorization, Content-Type, X-API-Key, X-Demo-Fail-Count, X-Demo-Fail-Part, X-Storage-File-Name, X-Storage-File-Size, X-Storage-File-Sha256, X-Storage-Input, X-Storage-Preview-Width, X-Storage-Preview-Height");
+  response.headers.set("Access-Control-Allow-Methods", "DELETE, GET, OPTIONS, POST, PUT");
+  response.headers.append("Vary", "Origin");
+  return response;
+}
+// src/router.ts
+class FileRouteBuilder {
+  #definition;
+  constructor(definition) {
+    this.#definition = definition;
+  }
+  input(parser) {
+    return new FileRouteBuilder({
+      ...this.#definition,
+      parseInput: parser,
+      authorize: this.#definition.authorize,
+      onComplete: this.#definition.onComplete
+    });
+  }
+  middleware(authorize) {
+    return new FileRouteBuilder({
+      ...this.#definition,
+      authorize,
+      onComplete: this.#definition.onComplete
+    });
+  }
+  onUploadComplete(callback) {
+    return new FileRouteBuilder({ ...this.#definition, onComplete: callback });
+  }
+  onUploadError(callback) {
+    return new FileRouteBuilder({ ...this.#definition, onError: callback });
+  }
+  build() {
+    return this.#definition;
+  }
+}
+function createFileRoute() {
+  return (config) => new FileRouteBuilder({
+    config,
+    parseInput: (value) => value,
+    authorize: () => {
+      return;
+    }
+  });
+}
+function defineFileRouter(router) {
+  return Object.fromEntries(Object.entries(router).map(([key, value]) => [
+    key,
+    value instanceof FileRouteBuilder ? value.build() : value
+  ]));
+}
+export {
+  defineFileRouter,
+  createFileRoute,
+  createFetchHandler
+};

package/dist/router.d.ts

@@ -0,0 +1,45 @@
+import type { MaybePromise, StorageReceipt } from "@minhvuong/pirate-storage";
+export interface FileRouteConfig<Provider extends string = string> {
+    provider: Provider;
+    accept?: readonly string[];
+    maxFileSize?: number;
+    maxFileCount?: number;
+}
+export interface FileRouteContext<Input = unknown> {
+    request: Request;
+    input: Input;
+    route: string;
+}
+export interface UploadCompleteContext<Metadata = unknown, Input = unknown> {
+    request: Request;
+    input: Input;
+    metadata: Metadata;
+    receipt: StorageReceipt;
+    route: string;
+}
+export interface FileRouteDefinition<Provider extends string = string, Input = unknown, Metadata = unknown, ServerData = unknown> {
+    readonly config: FileRouteConfig<Provider>;
+    readonly parseInput: (value: unknown) => MaybePromise<Input>;
+    readonly authorize: (context: FileRouteContext<Input>) => MaybePromise<Metadata>;
+    readonly onComplete?: (context: UploadCompleteContext<Metadata, Input>) => MaybePromise<ServerData>;
+    readonly onError?: (context: {
+        request: Request;
+        route: string;
+        error: unknown;
+    }) => MaybePromise<void>;
+}
+export type FileRouter = Readonly<Record<string, FileRouteDefinition<any, any, any, any>>>;
+declare class FileRouteBuilder<Provider extends string, Input = unknown, Metadata = undefined, ServerData = undefined> {
+    #private;
+    constructor(definition: FileRouteDefinition<Provider, Input, Metadata, ServerData>);
+    input<NextInput>(parser: (value: unknown) => MaybePromise<NextInput>): FileRouteBuilder<Provider, NextInput, Metadata, ServerData>;
+    middleware<NextMetadata>(authorize: (context: FileRouteContext<Input>) => MaybePromise<NextMetadata>): FileRouteBuilder<Provider, Input, NextMetadata, ServerData>;
+    onUploadComplete<NextServerData>(callback: (context: UploadCompleteContext<Metadata, Input>) => MaybePromise<NextServerData>): FileRouteBuilder<Provider, Input, Metadata, NextServerData>;
+    onUploadError(callback: NonNullable<FileRouteDefinition["onError"]>): FileRouteBuilder<Provider, Input, Metadata, ServerData>;
+    build(): FileRouteDefinition<Provider, Input, Metadata, ServerData>;
+}
+export declare function createFileRoute(): <Provider extends string>(config: FileRouteConfig<Provider>) => FileRouteBuilder<Provider, unknown, undefined, undefined>;
+export declare function defineFileRouter<const Router extends Record<string, FileRouteBuilder<any, any, any, any> | FileRouteDefinition>>(router: Router): {
+    [Key in keyof Router]: Router[Key] extends FileRouteBuilder<infer P, infer I, infer M, infer S> ? FileRouteDefinition<P, I, M, S> : Router[Key];
+};
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@minhvuong/pirate-storage-server",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target browser --packages external && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@minhvuong/pirate-storage": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "typescript": "catalog:"
+  }
+}