@podosoft/podokit 1.5.0 → 1.6.1

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

@@ -16,9 +16,13 @@
     "apps/api/src/jobs/**",
     "apps/api/src/main-worker.ts"
   ],
+  "ownedGlobs": [
+    "apps/api/src/worker.extensions.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
-    "bullmq": "^5.57.0"
+    "bullmq": "^5.57.0",
+    "cron-parser": "^4.9.0"
   },
   "scripts": {
     "start:worker": "bun dist/main-worker.js",

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

@@ -41,6 +41,8 @@ function fakeQueue(): FakeQueue {
       if (!handler) throw new Error(`no handler for ${job.name}`);
       await handler(payload, job);
     },
+    schedule: async () => undefined,
+    unschedule: async () => undefined,
     close: () => undefined,
   };
 }

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

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "bun:test";
 import { SQL } from "bun";
-import { LocalJobQueue } from "./local-job.queue";
+import { LocalJobQueue, nextScheduledTime, type ScheduleTimer } from "./local-job.queue";
 
 let sql: SQL | undefined;
 
@@ -66,3 +66,176 @@ describe("local job queue", () => {
     queue.close();
   });
 });
+
+/** A clock and timer the test moves by hand. */
+function manualTime(start: number): { now: () => number; timer: ScheduleTimer; advance: (to: number) => void; waiting: () => number } {
+  let now = start;
+  const timers: Array<{ at: number; task: () => void; done: boolean }> = [];
+  return {
+    now: () => now,
+    timer: {
+      after: (delayMs, task) => {
+        const entry = { at: now + delayMs, task, done: false };
+        timers.push(entry);
+        return () => { entry.done = true; };
+      },
+    },
+    advance: (to) => {
+      for (;;) {
+        const due = timers.filter((entry) => !entry.done && entry.at <= to).sort((a, b) => a.at - b.at)[0];
+        if (!due) break;
+        due.done = true;
+        now = due.at;
+        due.task();
+      }
+      now = to;
+    },
+    waiting: () => timers.filter((entry) => !entry.done).length,
+  };
+}
+
+async function scheduledJobs(database: SQL): Promise<string[]> {
+  // Scheduled jobs are added without waiting; let those inserts finish.
+  await Bun.sleep(5);
+  const rows = await database<Array<{ id: string }>>`SELECT "id" FROM "podokit_job" ORDER BY "createdAt", "id"`;
+  return rows.map((row) => row.id);
+}
+
+describe("local job schedules", () => {
+  it("adds one job for each time of an interval and keeps going", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(10_500);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.schedule("nightly", "report", { scope: "all" }, { everyMs: 1_000 });
+    await queue.start();
+    time.advance(11_000);
+    expect(await scheduledJobs(sql)).toEqual(["report:schedule:nightly:11000"]);
+    time.advance(13_200);
+    expect(await scheduledJobs(sql)).toEqual([
+      "report:schedule:nightly:11000",
+      "report:schedule:nightly:12000",
+      "report:schedule:nightly:13000",
+    ]);
+    await expect(queue.get("report:schedule:nightly:12000")).resolves.toMatchObject({ name: "report", status: "waiting" });
+    queue.close();
+    expect(time.waiting()).toBe(0);
+  });
+
+  it("replaces a schedule with the same id and stops one on unschedule", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.start();
+    await queue.schedule("sync", "sync", {}, { everyMs: 1_000 });
+    await queue.schedule("sync", "sync", {}, { everyMs: 5_000 });
+    time.advance(5_000);
+    expect(await scheduledJobs(sql)).toEqual(["sync:schedule:sync:5000"]);
+    await queue.unschedule("sync");
+    time.advance(20_000);
+    expect(await scheduledJobs(sql)).toEqual(["sync:schedule:sync:5000"]);
+    queue.close();
+  });
+
+  it("reads cron expressions in the schedule's time zone, UTC by default", () => {
+    const after = Date.UTC(2026, 0, 1, 0, 0);
+    expect(nextScheduledTime({ cron: "0 3 * * *" }, after)).toBe(Date.UTC(2026, 0, 1, 3, 0));
+    expect(nextScheduledTime({ cron: "0 3 * * *", timezone: "Asia/Seoul" }, after)).toBe(Date.UTC(2026, 0, 1, 18, 0));
+    expect(nextScheduledTime({ everyMs: 60_000 }, after + 1)).toBe(after + 60_000);
+  });
+
+  it("rejects an invalid schedule before it is kept", async () => {
+    sql = new SQL(":memory:");
+    const queue = new LocalJobQueue(sql);
+    await expect(queue.schedule("bad", "report", {}, { cron: "61 * * * *" })).rejects.toThrow();
+    await expect(queue.schedule("bad", "report", {}, { cron: "0 3 * * *", timezone: "Mars/Olympus" })).rejects.toThrow();
+    await expect(queue.schedule("bad", "report", {}, { everyMs: 10 })).rejects.toThrow("at least 1000");
+    await expect(queue.schedule("bad", "report", {}, { everyMs: 1_000 }, { keepCompleted: -1 })).rejects.toThrow(
+      "keepCompleted must be a whole number of at least 0",
+    );
+    queue.close();
+  });
+});
+
+/** Moves the clock to each time and runs the job the schedule added then. */
+async function runScheduled(queue: LocalJobQueue, time: ReturnType<typeof manualTime>, times: number[]): Promise<void> {
+  for (const at of times) {
+    time.advance(at);
+    // The schedule adds its job without waiting; let the insert finish.
+    await Bun.sleep(1);
+    expect(await queue.runOnce()).toBe(true);
+  }
+}
+
+async function finishedJobs(database: SQL): Promise<string[]> {
+  const rows = await database<Array<{ id: string; status: string }>>`
+    SELECT "id", "status" FROM "podokit_job" ORDER BY "updatedAt", "id"
+  `;
+  return rows.map((row) => `${row.id} ${row.status}`);
+}
+
+describe("local job schedule cleanup", () => {
+  it("keeps the newest finished jobs of a scheduled run's name up to the schedule's limits", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.process("report", (_payload, job) => {
+      if (job.id.endsWith(":3000") || job.id.endsWith(":5000")) throw new Error("expected failure");
+    });
+    await queue.process("other", () => undefined);
+    const other = await queue.enqueue("other", {});
+    const adHoc = await queue.enqueue("report", {});
+    while (await queue.runOnce());
+    await queue.schedule("tick", "report", {}, { everyMs: 1_000 }, { keepCompleted: 2, keepFailed: 1 });
+    await queue.start();
+    await Bun.sleep(5);
+
+    await runScheduled(queue, time, [1_000, 2_000, 3_000, 4_000, 5_000, 6_000]);
+
+    // As BullMQ trims a queue: the job enqueue() added goes too, another name's stays.
+    expect(await finishedJobs(sql)).toEqual([
+      `${other.id} completed`,
+      "report:schedule:tick:4000 completed",
+      "report:schedule:tick:5000 failed",
+      "report:schedule:tick:6000 completed",
+    ]);
+    expect(await queue.get(adHoc.id)).toBeNull();
+    queue.close();
+  });
+
+  it("removes only the run itself when a limit is 0", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.process("report", (_payload, job) => {
+      if (job.id.endsWith(":2000")) throw new Error("expected failure");
+    });
+    const adHoc = await queue.enqueue("report", {});
+    while (await queue.runOnce());
+    await queue.schedule("tick", "report", {}, { everyMs: 1_000 }, { keepCompleted: 0, keepFailed: 0 });
+    await queue.start();
+    await Bun.sleep(5);
+
+    await runScheduled(queue, time, [1_000, 2_000, 3_000]);
+
+    expect(await finishedJobs(sql)).toEqual([`${adHoc.id} completed`]);
+    queue.close();
+  });
+
+  it("keeps 100 completed runs of a schedule by default", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.process("report", () => undefined);
+    await queue.schedule("tick", "report", {}, { everyMs: 1_000 });
+    await queue.start();
+    await Bun.sleep(5);
+
+    await runScheduled(queue, time, Array.from({ length: 105 }, (_, index) => (index + 1) * 1_000));
+
+    const kept = await finishedJobs(sql);
+    expect(kept).toHaveLength(100);
+    expect(kept[0]).toBe("report:schedule:tick:6000 completed");
+    expect(kept.at(-1)).toBe("report:schedule:tick:105000 completed");
+    queue.close();
+  });
+});

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

