@podosoft/podokit 1.2.0 → 1.4.0

package/dist/templates/fullstack/apps/api/src/config/redis.connection.ts

@@ -68,6 +68,51 @@ export function redisConnectionOptions(
   return { ...base, ...overrides };
 }
 
+export const DEFAULT_REDIS_COMMAND_TIMEOUT_MS = 1_000;
+
+/** How long the API waits for Redis to answer one command (`REDIS_COMMAND_TIMEOUT_MS`). */
+export function redisCommandTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  const value = env.REDIS_COMMAND_TIMEOUT_MS;
+  if (value === undefined || value === "") return DEFAULT_REDIS_COMMAND_TIMEOUT_MS;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error("REDIS_COMMAND_TIMEOUT_MS must be a positive integer");
+  }
+  return parsed;
+}
+
+export class RedisCommandTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Redis did not answer within ${timeoutMs} ms`);
+    this.name = "RedisCommandTimeoutError";
+  }
+}
+
+/**
+ * Rejects with `RedisCommandTimeoutError` when `reply` has not settled within
+ * `timeoutMs`, after calling `onTimeout`. Redis answers a connection's commands
+ * in order, so a missing reply holds back every later one: `onTimeout` closes
+ * the connection, which fails those too and lets its supervisor reconnect.
+ */
+export async function withReplyTimeout<T>(
+  reply: Promise<T>,
+  timeoutMs: number,
+  onTimeout: () => void,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new RedisCommandTimeoutError(timeoutMs));
+      onTimeout();
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([reply, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /** Resolve the same Redis configuration as BullMQ into a URL for Bun.RedisClient. */
 export function redisConnectionUrl(env: NodeJS.ProcessEnv = process.env): string {
   if (env.REDIS_URL) {

package/dist/templates/fullstack/apps/api/src/config/server-options.spec.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "bun:test";
+import { Elysia } from "elysia";
+import { validateEnv } from "./env.validation";
+import { apiServerOptions, DEFAULT_MAX_REQUEST_BODY_SIZE } from "./server-options";
+
+describe("apiServerOptions", () => {
+  it("defaults to Bun's request body limit and leaves the idle timeout to Elysia", () => {
+    const env = validateEnv({});
+    expect(env.API_MAX_REQUEST_BODY_SIZE).toBe(DEFAULT_MAX_REQUEST_BODY_SIZE);
+    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE });
+  });
+
+  it("reads API_MAX_REQUEST_BODY_SIZE and rejects values that are not byte counts", () => {
+    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}))
+      .toEqual({ maxRequestBodySize: 1_073_741_824 });
+    for (const value of ["0", "-1", "1.5", "lots"]) {
+      expect(() => validateEnv({ API_MAX_REQUEST_BODY_SIZE: value })).toThrow("API_MAX_REQUEST_BODY_SIZE");
+    }
+  });
+
+  it("lets the application's options win over the environment", () => {
+    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024" });
+    expect(apiServerOptions(env, { maxRequestBodySize: 4096, idleTimeout: 120 }))
+      .toEqual({ maxRequestBodySize: 4096, idleTimeout: 120 });
+    expect(apiServerOptions(env, (current) => ({ maxRequestBodySize: current.API_MAX_REQUEST_BODY_SIZE * 2 })))
+      .toEqual({ maxRequestBodySize: 2048 });
+    expect(() => apiServerOptions(env, { maxRequestBodySize: 0 })).toThrow("maxRequestBodySize");
+    expect(() => apiServerOptions(env, { idleTimeout: 256 })).toThrow("idleTimeout");
+    expect(() => apiServerOptions(env, { idleTimeout: -1 })).toThrow("idleTimeout");
+  });
+
+  it("makes the server refuse a body above the limit with 413", async () => {
+    const app = new Elysia()
+      .post("/upload", async ({ request }) => ({ size: (await request.arrayBuffer()).byteLength }))
+      .listen({ ...apiServerOptions(validateEnv({}), { maxRequestBodySize: 1024 }), hostname: "127.0.0.1", port: 0 });
+    try {
+      const url = `http://127.0.0.1:${app.server?.port}/upload`;
+      const accepted = await fetch(url, { method: "POST", body: new Uint8Array(1024) });
+      expect(await accepted.json()).toEqual({ size: 1024 });
+      const refused = await fetch(url, { method: "POST", body: new Uint8Array(1025) });
+      expect(refused.status).toBe(413);
+    } finally {
+      await app.stop();
+    }
+  });
+});

