@podosoft/podokit 1.3.0 → 1.4.0

package/dist/templates/fullstack/apps/api/src/database/pool-guard.spec.ts

@@ -0,0 +1,188 @@
+import { SQL } from "bun";
+import { describe, expect, it } from "bun:test";
+import { answersOnNewConnection, PoolGuard } from "./pool-guard";
+
+const STALL_MS = 20;
+
+/** Settles like a Bun query: a subclass of Promise whose `then` returns a plain promise. */
+class FakeQuery extends Promise<unknown> {
+  static override get [Symbol.species](): PromiseConstructor {
+    return Promise;
+  }
+}
+
+interface FakePool {
+  sql: SQL;
+  closed: () => boolean;
+  /** Settles every query that waits for the server. */
+  resume: () => void;
+}
+
+interface FakeServer {
+  /** While true, queries wait until the pool closes or the server resumes. */
+  stalled: boolean;
+  pools: FakePool[];
+}
+
+function fakeServer(): FakeServer & { open: () => SQL } {
+  const server: FakeServer = { stalled: false, pools: [] };
+  const open = (): SQL => {
+    const waiting = new Set<(error?: Error) => void>();
+    let closed = false;
+    const query = (): FakeQuery =>
+      new FakeQuery((resolve, reject) => {
+        if (closed) return reject(new Error("Connection closed"));
+        if (!server.stalled) return resolve([{ ok: 1 }]);
+        waiting.add((error) => (error ? reject(error) : resolve([{ ok: 1 }])));
+      });
+    const settleAll = (error?: Error): void => {
+      for (const settle of waiting) settle(error);
+      waiting.clear();
+    };
+    const sql = Object.assign((..._args: unknown[]): FakeQuery => query(), {
+      begin: async (run: (tx: () => FakeQuery) => Promise<unknown>): Promise<unknown> => run(query),
+      close: async (): Promise<void> => {
+        closed = true;
+        settleAll(new Error("Connection closed"));
+      },
+    });
+    // The fake covers the members the guard and these tests use.
+    const pool = sql as unknown as SQL;
+    server.pools.push({ sql: pool, closed: () => closed, resume: () => settleAll() });
+    return pool;
+  };
+  return Object.assign(server, { open });
+}
+
+function guarded(answers: boolean): {
+  server: ReturnType<typeof fakeServer>;
+  guard: PoolGuard;
+  checks: () => number;
+  losses: Error[];
+} {
+  const server = fakeServer();
+  let checks = 0;
+  const guard = new PoolGuard(server.open, {
+    stallTimeoutMs: STALL_MS,
+    serverAnswers: async () => {
+      checks += 1;
+      return answers;
+    },
+  });
+  const losses: Error[] = [];
+  guard.onLost((reason) => losses.push(reason));
+  return { server, guard, checks: () => checks, losses };
+}
+
+function outcome(pending: Promise<unknown>): Promise<string> {
+  return pending.then(() => "resolved", (error: unknown) => `rejected: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+const pause = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe("PoolGuard", () => {
+  it("passes queries, fragments, helpers, and transactions through to the pool", async () => {
+    const guard = new PoolGuard(() => new SQL(":memory:", { adapter: "sqlite" }), {
+      stallTimeoutMs: STALL_MS,
+      serverAnswers: async () => true,
+    });
+    const { sql } = guard;
+    try {
+      await sql`CREATE TABLE item (id INTEGER PRIMARY KEY, name TEXT)`;
+      await sql`INSERT INTO item ${sql([{ id: 1, name: "a" }, { id: 2, name: "b" }], "id", "name")}`;
+      const filter = sql`WHERE "name" = ${"b"}`;
+      expect(await sql`SELECT "id" FROM item ${filter}`).toEqual([{ id: 2 }]);
+      expect(await sql`SELECT count(*) AS n FROM item`.values()).toEqual([[2]]);
+      const names = await sql.begin(async (tx) => {
+        await tx`UPDATE item SET "name" = 'c' WHERE "id" = 1`;
+        return tx`SELECT "name" FROM item ORDER BY "id"`;
+      });
+      expect(names).toEqual([{ name: "c" }, { name: "b" }]);
+      expect(await Promise.all([sql`SELECT 1 AS v`, sql.unsafe("SELECT 2 AS v")])).toEqual([[{ v: 1 }], [{ v: 2 }]]);
+    } finally {
+      await sql.close();
+    }
+  });
+
+  it("replaces the pool when a query stalls and the server does not answer", async () => {
+    const { server, guard, checks, losses } = guarded(false);
+    await guard.sql`SELECT 1`;
+    server.stalled = true;
+    const stalled = outcome(guard.sql`SELECT 1`);
+    const transaction = outcome(guard.sql.begin(async (tx) => tx`SELECT 1`));
+
+    expect(await stalled).toBe("rejected: Connection closed");
+    expect(await transaction).toBe("rejected: Connection closed");
+    expect(checks()).toBe(1);
+    expect(losses).toHaveLength(1);
+    expect(losses[0]?.message).toContain(`unanswered for ${STALL_MS} ms`);
+    expect(server.pools.map((pool) => pool.closed())).toEqual([true, false]);
+
+    server.stalled = false;
+    expect(await guard.sql`SELECT 1`).toEqual([{ ok: 1 }]);
+  });
+
+  it("keeps a slow query running while the server answers", async () => {
+    const { server, guard, checks, losses } = guarded(true);
+    await guard.sql`SELECT 1`;
+    server.stalled = true;
+    const slow = outcome(guard.sql`SELECT 1`);
+    await pause(STALL_MS * 3);
+
+    expect(checks()).toBe(1);
+    server.pools[0]?.resume();
+    expect(await slow).toBe("resolved");
+    expect(losses).toHaveLength(0);
+    expect(server.pools).toHaveLength(1);
+  });
+
+  it("checks the server once for queries that stall together", async () => {
+    const { server, guard, checks, losses } = guarded(false);
+    await guard.sql`SELECT 1`;
+    server.stalled = true;
+    const results = await Promise.all([1, 2, 3].map(() => outcome(guard.sql`SELECT 1`)));
+
+    expect(results).toEqual(Array(3).fill("rejected: Connection closed"));
+    expect(checks()).toBe(1);
+    expect(losses).toHaveLength(1);
+    expect(server.pools).toHaveLength(2);
+  });
+
+  it("leaves a pool that never answered to the connection timeout", async () => {
+    const { server, guard, checks } = guarded(false);
+    server.stalled = true;
+    const pending = guard.sql`SELECT 1`;
+    void pending.then(undefined, () => undefined);
+    await pause(STALL_MS * 3);
+
+    expect(checks()).toBe(0);
+    expect(server.pools).toHaveLength(1);
+    server.pools[0]?.resume();
+  });
+
+  it("starts the clock only when a query runs, not when it is built", async () => {
+    const { server, guard, checks } = guarded(false);
+    await guard.sql`SELECT 1`;
+    server.stalled = true;
+    guard.sql`WHERE true`;
+    await pause(STALL_MS * 3);
+
+    expect(checks()).toBe(0);
+    expect(server.pools).toHaveLength(1);
+  });
+});
+
+describe("answersOnNewConnection", () => {
+  it("reports a server that accepts the connection but never answers", async () => {
+    const server = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+    try {
+      const startedAt = Date.now();
+      expect(await answersOnNewConnection(`postgres://podokit:podokit@127.0.0.1:${server.port}/podokit`, 200)).toBe(
+        false,
+      );
+      expect(Date.now() - startedAt).toBeLessThan(1_000);
+    } finally {
+      server.stop(true);
+    }
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/pool-guard.ts

