@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.worker.spec.ts

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { AppException } from "@podosoft/podokit-contracts";
+import {
+  MemoryEventBus,
+  type JobHandler,
+  type JobQueue,
+  type JobReference,
+} from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { RequestIdentity } from "../core/services";
+import type { EventStream, StreamFrame } from "../events/event-stream";
+import { EventsService } from "../events/events.service";
+import { ReadinessService } from "../health/readiness.service";
+import { progressRoutes } from "./job-progress.module";
+import { JOB_PROGRESS_TOPIC } from "./progress.processor";
+import { ProgressWorker } from "./progress.worker";
+
+interface FakeQueue extends JobQueue {
+  enqueued: Array<{ name: string; payload: unknown }>;
+  run(payload: unknown, job: JobReference): Promise<void>;
+}
+
+function fakeQueue(): FakeQueue {
+  const handlers = new Map<string, JobHandler>();
+  const enqueued: Array<{ name: string; payload: unknown }> = [];
+  return {
+    enqueued,
+    enqueue: async (name, payload) => {
+      enqueued.push({ name, payload });
+      return { id: `job-${enqueued.length}`, name };
+    },
+    get: async () => null,
+    process: async (name, handler) => {
+      handlers.set(name, handler);
+      return () => {
+        handlers.delete(name);
+      };
+    },
+    run: async (payload, job) => {
+      const handler = handlers.get(job.name);
+      if (!handler) throw new Error(`no handler for ${job.name}`);
+      await handler(payload, job);
+    },
+    close: () => undefined,
+  };
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup();
+});
+
+async function harness(): Promise<{ events: EventsService; queue: FakeQueue }> {
+  const events = new EventsService(new MemoryEventBus(), new ReadinessService());
+  await events.connect();
+  const queue = fakeQueue();
+  const worker = new ProgressWorker(queue, (event) => events.publishAsync(event), async () => undefined);
+  await worker.connect();
+  cleanups.push(async () => {
+    await worker.close();
+    await events.close();
+  });
+  return { events, queue };
+}
+
+function stream(events: EventsService, userId: string): Promise<EventStream> {
+  return events.open({ userId, roles: [] }, [JOB_PROGRESS_TOPIC, "marker"], new AbortController().signal);
+}
+
+function decoded(frame: StreamFrame | undefined): unknown {
+  return frame?.kind === "event" ? JSON.parse(frame.data) : frame;
+}
+
+async function progressBeforeMarker(events: EventsService, target: EventStream): Promise<unknown[]> {
+  await events.publishAsync({ topic: "marker", data: "end" });
+  const frames: unknown[] = [];
+  for (;;) {
+    const frame = decoded(await target.next());
+    if (JSON.stringify(frame) === JSON.stringify({ topic: "marker", data: "end" })) return frames;
+    frames.push(frame);
+  }
+}
+
+describe("progress worker", () => {
+  it("sends a job's progress only to the user who started it", async () => {
+    const { events, queue } = await harness();
+    const owner = await stream(events, "alice");
+    const other = await stream(events, "bob");
+
+    await queue.run({ steps: 2, ownerId: "alice" }, { id: "job-1", name: "progress" });
+
+    expect(await progressBeforeMarker(events, owner)).toEqual([
+      { topic: JOB_PROGRESS_TOPIC, data: { jobId: "job-1", progress: 50 } },
+      { topic: JOB_PROGRESS_TOPIC, data: { jobId: "job-1", progress: 100 } },
+    ]);
+    expect(await progressBeforeMarker(events, other)).toEqual([]);
+  });
+
+  it("publishes nothing for a job without an owner", async () => {
+    const { events, queue } = await harness();
+    const listener = await stream(events, "alice");
+    await queue.run({ steps: 2 }, { id: "legacy", name: "progress" });
+    expect(await progressBeforeMarker(events, listener)).toEqual([]);
+  });
+});
+
+describe("progress routes", () => {
+  const identity = (userId: string | undefined): RequestIdentity => ({
+    userId: async () => userId,
+    isAdmin: async () => false,
+    roles: async () => [],
+    activeOrganizationId: async () => undefined,
+  });
+
+  async function start(queue: JobQueue, userId: string | undefined): Promise<Response> {
+    const app = new Elysia()
+      .onError(({ error, set }) => {
+        if (!(error instanceof AppException)) return undefined;
+        set.status = error.statusCode;
+        return { code: error.code };
+      })
+      .use(progressRoutes(queue, identity(userId)));
+    return app.handle(new Request("http://localhost/progress", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ steps: 3 }),
+    }));
+  }
+
+  it("records the caller as the job owner", async () => {
+    const queue = fakeQueue();
+    const response = await start(queue, "alice");
+    expect(response.status).toBe(201);
+    expect(await response.json()).toEqual({ jobId: "job-1" });
+    expect(queue.enqueued).toEqual([{ name: "progress", payload: { steps: 3, ownerId: "alice" } }]);
+  });
+
+  it("requires a signed-in user", async () => {
+    const queue = fakeQueue();
+    const response = await start(queue, undefined);
+    expect(response.status).toBe(401);
+    expect(queue.enqueued).toEqual([]);
+  });
+});

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.worker.ts