package/dist/templates/fullstack/apps/api/src/config/server-options.ts

@@ -0,0 +1,48 @@
+import * as extensions from "../app.extensions";
+import type { AppEnv } from "./env.validation";
+
+/** Bun's default request body limit. */
+export const DEFAULT_MAX_REQUEST_BODY_SIZE = 128 * 1024 * 1024;
+const MAX_IDLE_TIMEOUT_SECONDS = 255;
+
+/** Bun server options an application sets from `app.extensions.ts`. */
+export interface ApiServerOptions {
+  /** The largest request body in bytes. Defaults to `API_MAX_REQUEST_BODY_SIZE`. */
+  maxRequestBodySize?: number;
+  /**
+   * Seconds a connection may stay idle before it is closed, from 0 (never) to
+   * 255. Defaults to Elysia's 30 seconds.
+   */
+  idleTimeout?: number;
+}
+
+/** A fixed set of options, or a function of the validated environment. */
+export type ApiServerOptionsSource = ApiServerOptions | ((env: AppEnv) => ApiServerOptions);
+
+// `apiServerOptions` is an optional export of the application-owned
+// app.extensions.ts. The index signature keeps extension files written before
+// it existed assignable, while a wrongly typed export still fails to compile.
+const owned: { readonly [name: string]: unknown; readonly apiServerOptions?: ApiServerOptionsSource } = extensions;
+
+/**
+ * The Bun serve options for the API. Values from `apiServerOptions` win over
+ * the environment; the function form receives the environment to combine both.
+ */
+export function apiServerOptions(
+  env: AppEnv,
+  source: ApiServerOptionsSource | undefined = owned.apiServerOptions,
+): ApiServerOptions & { maxRequestBodySize: number } {
+  const options = typeof source === "function" ? source(env) : source ?? {};
+  const maxRequestBodySize = options.maxRequestBodySize ?? env.API_MAX_REQUEST_BODY_SIZE;
+  if (!Number.isSafeInteger(maxRequestBodySize) || maxRequestBodySize < 1) {
+    throw new Error("apiServerOptions.maxRequestBodySize must be a positive integer of bytes");
+  }
+  const { idleTimeout } = options;
+  if (
+    idleTimeout !== undefined &&
+    (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS)
+  ) {
+    throw new Error(`apiServerOptions.idleTimeout must be an integer from 0 to ${MAX_IDLE_TIMEOUT_SECONDS} seconds`);
+  }
+  return { maxRequestBodySize, ...(idleTimeout === undefined ? {} : { idleTimeout }) };
+}

package/dist/templates/fullstack/apps/api/src/core/api-contract.spec.ts

@@ -16,6 +16,7 @@ describe("API contract inventory", () => {
     expect(expected).toContain("POST /api/auth/sign-in/email");
     expect(expected).toContain("PUT /cache/{key}");
     expect(expected).toContain("POST /files");
+    expect(expected).toContain("PUT /files/uploads/{id}/parts/{partNumber}");
   });
 
   it("uses one structural parameter name for every public blog post route", () => {

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -37,6 +37,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "GET /profile-images/{fileName}",
     "GET /admin/sessions",
     "DELETE /admin/sessions/{id}",
+    "GET /admin/users",
   ],
   "api-key-auth": ["GET /machine/ping"],
   "audit-log": ["GET /audit-logs", "GET /audit-logs/actions"],
@@ -70,7 +71,15 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "DELETE /admin/blog/{id}",
   ],
   bullmq: ["POST /jobs", "GET /jobs/{id}"],
-  "file-upload": ["POST /files", "GET /files/{key}/url"],
+  "file-upload": [
+    "POST /files",
+    "GET /files/{key}/url",
+    "POST /files/uploads",
+    "GET /files/uploads/{id}",
+    "PUT /files/uploads/{id}/parts/{partNumber}",
+    "POST /files/uploads/{id}/complete",
+    "DELETE /files/uploads/{id}",
+  ],
   "job-progress": ["POST /progress"],
   "object-storage-local": [
     "GET /files/content/*",

package/dist/templates/fullstack/apps/api/src/core/services.spec.ts

@@ -4,11 +4,15 @@ import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import {
   AccessPolicy,
+  ConnectionSupervisor,
   createCoreServices,
   OpenApiRegistry,
   REQUEST_IDENTITY,
   RequestGuardRegistry,
   ServiceRegistry,
+  type ConnectionEvents,
+  type RetryTimer,
+  type SupervisedConnection,
 } from "./services";
 
 function databaseProvider(): DatabaseProviderName {
@@ -50,6 +54,180 @@ describe("ServiceRegistry", () => {
   });
 });
 