@@ -0,0 +1,151 @@
+import { SQL } from "bun";
+
+// Bun 1.4 treats `close({ timeout: 0 })` like no timeout and waits for every
+// pending query, so a stalled pool is closed after the shortest delay instead.
+const CLOSE_NOW_SECONDS = 0.001;
+
+// Pool members whose result is pending database work: `unsafe` and `file` build
+// queries, and `begin` and `transaction` settle when the transaction ends.
+const WATCHED_MEMBERS = new Set<PropertyKey>(["unsafe", "file", "begin", "transaction"]);
+
+/** Whether PostgreSQL at `url` answers `SELECT 1` on a new connection within `timeoutMs`. */
+export async function answersOnNewConnection(url: string, timeoutMs: number): Promise<boolean> {
+  const sql = new SQL(url, { max: 1, connectionTimeout: timeoutMs / 1000 });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => resolve(false), timeoutMs);
+  });
+  try {
+    return await Promise.race([sql`SELECT 1`.then(() => true, () => false), deadline]);
+  } finally {
+    clearTimeout(timer);
+    void sql.close({ timeout: CLOSE_NOW_SECONDS }).catch(() => undefined);
+  }
+}
+
+export interface PoolGuardOptions {
+  /** How long a query or transaction may stay pending before the server is checked. */
+  stallTimeoutMs: number;
+  /** Resolves whether the server answers a new connection now; never rejects. */
+  serverAnswers: () => Promise<boolean>;
+}
+
+interface Generation {
+  sql: SQL;
+  /** Whether a query on this pool has succeeded, so it may hold connections the server stopped answering. */
+  answered: boolean;
+}
+
+/**
+ * Keeps a Bun SQL pool usable when PostgreSQL keeps its connections open but
+ * stops answering, as a paused container, a frozen VM, or a network partition
+ * does. Bun SQL has no query timeout, `query.cancel()` does not stop a query
+ * that is running, and one pool connection cannot be closed on its own, so a
+ * query on such a connection waits until the server answers again or TCP gives
+ * up, and the pool keeps the connection.
+ *
+ * `sql` stands in for the pool and passes every call through. A query or
+ * transaction still pending after `stallTimeoutMs` makes the guard check the
+ * server on a new connection. When the server does not answer either, the guard
+ * opens a new pool and closes the old one, which fails every query still waiting
+ * on it with `ERR_POSTGRES_CONNECTION_CLOSED`. A slow query on a server that
+ * answers keeps running.
+ */
+export class PoolGuard {
+  readonly sql: SQL;
+  private generation: Generation;
+  private checking?: Promise<void>;
+  private readonly lostListeners: Array<(reason: Error) => void> = [];
+
+  constructor(
+    private readonly open: () => SQL,
+    private readonly options: PoolGuardOptions,
+  ) {
+    this.generation = { sql: open(), answered: false };
+    this.sql = new Proxy(this.generation.sql, {
+      apply: (_target, _thisArg, args: unknown[]) => {
+        const generation = this.generation;
+        return this.watch(generation, Reflect.apply(generation.sql, undefined, args));
+      },
+      get: (_target, key) => this.member(key),
+      has: (_target, key) => Reflect.has(this.generation.sql, key),
+    });
+  }
+
+  /** Takes the callback to run whenever the guard replaces a pool the server stopped answering. */
+  onLost(listener: (reason: Error) => void): void {
+    this.lostListeners.push(listener);
+  }
+
+  private member(key: PropertyKey): unknown {
+    const generation = this.generation;
+    const value: unknown = Reflect.get(generation.sql, key);
+    if (typeof value !== "function") return value;
+    return (...args: unknown[]): unknown => {
+      const result: unknown = Reflect.apply(value, generation.sql, args);
+      return WATCHED_MEMBERS.has(key) ? this.watch(generation, result) : result;
+    };
+  }
+
+  private watch(generation: Generation, result: unknown): unknown {
+    if (!(result instanceof Promise)) return result;
+    const pending: Promise<unknown> = result;
+    const then = pending.then;
+    // A transaction is a plain promise that is already running, and `await`
+    // does not call `then` on a plain promise.
+    if (Object.getPrototypeOf(pending) === Promise.prototype) {
+      this.track(generation, pending, then);
+      return pending;
+    }
+    // Bun builds a query without running it, and the same object can be nested
+    // in another query as a fragment, so the clock starts with the first `then`,
+    // which is what runs it. Every call still reaches Bun's own `then`.
+    let tracked = false;
+    Object.defineProperty(pending, "then", {
+      configurable: true,
+      writable: true,
+      value: (...args: Parameters<Promise<unknown>["then"]>): Promise<unknown> => {
+        const chained = then.apply(pending, args);
+        if (!tracked) {
+          tracked = true;
+          this.track(generation, pending, then);
+        }
+        return chained;
+      },
+    });
+    return pending;
+  }
+
+  private track(generation: Generation, pending: Promise<unknown>, then: Promise<unknown>["then"]): void {
+    const timer = setTimeout(() => this.stalled(generation), this.options.stallTimeoutMs);
+    timer.unref?.();
+    then.call(
+      pending,
+      () => {
+        clearTimeout(timer);
+        generation.answered = true;
+      },
+      () => clearTimeout(timer),
+    );
+  }
+
+  private stalled(generation: Generation): void {
+    // A pool that never answered holds only connections that are still opening,
+    // and the connection timeout ends those.
+    if (generation !== this.generation || !generation.answered) return;
+    this.checking ??= this.check(generation).finally(() => {
+      this.checking = undefined;
+    });
+  }
+
+  private async check(generation: Generation): Promise<void> {
+    if (await this.options.serverAnswers()) return;
+    if (generation !== this.generation) return;
+    this.generation = { sql: this.open(), answered: false };
+    void generation.sql.close({ timeout: CLOSE_NOW_SECONDS }).catch(() => undefined);
+    const reason = new Error(
+      `PostgreSQL left a query unanswered for ${this.options.stallTimeoutMs} ms and did not answer a new connection; replaced the pool`,
+    );
+    for (const listener of this.lostListeners) listener(reason);
+  }
+}

