@podosoft/podokit 1.5.0 → 1.6.0

package/dist/templates/modules/auth/files/apps/api/src/auth/schema-recheck.ts

@@ -0,0 +1,44 @@
+/** The shortest time between two rebuilds while Better Auth reports a schema mismatch. */
+export const SCHEMA_RECHECK_INTERVAL_MS = 2_000;
+
+export interface SchemaCheckedAuth {
+  $context: Promise<{ checkSchema?: (() => Promise<void> | undefined) | undefined }>;
+}
+
+export interface SchemaRecheckOptions {
+  intervalMs?: number;
+  now?: () => number;
+}
+
+export function isSchemaMismatch(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "SCHEMA_MISMATCH";
+}
+
+/**
+ * Better Auth keeps a schema mismatch it found until a migration run by the
+ * same process clears it. An API that started before `migrate:all` ran in
+ * another process, such as a separate container, therefore failed every
+ * sign-in until it restarted. The returned function calls `rebuild` when
+ * `auth` holds a mismatch, at most once per interval; the new instance checks
+ * the database again, so the first request after the migration succeeds.
+ */
+export function createSchemaRecheck(
+  options: SchemaRecheckOptions = {},
+): (auth: SchemaCheckedAuth, rebuild: () => void) => Promise<void> {
+  const intervalMs = options.intervalMs ?? SCHEMA_RECHECK_INTERVAL_MS;
+  const now = options.now ?? Date.now;
+  let rebuiltAt = Number.NEGATIVE_INFINITY;
+  return async (auth, rebuild) => {
+    // Nothing is pending once the schema is known to be clean.
+    const pending = (await auth.$context).checkSchema?.();
+    if (!pending) return;
+    try {
+      await pending;
+    } catch (error) {
+      // A failure to reach the database is not kept, so only a mismatch needs a rebuild.
+      if (!isSchemaMismatch(error) || now() - rebuiltAt < intervalMs) return;
+      rebuiltAt = now();
+      rebuild();
+    }
+  };
+}

package/dist/templates/modules/auth/files/apps/api/src/auth-config/auth-config.service.ts