+describe("ServiceRegistry supervision", () => {
+  test("starts and runs start hooks while a supervised dependency is down", async () => {
+    const registry = new ServiceRegistry();
+    let attempts = 0;
+    let hookRan = false;
+    registry.supervise("redis", {
+      connect: () => {
+        attempts += 1;
+        return Promise.reject(new Error("Connection closed"));
+      },
+    });
+    registry.onStart(() => { hookRan = true; });
+    registry.freeze();
+
+    await registry.start();
+    expect(hookRan).toBe(true);
+    expect(attempts).toBe(1);
+    await registry.close();
+    await Bun.sleep(400);
+    expect(attempts).toBe(1);
+  });
+
+  test("connects a reachable dependency before the start hooks run", async () => {
+    const registry = new ServiceRegistry();
+    const order: string[] = [];
+    registry.supervise("database", {
+      connect: async () => {
+        await Bun.sleep(5);
+        order.push("connected");
+      },
+    });
+    registry.onStart(() => { order.push("hook"); });
+    registry.freeze();
+
+    await registry.start();
+    expect(order).toEqual(["connected", "hook"]);
+    await registry.close();
+  });
+});
+
+interface FakeTimer extends RetryTimer {
+  delays: number[];
+  pending(): number;
+  fire(): Promise<void>;
+}
+
+function fakeTimer(): FakeTimer {
+  const tasks: Array<{ task: () => void; cancelled: boolean }> = [];
+  const delays: number[] = [];
+  return {
+    delays,
+    after: (delayMs, task) => {
+      const entry = { task, cancelled: false };
+      delays.push(delayMs);
+      tasks.push(entry);
+      return () => { entry.cancelled = true; };
+    },
+    pending: () => tasks.filter((entry) => !entry.cancelled).length,
+    fire: async () => {
+      const entry = tasks.shift();
+      if (entry && !entry.cancelled) entry.task();
+      await Bun.sleep(0);
+    },
+  };
+}
+
+function recordingEvents(): ConnectionEvents & { log: string[] } {
+  const log: string[] = [];
+  return {
+    log,
+    unavailable: (name, reason) => { log.push(`unavailable ${name}: ${reason}`); },
+    restored: (name) => { log.push(`restored ${name}`); },
+  };
+}
+
+class FlakyConnection implements SupervisedConnection {
+  attempts = 0;
+  failuresLeft = 0;
+  private listener?: (reason: unknown) => void;
+
+  connect(): Promise<void> {
+    this.attempts += 1;
+    if (this.failuresLeft > 0) {
+      this.failuresLeft -= 1;
+      return Promise.reject(new Error("Connection closed"));
+    }
+    return Promise.resolve();
+  }
+
+  onLost(listener: (reason: unknown) => void): void {
+    this.listener = listener;
+  }
+
+  drop(): void {
+    this.listener?.(new Error("Connection reset"));
+  }
+}
+
+describe("ConnectionSupervisor", () => {
+  const policy = { initialDelayMs: 100, maxDelayMs: 400 };
+
+  test("retries with doubling delays up to the cap and reports each state change once", async () => {
+    const connection = new FlakyConnection();
+    connection.failuresLeft = 5;
+    const timer = fakeTimer();
+    const events = recordingEvents();
+    const supervisor = new ConnectionSupervisor("redis", connection, events, { policy, timer });
+
+    await supervisor.start();
+    expect(supervisor.connected).toBe(false);
+    while (timer.pending() > 0) await timer.fire();
+
+    expect(connection.attempts).toBe(6);
+    expect(timer.delays).toEqual([100, 200, 400, 400, 400]);
+    expect(events.log).toEqual(["unavailable redis: Connection closed", "restored redis"]);
+    expect(supervisor.connected).toBe(true);
+  });
+
+  test("reopens a lost connection and starts the backoff over", async () => {
+    const connection = new FlakyConnection();
+    const timer = fakeTimer();
+    const events = recordingEvents();
+    const supervisor = new ConnectionSupervisor("redis", connection, events, { policy, timer });
+    await supervisor.start();
+    expect(supervisor.connected).toBe(true);
+
+    connection.failuresLeft = 1;
+    connection.drop();
+    connection.drop();
+    expect(supervisor.connected).toBe(false);
+    expect(timer.pending()).toBe(1);
+    while (timer.pending() > 0) await timer.fire();
+
+    expect(timer.delays).toEqual([100, 200]);
+    expect(connection.attempts).toBe(3);
+    expect(events.log).toEqual(["unavailable redis: Connection reset", "restored redis"]);
+    expect(supervisor.connected).toBe(true);
+  });
+
+  test("tries again when the connection drops while an attempt runs", async () => {
+    const connection = new FlakyConnection();
+    const timer = fakeTimer();
+    const supervisor = new ConnectionSupervisor("events", {
+      connect: async () => {
+        await connection.connect();
+        if (connection.attempts === 1) connection.drop();
+      },
+      onLost: (listener) => connection.onLost(listener),
+    }, recordingEvents(), { policy, timer });
+
+    await supervisor.start();
+    expect(supervisor.connected).toBe(false);
+    await timer.fire();
+    expect(connection.attempts).toBe(2);
+    expect(supervisor.connected).toBe(true);
+  });
+
+  test("stops retrying once stopped", async () => {
+    const connection = new FlakyConnection();
+    connection.failuresLeft = 10;
+    const timer = fakeTimer();
+    const supervisor = new ConnectionSupervisor("redis", connection, recordingEvents(), { policy, timer });
+    await supervisor.start();
+    expect(timer.pending()).toBe(1);
+
+    supervisor.stop();
+    expect(timer.pending()).toBe(0);
+    connection.drop();
+    await timer.fire();
+    expect(connection.attempts).toBe(1);
+    expect(timer.pending()).toBe(0);
+  });
+});
+
 describe("AccessPolicy", () => {
   test("defaults to session access", () => {
     const policy = new AccessPolicy();
@@ -66,6 +244,24 @@ describe("AccessPolicy", () => {
     expect(policy.resolve(new Request("http://localhost/api/auth/sign-in/email"))).toBe("public");
   });
 
+  test("applies GET rules to HEAD requests and leaves other methods alone", () => {
+    const policy = new AccessPolicy();
+    policy.register("GET", "/profile-images/:fileName", "public");
+    policy.register("POST", "/uploads", "public");
+    policy.register("GET", "/reports/:id", "api-key");
+
+    const head = (path: string): Request => new Request(`http://localhost${path}`, { method: "HEAD" });
+    expect(policy.resolve(head("/profile-images/a.png"))).toBe("public");
+    expect(policy.resolve(head("/reports/1"))).toBe("api-key");
+    expect(policy.resolve(head("/uploads"))).toBe("session");
+    expect(policy.resolve(head("/todos"))).toBe("session");
+    expect(policy.resolve(new Request("http://localhost/profile-images/a.png", { method: "DELETE" }))).toBe("session");
+
+    policy.register("HEAD", "/profile-images/:fileName", "session");
+    expect(policy.resolve(head("/profile-images/a.png"))).toBe("session");
+    expect(policy.resolve(new Request("http://localhost/profile-images/a.png"))).toBe("public");
+  });
+
   test("uses the most recently registered matching rule", () => {
     const policy = new AccessPolicy();
     policy.register("*", "/content/*", "public");

package/dist/templates/fullstack/apps/api/src/core/services.ts

@@ -10,9 +10,151 @@ import { DATABASE_READINESS_CHECK, ReadinessService } from "../health/readiness.
 
 export type { ServiceKey } from "@podosoft/podokit-runtime";
 
+/** A dependency that `ServiceRegistry.supervise` keeps connected. */
+export interface SupervisedConnection {
+  /**
+   * Opens whatever is closed and restores what depends on it, such as
+   * subscriptions. Rejects while the dependency is unreachable.
+   */
+  connect(): Promise<void>;
+  /** Takes the callback to run whenever an open connection drops. */
+  onLost?(listener: (reason: unknown) => void): void;
+}
+
+export interface ReconnectPolicy {
+  /** Delay before the first retry. Each further failure doubles it. */
+  initialDelayMs: number;
+  /** Longest delay between two attempts. */
+  maxDelayMs: number;
+}
+
+export const DEFAULT_RECONNECT_POLICY: ReconnectPolicy = { initialDelayMs: 250, maxDelayMs: 5_000 };
+
+export interface ConnectionEvents {
+  unavailable(name: string, reason: string): void;
+  restored(name: string, downtimeMs: number): void;
+}
+
+export interface RetryTimer {
+  /** Runs `task` once after `delayMs`; the returned function cancels it. */
+  after(delayMs: number, task: () => void): () => void;
+}
+
+const unrefTimer: RetryTimer = {
+  after: (delayMs, task) => {
+    const timer = setTimeout(task, delayMs);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+  },
+};
+
+export interface SupervisorOptions {
+  policy?: ReconnectPolicy;
+  timer?: RetryTimer;
+}
+
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Connects in the background and keeps the connection open: a failed attempt is
+ * retried with capped exponential backoff, and a lost connection is reopened.
+ * Events fire when the state changes, not on every attempt.
+ */
+export class ConnectionSupervisor {
+  private up = false;
+  private stopped = false;
+  private failures = 0;
+  private drops = 0;
+  private lastDrop: unknown;
+  private downSince?: number;
+  private cancelRetry?: () => void;
+  private firstAttempt?: Promise<void>;
+  private readonly policy: ReconnectPolicy;
+  private readonly timer: RetryTimer;
+
+  constructor(
+    readonly name: string,
+    private readonly connection: SupervisedConnection,
+    private readonly events: ConnectionEvents,
+    options: SupervisorOptions = {},
+  ) {
+    this.policy = options.policy ?? DEFAULT_RECONNECT_POLICY;
+    this.timer = options.timer ?? unrefTimer;
+    connection.onLost?.((reason) => this.lost(reason));
+  }
+
+  get connected(): boolean {
+    return this.up;
+  }
+
+  /** Resolves after the first attempt, whether or not it connected. */
+  start(): Promise<void> {
+    this.firstAttempt ??= this.attempt();
+    return this.firstAttempt;
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.up = false;
+    this.cancelRetry?.();
+    this.cancelRetry = undefined;
+  }
+
+  private lost(reason: unknown): void {
+    if (this.stopped) return;
+    this.drops += 1;
+    this.lastDrop = reason;
+    // While an attempt is pending it sees the changed count and tries again.
+    if (!this.up) return;
+    this.up = false;
+    this.retry(reason);
+  }
+
+  private async attempt(): Promise<void> {
+    this.cancelRetry = undefined;
+    if (this.stopped) return;
+    const drops = this.drops;
+    try {
+      await this.connection.connect();
+    } catch (error) {
+      if (!this.stopped) this.retry(error);
+      return;
+    }
+    if (this.stopped) return;
+    // Bun reports a failed reconnect through the same close callback, so a drop
+    // during the attempt can mean a part of the connection is closed again.
+    if (drops !== this.drops) {
+      this.retry(this.lastDrop);
+      return;
+    }
+    this.up = true;
+    this.failures = 0;
+    if (this.downSince !== undefined) {
+      this.events.restored(this.name, Date.now() - this.downSince);
+      this.downSince = undefined;
+    }
+  }
+
+  private retry(reason: unknown): void {
+    if (this.downSince === undefined) {
+      this.downSince = Date.now();
+      this.events.unavailable(this.name, reasonOf(reason));
+    }
+    const delay = Math.min(
+      this.policy.maxDelayMs,
+      this.policy.initialDelayMs * 2 ** Math.min(this.failures, 30),
+    );
+    this.failures += 1;
+    this.cancelRetry = this.timer.after(delay, () => void this.attempt());
+  }
+}
+
 export class ServiceRegistry {
   private readonly values = new Map<symbol, unknown>();
   private readonly starters: Array<() => void | Promise<void>> = [];
+  private readonly supervisors: ConnectionSupervisor[] = [];
   private readonly closers: Array<() => void | Promise<void>> = [];
   private startPromise?: Promise<void>;
   private closePromise?: Promise<void>;
@@ -41,17 +183,44 @@ export class ServiceRegistry {
     return this.values.get(key) as T | undefined;
   }
 
+  /** Runs `start` before the server listens; a rejection fails startup. */
   onStart(start: () => void | Promise<void>): void {
     if (this.frozen) throw new Error("Service registry is frozen");
     this.starters.push(start);
   }
 
+  /**
+   * Connects `connection` when the registry starts and keeps it connected.
+   * Startup waits only for the first attempt, so the server listens while the
+   * dependency is down; register a readiness check that reports it.
+   */
+  supervise(name: string, connection: SupervisedConnection): void {
+    if (this.frozen) throw new Error("Service registry is frozen");
+    this.supervisors.push(new ConnectionSupervisor(name, connection, {
+      // Resolved on use: a module such as logging may replace the logger.
+      unavailable: (dependency, reason) => {
+        this.tryResolve(LOGGER)?.warn(
+          { dependency, reason },
+          "Dependency connection failed; retrying in the background",
+        );
+      },
+      restored: (dependency, downtimeMs) => {
+        this.tryResolve(LOGGER)?.info({ dependency, downtimeMs }, "Dependency connection restored");
+      },
+    }));
+  }
+
   freeze(): void {
     this.frozen = true;
   }
 
+  /**
+   * Makes a first connection attempt for every supervised dependency at once,
+   * so those that are up are connected before the start hooks run in order.
+   */
   start(): Promise<void> {
     this.startPromise ??= (async () => {
+      await Promise.all(this.supervisors.map((supervisor) => supervisor.start()));
       for (const start of this.starters) await start();
     })();
     return this.startPromise;
@@ -59,6 +228,7 @@ export class ServiceRegistry {
 
   close(): Promise<void> {
     this.closePromise ??= (async () => {
+      for (const supervisor of this.supervisors) supervisor.stop();
       for (const close of [...this.closers].reverse()) await close();
     })();
     return this.closePromise;
@@ -90,13 +260,19 @@ export class AccessPolicy {
     this.rules.push({ method: method.toUpperCase(), matcher: routeMatcher(pattern), level });
   }
 
+  /**
+   * The level of the most recently registered matching rule. A HEAD request
+   * also matches GET rules, because Elysia answers it with the GET handler.
+   */
   resolve(request: Request): AccessLevel {
     const path = new URL(request.url).pathname;
     const method = request.method.toUpperCase();
     const rule = [...this.rules]
       .reverse()
       .find((candidate) =>
-        (candidate.method === "*" || candidate.method === method) && candidate.matcher.test(path)
+        (candidate.method === "*" || candidate.method === method ||
+          (method === "HEAD" && candidate.method === "GET")) &&
+        candidate.matcher.test(path)
       );
     return rule?.level ?? "session";
   }
@@ -199,7 +375,10 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
   accessPolicy.register("*", "/api-docs-json", "public");
   accessPolicy.register("*", "/api-docs-elysia-json", "public");
   services.register(DATABASE, database, () => database.close());
-  services.onStart(() => database.connect());
+  services.supervise(DATABASE_READINESS_CHECK, {
+    connect: () => services.resolve(DATABASE).connect(),
+    onLost: (listener) => database.onLost(listener),
+  });
   services.register(READINESS, readiness);
   readiness.register(DATABASE_READINESS_CHECK, () => services.resolve(DATABASE).ping());
   services.register(LOGGER, logger);

package/dist/templates/fullstack/apps/api/src/database/data-source.spec.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "bun:test";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { PROVIDERS } from "../config/providers";
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+// SQLite applications migrate with the Bun SQLite migrator, not this TypeORM source.
+describe.skipIf(databaseProvider() !== "postgres")("migration data source", () => {
+  it("runs each migration in its own transaction so one can build indexes concurrently", async () => {
+    const { dataSourceOptions } = await import("./data-source.js");
+    expect(dataSourceOptions.migrationsTransactionMode).toBe("each");
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/data-source.ts

@@ -15,6 +15,9 @@ const migrations = existsSync(compiledMigrations)
 const commonOptions = {
   entities: [],
   migrations,
+  // One transaction per migration, so a migration can set `transaction = false`
+  // for statements such as CREATE INDEX CONCURRENTLY.
+  migrationsTransactionMode: "each" as const,
   synchronize: false,
 };