@@ -1,11 +1,17 @@
 import type { SQL } from "bun";
+import cronParser from "cron-parser";
 import {
+  assertRepeatOptions,
   type EnqueueOptions,
   type JobHandler,
   type JobQueue,
   type JobReference,
   type JobSnapshot,
   type JobStatus,
+  type RepeatOptions,
+  type ScheduleOptions,
+  type ScheduleRetention,
+  scheduleRetention,
   type Unsubscribe,
 } from "@podosoft/podokit-runtime";
 
@@ -22,15 +28,58 @@ interface JobRow {
   error: string | null;
 }
 
+export interface ScheduleTimer {
+  /** Runs `task` once after `delayMs`; the returned function cancels it. */
+  after(delayMs: number, task: () => void): () => void;
+}
+
 export interface LocalJobQueueOptions {
   pollIntervalMs?: number;
   now?: () => number;
+  /** Waits for schedules; an unref'd setTimeout by default. */
+  timer?: ScheduleTimer;
+}
+
+interface Schedule {
+  id: string;
+  name: string;
+  payload: unknown;
+  repeat: RepeatOptions;
+  retention: ScheduleRetention;
+  cancel?: () => void;
+}
+
+type FinishedStatus = "completed" | "failed";
+
+// A scheduled job's deduplication key: this prefix, the schedule id, ":", and the time.
+const SCHEDULE_KEY = "schedule:";
+
+// setTimeout fires at once for a delay above 2^31 - 1 ms, so longer waits are split.
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+
+const unrefTimer: ScheduleTimer = {
+  after: (delayMs, task) => {
+    const timer = setTimeout(task, delayMs);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+  },
+};
+
+/** The first time after `after` (epoch milliseconds) that `repeat` adds a job. */
+export function nextScheduledTime(repeat: RepeatOptions, after: number): number {
+  if (repeat.everyMs !== undefined) return (Math.floor(after / repeat.everyMs) + 1) * repeat.everyMs;
+  return cronParser
+    .parseExpression(repeat.cron ?? "", { currentDate: new Date(after), tz: repeat.timezone ?? "UTC" })
+    .next()
+    .getTime();
 }
 
 export class LocalJobQueue implements JobQueue {
   private readonly handlers = new Map<string, JobHandler>();
+  private readonly schedules = new Map<string, Schedule>();
   private readonly pollIntervalMs: number;
   private readonly now: () => number;
+  private readonly scheduleTimer: ScheduleTimer;
   private timer?: ReturnType<typeof setTimeout>;
   private started = false;
   private initialized?: Promise<void>;
@@ -44,6 +93,7 @@ export class LocalJobQueue implements JobQueue {
       throw new Error("pollIntervalMs must be an integer of at least 10");
     }
     this.now = options.now ?? Date.now;
+    this.scheduleTimer = options.timer ?? unrefTimer;
   }
 
   initialize(): Promise<void> {
@@ -63,7 +113,8 @@ export class LocalJobQueue implements JobQueue {
     if (this.started) return;
     await this.initialize();
     this.started = true;
-    this.schedule(0);
+    this.poll(0);
+    for (const schedule of this.schedules.values()) this.arm(schedule);
   }
 
   async enqueue(
@@ -118,6 +169,29 @@ export class LocalJobQueue implements JobQueue {
     });
   }
 
