@checkstack/backend-api 0.19.0 → 0.21.0

package/src/advisory-lock.test.ts

@@ -7,8 +7,9 @@ import {
 
 /**
  * Faithful fake of a `pg.Pool` that models Postgres' per-connection
- * SESSION advisory-lock semantics:
+ * advisory-lock semantics for BOTH lock flavours:
  *
+ * SESSION locks (`tryAcquire`):
  *   - A key can be held by at most one connection at a time.
  *   - `pg_try_advisory_lock` succeeds only if the key is free; it then
  *     binds the key to the acquiring connection.
@@ -16,8 +17,15 @@ import {
  *     (a no-op otherwise) — exactly the bug we are guarding against: an
  *     unlock issued on a different connection does nothing.
  *
- * This lets the test prove the service keeps acquire + release on ONE
- * client.
+ * TRANSACTION locks (`withXactLock`):
+ *   - `pg_advisory_xact_lock` BLOCKS until the key is free, then binds it to
+ *     the acquiring connection's transaction.
+ *   - `COMMIT` / `ROLLBACK` release every xact lock held by that connection
+ *     and wake the next blocked waiter (FIFO) — modelling auto-release and
+ *     the serialization guarantee.
+ *
+ * This lets the tests prove the service keeps acquire + release on ONE
+ * client and that concurrent `withXactLock` callers serialize.
  */
 interface FakePool extends AdvisoryLockPool {
   checkedOut: number;
@@ -27,6 +35,9 @@ interface FakePool extends AdvisoryLockPool {
 function makeFakePool(): FakePool {
   // key -> owning connection id (or absent if free)
   const heldBy = new Map<string, number>();
+  // xact key -> owning connection id; waiters queued FIFO per key.
+  const xactHeldBy = new Map<string, number>();
+  const xactWaiters = new Map<string, Array<() => void>>();
   let nextConnId = 0;
   const counters = { checkedOut: 0, released: 0 };
 
@@ -46,8 +57,21 @@ function makeFakePool(): FakePool {
     async connect(): Promise<AdvisoryLockPoolClient> {
       const connId = nextConnId++;
       counters.checkedOut++;
+      const releaseXactLocks = () => {
+        for (const [key, owner] of [...xactHeldBy.entries()]) {
+          if (owner !== connId) continue;
+          xactHeldBy.delete(key);
+          const next = xactWaiters.get(key)?.shift();
+          if (next) next();
+        }
+      };
       return {
         async query<T>(queryText: string, values?: unknown[]) {
+          if (queryText === "BEGIN") return { rows: [] };
+          if (queryText === "COMMIT" || queryText === "ROLLBACK") {
+            releaseXactLocks();
+            return { rows: [] };
+          }
           const key = keyOf(values);
           if (queryText.includes("pg_try_advisory_lock")) {
             const owner = heldBy.get(key);
@@ -55,6 +79,22 @@ function makeFakePool(): FakePool {
             if (ok) heldBy.set(key, connId);
             return { rows: [{ ok } as unknown as T] };
           }
+          if (queryText.includes("pg_advisory_xact_lock")) {
+            if (!xactHeldBy.has(key)) {
+              xactHeldBy.set(key, connId);
+              return { rows: [] };
+            }
+            // Blocked: enqueue and wait until a holder commits/rolls back.
+            await new Promise<void>((resolve) => {
+              const q = xactWaiters.get(key) ?? [];
+              q.push(() => {
+                xactHeldBy.set(key, connId);
+                resolve();
+              });
+              xactWaiters.set(key, q);
+            });
+            return { rows: [] };
+          }
           if (queryText.includes("pg_advisory_unlock")) {
             // Only the owning connection can release — model the leak bug.
             if (heldBy.get(key) === connId) heldBy.delete(key);
@@ -70,6 +110,10 @@ function makeFakePool(): FakePool {
           // `on('error')` hardening is exercised by the IT against real
           // Postgres (killing the holding connection).
         },
+        off() {
+          // Counterpart to `on`; the service detaches its error listener on
+          // release. No-op here since the fake never attaches one.
+        },
       };
     },
   };
@@ -130,3 +174,100 @@ describe("createAdvisoryLockService", () => {
     await b!.release();
   });
 });
+
+describe("createAdvisoryLockService.withXactLock", () => {
+  const tick = (ms = 5) => new Promise((r) => setTimeout(r, ms));
+
+  it("runs fn, returns its value, and releases the client", async () => {
+    const pool = makeFakePool();
+    const svc = createAdvisoryLockService(pool);
+    const result = await svc.withXactLock({ key: "k", fn: async () => 42 });
+    expect(result).toBe(42);
+    expect(pool.checkedOut).toBe(1);
+    expect(pool.released).toBe(1);
+  });
+
+  it("serializes concurrent calls on the same key (second fn waits for first to commit)", async () => {
+    const pool = makeFakePool();
+    const svc = createAdvisoryLockService(pool);
+    const order: string[] = [];
+
+    let releaseFirst!: () => void;
+    const firstHeld = new Promise<void>((r) => (releaseFirst = r));
+
+    const p1 = svc.withXactLock({
+      key: "k",
+      fn: async () => {
+        order.push("1-start");
+        await firstHeld;
+        order.push("1-end");
+      },
+    });
+
+    // Let p1 acquire the lock before p2 attempts it.
+    await tick();
+    const p2 = svc.withXactLock({
+      key: "k",
+      fn: async () => {
+        order.push("2-start");
+      },
+    });
+
+    // While p1 holds the lock, p2's fn must NOT have started.
+    await tick();
+    expect(order).toEqual(["1-start"]);
+
+    releaseFirst();
+    await Promise.all([p1, p2]);
+    expect(order).toEqual(["1-start", "1-end", "2-start"]);
+    expect(pool.released).toBe(2);
+  });
+
+  it("rolls back and releases the client when fn throws, freeing the lock", async () => {
+    const pool = makeFakePool();
+    const svc = createAdvisoryLockService(pool);
+
+    await expect(
+      svc.withXactLock({
+        key: "k",
+        fn: async () => {
+          throw new Error("boom");
+        },
+      }),
+    ).rejects.toThrow("boom");
+
+    // Lock was released on rollback: a subsequent acquire succeeds promptly.
+    const after = await svc.withXactLock({ key: "k", fn: async () => "ok" });
+    expect(after).toBe("ok");
+    expect(pool.released).toBe(2);
+  });
+
+  it("different keys do not serialize", async () => {
+    const pool = makeFakePool();
+    const svc = createAdvisoryLockService(pool);
+    const started: string[] = [];
+
+    let release!: () => void;
+    const held = new Promise<void>((r) => (release = r));
+
+    const pA = svc.withXactLock({
+      key: "a",
+      fn: async () => {
+        started.push("a");
+        await held;
+      },
+    });
+    await tick();
+    // Key "b" must run even while "a" is still held.
+    await svc.withXactLock({
+      key: "b",
+      fn: async () => {
+        started.push("b");
+      },
+    });
+    expect(started).toContain("b");
+
+    release();
+    await pA;
+  });
+});

package/src/advisory-lock.ts

@@ -18,19 +18,25 @@
  *     (e.g. an installer election held across a minutes-long `bun install`)
  *     where a long-open transaction would be unacceptable.
  *
- *   - {@link withXactLock} wraps acquire + work + release in a single
- *     transaction using `pg_advisory_xact_lock`, which auto-releases at
- *     COMMIT/ROLLBACK. Use this for SHORT critical sections (e.g. a
- *     find-then-create dedup) where holding a transaction for the duration
- *     is fine and the auto-release removes any chance of a leak.
+ *   - {@link AdvisoryLockService.withXactLock} wraps acquire + work + release
+ *     in a single transaction using `pg_advisory_xact_lock`, which auto-
+ *     releases at COMMIT/ROLLBACK. Use this for SHORT critical sections (e.g. a
+ *     find-then-create dedup) where holding a transaction for the duration is
+ *     fine and the auto-release removes any chance of a leak.
+ *
+ * BOTH run on the service's pool, which MUST be a pool dedicated to advisory
+ * locks (separate from the pool the locked work runs on). A held lock keeps its
+ * connection checked out for the lock's lifetime; if lock and work shared one
+ * pool, concurrency >= pool size would deadlock (every slot a lock-holder
+ * waiting for a work connection). The backend wires this to a dedicated
+ * `lockPool`; that pool also sets `idle_in_transaction_session_timeout` /
+ * `lock_timeout` so a stalled critical section cannot strand a lock forever.
  *
  * Keys are arbitrary strings hashed to Postgres' 64-bit lock space via
  * `hashtextextended(key, 0)`. Callers SHOULD namespace keys (e.g.
  * `"script-packages.installer"`, `"incident.dedupe:<systemId>"`) since the
  * advisory-lock space is global to the database server, not schema-scoped.
  */
-import { sql } from "drizzle-orm";
-import type { SafeDatabase } from "./plugin-system";
 
 /**
  * Minimal pool surface this module needs. Modelled on `pg.Pool` /
@@ -45,13 +51,22 @@ export interface AdvisoryLockPoolClient {
   /** Return the client to the pool. */
   release(): void;
   /**
-   * Subscribe to async client errors. A session-lock client is held for a long
-   * time; if its backend dies (admin termination, failover, network drop) `pg`
-   * emits `'error'` on the client, and an `'error'` with no listener is
-   * re-thrown by the EventEmitter and would crash the pod. We attach a listener
-   * so that loss degrades gracefully instead. Modelled on `pg.Client.on`.
+   * Subscribe to async client errors. A held client (session lock, or an open
+   * xact-lock transaction) is checked out for a while; if its backend dies
+   * (admin termination, failover, network drop) `pg` emits `'error'` on the
+   * client, and an `'error'` with no listener is re-thrown by the EventEmitter
+   * and would crash the pod. We attach a listener so that loss degrades
+   * gracefully instead. Modelled on `pg.Client.on`.
    */
   on(event: "error", listener: (err: Error) => void): void;
+  /**
+   * Detach a previously-attached error listener. MUST be called before
+   * returning the client to the pool: pooled clients are reused, so attaching a
+   * fresh listener on every checkout WITHOUT removing it on release leaks one
+   * listener per acquisition on each long-lived physical connection (an
+   * unbounded `MaxListenersExceeded` leak). Modelled on `pg.Client.off`.
+   */
+  off(event: "error", listener: (err: Error) => void): void;
 }
 
 export interface AdvisoryLockPool {
@@ -76,8 +91,30 @@ export interface AdvisoryLockService {
    * `finally`.
    */
   tryAcquire(key: string): Promise<AdvisoryLockHandle | null>;
+  /**
+   * Run `fn` while holding a transaction-scoped advisory lock for `key`,
+   * acquired with `pg_advisory_xact_lock` (which BLOCKS until granted) on a
+   * dedicated client from THIS service's pool, and auto-released when that
+   * transaction commits/rolls back after `fn` settles.
+   *
+   * The lock transaction runs on this service's (dedicated lock) pool, while
+   * `fn` does its real work on whatever database it already holds (typically
+   * the shared admin pool). Because the held lock connection and the work
+   * connection come from DIFFERENT pools, the nested acquisition can never
+   * deadlock the work pool. Use this for SHORT critical sections that gate a
+   * read-then-write on another connection.
+   */
+  withXactLock<T>(args: { key: string; fn: () => Promise<T> }): Promise<T>;
 }
 
+/**
+ * Shared no-op `'error'` listener for held clients. A single module-level
+ * reference (rather than a fresh closure per acquisition) is what lets `off`
+ * detach exactly the listener `on` attached, and avoids allocating one per
+ * lock. It captures nothing, so sharing it is safe.
+ */
+const swallowClientError = (): void => {};
+
 /**
  * Build an {@link AdvisoryLockService} backed by a pool. The backend
  * provides the real admin pool; tests can provide a faithful fake that
@@ -95,8 +132,13 @@ export function createAdvisoryLockService(
       // here; without a listener the process crashes. Swallow it - the session
       // lock is auto-released server-side when the backend dies, and a stale
       // `release()` is already a no-op-safe `finally`, so the loss surfaces as
-      // the key simply becoming acquirable again.
-      client.on("error", () => {});
+      // the key simply becoming acquirable again. The listener is removed on
+      // release so it does not accumulate on the reused pooled connection.
+      client.on("error", swallowClientError);
+      const releaseClient = () => {
+        client.off("error", swallowClientError);
+        client.release();
+      };
       let acquired = false;
       try {
         const result = await client.query<{ ok: boolean }>(
@@ -105,14 +147,14 @@ export function createAdvisoryLockService(
         );
         acquired = Boolean(result.rows[0]?.ok);
       } catch (error) {
-        client.release();
+        releaseClient();
         throw error;
       }
       if (!acquired) {
         // Did not get the lock — return the client immediately. (A failed
         // pg_try_advisory_lock acquires nothing, so there is nothing to
         // unlock.)
-        client.release();
+        releaseClient();
         return null;
       }
 
@@ -127,48 +169,48 @@ export function createAdvisoryLockService(
               [key],
             );
           } finally {
-            client.release();
+            releaseClient();
           }
         },
       };
     },
-  };
-}
 
-/**
- * Run `fn` while holding a transaction-scoped advisory lock for `key`. The
- * lock is acquired with `pg_advisory_xact_lock` (which BLOCKS until granted)
- * inside a transaction and auto-released at COMMIT/ROLLBACK, so there is no
- * unlock to leak. Use only for SHORT critical sections — the lock is held
- * for the whole transaction.
- *
- * Because the scoped DB runs an entire `transaction()` callback on a single
- * dedicated connection, the lock + the work + the implicit release all share
- * one session, which is exactly the affinity session locks require.
- *
- * `fn` receives the transaction handle `tx` and MUST run its
- * read-then-write critical section on it (not on the outer pool). Running
- * the work on the pool would put it on a DIFFERENT connection than the one
- * holding the lock — so two concurrent callers' critical sections could
- * interleave even though both "hold" the lock. Using `tx` keeps the
- * read-check + write atomic with respect to the lock.
- */
-export async function withXactLock<
-  S extends Record<string, unknown>,
-  T,
->({
-  db,
-  key,
-  fn,
-}: {
-  db: SafeDatabase<S>;
-  key: string;
-  fn: (tx: Parameters<Parameters<SafeDatabase<S>["transaction"]>[0]>[0]) => Promise<T>;
-}): Promise<T> {
-  return db.transaction(async (tx) => {
-    await tx.execute(
-      sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`,
-    );
-    return fn(tx);
-  });
+    async withXactLock({ key, fn }) {
+      const client = await pool.connect();
+      // Same rationale as tryAcquire: the lock transaction keeps this client
+      // checked out (idle in transaction) while `fn` runs, so attach an error
+      // listener to survive a backend termination instead of crashing the pod.
+      // Removed in the finally so it does not accumulate on the reused client.
+      client.on("error", swallowClientError);
+      try {
+        await client.query("BEGIN");
+        try {
+          // BLOCKS on this dedicated client until the lock is granted; auto-
+          // released by the COMMIT/ROLLBACK below. `fn`'s own work runs on a
+          // DIFFERENT pool, so no same-pool nested-acquisition deadlock.
+          await client.query(
+            "SELECT pg_advisory_xact_lock(hashtextextended($1, 0))",
+            [key],
+          );
+          const result = await fn();
+          await client.query("COMMIT");
+          return result;
+        } catch (error) {
+          // Roll back so the xact lock releases and nothing partial lingers on
+          // this connection before it returns to the pool. Best-effort: if the
+          // backend already died, ROLLBACK throws but release() still frees the
+          // slot and the lock is auto-released server-side.
+          try {
+            await client.query("ROLLBACK");
+          } catch (rollbackError) {
+            void rollbackError;
+          }
+          throw error;
+        }
+      } finally {
+        client.off("error", swallowClientError);
+        client.release();
+      }
+    },
+  };
 }

package/src/auth-strategy.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { Migration } from "./config-versioning";
-import type { LucideIconName } from "@checkstack/common";
+import type { IconName } from "@checkstack/common";
 
 /**
  * Migration chain for auth strategy configurations.
@@ -21,8 +21,11 @@ export interface AuthStrategy<Config = unknown> {
   /** Optional description of the strategy */
   description?: string;
 
-  /** Lucide icon name in PascalCase (e.g., 'Github', 'Chrome', 'Mail') */
-  icon?: LucideIconName;
+  /**
+   * Icon name in PascalCase. A lucide icon (e.g. 'Mail') or a vendored brand
+   * icon (e.g. 'Github') - see `IconName` / `DynamicIcon`.
+   */
+  icon?: IconName;
 
   /** Current version of the configuration schema */
   configVersion: number;

package/src/bearer-token.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared opaque-bearer extraction used by the OAuth resource-server validate
+ * path (auth-backend) and the MCP transport (ai-backend) so the two never
+ * drift. A `ck_` API key is NOT an opaque OAuth bearer token (it has its own
+ * dedicated auth branch), so it is explicitly excluded here.
+ */
+export function opaqueBearerToken(request: Request): string | undefined {
+  const header = request.headers.get("authorization");
+  if (!header?.startsWith("Bearer ") || header.startsWith("Bearer ck_")) {
+    return undefined;
+  }
+  return header.slice("Bearer ".length);
+}

package/src/collector-strategy.ts

@@ -24,6 +24,15 @@ export interface CollectorResult<TResult> {
 export interface CollectorRunContext {
   check: { id: string; name: string; intervalSeconds: number };
   system: { id: string; name: string };
+  /**
+   * The resolved environment for THIS run, when the check fanned out into
+   * one. Absent when the assignment opts out or the system has no
+   * environments (the env-less run). `fields` is the environment's
+   * free-form custom metadata (verbatim values) - metadata only, never
+   * secrets. Exposed to scripts as `globalThis.context.environment` (inline)
+   * and the `CHECKSTACK_ENV_*` shell vars.
+   */
+  environment?: { id: string; name: string; fields: Record<string, unknown> };
 }
 
 /**