package/dist/templates/fullstack/apps/api/src/health/health.plugin.spec.ts

@@ -49,7 +49,9 @@ async function readiness(
   const app = new Elysia()
     .onError(({ error, set }) => {
       set.status = error instanceof AppException ? error.statusCode : 500;
-      return { code: error instanceof AppException ? error.code : "INTERNAL_ERROR" };
+      return error instanceof AppException
+        ? { code: error.code, message: error.message }
+        : { code: "INTERNAL_ERROR" };
     })
     .use(healthPlugin(appContext(env, services)));
   const response = await app.handle(new Request("http://localhost/health/ready"));
@@ -69,10 +71,29 @@ describe("GET /health/ready", () => {
     });
   });
 
-  it("fails when the database is down", async () => {
+  it("fails when the database is down and names it", async () => {
     const result = await readiness({ databaseUp: false });
 
-    expect(result).toEqual({ status: 503, body: { code: "READINESS_FAILED" } });
+    expect(result).toEqual({
+      status: 503,
+      body: { code: "READINESS_FAILED", message: "One or more dependencies are unavailable: db" },
+    });
+  });
+
+  it("names every module check that is down", async () => {
+    const result = await readiness({
+      databaseUp: true,
+      checks: {
+        cache: () => Promise.resolve(),
+        redis: () => Promise.reject(new Error("Connection closed")),
+        events: () => Promise.reject(new Error("Event transport is not subscribed")),
+      },
+    });
+
+    expect(result).toEqual({
+      status: 503,
+      body: { code: "READINESS_FAILED", message: "One or more dependencies are unavailable: redis, events" },
+    });
   });
 
   it("fails when a module check exceeds its timeout", async () => {
@@ -81,6 +102,9 @@ describe("GET /health/ready", () => {
       checks: { storage: () => new Promise<void>(() => {}) },
     });
 
-    expect(result).toEqual({ status: 503, body: { code: "READINESS_FAILED" } });
+    expect(result).toEqual({
+      status: 503,
+      body: { code: "READINESS_FAILED", message: "One or more dependencies are unavailable: storage" },
+    });
   });
 });

