@podosoft/podokit 1.2.0 → 1.4.0

package/dist/templates/modules/auth/files/apps/api/src/auth/postgres-pool.ts

@@ -0,0 +1,40 @@
+import { Pool, type PoolClient } from "pg";
+
+type ConnectCallback = Parameters<Pool["connect"]>[0];
+
+/** Whether `client` still waits for the reply to a query; pg sets `readyForQuery` once the server is ready for the next one. */
+function awaitingReply(client: PoolClient): boolean {
+  return Reflect.get(client, "readyForQuery") === false;
+}
+
+function discardWhileAwaitingReply(client: PoolClient): PoolClient {
+  const release = client.release;
+  client.release = (error?: Error | boolean): void => {
+    release.call(
+      client,
+      error || (awaitingReply(client) ? new Error("Released while waiting for a query reply") : undefined),
+    );
+  };
+  return client;
+}
+
+/**
+ * pg fails a query after `query_timeout` but leaves the connection waiting for
+ * the reply. `Pool.query` discards that client, but Kysely, which Better Auth
+ * runs on, releases it as healthy, so the pool would hand it out again and
+ * every later query on it would queue behind the missing reply. This pool
+ * discards a client released while it still waits for a reply: pg closes its
+ * socket, and the next query gets a new connection.
+ */
+export class AuthPostgresPool extends Pool {
+  override connect(): Promise<PoolClient>;
+  override connect(callback: ConnectCallback): void;
+  override connect(callback?: ConnectCallback): Promise<PoolClient> | void {
+    if (!callback) return super.connect().then(discardWhileAwaitingReply);
+    super.connect((error, client, done) => {
+      if (!client) return callback(error, client, done);
+      const guarded = discardWhileAwaitingReply(client);
+      callback(error, guarded, guarded.release);
+    });
+  }
+}

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

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import type { QueryRunner } from "typeorm";
+import { InitAuthConfig1720500000000 } from "../migrations/1720500000000-InitAuthConfig";
+import { readAuthConfigRow, readAuthConfigRows, writeAuthConfigRow } from "./auth-config.rows";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+async function sqliteDatabase(): Promise<SQL> {
+  const sql = new SQL(":memory:");
+  open = sql;
+  const runner = {
+    connection: { options: { type: "better-sqlite3" } },
+    query: (query: string): Promise<unknown> => sql.unsafe(query),
+  } as unknown as QueryRunner;
+  await new InitAuthConfig1720500000000().up(runner);
+  return sql;
+}
+
+describe("auth config rows on SQLite", () => {
+  it("reads the integer enabled column back as a boolean", async () => {
+    const sql = await sqliteDatabase();
+    await writeAuthConfigRow(sql, "sqlite", { key: "smtp", enabled: true, config: { host: "mail" }, secret: null });
+    await writeAuthConfigRow(sql, "sqlite", { key: "social.github", enabled: false, config: {}, secret: null });
+
+    expect(await readAuthConfigRow(sql, "smtp")).toEqual({
+      key: "smtp",
+      enabled: true,
+      config: JSON.stringify({ host: "mail" }),
+      secret: null,
+    });
+    const rows = await readAuthConfigRows(sql);
+    expect(rows.map((row) => [row.key, row.enabled])).toEqual([
+      ["smtp", true],
+      ["social.github", false],
+    ]);
+    expect(await readAuthConfigRow(sql, "server")).toBeNull();
+  });
+
+  it("keeps a boolean through a read and rewrite", async () => {
+    const sql = await sqliteDatabase();
+    await writeAuthConfigRow(sql, "sqlite", { key: "smtp", enabled: true, config: {}, secret: null });
+    const current = await readAuthConfigRow(sql, "smtp");
+    if (!current) throw new Error("expected the smtp row");
+    await writeAuthConfigRow(sql, "sqlite", { ...current, secret: "sealed" });
+    expect((await readAuthConfigRow(sql, "smtp"))?.enabled).toBe(true);
+  });
+});

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