@@ -11,6 +11,7 @@ import {
   SUPPORTED_SOCIAL_PROVIDERS,
 } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { AUTH_CONFIG_DEFAULTS } from "../auth/auth-config-store";
 import { refreshAuthNow } from "../auth/auth-provider";
 import {
   readAuthConfigRow,
@@ -123,7 +124,7 @@ export class AuthConfigService {
   async describe(): Promise<AuthConfigView> {
     const rows = await this.rows();
     const byKey = new Map(rows.map((row) => [row.key, row]));
-    const environment = envAuthConfig();
+    const environment = envAuthConfig(AUTH_CONFIG_DEFAULTS);
     const social: Record<string, SocialProviderView> = {};
 
     for (const row of rows) {

package/dist/templates/modules/auth/files/apps/api/src/migrate.ts

@@ -10,6 +10,7 @@ import {
   migrateSqliteLegacyAccountIssuers,
   postgresAccountIssuerMigrationDatabase,
 } from "./auth/account-issuer-migration";
+import { assertMigrationsLoaded } from "./database/migration-files";
 import { runSqliteMigrations } from "./database/sqlite-migrator";
 
 async function runMigrations(): Promise<void> {
@@ -24,9 +25,10 @@ async function runMigrations(): Promise<void> {
   if (sqliteDatabase) {
     await runSqliteMigrations(sqliteDatabase);
   } else {
-    const { appDataSource: dataSource } = await import("./database/data-source.js");
+    const { appDataSource: dataSource, appMigrations } = await import("./database/data-source.js");
     await dataSource.initialize();
     try {
+      assertMigrationsLoaded(dataSource.migrations, appMigrations);
       await dataSource.runMigrations();
     } finally {
       await dataSource.destroy();

package/dist/templates/modules/auth/files/apps/api/src/settings/app-flags.ts

@@ -0,0 +1,9 @@
+// This owned file is never overwritten by `podo update`. Declare the
+// application's on/off settings and their defaults here. They are stored with
+// PodoKit's feature flags in app_setting: administrators change them through
+// PUT /account/settings, the API reads them with SettingsService.getBool(), and
+// GET /account/capabilities returns them as `appFlags`, so do not put anything
+// secret in a name. A missing row keeps the default. For example:
+//
+//   export const APP_FLAG_DEFAULTS = { reportsEnabled: true } satisfies Record<string, boolean>;
+export const APP_FLAG_DEFAULTS = {} satisfies Record<string, boolean>;

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { copyFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { FLAG_DEFAULTS, mergeFlagDefaults } from "./flag-defaults";
+
+describe("feature flag defaults", () => {
+  test("adds the application's flags after PodoKit's", () => {
+    const merged = mergeFlagDefaults(FLAG_DEFAULTS, { reportsEnabled: true, betaSearch: false });
+    expect(merged).toMatchObject({ twoFactor: true, phoneNumber: false, reportsEnabled: true, betaSearch: false });
+  });
+
+  test("rejects an application flag that reuses a PodoKit name", () => {
+    expect(() => mergeFlagDefaults(FLAG_DEFAULTS, { passkey: false })).toThrow(
+      "app-flags.ts redefines PodoKit feature flags: passkey",
+    );
+  });
+
+  test("reads stored application flags and keeps their defaults otherwise", async () => {
+    // A copy next to an app-flags.ts of the test's own, in the API directory.
+    const root = mkdtempSync(join(__dirname, ".app-flags-"));
+    try {
+      copyFileSync(join(__dirname, "flag-defaults.ts"), join(root, "flag-defaults.ts"));
+      writeFileSync(
+        join(root, "app-flags.ts"),
+        "export const APP_FLAG_DEFAULTS = { reportsEnabled: true, betaSearch: false };\n",
+      );
+      writeFileSync(join(root, "check.ts"), [
+        'import { APP_FLAGS, FEATURE_FLAGS, flagsFrom } from "./flag-defaults";',
+        'const flags = flagsFrom(new Map([["betaSearch", "true"], ["magicLink", "false"]]));',
+        "console.log(JSON.stringify([APP_FLAGS, FEATURE_FLAGS.includes(\"reportsEnabled\"), flags.reportsEnabled, flags.betaSearch, flags.magicLink]));",
+        "",
+      ].join("\n"));
+      const child = Bun.spawn([process.execPath, join(root, "check.ts")], { stdout: "pipe", stderr: "pipe" });
+      const [stdout, code] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+      expect({ code, stdout: stdout.trim() }).toEqual({
+        code: 0,
+        stdout: '[["reportsEnabled","betaSearch"],true,true,true,false]',
+      });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -1,14 +1,22 @@
-/** Admin-managed auth feature flags and their shipped defaults.
+import { APP_FLAG_DEFAULTS } from "./app-flags";
+
+/** Admin-managed auth feature flags and their shipped defaults, followed by the
+ *  application's flags from the owned app-flags.ts.
  *
  *  Kept free of framework/ORM imports so both SettingsService and the Better
  *  Auth feature gate (loaded by auth.ts, including when
  *  the better-auth CLI evaluates auth.ts for migrations) can import it safely.
  *
- *  Must match the rows seeded by the InitAppSettings migration. phoneNumber is
- *  off by default because real delivery needs an SMS provider. */
-export type FeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider" | "require2fa";
+ *  The PodoKit defaults must match the rows seeded by the InitAppSettings
+ *  migration. phoneNumber is off by default because real delivery needs an SMS
+ *  provider. */
+export type PodokitFeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider" | "require2fa";
+
+export type AppFlag = keyof typeof APP_FLAG_DEFAULTS;
 
-export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
+export type FeatureFlag = PodokitFeatureFlag | AppFlag;
+
+const PODOKIT_FLAG_DEFAULTS: Record<PodokitFeatureFlag, boolean> = {
   twoFactor: true,
   magicLink: true,
   emailOtp: true,
@@ -26,8 +34,25 @@ export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
   require2fa: false,
 };
 
+/** PodoKit's defaults with the application's; an application flag may not reuse a PodoKit name. */
+export function mergeFlagDefaults<App extends Record<string, boolean>>(
+  podokit: Record<PodokitFeatureFlag, boolean>,
+  app: App,
+): Record<PodokitFeatureFlag | keyof App, boolean> {
+  const redefined = Object.keys(app).filter((flag) => flag in podokit);
+  if (redefined.length > 0) {
+    throw new Error(`app-flags.ts redefines PodoKit feature flags: ${redefined.join(", ")}`);
+  }
+  return { ...podokit, ...app };
+}
+
+export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = mergeFlagDefaults(PODOKIT_FLAG_DEFAULTS, APP_FLAG_DEFAULTS);
+
 export const FEATURE_FLAGS = Object.keys(FLAG_DEFAULTS) as FeatureFlag[];
 
+/** The application's flags, which the capabilities endpoint returns as `appFlags`. */
+export const APP_FLAGS = Object.keys(APP_FLAG_DEFAULTS) as AppFlag[];
+
 /** Stored values override the shipped defaults; a missing row keeps the default. */
 export function flagsFrom(settings: ReadonlyMap<string, string>): Record<FeatureFlag, boolean> {
   const flags = { ...FLAG_DEFAULTS };

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

@@ -6,9 +6,12 @@
   "managedOverrides": [
     ".claude/skills/podokit-configure-auth/**"
   ],
+  "ownedGlobs": [
+    "apps/api/src/settings/app-flags.ts"
+  ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.5.0",
-    "@podosoft/podokit-contracts": "^0.5.0",
+    "@podosoft/podokit-auth": "^0.6.0",
+    "@podosoft/podokit-contracts": "^0.6.0",
     "better-auth": "^1.7.7",
     "pg": "^8.12.0",
     "@better-auth/api-key": "^1.7.7",
@@ -28,6 +31,9 @@
     "# makes previously saved DB secrets undecryptable.",
     "BETTER_AUTH_SECRET=change-me-in-production-min-32-characters",
     "BETTER_AUTH_URL=http://localhost:5002",
+    "# The name authenticator apps and passkey prompts show. Unset, it is the site",
+    "# name from the admin Settings, then the project name.",
+    "# AUTH_APP_NAME=",
     "# Everything below is optional. OAuth providers, SMTP, and server-enforced",
     "# toggles are configured on the admin Settings page and applied without restart.",
     "# Email/SMTP is provided by the mailer module (see its .env block).",

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import type { ConnectionOptions } from "bullmq";
+import { Queue, type ConnectionOptions } from "bullmq";
 import { BullMqJobQueue, externalJobId, parseExternalJobId } from "./bullmq-job.queue";
 import { producerConnection, reconnectDelay, redisConnection } from "./queue";
 
@@ -128,3 +128,59 @@ describe("BullMqJobQueue while Redis is unavailable", () => {
     }
   });
 });
+
+describe("BullMqJobQueue schedules", () => {
+  it("rejects an invalid schedule before keeping it", async () => {
+    const queue = new BullMqJobQueue(producerAt(closedPort()));
+    try {
+      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");
+    } finally {
+      await queue.close();
+    }
+  });
+
+  it("keeps a schedule while Redis is unreachable instead of failing", async () => {
+    const queue = new BullMqJobQueue(producerAt(closedPort()));
+    try {
+      await expect(queue.schedule("nightly", "report", {}, { cron: "0 3 * * *" })).resolves.toBeUndefined();
+      await expect(queue.unschedule("nightly")).resolves.toBeUndefined();
+    } finally {
+      await queue.close();
+    }
+  });
+});
+
+// Runs against the Redis the app's environment names (REDIS_URL or REDIS_HOST, as
+// in .env); skipped when neither is set.
+describe.skipIf(!process.env.REDIS_URL && !process.env.REDIS_HOST)("BullMqJobQueue schedules in Redis", () => {
+  const REDIS = process.env;
+  it("applies schedules on connect, again after Redis lost them, and removes them", async () => {
+    const name = `schedule-test-${crypto.randomUUID()}`;
+    const queue = new BullMqJobQueue(producerConnection(REDIS));
+    const inspect = new Queue(name, { connection: redisConnection(REDIS) });
+    try {
+      await queue.schedule("hourly", name, { scope: "all" }, { everyMs: 3_600_000 });
+      await queue.schedule("nightly", name, {}, { cron: "0 3 * * *", timezone: "Asia/Seoul" });
+      expect(await inspect.getJobScheduler("hourly")).toBeUndefined();
+
+      await queue.connect();
+      expect(await inspect.getJobScheduler("hourly")).toMatchObject({ every: 3_600_000, name });
+      expect(await inspect.getJobScheduler("nightly")).toMatchObject({ pattern: "0 3 * * *", tz: "Asia/Seoul" });
+
+      // A Redis that lost its data gets the schedules back on the next connect.
+      await inspect.removeJobScheduler("hourly");
+      await queue.connect();
+      expect(await inspect.getJobScheduler("hourly")).toMatchObject({ every: 3_600_000 });
+
+      await queue.unschedule("nightly");
+      expect(await inspect.getJobScheduler("nightly")).toBeUndefined();
+      expect(await inspect.getJobSchedulersCount()).toBe(1);
+    } finally {
+      await queue.close();
+      await inspect.obliterate({ force: true });
+      await inspect.close();
+    }
+  });
+});

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

@@ -1,13 +1,16 @@
 import { AppException } from "@podosoft/podokit-contracts";
 import { Queue, RedisConnection, Worker, type ConnectionOptions, type RedisClient } from "bullmq";
-import type {
-  EnqueueOptions,
-  JobHandler,
-  JobQueue,
-  JobReference,
-  JobSnapshot,
-  JobStatus,
-  Unsubscribe,
+import cronParser from "cron-parser";
+import {
+  assertRepeatOptions,
+  type EnqueueOptions,
+  type JobHandler,
+  type JobQueue,
+  type JobReference,
+  type JobSnapshot,
+  type JobStatus,
+  type RepeatOptions,
+  type Unsubscribe,
 } from "@podosoft/podokit-runtime";
 import type { SupervisedConnection } from "../core/services";
 import { producerConnection, redisConnection } from "./queue";
@@ -45,6 +48,24 @@ export function jobsUnavailable(): AppException {
   return new AppException("JOBS_UNAVAILABLE", "Background jobs are temporarily unavailable.", 503);
 }
 
+function isJobsUnavailable(error: unknown): boolean {
+  return error instanceof AppException && error.code === "JOBS_UNAVAILABLE";
+}
+
+interface Schedule {
+  name: string;
+  payload: unknown;
+  repeat: RepeatOptions;
+}
+
+/** Rejects a schedule BullMQ could not run, before it is kept. */
+function assertSchedule(repeat: RepeatOptions): void {
+  assertRepeatOptions(repeat);
+  if (repeat.cron !== undefined) {
+    cronParser.parseExpression(repeat.cron, { tz: repeat.timezone ?? "UTC" }).next();
+  }
+}
+
 /**
  * Adds and reads jobs over one producer connection that the service registry
  * supervises, and runs in-process handlers on BullMQ workers, which keep their
@@ -53,6 +74,9 @@ export function jobsUnavailable(): AppException {
 export class BullMqJobQueue implements JobQueue, SupervisedConnection {
   private readonly queues = new Map<string, Queue>();
   private readonly workers = new Map<string, Worker>();
+  private readonly schedules = new Map<string, Schedule>();
+  // Schedules to delete from Redis once it is reachable: id to queue name.
+  private readonly removals = new Map<string, string>();
   private producer: RedisConnection;
   private lostListener?: (reason: unknown) => void;
   private closed = false;
@@ -65,10 +89,17 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     this.lostListener = listener;
   }
 
-  /** Opens the producer connection. */
+  /**
+   * Opens the producer connection and applies every schedule, so a Redis that
+   * lost them, such as one restarted without persistence, gets them back.
+   */
   async connect(): Promise<void> {
     const client = await this.producer.client;
     if (client.status !== "ready") await client.connect();
+    await this.command(async (ready) => {
+      for (const id of [...this.removals.keys()]) await this.removeSchedule(ready, id);
+      for (const id of this.schedules.keys()) await this.applySchedule(ready, id);
+    });
   }
 
   /** Rejects while Redis is unreachable or slower to answer than `REDIS_COMMAND_TIMEOUT_MS`. */
@@ -110,6 +141,27 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     };
   }
 
+  async schedule(id: string, name: string, payload: unknown, repeat: RepeatOptions): Promise<void> {
+    assertSchedule(repeat);
+    const previous = this.schedules.get(id);
+    // A scheduler lives in its queue, so a schedule that moves leaves the old one.
+    if (previous && previous.name !== name) this.removals.set(id, previous.name);
+    if (this.removals.get(id) === name) this.removals.delete(id);
+    this.schedules.set(id, { name, payload, repeat });
+    await this.whenConnected(async (client) => {
+      if (this.removals.has(id)) await this.removeSchedule(client, id);
+      await this.applySchedule(client, id);
+    });
+  }
+
+  async unschedule(id: string): Promise<void> {
+    const schedule = this.schedules.get(id);
+    if (!schedule) return;
+    this.schedules.delete(id);
+    this.removals.set(id, schedule.name);
+    await this.whenConnected((client) => this.removeSchedule(client, id));
+  }
+
   process(name: string, handler: JobHandler): Promise<Unsubscribe> {
     if (this.workers.has(name)) throw new Error(`A handler is already registered for job ${name}`);
     const worker = new Worker(
@@ -140,6 +192,38 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     await this.producer.close(true);
   }
 
+  private async applySchedule(client: RedisClient, id: string): Promise<void> {
+    const schedule = this.schedules.get(id);
+    if (!schedule) return;
+    const { cron, everyMs, timezone } = schedule.repeat;
+    await this.queue(schedule.name, client).upsertJobScheduler(
+      id,
+      cron !== undefined ? { pattern: cron, tz: timezone ?? "UTC" } : { every: everyMs },
+      { name: schedule.name, data: schedule.payload },
+    );
+  }
+
+  private async removeSchedule(client: RedisClient, id: string): Promise<void> {
+    const name = this.removals.get(id);
+    if (name === undefined) return;
+    await this.queue(name, client).removeJobScheduler(id);
+    if (this.removals.get(id) === name) this.removals.delete(id);
+  }
+
+  /**
+   * Runs `send` while the producer is connected. Otherwise, or when Redis goes
+   * away during it, the next connect() applies the change instead.
+   */
+  private async whenConnected(send: (client: RedisClient) => Promise<void>): Promise<void> {
+    const client = await this.producer.client;
+    if (client.status !== "ready") return;
+    try {
+      await this.command(send);
+    } catch (error) {
+      if (!isJobsUnavailable(error)) throw error;
+    }
+  }
+
   /**
    * Runs `send` on the producer connection and fails it with JOBS_UNAVAILABLE
    * while the connection is closed or when Redis does not answer in time.

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/worker.module.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "bun:test";
+import type { Processor } from "bullmq";
+import { DEMO_QUEUE } from "./queue";
+import { collectWorkers, type WorkerDefinition } from "./worker.module";
+
+const processor: Processor = async () => undefined;
+
+describe("worker definitions", () => {
+  it("adds the application's queues after PodoKit's and releases them last first", async () => {
+    const released: string[] = [];
+    const collected = await collectWorkers(async (setup) => {
+      setup.onClose(() => { released.push("database"); });
+      setup.onClose(async () => { released.push("cache"); });
+      return [{ queue: "reports", processor, options: { concurrency: 2 } }];
+    });
+    expect(collected.definitions.map((definition) => definition.queue)).toEqual([DEMO_QUEUE, "reports"]);
+    expect(collected.definitions[1]?.options).toEqual({ concurrency: 2 });
+    await collected.release();
+    expect(released).toEqual(["cache", "database"]);
+  });
+
+  it("refuses two workers for one queue and releases what was opened", async () => {
+    const released: string[] = [];
+    const duplicate: WorkerDefinition = { queue: DEMO_QUEUE, processor };
+    await expect(collectWorkers(async (setup) => {
+      setup.onClose(() => { released.push("database"); });
+      return [duplicate];
+    })).rejects.toThrow(`More than one worker for queue ${DEMO_QUEUE}`);
+    expect(released).toEqual(["database"]);
+  });
+
+  it("releases what was opened when the application setup fails", async () => {
+    const released: string[] = [];
+    await expect(collectWorkers(async (setup) => {
+      setup.onClose(() => { released.push("database"); });
+      throw new Error("no database");
+    })).rejects.toThrow("no database");
+    expect(released).toEqual(["database"]);
+  });
+});

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/worker.module.ts

@@ -1,12 +1,25 @@
-import { Worker, type Processor } from "bullmq";
+import { Worker, type Processor, type WorkerOptions } from "bullmq";
+import { configureWorkers } from "../worker.extensions";
 import { processDemoJob } from "./demo.processor";
 import { DEMO_QUEUE, redisConnection } from "./queue";
 // podokit:begin:worker-imports
 // podokit:end:worker-imports
 
-interface WorkerDefinition {
+export interface WorkerDefinition {
   queue: string;
   processor: Processor;
+  /** BullMQ worker options other than the connection, such as `concurrency`. */
+  options?: Omit<WorkerOptions, "connection">;
+}
+
+export interface WorkerSetup {
+  /** Runs `close` when the worker process stops, after its workers; the last one registered runs first. */
+  onClose(close: () => void | Promise<void>): void;
+}
+
+export interface WorkerRuntime {
+  workers: Worker[];
+  close(): Promise<void>;
 }
 
 const definitions: WorkerDefinition[] = [
@@ -15,8 +28,42 @@ const definitions: WorkerDefinition[] = [
   // podokit:end:worker-processors
 ];
 
-export function startWorkers(): Worker[] {
-  return definitions.map(({ queue, processor }) =>
-    new Worker(queue, processor, { connection: redisConnection() })
+export interface CollectedWorkers {
+  definitions: WorkerDefinition[];
+  /** Releases what `configure` opened. */
+  release(): Promise<void>;
+}
+
+/** PodoKit's queues followed by the application's from worker.extensions.ts; one worker per queue. */
+export async function collectWorkers(
+  configure: (setup: WorkerSetup) => Promise<WorkerDefinition[]> = configureWorkers,
+): Promise<CollectedWorkers> {
+  const closers: Array<() => void | Promise<void>> = [];
+  const release = async (): Promise<void> => {
+    for (const close of closers.splice(0).reverse()) await close();
+  };
+  try {
+    const all = [...definitions, ...await configure({ onClose: (close) => closers.push(close) })];
+    const queues = all.map((definition) => definition.queue);
+    const repeated = queues.filter((queue, index) => queues.indexOf(queue) !== index);
+    if (repeated.length > 0) throw new Error(`More than one worker for queue ${[...new Set(repeated)].join(", ")}`);
+    return { definitions: all, release };
+  } catch (error) {
+    await release();
+    throw error;
+  }
+}
+
+export async function startWorkers(): Promise<WorkerRuntime> {
+  const { definitions: all, release } = await collectWorkers();
+  const workers = all.map(({ queue, processor, options }) =>
+    new Worker(queue, processor, { ...options, connection: redisConnection() })
   );
+  return {
+    workers,
+    close: async (): Promise<void> => {
+      await Promise.all(workers.map((worker) => worker.close()));
+      await release();
+    },
+  };
 }

package/dist/templates/modules/bullmq/files/apps/api/src/main-worker.ts

@@ -6,16 +6,18 @@ if (PROVIDERS.jobs !== "bullmq") {
   throw new Error("The BullMQ worker cannot start unless jobs=bullmq is selected");
 }
 
-const workers = startWorkers();
+const runtime = startWorkers();
 
-for (const worker of workers) {
-  worker.on("failed", (job, error) => {
-    process.stderr.write(`Process job failed: ${job?.id ?? "unknown"} ${error.message}\n`);
-  });
-}
+void runtime.then(({ workers }) => {
+  for (const worker of workers) {
+    worker.on("failed", (job, error) => {
+      process.stderr.write(`Process job failed: ${job?.id ?? "unknown"} ${error.message}\n`);
+    });
+  }
+});
 
 for (const signal of ["SIGINT", "SIGTERM"] as const) {
   process.once(signal, () => {
-    void Promise.all(workers.map((worker) => worker.close())).finally(() => process.exit(0));
+    void runtime.then((started) => started.close()).finally(() => process.exit(0));
   });
 }

package/dist/templates/modules/bullmq/files/apps/api/src/worker.extensions.ts

@@ -0,0 +1,13 @@
+import type { WorkerDefinition, WorkerSetup } from "./jobs/worker.module";
+
+// This owned file is never overwritten by `podo update`. Return the queues the
+// BullMQ worker process (`main-worker.ts`) consumes for the application, next to
+// PodoKit's. Open what the processors need here and release it with
+// `setup.onClose`, which runs after the workers stop. For example:
+//
+//   const database = new Database(validateEnv(process.env));
+//   setup.onClose(() => database.close());
+//   return [{ queue: "reports", processor: (job) => buildReport(database, job.data), options: { concurrency: 2 } }];
+export async function configureWorkers(_setup: WorkerSetup): Promise<WorkerDefinition[]> {
+  return [];
+}

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,
   };
 }