package/dist/templates/fullstack/apps/api/src/health/health.plugin.ts

@@ -14,8 +14,16 @@ export const healthPlugin: AppPlugin = ({ readiness }) =>
       "/health/ready",
       async () => {
         const { [DATABASE_READINESS_CHECK]: db, ...checks } = await readiness.run();
-        if (db !== "up" || Object.values(checks).includes("down")) {
-          throw new AppException("READINESS_FAILED", "One or more dependencies are unavailable", 503);
+        const down = [
+          ...(db === "up" ? [] : ["db"]),
+          ...Object.entries(checks).flatMap(([name, status]) => status === "down" ? [name] : []),
+        ];
+        if (down.length > 0) {
+          throw new AppException(
+            "READINESS_FAILED",
+            `One or more dependencies are unavailable: ${down.join(", ")}`,
+            503,
+          );
         }
         return { status: "ready" as const, db: "up" as const, checks };
       },

package/dist/templates/fullstack/apps/api/src/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from "./app";
 import { validateEnv } from "./config/env.validation";
+import { apiServerOptions } from "./config/server-options";
 import { createCoreServices } from "./core/services";
 
 const env = validateEnv(process.env);
@@ -9,7 +10,7 @@ const app = createApp({ env, services });
 async function bootstrap(): Promise<void> {
   try {
     await services.start();
-    app.listen({ hostname: "0.0.0.0", port: env.PORT });
+    app.listen({ ...apiServerOptions(env), hostname: "0.0.0.0", port: env.PORT });
     process.stdout.write(`API listening on http://0.0.0.0:${env.PORT}\n`);
   } catch (error) {
     await services.close();

package/dist/templates/fullstack/apps/web/components.json

@@ -8,7 +8,9 @@
   "aliases": {
     "components": "#lib/components",
     "ui": "#lib/components/ui",
-    "utils": "#lib/utils.js"
+    "utils": "#lib/utils",
+    "hooks": "#lib/hooks",
+    "lib": "#lib"
   },
   "typescript": true,
   "registry": "https://shadcn-svelte.com/registry"

package/dist/templates/fullstack/apps/web/package.json

@@ -16,7 +16,7 @@
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
-    "@podosoft/podokit-api-client": "^0.8.5",
+    "@podosoft/podokit-api-client": "^0.9.0",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",

package/dist/templates/fullstack/apps/web/src/lib/components/ui/textarea/index.ts

@@ -0,0 +1,7 @@
+import Root from "./textarea.svelte";
+
+export {
+	Root,
+	//
+	Root as Textarea,
+};

package/dist/templates/fullstack/apps/web/src/lib/components/ui/textarea/textarea.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import { cn, type WithElementRef, type WithoutChildren } from "#lib/utils.js";
+	import type { HTMLTextareaAttributes } from "svelte/elements";
+
+	let {
+		ref = $bindable(null),
+		value = $bindable(),
+		class: className,
+		"data-slot": dataSlot = "textarea",
+		...restProps
+	}: WithoutChildren<WithElementRef<HTMLTextareaAttributes>> = $props();
+</script>
+
+<textarea
+	bind:this={ref}
+	data-slot={dataSlot}
+	class={cn(
+		"border-input dark:bg-input/30 focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 disabled:bg-input/50 dark:disabled:bg-input/80 rounded-lg border bg-transparent px-2.5 py-2 text-base transition-colors focus-visible:ring-3 aria-invalid:ring-3 md:text-sm flex field-sizing-content min-h-16 w-full outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50",
+		className
+	)}
+	bind:value
+	{...restProps}></textarea>