+  async schedule(
+    id: string,
+    name: string,
+    payload: unknown,
+    repeat: RepeatOptions,
+    options?: ScheduleOptions,
+  ): Promise<void> {
+    assertRepeatOptions(repeat);
+    const retention = scheduleRetention(options);
+    // Rejects an invalid cron expression or time zone now rather than at the first run.
+    nextScheduledTime(repeat, this.now());
+    if (JSON.stringify(payload) === undefined) throw new Error("Job payload must be JSON serializable");
+    this.schedules.get(id)?.cancel?.();
+    const schedule: Schedule = { id, name, payload, repeat, retention };
+    this.schedules.set(id, schedule);
+    if (this.started) this.arm(schedule);
+  }
+
+  async unschedule(id: string): Promise<void> {
+    this.schedules.get(id)?.cancel?.();
+    this.schedules.delete(id);
+  }
+
   async runOnce(): Promise<boolean> {
     await this.initialize();
     const now = this.now();
@@ -147,6 +221,7 @@ export class LocalJobQueue implements JobQueue {
         SET "status" = 'completed', "updatedAt" = ${completedAt}, "error" = NULL
         WHERE "id" = ${row.id}
       `;
+      await this.removeFinished(row, "completed");
     } catch (error) {
       await this.fail(row, error);
     }
@@ -157,9 +232,41 @@ export class LocalJobQueue implements JobQueue {
     this.started = false;
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined;
+    for (const schedule of this.schedules.values()) schedule.cancel?.();
     this.handlers.clear();
   }
 
+  /**
+   * Adds the schedule's next job when its time comes. The job id names the
+   * schedule and the time, so a job is added once for each time.
+   */
+  private arm(schedule: Schedule, after = this.now()): void {
+    const at = nextScheduledTime(schedule.repeat, after);
+    schedule.cancel = this.waitUntil(at, () => {
+      if (!this.started || this.schedules.get(schedule.id) !== schedule) return;
+      void this.enqueue(schedule.name, schedule.payload, { deduplicationKey: `${SCHEDULE_KEY}${schedule.id}:${at}` })
+        .catch((error: unknown) => {
+          const message = error instanceof Error ? error.message : String(error);
+          process.stderr.write(`Add scheduled job failed: ${schedule.id} ${message}\n`);
+        });
+      this.arm(schedule, Math.max(this.now(), at));
+    });
+  }
+
+  private waitUntil(at: number, task: () => void): () => void {
+    let cancel = (): void => undefined;
+    const step = (): void => {
+      const delay = at - this.now();
+      if (delay <= 0) {
+        task();
+        return;
+      }
+      cancel = this.scheduleTimer.after(Math.min(delay, MAX_TIMER_DELAY_MS), step);
+    };
+    cancel = this.scheduleTimer.after(Math.max(0, Math.min(at - this.now(), MAX_TIMER_DELAY_MS)), step);
+    return () => cancel();
+  }
+
   private async createTables(): Promise<void> {
     await this.sql`
       CREATE TABLE IF NOT EXISTS "podokit_job" (
@@ -179,9 +286,48 @@ export class LocalJobQueue implements JobQueue {
       CREATE INDEX IF NOT EXISTS "podokit_job_pending"
       ON "podokit_job" ("status", "availableAt", "createdAt")
     `;
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "podokit_job_finished"
+      ON "podokit_job" ("name", "status", "updatedAt")
+    `;
+  }
+
+  /** The schedule whose job id `row` has, while that schedule is kept. */
+  private scheduleOf(row: JobRow): Schedule | undefined {
+    for (const schedule of this.schedules.values()) {
+      const prefix = `${schedule.name}:${SCHEDULE_KEY}${schedule.id}:`;
+      if (schedule.name === row.name && row.id.startsWith(prefix) && /^\d+$/.test(row.id.slice(prefix.length))) {
+        return schedule;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * After a scheduled run finishes, keeps the newest finished jobs of its name
+   * up to the schedule's limit, as BullMQ trims a queue, or removes only the
+   * run when the limit is 0.
+   */
+  private async removeFinished(row: JobRow, status: FinishedStatus): Promise<void> {
+    const schedule = this.scheduleOf(row);
+    if (!schedule) return;
+    const keep = status === "completed" ? schedule.retention.keepCompleted : schedule.retention.keepFailed;
+    if (keep === 0) {
+      await this.sql`DELETE FROM "podokit_job" WHERE "id" = ${row.id}`;
+      return;
+    }
+    await this.sql`
+      DELETE FROM "podokit_job"
+      WHERE "name" = ${row.name} AND "status" = ${status} AND "id" NOT IN (
+        SELECT "id" FROM "podokit_job"
+        WHERE "name" = ${row.name} AND "status" = ${status}
+        ORDER BY "updatedAt" DESC, "id" DESC
+        LIMIT ${keep}
+      )
+    `;
   }
 
-  private schedule(delay: number): void {
+  private poll(delay: number): void {
     if (!this.started) return;
     this.timer = setTimeout(() => {
       void this.runOnce()
@@ -189,7 +335,7 @@ export class LocalJobQueue implements JobQueue {
           const message = error instanceof Error ? error.message : String(error);
           process.stderr.write(`Process local job failed: ${message}\n`);
         })
-        .finally(() => this.schedule(this.pollIntervalMs));
+        .finally(() => this.poll(this.pollIntervalMs));
     }, delay);
     this.timer.unref?.();
   }
@@ -206,6 +352,7 @@ export class LocalJobQueue implements JobQueue {
           "error" = ${message.slice(0, 2_000)}
       WHERE "id" = ${row.id}
     `;
+    if (!retry) await this.removeFinished(row, "failed");
   }
 
   private snapshot(row: JobRow): JobSnapshot {

package/dist/templates/modules/jobs-local/module.manifest.json

@@ -15,6 +15,9 @@
     "apps/api/src/jobs-local/**"
   ],
   "targetApp": "api",
+  "dependencies": {
+    "cron-parser": "^4.9.0"
+  },
   "env": [
     "LOCAL_JOBS_POLL_INTERVAL_MS=250"
   ],

package/dist/templates/modules/logging/files/apps/api/src/logging/logging.module.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import { loggingOptions } from "./logging.module";
+
+describe("logging options", () => {
+  test("writes JSON without the development transport in production", () => {
+    expect(loggingOptions(validateEnv({ NODE_ENV: "production" })).transport).toBeUndefined();
+  });
+
+  test("pretty-prints single lines in development", () => {
+    expect(loggingOptions(validateEnv({})).transport).toEqual({
+      target: "pino-pretty",
+      options: { singleLine: true },
+    });
+  });
+});

package/dist/templates/modules/logging/files/apps/api/src/logging/logging.module.ts

@@ -1,16 +1,21 @@
-import pino from "pino";
+import pino, { type LoggerOptions } from "pino";
+import type { AppEnv } from "../config/env.validation";
 import { LOGGER, type PodokitModule } from "../core/services";
 
+/** Pretty single-line logs in development, JSON in production. */
+export function loggingOptions(env: Pick<AppEnv, "NODE_ENV">): LoggerOptions {
+  return {
+    level: process.env.LOG_LEVEL ?? "info",
+    // pino-pretty is a development dependency, so production must not ask for it.
+    transport: env.NODE_ENV === "production"
+      ? undefined
+      : { target: "pino-pretty", options: { singleLine: true } },
+  };
+}
+
 export const loggingModule: PodokitModule = {
   name: "logging",
-  configure: (_env, services): void => {
-    const isProduction = process.env.NODE_ENV === "production";
-    const logger = pino({
-      level: process.env.LOG_LEVEL ?? "info",
-      transport: isProduction
-        ? undefined
-        : { target: "pino-pretty", options: { singleLine: true } },
-    });
-    services.override(LOGGER, logger);
+  configure: (env, services): void => {
+    services.override(LOGGER, pino(loggingOptions(env)));
   },
 };

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

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

package/dist/templates/modules/object-storage-local/files/tests/api/storage-local.api.spec.ts

@@ -1,13 +1,8 @@
 import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
+import { seededAdmin } from "../helpers/seeded-admin";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
-// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
-// spec also compiles in apps that do not install that module.
-const admin = {
-  email: "admin@example.com",
-  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
-};
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 
@@ -36,6 +31,8 @@ async function signUp(ctx: APIRequestContext): Promise<boolean> {
 
 /** Resolves false when no administrator session is available. */
 async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const admin = await seededAdmin();
+  if (!admin) return false;
   const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
   return response.ok() && ((await sessionRoles(ctx)) ?? []).includes("admin");
 }

package/dist/templates/modules/object-storage-s3/files/infra/docker/minio.compose.yml

@@ -24,12 +24,13 @@ services:
     profiles: ["dev"]
     depends_on:
       - minio
+    # -e stops at the first failing command, so a bucket that cannot be
+    # created fails this service instead of leaving uploads to fail later.
     entrypoint: >
-      /bin/sh -c "
+      /bin/sh -ec "
       until mc alias set local http://minio:9000 ${S3_ACCESS_KEY_ID:-podokit} ${S3_SECRET_ACCESS_KEY:-podokitsecret}; do echo 'waiting for minio'; sleep 1; done;
-      mc mb -p local/${S3_BUCKET:-podokit};
-      echo 'bucket ready';
-      exit 0"
+      mc mb --ignore-existing local/${S3_BUCKET:-podokit};
+      echo 'bucket ready'"
 
 volumes:
   minio-data:

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -1,13 +1,8 @@
 import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
+import { seededAdmin } from "../helpers/seeded-admin";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
-// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
-// spec also compiles in apps that do not install that module.
-const admin = {
-  email: "admin@example.com",
-  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
-};
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 
@@ -36,6 +31,8 @@ async function signUp(ctx: APIRequestContext): Promise<boolean> {
 
 /** Resolves false when no administrator session is available. */
 async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const admin = await seededAdmin();
+  if (!admin) return false;
   const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
   return response.ok() && ((await sessionRoles(ctx)) ?? []).includes("admin");
 }

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -1,4 +1,10 @@
-import { expect, test, type APIResponse } from "@playwright/test";
+import {
+  expect,
+  test,
+  type APIRequestContext,
+  type APIResponse,
+  type PlaywrightWorkerArgs,
+} from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -19,20 +25,42 @@ const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
 const authLimit = Number(process.env.RATE_LIMIT_AUTH_MAX ?? 20);
 const runtimeLimit = Number(process.env.RATE_LIMIT_RUNTIME_MAX ?? 1000);
 
-async function session(
-  playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
-) {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  const signup = await ctx.post("/api/auth/sign-up/email", {
-    data: {
-      email,
-      password: "Podokit3e-Str0ng!pw",
-      name: "Rate Limit",
-    },
+type Playwright = PlaywrightWorkerArgs["playwright"];
+const password = "Podokit3e-Str0ng!pw";
+
+function uniqueEmail(): string {
+  return `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+}
+
+// Sign-ups and sign-ins are authentication writes. From an anonymous client the
+// limiter counts them against the per-address budget that the setup project's
+// and every other spec's sign-ins share. Only this worker's first one is
+// anonymous: the later ones carry its session cookie, so the limiter counts them
+// against that session instead.
+let carrier: string | undefined;
+
+/** Run one authentication write and return a context holding the session it set. */
+async function authenticated(
+  playwright: Playwright,
+  path: "/api/auth/sign-up/email" | "/api/auth/sign-in/email",
+  data: Record<string, string>,
+): Promise<APIRequestContext> {
+  const writer = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, ...(carrier ? { cookie: carrier } : {}) },
   });
-  expect(signup.ok()).toBeTruthy();
-  return ctx;
+  const response = await writer.post(path, { data });
+  expect(response.ok(), `${path}: ${response.status()}`).toBeTruthy();
+  const storageState = await writer.storageState();
+  await writer.dispose();
+  const token = storageState.cookies.find((cookie) => cookie.name.endsWith("session_token"));
+  carrier ??= token ? `${token.name}=${token.value}` : undefined;
+  return playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin, storageState });
+}
+
+/** A new account, signed in. */
+async function session(playwright: Playwright, email = uniqueEmail()): Promise<APIRequestContext> {
+  return authenticated(playwright, "/api/auth/sign-up/email", { email, password, name: "Rate Limit" });
 }
 
 test("rate limit: health probes stay available while ordinary routes return 429 @smoke", async ({
@@ -73,10 +101,8 @@ test("rate limit: health probes stay available while ordinary routes return 429
 test("rate limit: a user's sessions share one counter and forged sessions do not get one", async ({
   playwright,
 }) => {
-  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  const password = "Podokit3e-Str0ng!pw";
-  const first = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await first.post("/api/auth/sign-up/email", { data: { email, password, name: "Rate Limit" } })).ok()).toBeTruthy();
+  const email = uniqueEmail();
+  const first = await session(playwright, email);
   const probe = await first.get("/api/cache/rate-limit-probe");
   test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
   const remaining = (response: APIResponse): number => Number(response.headers()["ratelimit-remaining"]);
@@ -86,8 +112,7 @@ test("rate limit: a user's sessions share one counter and forged sessions do not
   // session. The probe requires a session, so each request below resolves it; a
   // session counts under its user from the request after the API first resolves
   // it (or from that request when authentication runs before the limiter).
-  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
+  const second = await authenticated(playwright, "/api/auth/sign-in/email", { email, password });
   const cookie = (await first.storageState()).cookies.find((c) => c.name.endsWith("session_token"));
   expect(cookie, "sign-up set a session cookie").toBeTruthy();
   const bearer = await playwright.request.newContext({