@@ -0,0 +1,37 @@
+import type { JobQueue, Unsubscribe } from "@podosoft/podokit-runtime";
+import type { EventEnvelope } from "../events/event-envelope";
+import {
+  PROGRESS_JOB,
+  processProgress,
+  progressEvent,
+  progressPayload,
+} from "./progress.processor";
+
+export class ProgressWorker {
+  private unsubscribe?: Unsubscribe;
+
+  constructor(
+    private readonly queue: JobQueue,
+    private readonly publish: (event: EventEnvelope) => Promise<void>,
+    private readonly delay?: (milliseconds: number) => Promise<unknown>,
+  ) {}
+
+  async connect(): Promise<void> {
+    this.unsubscribe = await this.queue.process(PROGRESS_JOB, async (payload, job) => {
+      // Jobs enqueued before progress had owners run without publishing,
+      // because there is nobody they may be shown to.
+      const ownerId = progressPayload(payload).ownerId;
+      await processProgress(
+        payload,
+        async (progress) => {
+          if (ownerId) await this.publish(progressEvent(job.id, ownerId, progress));
+        },
+        this.delay,
+      );
+    });
+  }
+
+  async close(): Promise<void> {
+    await this.unsubscribe?.();
+  }
+}

package/dist/templates/modules/job-progress/files/tests/api/progress.api.spec.ts

@@ -1,17 +1,78 @@
-import { expect, test } from "@playwright/test";
+import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
 