@@ -0,0 +1,65 @@
+import type { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { authConfigParam } from "./config-param";
+
+export interface AuthConfigRow {
+  key: string;
+  enabled: boolean;
+  config: unknown;
+  secret: string | null;
+}
+
+function configObject(value: unknown): Record<string, unknown> {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === "string") {
+    try {
+      return configObject(JSON.parse(value) as unknown);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+// SQLite stores booleans as 0 or 1.
+interface StoredAuthConfigRow extends Omit<AuthConfigRow, "enabled"> {
+  enabled: boolean | number;
+}
+
+function authConfigRow(row: StoredAuthConfigRow): AuthConfigRow {
+  return { ...row, enabled: row.enabled === true || row.enabled === 1 };
+}
+
+export async function readAuthConfigRows(sql: SQL): Promise<AuthConfigRow[]> {
+  const rows = await sql<StoredAuthConfigRow[]>`
+    SELECT "key", "enabled", "config", "secret" FROM "auth_config"
+  `;
+  return rows.map(authConfigRow);
+}
+
+export async function readAuthConfigRow(sql: SQL, key: string): Promise<AuthConfigRow | null> {
+  const rows = await sql<StoredAuthConfigRow[]>`
+    SELECT "key", "enabled", "config", "secret"
+    FROM "auth_config" WHERE "key" = ${key}
+  `;
+  return rows[0] ? authConfigRow(rows[0]) : null;
+}
+
+export async function writeAuthConfigRow(
+  sql: SQL,
+  provider: DatabaseProviderName,
+  row: AuthConfigRow,
+): Promise<void> {
+  const config = authConfigParam(provider, configObject(row.config));
+  await sql`
+    INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
+    VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
+    ON CONFLICT ("key") DO UPDATE SET
+      "enabled" = EXCLUDED."enabled",
+      "config" = EXCLUDED."config",
+      "secret" = EXCLUDED."secret",
+      "updatedAt" = CURRENT_TIMESTAMP
+  `;
+}

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

@@ -12,7 +12,13 @@ import {
 } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { refreshAuthNow } from "../auth/auth-provider";
-import { authConfigParam } from "./config-param";
+import {
+  readAuthConfigRow,
+  readAuthConfigRows,
+  writeAuthConfigRow,
+  type AuthConfigRow,
+} from "./auth-config.rows";
+import { resetSessionExpirations } from "./session-expiry";
 
 export type SocialProviderView = {
   id: string;
@@ -73,13 +79,6 @@ export type AuthConfigUpdate = {
   };
 };
 
-interface AuthConfigRow {
-  key: string;
-  enabled: boolean;
-  config: unknown;
-  secret: string | null;
-}
-
 function object(value: unknown): Record<string, unknown> {
   if (value !== null && typeof value === "object" && !Array.isArray(value)) {
     return value as Record<string, unknown>;
@@ -110,30 +109,15 @@ export class AuthConfigService {
   ) {}
 
   private async rows(): Promise<AuthConfigRow[]> {
-    return this.sql<AuthConfigRow[]>`
-      SELECT "key", "enabled", "config", "secret" FROM "auth_config"
-    `;
+    return readAuthConfigRows(this.sql);
   }
 
   private async row(key: string): Promise<AuthConfigRow | null> {
-    const rows = await this.sql<AuthConfigRow[]>`
-      SELECT "key", "enabled", "config", "secret"
-      FROM "auth_config" WHERE "key" = ${key}
-    `;
-    return rows[0] ?? null;
+    return readAuthConfigRow(this.sql, key);
   }
 
   private async upsert(row: AuthConfigRow): Promise<void> {
-    const config = authConfigParam(this.provider, object(row.config));
-    await this.sql`
-      INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
-      VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
-      ON CONFLICT ("key") DO UPDATE SET
-        "enabled" = EXCLUDED."enabled",
-        "config" = EXCLUDED."config",
-        "secret" = EXCLUDED."secret",
-        "updatedAt" = CURRENT_TIMESTAMP
-    `;
+    await writeAuthConfigRow(this.sql, this.provider, row);
   }
 
   async describe(): Promise<AuthConfigView> {
@@ -216,7 +200,12 @@ export class AuthConfigService {
     if (update.server) await this.upsertServer(update.server);
     await refreshAuthNow();
     if (update.server?.sessionIdleTimeoutMinutes !== undefined) {
-      await this.resetSessionExpirations(update.server.sessionIdleTimeoutMinutes);
+      const minutes = update.server.sessionIdleTimeoutMinutes;
+      await resetSessionExpirations(
+        this.sql,
+        this.provider,
+        minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60,
+      );
     }
     return this.describe();
   }
@@ -285,14 +274,4 @@ export class AuthConfigService {
     }
     await this.upsert({ ...current, config });
   }
-
-  private async resetSessionExpirations(minutes: number | null): Promise<void> {
-    const lifetimeSeconds = minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60;
-    await this.sql`
-      UPDATE "session"
-      SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
-          "updatedAt" = CURRENT_TIMESTAMP
-      WHERE "expiresAt" > CURRENT_TIMESTAMP
-    `;
-  }
 }

package/dist/templates/modules/auth/files/apps/api/src/auth-config/session-expiry.spec.ts

@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { resetSessionExpirations } from "./session-expiry";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+describe("session expiry reset on SQLite", () => {
+  it("moves active sessions to the new lifetime and leaves expired ones", async () => {
+    const sql = new SQL(":memory:");
+    open = sql;
+    // Better Auth stores SQLite dates as ISO 8601 text.
+    await sql`CREATE TABLE "session" ("id" text PRIMARY KEY, "expiresAt" date NOT NULL, "updatedAt" date NOT NULL)`;
+    const now = new Date("2026-10-15T10:00:00.000Z");
+    const active = new Date(now.getTime() + 3_600_000).toISOString();
+    const expired = new Date(now.getTime() - 1_000).toISOString();
+    await sql`INSERT INTO "session" VALUES (${"active"}, ${active}, ${active}), (${"expired"}, ${expired}, ${expired})`;
+
+    await resetSessionExpirations(sql, "sqlite", 1_800, now);
+
+    const rows = await sql<Array<{ id: string; expiresAt: string; updatedAt: string }>>`
+      SELECT "id", "expiresAt", "updatedAt" FROM "session" ORDER BY "id"
+    `;
+    expect(rows).toEqual([
+      { id: "active", expiresAt: "2026-10-15T10:30:00.000Z", updatedAt: now.toISOString() },
+      { id: "expired", expiresAt: expired, updatedAt: expired },
+    ]);
+  });
+});

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

@@ -0,0 +1,29 @@
+import type { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+
+/** Give every active session the configured lifetime from now. */
+export async function resetSessionExpirations(
+  sql: SQL,
+  provider: DatabaseProviderName,
+  lifetimeSeconds: number,
+  now: Date = new Date(),
+): Promise<void> {
+  if (provider === "sqlite") {
+    // Better Auth stores SQLite dates as ISO 8601 text, which sorts in time
+    // order. SQLite has no interval arithmetic.
+    const current = now.toISOString();
+    const expiresAt = new Date(now.getTime() + lifetimeSeconds * 1000).toISOString();
+    await sql`
+      UPDATE "session"
+      SET "expiresAt" = ${expiresAt}, "updatedAt" = ${current}
+      WHERE "expiresAt" > ${current}
+    `;
+    return;
+  }
+  await sql`
+    UPDATE "session"
+    SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
+        "updatedAt" = CURRENT_TIMESTAMP
+    WHERE "expiresAt" > CURRENT_TIMESTAMP
+  `;
+}

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

@@ -1,6 +1,7 @@
 // Keep this first: Better Auth checks the schema when ./auth/auth creates its
-// instance, and the migrations below are what make that schema match.
-import "./auth/skip-schema-validation";
+// instance, the migrations below are what make that schema match, and they may
+// run longer than the auth pool's query timeout.
+import "./auth/maintenance-command";
 import { getMigrations } from "better-auth/db/migration";
 import { auth } from "./auth/auth";
 import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/bootstrap-admin.md

@@ -1,6 +1,8 @@
 # Bootstrap the initial administrator
 
 Use the generated database-backed command after the API build and migrations.
+With `NODE_ENV=production` it loads the bundled `dist/bootstrap-admin-runtime.js`;
+otherwise it runs the source entry. It supports PostgreSQL and SQLite.
 Do not create the first administrator through the public sign-up page.
 
 ## Set the persistent allowlist

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

@@ -1,5 +1,53 @@
 import { describe, expect, it } from "bun:test";
-import { externalJobId, parseExternalJobId } from "./bullmq-job.queue";
+import type { ConnectionOptions } from "bullmq";
+import { BullMqJobQueue, externalJobId, parseExternalJobId } from "./bullmq-job.queue";
+import { producerConnection, reconnectDelay, redisConnection } from "./queue";
+
+function producerAt(port: number): ConnectionOptions {
+  return producerConnection({
+    REDIS_HOST: "127.0.0.1",
+    REDIS_PORT: String(port),
+    REDIS_COMMAND_TIMEOUT_MS: "100",
+  });
+}
+
+function closedPort(): number {
+  const server = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+  const port = server.port;
+  server.stop(true);
+  return port;
+}
+
+/**
+ * Answers the connection handshake and INFO like Redis 7, but stops answering a
+ * connection, without closing it, once it sends any other command.
+ */
+function stallingRedis(): { port: number; stop: () => void } {
+  const info = "# Server\r\nredis_version:7.2.0\r\nloading:0\r\n";
+  const stalled = new WeakSet<object>();
+  const server = Bun.listen({
+    hostname: "127.0.0.1",
+    port: 0,
+    socket: {
+      data(socket, data) {
+        // Each command is an array of bulk strings: "*<count>", "$<length>", "<name>", ...
+        const lines = data.toString().split("\r\n");
+        lines.forEach((line, index) => {
+          if (stalled.has(socket) || !line.startsWith("*")) return;
+          const command = lines[index + 2]?.toLowerCase();
+          if (command === "client") socket.write("+OK\r\n");
+          else if (command === "info") socket.write(`$${Buffer.byteLength(info)}\r\n${info}\r\n`);
+          else stalled.add(socket);
+        });
+      },
+    },
+  });
+  return { port: server.port, stop: () => server.stop(true) };
+}
+
+async function rejection(promise: Promise<unknown>): Promise<unknown> {
+  return promise.then(() => undefined, (error: unknown) => error);
+}
 
 describe("BullMQ job identifiers", () => {
   it("round-trips queue names without exposing an ambiguous id", () => {
@@ -8,3 +56,75 @@ describe("BullMQ job identifiers", () => {
     expect(parseExternalJobId("invalid")).toBeNull();
   });
 });
+
+describe("BullMQ connections", () => {
+  it("lets workers wait for replies and gives producers a bounded, supervised connection", () => {
+    expect(redisConnection({})).toMatchObject({ maxRetriesPerRequest: null });
+    const producer = producerConnection({ REDIS_COMMAND_TIMEOUT_MS: "750" });
+    expect(producer).toMatchObject({ enableOfflineQueue: false, commandTimeout: 750, lazyConnect: true });
+    expect("retryStrategy" in producer && producer.retryStrategy?.(1)).toBeNull();
+  });
+
+  it("backs off reconnects from 250 ms up to 5 seconds", () => {
+    expect([1, 2, 3, 4, 5, 6, 30].map(reconnectDelay)).toEqual([250, 500, 1_000, 2_000, 4_000, 5_000, 5_000]);
+  });
+});
+
+describe("BullMqJobQueue while Redis is unavailable", () => {
+  it("fails enqueues and reads at once before the producer has connected", async () => {
+    const queue = new BullMqJobQueue(producerAt(closedPort()));
+    try {
+      const started = Date.now();
+      expect(await rejection(queue.enqueue("demo", { text: "hello" })))
+        .toMatchObject({ code: "JOBS_UNAVAILABLE", statusCode: 503 });
+      expect(await rejection(queue.get(externalJobId("demo", "1"))))
+        .toMatchObject({ code: "JOBS_UNAVAILABLE" });
+      expect(Date.now() - started).toBeLessThan(100);
+    } finally {
+      await queue.close();
+    }
+  });
+
+  it("reports a refused connection to the supervisor and keeps failing enqueues at once", async () => {
+    const queue = new BullMqJobQueue(producerAt(closedPort()));
+    const lost: unknown[] = [];
+    queue.onLost((reason) => { lost.push(reason); });
+    try {
+      await expect(queue.connect()).rejects.toThrow();
+      await expect(queue.ready()).rejects.toMatchObject({ code: "JOBS_UNAVAILABLE" });
+      const started = Date.now();
+      expect(await rejection(queue.enqueue("demo", {}))).toMatchObject({ code: "JOBS_UNAVAILABLE" });
+      expect(Date.now() - started).toBeLessThan(100);
+      expect(lost.length).toBeGreaterThan(0);
+    } finally {
+      await queue.close();
+    }
+  });
+
+  it("drops a connection Redis stops answering and fails at once until the supervisor reopens it", async () => {
+    const redis = stallingRedis();
+    const queue = new BullMqJobQueue(producerAt(redis.port));
+    const lost: unknown[] = [];
+    queue.onLost((reason) => { lost.push(reason); });
+    try {
+      await queue.connect();
+      let started = Date.now();
+      expect(await rejection(queue.enqueue("demo", { text: "hello" })))
+        .toMatchObject({ code: "JOBS_UNAVAILABLE", statusCode: 503 });
+      expect(Date.now() - started).toBeLessThan(1_000);
+      expect(lost.length).toBe(1);
+
+      started = Date.now();
+      expect(await rejection(queue.enqueue("demo", {}))).toMatchObject({ code: "JOBS_UNAVAILABLE" });
+      expect(Date.now() - started).toBeLessThan(100);
+
+      await queue.connect();
+      await queue.ready();
+      await Bun.sleep(50);
+      expect(lost.length).toBe(1);
+    } finally {
+      await queue.close();
+      redis.stop();
+    }
+  });
+});

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

@@ -1,4 +1,5 @@
-import { Queue, Worker } from "bullmq";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Queue, RedisConnection, Worker, type ConnectionOptions, type RedisClient } from "bullmq";
 import type {
   EnqueueOptions,
   JobHandler,
@@ -8,10 +9,15 @@ import type {
   JobStatus,
   Unsubscribe,
 } from "@podosoft/podokit-runtime";
-import { redisConnection } from "./queue";
+import type { SupervisedConnection } from "../core/services";
+import { producerConnection, redisConnection } from "./queue";
 
 const ID_SEPARATOR = "~";
 
+// BullMQ would otherwise wait for Redis and ask its version before the first
+// command, which keeps a call pending while Redis is down instead of failing it.
+const NO_STARTUP_ROUND_TRIP = { skipWaitingForReady: true, skipVersionCheck: true } as const;
+
 export function externalJobId(name: string, id: string): string {
   return `${encodeURIComponent(name)}${ID_SEPARATOR}${id}`;
 }
@@ -31,23 +37,57 @@ function statusOf(state: string): JobStatus {
   return "waiting";
 }
 
-export class BullMqJobQueue implements JobQueue {
+function isReplyTimeout(error: unknown): boolean {
+  return error instanceof Error && error.message === "Command timed out";
+}
+
+export function jobsUnavailable(): AppException {
+  return new AppException("JOBS_UNAVAILABLE", "Background jobs are temporarily unavailable.", 503);
+}
+
+/**
+ * Adds and reads jobs over one producer connection that the service registry
+ * supervises, and runs in-process handlers on BullMQ workers, which keep their
+ * own blocking connections and reconnect by themselves.
+ */
+export class BullMqJobQueue implements JobQueue, SupervisedConnection {
   private readonly queues = new Map<string, Queue>();
   private readonly workers = new Map<string, Worker>();
+  private producer: RedisConnection;
+  private lostListener?: (reason: unknown) => void;
+  private closed = false;
+
+  constructor(private readonly connection: ConnectionOptions = producerConnection()) {
+    this.producer = this.openProducer();
+  }
+
+  onLost(listener: (reason: unknown) => void): void {
+    this.lostListener = listener;
+  }
+
+  /** Opens the producer connection. */
+  async connect(): Promise<void> {
+    const client = await this.producer.client;
+    if (client.status !== "ready") await client.connect();
+  }
+
+  /** Rejects while Redis is unreachable or slower to answer than `REDIS_COMMAND_TIMEOUT_MS`. */
+  async ready(): Promise<void> {
+    await this.command((client) => client.info());
+  }
 
   async enqueue(
     name: string,
     payload: unknown,
     options: EnqueueOptions = {},
   ): Promise<JobReference> {
-    const queue = this.queue(name);
-    const job = await queue.add(name, payload, {
+    const job = await this.command((client) => this.queue(name, client).add(name, payload, {
       ...(options.delayMs === undefined ? {} : { delay: options.delayMs }),
       ...(options.attempts === undefined ? {} : { attempts: options.attempts }),
       ...(options.deduplicationKey === undefined
         ? {}
         : { deduplication: { id: options.deduplicationKey } }),
-    });
+    }));
     if (job.id === undefined) throw new Error("BullMQ did not assign a job id");
     return { id: externalJobId(name, job.id), name };
   }
@@ -55,12 +95,13 @@ export class BullMqJobQueue implements JobQueue {
   async get(externalId: string): Promise<JobSnapshot | null> {
     const parsed = parseExternalJobId(externalId);
     if (!parsed) return null;
-    const job = await this.queue(parsed.name).getJob(parsed.id);
+    const job = await this.command((client) => this.queue(parsed.name, client).getJob(parsed.id));
     if (!job) return null;
+    const state = await this.command(() => job.getState());
     return {
       id: externalId,
       name: parsed.name,
-      status: statusOf(await job.getState()),
+      status: statusOf(state),
       attempts: job.attemptsMade,
       createdAt: job.timestamp,
       updatedAt: job.finishedOn ?? job.processedOn ?? job.timestamp,
@@ -89,18 +130,75 @@ export class BullMqJobQueue implements JobQueue {
   }
 
   async close(): Promise<void> {
+    this.closed = true;
     await Promise.all([
       ...[...this.workers.values()].map((worker) => worker.close()),
       ...[...this.queues.values()].map((queue) => queue.close()),
     ]);
     this.workers.clear();
     this.queues.clear();
+    await this.producer.close(true);
+  }
+
+  /**
+   * 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.
+   */
+  private async command<T>(send: (client: RedisClient) => Promise<T>): Promise<T> {
+    const producer = this.producer;
+    const client = await producer.client;
+    if (client.status !== "ready") throw jobsUnavailable();
+    try {
+      return await send(client);
+    } catch (error) {
+      const timedOut = isReplyTimeout(error);
+      if (timedOut && producer === this.producer) this.replaceProducer(error);
+      if (timedOut || producer !== this.producer || client.status !== "ready") throw jobsUnavailable();
+      throw error;
+    }
+  }
+
+  private openProducer(): RedisConnection {
+    const producer = new RedisConnection(this.connection, {
+      shared: false,
+      blocking: false,
+      ...NO_STARTUP_ROUND_TRIP,
+    });
+    // Connection errors reach callers as JOBS_UNAVAILABLE and the supervisor's log.
+    producer.on("error", () => undefined);
+    producer.on("close", () => {
+      if (producer === this.producer) this.report(new Error("Connection closed"));
+    });
+    return producer;
+  }
+
+  /**
+   * Redis answers in order, so after a reply times out every later command
+   * would wait behind it, and a server that stopped answering never completes
+   * the close either. The connection is dropped for a new one that the
+   * supervisor opens.
+   */
+  private replaceProducer(reason: unknown): void {
+    const stale = this.producer;
+    const queues = [...this.queues.values()];
+    this.queues.clear();
+    this.producer = this.openProducer();
+    void Promise.all(queues.map((queue) => queue.close()))
+      .then(() => stale.close(true))
+      .catch(() => undefined);
+    this.report(reason);
+  }
+
+  private report(reason: unknown): void {
+    if (!this.closed) this.lostListener?.(reason);
   }
 
-  private queue(name: string): Queue {
+  private queue(name: string, client: RedisClient): Queue {
     const current = this.queues.get(name);
     if (current) return current;
-    const queue = new Queue(name, { connection: redisConnection() });
+    const queue = new Queue(name, { connection: client, ...NO_STARTUP_ROUND_TRIP });
+    // It reports the producer connection's errors, which `openProducer` already handles.
+    queue.on("error", () => undefined);
     this.queues.set(name, queue);
     return queue;
   }

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

@@ -2,7 +2,7 @@ import { AppException } from "@podosoft/podokit-contracts";
 import { JOBS } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
 import { PROVIDERS } from "../config/providers";
-import type { AppPlugin, PodokitModule } from "../core/services";
+import { READINESS, type AppPlugin, type PodokitModule } from "../core/services";
 import { BullMqJobQueue } from "./bullmq-job.queue";
 
 const jobsPlugin: AppPlugin = ({ services }) => {
@@ -33,6 +33,8 @@ export const jobsModule: PodokitModule = {
     if (PROVIDERS.jobs !== "bullmq") return;
     const queue = new BullMqJobQueue();
     services.register(JOBS, queue, () => queue.close());
+    services.resolve(READINESS).register("jobs", () => queue.ready());
+    services.supervise("jobs", queue);
   },
   plugin: jobsPlugin,
 };