@podosoft/podokit 1.3.0 → 1.4.1

package/dist/templates/modules/file-upload/files/apps/web/src/lib/uploads.ts

@@ -0,0 +1,356 @@
+import { ApiError, type ApiClient } from "@podosoft/podokit-api-client";
+import { api } from "./api";
+
+// Resumable uploads through the API's /files/uploads routes (file-upload module).
+// Parts go to the same-origin /api/files/uploads path. The module declares it as
+// a direct API path, so `podo add` lists it in the gateway's apiPaths and parts
+// larger than the web server's BODY_SIZE_LIMIT reach the API.
+
+export interface UploadSession {
+  id: string;
+  partSize: number;
+  partCount: number;
+  expiresAt: string;
+}
+
+export type UploadState = "open" | "completing" | "completed" | "aborted";
+
+export interface UploadStatus extends UploadSession {
+  status: UploadState;
+  filename: string;
+  contentType: string | null;
+  size: number;
+  receivedParts: number[];
+  key?: string;
+}
+
+export interface UploadedFile {
+  id: string;
+  status: "completed";
+  key: string;
+  size: number;
+  contentType: string | null;
+  url: string;
+}
+
+export interface UploadOptions {
+  /**
+   * Called with the bytes sent so far. With the default client in a browser it
+   * reports bytes as they leave; otherwise it reports when a part is stored.
+   * The value never decreases: when a part fails, its bytes stop counting and
+   * the value holds until the retry passes it.
+   */
+  onProgress?: (sentBytes: number, totalBytes: number) => void;
+  /** Aborting stops the transfer and cancels the upload on the server. */
+  signal?: AbortSignal;
+  /** Parts in flight at once. Defaults to 3. */
+  concurrency?: number;
+  /**
+   * Further attempts for a request that fails with a network error, 408, 425,
+   * 429, or 5xx. Defaults to 5.
+   */
+  retries?: number;
+  /** First retry delay in milliseconds, doubled per attempt up to 30 s. A Retry-After header wins. Defaults to 500. */
+  retryDelayMs?: number;
+  /**
+   * Defaults to the app's same-origin client, which sends parts with
+   * XMLHttpRequest in a browser. A custom client sends parts with its fetch.
+   */
+  client?: ApiClient;
+}
+
+export interface NewUploadOptions extends UploadOptions {
+  /** Defaults to the File's name. */
+  filename?: string;
+  /** Defaults to the Blob's type. */
+  contentType?: string;
+  /** Receives the session as soon as it exists; keep its id to resume after a reload. */
+  onSession?: (session: UploadSession) => void;
+}
+
+const BASE = "/files/uploads";
+/** The REST prefix of the default same-origin client in ./api. */
+const API_PREFIX = "/api";
+const MAX_DELAY_MS = 30_000;
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("The upload was aborted", "AbortError");
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw abortReason(signal);
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal ? abortReason(signal) : new DOMException("Aborted", "AbortError"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Network failures surface from fetch, and from sendPart, as a TypeError. */
+function transient(error: unknown): boolean {
+  return error instanceof ApiError ? RETRYABLE_STATUS.has(error.statusCode) : error instanceof TypeError;
+}
+
+/** Reads Retry-After as delay seconds or an HTTP date, as the API client does. */
+function retryAfterSeconds(value: string | null): number | undefined {
+  const header = value?.trim();
+  if (!header) return undefined;
+  if (/^\d+$/.test(header)) return Number(header);
+  const date = Date.parse(header);
+  return Number.isNaN(date) ? undefined : Math.max(0, Math.ceil((date - Date.now()) / 1000));
+}
+
+/** The API client's error for a failed response: the standard envelope, or HTTP_ERROR for text bodies. */
+function responseError(request: XMLHttpRequest): ApiError {
+  const retryAfter = retryAfterSeconds(request.getResponseHeader("retry-after"));
+  let body: unknown;
+  try {
+    body = request.responseText ? JSON.parse(request.responseText) : undefined;
+  } catch {
+    body = undefined;
+  }
+  const error = body && typeof body === "object" && "error" in body ? body.error : undefined;
+  if (error && typeof error === "object") {
+    const record = error as Record<string, unknown>;
+    return new ApiError(
+      typeof record.code === "string" ? record.code : "HTTP_ERROR",
+      typeof record.message === "string" ? record.message : request.statusText,
+      typeof record.statusCode === "number" ? record.statusCode : request.status,
+      record.details,
+      retryAfter,
+    );
+  }
+  return new ApiError("HTTP_ERROR", request.statusText || "Request failed", request.status, undefined, retryAfter);
+}
+
+/**
+ * PUTs one part with XMLHttpRequest, whose upload progress events report bytes
+ * as the browser sends them; fetch has no upload progress.
+ */
+function sendPart(
+  url: string,
+  part: Blob,
+  signal: AbortSignal | undefined,
+  onBytes: (loaded: number) => void,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const request = new XMLHttpRequest();
+    const onAbort = (): void => request.abort();
+    const settle = (outcome: () => void): void => {
+      signal?.removeEventListener("abort", onAbort);
+      outcome();
+    };
+    request.open("PUT", url);
+    // Same-origin requests carry the session cookie without withCredentials.
+    request.withCredentials = false;
+    request.setRequestHeader("content-type", "application/octet-stream");
+    request.upload.onprogress = (event) => onBytes(Math.min(event.loaded, part.size));
+    request.onload = () =>
+      settle(() => (request.status >= 200 && request.status < 300 ? resolve() : reject(responseError(request))));
+    request.onerror = () => settle(() => reject(new TypeError("Network request failed")));
+    request.onabort = () =>
+      settle(() => reject(signal?.aborted ? abortReason(signal) : new DOMException("Aborted", "AbortError")));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    request.send(part);
+  });
+}
+
+class Transfer {
+  private readonly client: ApiClient;
+  private readonly signal?: AbortSignal;
+  private readonly retries: number;
+  private readonly retryDelayMs: number;
+  private readonly concurrency: number;
+  /** Parts go through XMLHttpRequest only for the default client, whose URLs this file knows. */
+  private readonly xhr: boolean;
+
+  constructor(private readonly options: UploadOptions) {
+    this.client = options.client ?? api;
+    this.xhr = options.client === undefined && typeof XMLHttpRequest !== "undefined";
+    this.signal = options.signal;
+    this.retries = Math.max(0, options.retries ?? 5);
+    this.retryDelayMs = Math.max(0, options.retryDelayMs ?? 500);
+    this.concurrency = Math.max(1, Math.floor(options.concurrency ?? 3));
+  }
+
+  async attempt<T>(request: () => Promise<T>, retryable: (error: unknown) => boolean = transient): Promise<T> {
+    for (let attempt = 0; ; attempt++) {
+      throwIfAborted(this.signal);
+      try {
+        return await request();
+      } catch (error) {
+        throwIfAborted(this.signal);
+        if (attempt >= this.retries || !retryable(error)) throw error;
+        const retryAfter = error instanceof ApiError ? error.retryAfterSeconds : undefined;
+        const delay = retryAfter !== undefined
+          ? retryAfter * 1000
+          : Math.min(MAX_DELAY_MS, this.retryDelayMs * 2 ** attempt);
+        await sleep(delay, this.signal);
+      }
+    }
+  }
+
+  create(body: { filename: string; size: number; contentType?: string }): Promise<UploadSession> {
+    return this.attempt(() => this.client.post<UploadSession>(BASE, body, { signal: this.signal }));
+  }
+
+  status(id: string): Promise<UploadStatus> {
+    return this.attempt(() => this.client.get<UploadStatus>(`${BASE}/${id}`, { signal: this.signal }));
+  }
+
+  /** Runs the transfer; when the caller aborts, cancels the upload and rethrows the abort reason. */
+  async cancelOnAbort(id: string, transfer: () => Promise<UploadedFile>): Promise<UploadedFile> {
+    try {
+      return await transfer();
+    } catch (error) {
+      if (!this.signal?.aborted) throw error;
+      // Sent without the caller's signal, which has just aborted.
+      await this.client.del<void>(`${BASE}/${id}`).catch(() => undefined);
+      throw abortReason(this.signal);
+    }
+  }
+
+  private putPart(sessionId: string, partNumber: number, part: Blob, onBytes: (loaded: number) => void): Promise<void> {
+    const path = `${BASE}/${sessionId}/parts/${partNumber}`;
+    if (this.xhr) return sendPart(`${API_PREFIX}${path}`, part, this.signal, onBytes);
+    return this.client
+      .put(path, part, { contentType: "application/octet-stream", signal: this.signal })
+      .then(() => undefined);
+  }
+
+  /** Sends the parts not yet stored, then completes the upload. */
+  async run(session: UploadSession, file: Blob, stored: Iterable<number>): Promise<UploadedFile> {
+    const size = (partNumber: number): number =>
+      partNumber < session.partCount ? session.partSize : file.size - session.partSize * (session.partCount - 1);
+    const all = Array.from({ length: session.partCount }, (_, index) => index + 1);
+    const received = new Set(stored);
+    let sent = 0;
+    for (const partNumber of received) sent += size(partNumber);
+    // Bytes of each part's current attempt. A failed attempt's entry is dropped,
+    // so its retry starts from zero instead of counting those bytes twice, and
+    // the reported value holds until the retry passes it.
+    const inFlight = new Map<number, number>();
+    let reported = -1;
+    const report = (): void => {
+      let bytes = sent;
+      for (const loaded of inFlight.values()) bytes += loaded;
+      if (bytes <= reported) return;
+      reported = bytes;
+      this.options.onProgress?.(bytes, file.size);
+    };
+    report();
+
+    const send = async (numbers: number[]): Promise<void> => {
+      const queue = [...numbers];
+      let failure: { error: unknown } | undefined;
+      const worker = async (): Promise<void> => {
+        for (let partNumber = queue.shift(); partNumber !== undefined && !failure; partNumber = queue.shift()) {
+          const start = (partNumber - 1) * session.partSize;
+          const part = file.slice(start, start + size(partNumber));
+          const number = partNumber;
+          try {
+            await this.attempt(async () => {
+              try {
+                await this.putPart(session.id, number, part, (loaded) => {
+                  // A part sent again after completion reported it missing is already counted.
+                  if (received.has(number)) return;
+                  inFlight.set(number, loaded);
+                  report();
+                });
+              } finally {
+                inFlight.delete(number);
+              }
+            });
+          } catch (error) {
+            failure ??= { error };
+            return;
+          }
+          if (!received.has(number)) {
+            received.add(number);
+            sent += part.size;
+          }
+          report();
+        }
+      };
+      // Every worker settles before a failure is reported, so no part is still
+      // in flight when the caller cancels the upload.
+      await Promise.all(Array.from({ length: Math.min(this.concurrency, numbers.length) }, worker));
+      if (failure) throw failure.error;
+    };
+
+    await send(all.filter((partNumber) => !received.has(partNumber)));
+    for (let round = 0; ; round++) {
+      try {
+        return await this.attempt(
+          () => this.client.post<UploadedFile>(`${BASE}/${session.id}/complete`, {}, { signal: this.signal }),
+          (error) => transient(error) || (error instanceof ApiError && error.code === "UPLOAD_COMPLETING"),
+        );
+      } catch (error) {
+        if (round > 0 || !(error instanceof ApiError)) throw error;
+        // The server is the source of truth: resend what it lacks, once.
+        if (error.code === "UPLOAD_INCOMPLETE") {
+          const stored = new Set((await this.status(session.id)).receivedParts);
+          await send(all.filter((partNumber) => !stored.has(partNumber)));
+        } else if (error.code === "UPLOAD_INVALID_PART") {
+          await send(all);
+        } else {
+          throw error;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Uploads a file in parts and returns the stored file. Failed parts are
+ * retried with backoff; aborting `signal` cancels the upload on the server.
+ */
+export async function uploadFile(file: Blob, options: NewUploadOptions = {}): Promise<UploadedFile> {
+  const transfer = new Transfer(options);
+  const named = typeof File !== "undefined" && file instanceof File && file.name !== "";
+  const filename = options.filename ?? (named ? (file as File).name : "upload");
+  const contentType = options.contentType ?? (file.type || undefined);
+  const session = await transfer.create({
+    filename,
+    size: file.size,
+    ...(contentType ? { contentType } : {}),
+  });
+  options.onSession?.(session);
+  return transfer.cancelOnAbort(session.id, () => transfer.run(session, file, []));
+}
+
+/**
+ * Continues an upload started earlier, for example before a page reload, with
+ * the same file: only the parts the server has not stored are sent.
+ */
+export async function resumeUpload(id: string, file: Blob, options: UploadOptions = {}): Promise<UploadedFile> {
+  const transfer = new Transfer(options);
+  const status = await transfer.status(id);
+  if (status.size !== file.size) {
+    throw new Error(`The file has ${file.size} bytes, but upload ${id} expects ${status.size}`);
+  }
+  return transfer.cancelOnAbort(id, () => transfer.run(status, file, status.receivedParts));
+}
+
+/** Cancels an upload and discards its stored parts. */
+export async function cancelUpload(id: string, options: { client?: ApiClient } = {}): Promise<void> {
+  await (options.client ?? api).del<void>(`${BASE}/${id}`);
+}

package/dist/templates/modules/file-upload/files/tests/api/chunked-uploads.api.spec.ts

@@ -0,0 +1,153 @@
+import { createHash, randomBytes } from "node:crypto";
+import { expect, test, type APIRequestContext, type APIResponse, type PlaywrightWorkerArgs } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+// Parts are larger than the web server's BODY_SIZE_LIMIT, so they go to the API
+// the way the gateway's direct apiPaths entry sends them: E2E_API_URL when the
+// harness provides it, otherwise /api on a gateway that routes the path.
+const apiBase = process.env.E2E_API_URL ?? `${base}/api`;
+const uploads = `${apiBase}/files/uploads`;
+
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+interface Created {
+  id: string;
+  partSize: number;
+  partCount: number;
+  expiresAt: string;
+}
+
+async function session(playwright: Playwright): Promise<{ ctx: APIRequestContext; userId: string | undefined }> {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
+  const email = `chunks-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "C" } }).catch(() => undefined);
+  const current = await ctx.get("/api/auth/get-session");
+  const body = current.ok() ? await current.json() as { user?: { id?: string } } | null : null;
+  return { ctx, userId: body?.user?.id };
+}
+
+async function create(ctx: APIRequestContext, size: number, filename = "big.bin"): Promise<Created> {
+  const res = await ctx.post(uploads, { data: { filename, size, contentType: "application/octet-stream" } });
+  test.skip(res.status() >= 500, "selected object storage is not reachable");
+  expect(res.status(), await res.text()).toBe(201);
+  return await res.json() as Created;
+}
+
+function putPart(ctx: APIRequestContext, id: string, partNumber: number, body: Buffer): Promise<APIResponse> {
+  return ctx.put(`${uploads}/${id}/parts/${partNumber}`, {
+    data: body,
+    headers: { "content-type": "application/octet-stream" },
+  });
+}
+
+function part(file: Buffer, upload: Created, partNumber: number): Buffer {
+  return file.subarray((partNumber - 1) * upload.partSize, partNumber * upload.partSize);
+}
+
+function sha256(value: Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+test("chunked upload: parts, a retried part, resume status, and complete store the file", async ({ playwright }) => {
+  const { ctx, userId } = await session(playwright);
+  try {
+    const probe = await create(ctx, 1);
+    expect((await ctx.delete(`${uploads}/${probe.id}`)).status()).toBe(204);
+    const file = randomBytes(probe.partSize + 1024 * 1024 + 123);
+    const upload = await create(ctx, file.byteLength);
+    expect(upload.partCount).toBe(2);
+
+    expect((await putPart(ctx, upload.id, 2, part(file, upload, 2))).status()).toBe(200);
+    const first = await putPart(ctx, upload.id, 1, part(file, upload, 1));
+    expect(first.status(), await first.text()).toBe(200);
+    expect(await first.json()).toEqual({ partNumber: 1, size: upload.partSize });
+    // Sending a part again (a client retry) replaces it.
+    expect((await putPart(ctx, upload.id, 1, part(file, upload, 1))).status()).toBe(200);
+
+    const status = await ctx.get(`${uploads}/${upload.id}`);
+    expect(status.status()).toBe(200);
+    expect(await status.json()).toMatchObject({ status: "open", size: file.byteLength, receivedParts: [1, 2] });
+
+    const done = await ctx.post(`${uploads}/${upload.id}/complete`, { data: {} });
+    expect(done.status(), await done.text()).toBe(200);
+    const result = await done.json() as { key: string; size: number; url: string; status: string };
+    expect(result.status).toBe("completed");
+    expect(result.size).toBe(file.byteLength);
+    if (userId) expect(result.key).toMatch(new RegExp(`^uploads/${userId}/${upload.id}-big\\.bin$`));
+    // Completing again returns the same result.
+    expect(await (await ctx.post(`${uploads}/${upload.id}/complete`, { data: {} })).json()).toMatchObject({ key: result.key });
+
+    // Local storage returns a signed API path. S3 returns a URL signed for the API's
+    // S3 endpoint; a containerized dev stack signs an in-network host, so download it
+    // only when the runner was given that endpoint too. The completed size above
+    // comes from the stored object either way.
+    const local = result.url.startsWith("/");
+    if (local || process.env.S3_ENDPOINT) {
+      const download = await ctx.get(local ? `${apiBase}${result.url}` : result.url);
+      expect(download.status()).toBe(200);
+      const stored = await download.body();
+      expect(stored.byteLength).toBe(file.byteLength);
+      expect(sha256(stored)).toBe(sha256(file));
+    }
+  } finally {
+    await ctx.dispose();
+  }
+});
+
+test("chunked upload: other users see 404 for every upload route", async ({ playwright }) => {
+  const owner = await session(playwright);
+  const other = await session(playwright);
+  try {
+    test.skip(!owner.userId || !other.userId, "requires the auth module");
+    const upload = await create(owner.ctx, 10);
+    for (const res of [
+      await other.ctx.get(`${uploads}/${upload.id}`),
+      await putPart(other.ctx, upload.id, 1, Buffer.alloc(10)),
+      await other.ctx.post(`${uploads}/${upload.id}/complete`, { data: {} }),
+      await other.ctx.delete(`${uploads}/${upload.id}`),
+    ]) {
+      expect(res.status()).toBe(404);
+      expect(await res.json()).toMatchObject({ error: { code: "UPLOAD_NOT_FOUND" } });
+    }
+    expect((await owner.ctx.get(`${uploads}/${upload.id}`)).status()).toBe(200);
+  } finally {
+    await owner.ctx.dispose();
+    await other.ctx.dispose();
+  }
+});
+
+test("chunked upload: DELETE cancels the upload and later parts are refused", async ({ playwright }) => {
+  const { ctx } = await session(playwright);
+  try {
+    const upload = await create(ctx, 20);
+    expect((await ctx.delete(`${uploads}/${upload.id}`)).status()).toBe(204);
+    expect(await (await ctx.get(`${uploads}/${upload.id}`)).json()).toMatchObject({ status: "aborted" });
+    const late = await putPart(ctx, upload.id, 1, Buffer.alloc(20));
+    expect(late.status()).toBe(410);
+    expect(await late.json()).toMatchObject({ error: { code: "UPLOAD_ABORTED" } });
+    expect((await ctx.delete(`${uploads}/${upload.id}`)).status()).toBe(204);
+  } finally {
+    await ctx.dispose();
+  }
+});
+
+test("chunked upload: a part of the wrong size or content type is refused", async ({ playwright }) => {
+  const { ctx } = await session(playwright);
+  try {
+    const upload = await create(ctx, 20);
+    const short = await putPart(ctx, upload.id, 1, Buffer.alloc(19));
+    expect(short.status()).toBe(400);
+    expect(await short.json()).toMatchObject({ error: { code: "UPLOAD_PART_SIZE_MISMATCH" } });
+
+    const text = await ctx.put(`${uploads}/${upload.id}/parts/1`, { data: "x".repeat(20), headers: { "content-type": "text/plain" } });
+    expect(text.status()).toBe(415);
+    expect(await text.json()).toMatchObject({ error: { code: "UNSUPPORTED_MEDIA_TYPE" } });
+
+    const incomplete = await ctx.post(`${uploads}/${upload.id}/complete`, { data: {} });
+    expect(incomplete.status()).toBe(409);
+    expect(await incomplete.json()).toMatchObject({ error: { code: "UPLOAD_INCOMPLETE" } });
+    expect((await ctx.delete(`${uploads}/${upload.id}`)).status()).toBe(204);
+  } finally {
+    await ctx.dispose();
+  }
+});

package/dist/templates/modules/file-upload/module.manifest.json

@@ -1,23 +1,51 @@
 {
-  "manifestVersion": 3,
+  "manifestVersion": 4,
   "name": "file-upload",
-  "description": "Multipart file upload endpoint that stores each user's files via object storage and presigns them only for the uploader or an administrator.",
+  "description": "File uploads through object storage: a single-request multipart endpoint and resumable chunked uploads whose state lives in the database, with downloads presigned only for the uploader or an administrator.",
   "requiresCapabilities": ["object-storage"],
   "targetApp": "api",
+  "apiPaths": ["/api/files/uploads/"],
+  "requiredProjectFiles": ["apps/api/src/config/server-options.ts"],
   "requiredProjectContents": {
-    "apps/api/src/core/services.ts": ["isAdmin(request: Request): Promise<boolean>;"]
+    "apps/api/src/core/services.ts": [
+      "isAdmin(request: Request): Promise<boolean>;",
+      "tryResolve<T>(key: ServiceKey<T>): T | undefined {"
+    ]
   },
-  "env": [],
+  "env": [
+    "# file-upload: resumable chunked uploads. Largest file per upload, in bytes (1 GiB).",
+    "FILE_UPLOAD_MAX_BYTES=1073741824",
+    "# Part size in bytes: at least 5 MiB and within API_MAX_REQUEST_BODY_SIZE (8 MiB).",
+    "FILE_UPLOAD_PART_BYTES=8388608",
+    "# Seconds an unfinished upload may sit idle before it expires; each part restarts it.",
+    "FILE_UPLOAD_SESSION_TTL=86400",
+    "# Seconds between sweeps that abort expired uploads on every replica; 0 turns it off.",
+    "FILE_UPLOAD_SWEEP_INTERVAL=300",
+    "# Part uploads per caller in each RATE_LIMIT_TTL window when rate-limit is installed.",
+    "FILE_UPLOAD_RATE_LIMIT_MAX=3000"
+  ],
   "inject": [
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { filesModule } from \"./files/files.module\";" },
-    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "filesModule," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "filesModule," },
+    {
+      "file": "AGENTS.md",
+      "marker": "<!-- podokit:end:agents-modules -->",
+      "optional": true,
+      "text": "### file-upload\n- `POST /files` stores one multipart file under `uploads/<userId>/`; `GET /files/:key/url` presigns it for the owner or an administrator.\n- For large files use the resumable upload in the browser: `uploadFile(file, { onProgress, signal })` and `resumeUpload(id, file)` from `$lib/uploads`. They create a session (`POST /files/uploads`), send parts (`PUT /files/uploads/:id/parts/:n`, `application/octet-stream`, `Content-Length` equal to the part size; with `XMLHttpRequest` in the browser so `onProgress` reports bytes), retry failed parts honoring `Retry-After`, and complete (`POST /files/uploads/:id/complete`). `GET /files/uploads/:id` lists stored parts; `DELETE` cancels.\n- Upload sessions live in the database (`file_upload_sessions`, `file_upload_parts`), so any API replica serves any request; never keep upload state in memory. Run `{{apiRun}} migrate:all{{apiWorkspaceArg}}` after adding the module.\n- Parts are larger than the web `BODY_SIZE_LIMIT`, so the gateway sends `/api/files/uploads/` straight to the API: `podo add` listed it in `.podokit/dev.json` `apiPaths` and each deployment profile's `exposure.apiPaths`, and `podo deploy init` adds it to new profiles. Keep it there.\n- POST bodies must be `application/json` and parts `application/octet-stream` (else 415 `UNSUPPORTED_MEDIA_TYPE`), and a browser `Origin` outside `CORS_ORIGIN` gets 403. Branch on `error.code`: `UPLOAD_NOT_FOUND`, `UPLOAD_TOO_LARGE`, `UPLOAD_PART_SIZE_MISMATCH`, `UPLOAD_INCOMPLETE`, `UPLOAD_COMPLETING`, `UPLOAD_EXPIRED`, `UPLOAD_ABORTED`.\n"
+    }
   ],
   "instructions": [
     "Configure the selected object-storage provider before uploading files.",
+    "Run migrations to create the upload session tables: {{apiRun}} migrate:all{{apiWorkspaceArg}}",
     "Uploads are stored as uploads/<userId>/<uuid>-<name>. Add the auth module so every upload has an owner.",
     "Upload a file:  curl -b cookies.txt -F 'file=@./some.png' localhost:5002/files",
     "The response includes { key, url } — an S3 presigned URL or a signed local download URL.",
     "Presign it again (owner or administrator, key URL-encoded):  curl -b cookies.txt localhost:5002/files/uploads%2F<userId>%2F<file>/url",
-    "Uploads stored before per-user keys (uploads/<file>) can only be presigned by administrators."
+    "Uploads stored before per-user keys (uploads/<file>) can only be presigned by administrators.",
+    "Start a resumable upload:  curl -b cookies.txt -XPOST localhost:5002/files/uploads -H 'content-type: application/json' -d '{\"filename\":\"big.bin\",\"size\":20000000}'",
+    "Send each part with its exact size:  curl -b cookies.txt -XPUT localhost:5002/files/uploads/<id>/parts/1 -H 'content-type: application/octet-stream' --data-binary @part-1",
+    "Resume from GET /files/uploads/<id> (receivedParts), finish with POST /files/uploads/<id>/complete and '{}' as JSON, or cancel with DELETE /files/uploads/<id>.",
+    "In the browser, call uploadFile(file, { onProgress, signal }) or resumeUpload(id, file) from $lib/uploads.",
+    "Parts exceed the web server's BODY_SIZE_LIMIT, so they reach the API directly through /api/files/uploads/ (listed above as a direct API path). podo deploy init adds it to new deployment profiles."
   ]
 }

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/jobs-local.module.ts

@@ -36,7 +36,7 @@ export const jobsLocalModule: PodokitModule = {
     });
     void queue.process("demo", () => undefined);
     services.register(JOBS, queue, () => queue.close());
-    services.onStart(() => queue.start());
+    services.supervise("jobs", { connect: () => queue.start() });
   },
   plugin: localJobsPlugin,
 };

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/local-job.queue.spec.ts

@@ -25,6 +25,29 @@ describe("local job queue", () => {
     queue.close();
   });
 
+  it("creates its table on a later start after the database was unreachable", async () => {
+    const database = new SQL(":memory:");
+    sql = database;
+    let unreachable = true;
+    const flaky = new Proxy(database, {
+      apply: (target, thisArg, args) =>
+        unreachable
+          ? Promise.reject(new Error("Connection refused"))
+          : Reflect.apply(target, thisArg, args),
+    });
+    const queue = new LocalJobQueue(flaky, { pollIntervalMs: 10 });
+    const payloads: unknown[] = [];
+    await queue.process("demo", (payload) => { payloads.push(payload); });
+
+    await expect(queue.start()).rejects.toThrow("Connection refused");
+    unreachable = false;
+    await queue.start();
+    await queue.enqueue("demo", { text: "after outage" });
+    for (let waited = 0; payloads.length === 0 && waited < 1_000; waited += 10) await Bun.sleep(10);
+    expect(payloads).toEqual([{ text: "after outage" }]);
+    queue.close();
+  });
+
   it("retries failures and records the final error", async () => {
     sql = new SQL(":memory:");
     let now = 1_000;

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/local-job.queue.ts

@@ -47,29 +47,18 @@ export class LocalJobQueue implements JobQueue {
   }
 
   initialize(): Promise<void> {
-    this.initialized ??= (async () => {
-      await this.sql`
-        CREATE TABLE IF NOT EXISTS "podokit_job" (
-          "id" text PRIMARY KEY,
-          "name" text NOT NULL,
-          "payload" text NOT NULL,
-          "status" text NOT NULL,
-          "attempts" integer NOT NULL,
-          "maxAttempts" integer NOT NULL,
-          "availableAt" bigint NOT NULL,
-          "createdAt" bigint NOT NULL,
-          "updatedAt" bigint NOT NULL,
-          "error" text
-        )
-      `;
-      await this.sql`
-        CREATE INDEX IF NOT EXISTS "podokit_job_pending"
-        ON "podokit_job" ("status", "availableAt", "createdAt")
-      `;
-    })();
+    if (!this.initialized) {
+      const attempt = this.createTables();
+      this.initialized = attempt;
+      // Forget a failed attempt so the next call retries instead of replaying the failure.
+      void attempt.catch(() => {
+        if (this.initialized === attempt) this.initialized = undefined;
+      });
+    }
     return this.initialized;
   }
 
+  /** Creates the table, then polls for jobs. Rejects while the database is unreachable. */
   async start(): Promise<void> {
     if (this.started) return;
     await this.initialize();
@@ -171,6 +160,27 @@ export class LocalJobQueue implements JobQueue {
     this.handlers.clear();
   }
 
+  private async createTables(): Promise<void> {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS "podokit_job" (
+        "id" text PRIMARY KEY,
+        "name" text NOT NULL,
+        "payload" text NOT NULL,
+        "status" text NOT NULL,
+        "attempts" integer NOT NULL,
+        "maxAttempts" integer NOT NULL,
+        "availableAt" bigint NOT NULL,
+        "createdAt" bigint NOT NULL,
+        "updatedAt" bigint NOT NULL,
+        "error" text
+      )
+    `;
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "podokit_job_pending"
+      ON "podokit_job" ("status", "availableAt", "createdAt")
+    `;
+  }
+
   private schedule(delay: number): void {
     if (!this.started) return;
     this.timer = setTimeout(() => {