-async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+async function session(playwright: Playwright): Promise<APIRequestContext> {
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const email = `progress-${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: "P" } }).catch(() => undefined);
   return ctx;
 }
 
-// The end-to-end progress stream (worker → Redis pub/sub → SSE) needs the worker
-// process running; this asserts the API contract (a job is enqueued).
+async function signedIn(ctx: APIRequestContext): Promise<boolean> {
+  const response = await ctx.get("/api/auth/get-session");
+  if (!response.ok()) return false;
+  const body = await response.json() as { user?: { id?: string } } | null;
+  return Boolean(body?.user?.id);
+}
+
+class ProgressStream {
+  private readonly decoder = new TextDecoder();
+  private buffered = "";
+
+  private constructor(
+    private readonly reader: ReadableStreamDefaultReader<Uint8Array>,
+    private readonly controller: AbortController,
+  ) {}
+
+  static async open(ctx: APIRequestContext): Promise<ProgressStream> {
+    const controller = new AbortController();
+    const cookie = (await ctx.storageState()).cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+    const response = await fetch(`${base}/api/events/stream?topics=job-progress`, {
+      headers: { ...origin, cookie },
+      signal: controller.signal,
+    });
+    expect(response.status).toBe(200);
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("event stream has no body");
+    const stream = new ProgressStream(reader, controller);
+    await stream.until("retry:");
+    return stream;
+  }
+
+  async until(text: string, timeoutMs = 15_000): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    while (!this.buffered.includes(text)) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw new Error(`timed out waiting for ${text}`);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<"timeout">((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), remaining);
+      });
+      const result = await Promise.race([this.reader.read(), timeout]);
+      clearTimeout(timer);
+      if (result === "timeout") continue;
+      if (result.done) throw new Error(`stream ended before ${text}`);
+      this.buffered += this.decoder.decode(result.value, { stream: true });
+    }
+    const end = this.buffered.indexOf(text) + text.length;
+    const seen = this.buffered.slice(0, end);
+    this.buffered = this.buffered.slice(end);
+    return seen;
+  }
+
+  close(): void {
+    this.controller.abort();
+  }
+}
+
+function completed(jobId: string): string {
+  return JSON.stringify({ topic: "job-progress", data: { jobId, progress: 100 } });
+}
+
 test("job-progress: starting a job returns a job id @smoke", async ({ playwright }) => {
   const ctx = await session(playwright);
   const res = await ctx.post("/api/progress", { data: { steps: 3 } });
@@ -20,3 +81,32 @@ test("job-progress: starting a job returns a job id @smoke", async ({ playwright
   expect(typeof (await res.json()).jobId).toBe("string");
   await ctx.dispose();
 });
+
+test("job-progress: progress reaches only the user who started the job", async ({ playwright }) => {
+  const owner = await session(playwright);
+  const other = await session(playwright);
+  const streams: ProgressStream[] = [];
+  try {
+    test.skip(!(await signedIn(owner)) || !(await signedIn(other)), "requires the auth module");
+    const ownerStream = await ProgressStream.open(owner);
+    const otherStream = await ProgressStream.open(other);
+    streams.push(ownerStream, otherStream);
+
+    const started = await owner.post("/api/progress", { data: { steps: 2 } });
+    test.skip(started.status() >= 500, "redis not reachable");
+    expect(started.status()).toBe(201);
+    const { jobId } = await started.json() as { jobId: string };
+    await ownerStream.until(completed(jobId));
+
+    // Every event the owner's job produced was published before the other user's
+    // job started, so it would precede that job's completion on the other stream.
+    const otherStarted = await other.post("/api/progress", { data: { steps: 1 } });
+    expect(otherStarted.status()).toBe(201);
+    const { jobId: otherJobId } = await otherStarted.json() as { jobId: string };
+    expect(await otherStream.until(completed(otherJobId))).not.toContain(JSON.stringify(jobId));
+  } finally {
+    for (const stream of streams) stream.close();
+    await owner.dispose();
+    await other.dispose();
+  }
+});

package/dist/templates/modules/job-progress/module.manifest.json

@@ -12,8 +12,8 @@
   ],
   "instructions": [
     "Configure the selected jobs and events providers before starting the API.",
-    "Watch progress:  curl -N localhost:5002/events/stream",
-    "Start a job:     curl -XPOST localhost:5002/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
-    "The stream shows job-progress events 20 -> 40 -> ... -> 100 through the selected events provider."
+    "Watch progress as a signed-in user:  curl -N -b cookies.txt 'localhost:5002/events/stream?topics=job-progress'",
+    "Start a job as the same user:        curl -b cookies.txt -XPOST localhost:5002/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
+    "The stream shows job-progress events 20 -> 40 -> ... -> 100, delivered only to the user who started the job."
   ]
 }

package/dist/templates/modules/mailer/files/apps/api/src/mail/mailer.spec.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { SmtpConfig } from "@podosoft/podokit-auth";
+import type { Transporter } from "nodemailer";
+import { mailTransport, setMailConfigStore, setMailTransport } from "./mailer";
+
+function storeOf(read: () => SmtpConfig | null) {
+  let calls = 0;
+  return {
+    store: {
+      smtpConfig: async (): Promise<SmtpConfig | null> => {
+        calls += 1;
+        return read();
+      },
+    },
+    calls: (): number => calls,
+  };
+}
+
+afterEach(() => {
+  setMailTransport(null);
+});
+
+describe("mailer transport", () => {
+  test("reuses the transport while the SMTP settings are unchanged", async () => {
+    let smtp: SmtpConfig | null = { host: "smtp.example.com", port: 587, secure: false, user: "u", pass: "p" };
+    const { store, calls } = storeOf(() => smtp);
+    setMailConfigStore(store);
+
+    const first = await mailTransport();
+    expect(await mailTransport()).toBe(first);
+    smtp = { ...smtp };
+    expect(await mailTransport()).toBe(first);
+    expect(calls()).toBe(3);
+
+    smtp = { ...smtp, host: "smtp2.example.com" };
+    const second = await mailTransport();
+    expect(second).not.toBe(first);
+    expect(await mailTransport()).toBe(second);
+  });
+
+  test("falls back to the environment when the store fails, and honours an override", async () => {
+    setMailConfigStore({
+      smtpConfig: async () => {
+        throw new Error('relation "auth_config" does not exist');
+      },
+    });
+    const fallback = await mailTransport();
+    expect(fallback).toBeDefined();
+
+    const custom = { sendMail: async () => ({}) } as unknown as Transporter;
+    setMailTransport(custom);
+    expect(await mailTransport()).toBe(custom);
+  });
+});

package/dist/templates/modules/mailer/files/apps/api/src/mail/mailer.ts

@@ -1,17 +1,18 @@
 import nodemailer, { type Transporter } from "nodemailer";
 import { createConfigStore, type SmtpConfig } from "@podosoft/podokit-auth";
 
-// Reusable email sending. SMTP is resolved in priority order, applied live (short
-// TTL) so no restart is needed:
+// Reusable email sending. SMTP is resolved in priority order, applied live so no
+// restart is needed:
 //   1. admin-configured DB settings (auth_config) — only when the auth module is
-//      installed; read via the config store, which decrypts the SMTP password;
+//      installed; read from the shared config snapshot, which decrypts the SMTP
+//      password once per change and follows the snapshot TTL;
 //   2. SMTP_* env (fallback / production secrets-manager injection);
 //   3. none → a JSON transport that logs the message so dev links are grabbable.
 // The whole transport can also be overridden from app code (setMailTransport),
 // e.g. from apps/api/src/app.extensions.ts, to plug in a provider SDK.
 type MailConfigStore = Pick<ReturnType<typeof createConfigStore>, "smtpConfig">;
 let store: MailConfigStore | undefined;
-const TTL_MS = 3_000;
+const DEFAULT_FROM = "PodoKit <no-reply@example.com>";
 
 export function setMailConfigStore(configStore: MailConfigStore): void {
   store = configStore;
@@ -49,11 +50,19 @@ function buildTransport(smtp: SmtpConfig | null): Transporter {
   });
 }
 
-let transport = buildTransport(null);
-let transportFrom = process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
-let hasSmtp = false;
-let checkedAt = 0;
-let signature = "";
+type MailSetup = {
+  smtp: SmtpConfig | null;
+  signature: string;
+  transport: Transporter;
+  from: string;
+};
+
+let setup: MailSetup = {
+  smtp: null,
+  signature: "null",
+  transport: buildTransport(null),
+  from: process.env.MAIL_FROM ?? DEFAULT_FROM,
+};
 let override: Transporter | null = null;
 
 /** Override the transport from app code (e.g. a provider SDK). Pass null to
@@ -62,31 +71,44 @@ export function setMailTransport(custom: Transporter | null): void {
   override = custom;
 }
 
-async function getTransport(): Promise<Transporter> {
-  if (override) return override;
-  if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return transport;
-  checkedAt = Date.now();
+/** The config-driven setup. The store returns the same SMTP object until the
+ *  config changes, and the transport is rebuilt only when its settings differ. */
+async function currentSetup(): Promise<MailSetup> {
+  const smtp = await resolveSmtp();
+  if (smtp === setup.smtp) return setup;
+  const signature = JSON.stringify(smtp);
+  if (signature === setup.signature) {
+    setup = { ...setup, smtp };
+    return setup;
+  }
   try {
-    const smtp = await resolveSmtp();
-    const next = JSON.stringify(smtp ?? null);
-    if (next !== signature) {
-      transport = buildTransport(smtp);
-      transportFrom = smtp?.from ?? process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
-      hasSmtp = !!smtp;
-      signature = next;
-    }
+    setup = {
+      smtp,
+      signature,
+      transport: buildTransport(smtp),
+      from: smtp?.from ?? process.env.MAIL_FROM ?? DEFAULT_FROM,
+    };
   } catch {
     /* keep the last-good transport */
   }
-  return transport;
+  return setup;
+}
+
+/** The transport `sendMail` uses now: the override, or the one built from SMTP config. */
+export async function mailTransport(): Promise<Transporter> {
+  return override ?? (await currentSetup()).transport;
 }
 
 export type Mail = { to: string; subject: string; text: string; html?: string };
 
 export async function sendMail(mail: Mail): Promise<void> {
-  const t = await getTransport();
-  const info = await t.sendMail({ from: transportFrom, ...mail });
-  if (!override && !hasSmtp) {
+  if (override) {
+    await override.sendMail({ from: setup.from, ...mail });
+    return;
+  }
+  const current = await currentSetup();
+  const info = await current.transport.sendMail({ from: current.from, ...mail });
+  if (!current.smtp) {
     // JSON transport: surface the message so the link is grabbable from logs.
     console.log(`[mailer] no SMTP configured; message not delivered:\n${info.message as string}`);
   }

package/dist/templates/modules/mailer/module.manifest.json

@@ -5,7 +5,7 @@
   "targetApp": "api",
   "dependencies": {
     "nodemailer": "^9.0.5",
-    "@podosoft/podokit-auth": "^0.4.0"
+    "@podosoft/podokit-auth": "^0.5.0"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1"

package/dist/templates/modules/object-storage-local/files/apps/api/src/storage-local/download-url.spec.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LocalObjectStore } from "@podosoft/podokit-runtime";
+import { DownloadUrlSigner, objectKeyFromPath, SignedDownloadStore } from "./download-url";
+
+let root: string | undefined;
+
+async function tempRoot(): Promise<string> {
+  root = await mkdtemp(join(tmpdir(), "podokit-download-url-"));
+  return root;
+}
+
+afterEach(async () => {
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+describe("DownloadUrlSigner", () => {
+  it("accepts only the signed key before it expires", async () => {
+    const keyFile = join(await tempRoot(), ".podokit", "download-url.key");
+    const now = 1_700_000_000_000;
+    const signer = new DownloadUrlSigner(keyFile, () => now);
+    const { expires, signature } = await signer.sign("uploads/a/file.txt", 60);
+
+    expect(expires).toBe(String(now / 1000 + 60));
+    expect(await signer.verify("uploads/a/file.txt", expires, signature)).toBe(true);
+    expect(await signer.verify("uploads/b/file.txt", expires, signature)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", String(Number(expires) + 1), signature)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", expires, `${signature.slice(0, -2)}AA`)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", undefined, signature)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", expires, undefined)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", "1e9", signature)).toBe(false);
+
+    const later = new DownloadUrlSigner(keyFile, () => now + 61_000);
+    expect(await later.verify("uploads/a/file.txt", expires, signature)).toBe(false);
+  });
+
+  it("persists one private key for every signer that shares the key file", async () => {
+    const keyFile = join(await tempRoot(), ".podokit", "download-url.key");
+    const [first, second] = [new DownloadUrlSigner(keyFile), new DownloadUrlSigner(keyFile)];
+    const [signed] = await Promise.all([first.sign("demo/hello"), second.sign("demo/other")]);
+
+    expect(await second.verify("demo/hello", signed.expires, signed.signature)).toBe(true);
+    expect((await stat(keyFile)).mode & 0o777).toBe(0o600);
+  });
+
+  it("caps the lifetime at seven days", async () => {
+    const keyFile = join(await tempRoot(), "download-url.key");
+    const signer = new DownloadUrlSigner(keyFile, () => 0);
+    const { expires } = await signer.sign("demo/hello", 365 * 24 * 60 * 60);
+    expect(Number(expires)).toBe(7 * 24 * 60 * 60);
+  });
+});
+
+describe("objectKeyFromPath", () => {
+  it("decodes each path segment and rejects malformed encodings", () => {
+    expect(objectKeyFromPath("uploads/user%20one/a.txt")).toBe("uploads/user one/a.txt");
+    expect(objectKeyFromPath("uploads/%E0%A4%A")).toBeUndefined();
+  });
+});
+
+describe("SignedDownloadStore", () => {
+  it("adds a verifiable signature to local download URLs", async () => {
+    const directory = await tempRoot();
+    const signer = new DownloadUrlSigner(join(directory, ".podokit", "download-url.key"));
+    const store = new SignedDownloadStore(
+      new LocalObjectStore({ rootDirectory: directory, publicBaseUrl: "/files/content" }),
+      signer,
+      "/files/content",
+    );
+    await store.put("uploads/user one.txt", "hello", { contentType: "text/plain" });
+
+    const url = new URL(await store.getDownloadUrl("uploads/user one.txt"), "http://localhost");
+    expect(url.pathname).toBe("/files/content/uploads/user%20one.txt");
+    expect(
+      await signer.verify(
+        "uploads/user one.txt",
+        url.searchParams.get("expires") ?? undefined,
+        url.searchParams.get("signature") ?? undefined,
+      ),
+    ).toBe(true);
+    await expect(store.getDownloadUrl("../outside.txt")).rejects.toThrow("safe relative path");
+  });
+});