diff --git a/packages/db/src/work-signals.test.ts b/packages/db/src/work-signals.test.ts index 0a50429fd64..b98a868af96 100644 --- a/packages/db/src/work-signals.test.ts +++ b/packages/db/src/work-signals.test.ts @@ -3,7 +3,7 @@ import { drizzle } from "drizzle-orm/postgres-js"; import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; import { createDb, withDedicatedDbConnection } from "./client.js"; import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./test-embedded-postgres.js"; -import { databaseWorkScopeKey, databaseWorkPending, installDatabaseWorkSignals, notifyDatabaseWorkOnCommit, reconcileDatabaseWork, signalDatabaseWork, subscribeDatabaseWork } from "./work-signals.js"; +import { DATABASE_WORK_CHANNEL, databaseWorkScopeKey, databaseWorkPending, enableDatabaseWorkNotifications, installDatabaseWorkSignals, notifyDatabaseWorkOnCommit, reconcileDatabaseWork, signalDatabaseWork, subscribeDatabaseWork } from "./work-signals.js"; const support = await getEmbeddedPostgresTestSupport(); (support.supported ? describe : describe.skip)("database work signals", () => { @@ -221,3 +221,138 @@ describe("database work scope identity", () => { }); }); }); + +(support.supported ? describe : describe.skip)("database work notifications flushed once per transaction", () => { + let db: ReturnType; + let listener: ReturnType; + let temporary: Awaited>; + const delivered: string[] = []; + let notifyStatements = 0; + let sentPayloads: string[] = []; + beforeAll(async () => { + temporary = await startEmbeddedPostgresTestDatabase("work-signals-notify-"); + db = createDb(temporary.connectionString); + enableDatabaseWorkNotifications(db); + listener = createDb(temporary.connectionString, { maxConnections: 1 }); + await listener.$client.listen(DATABASE_WORK_CHANNEL, payload => { delivered.push(payload); }); + db.$client.options.debug = (_connection: number, query: string, parameters: unknown[]) => { + if (!/pg_notify/.test(query) || parameters.some(value => String(value).includes("fence"))) return; + notifyStatements += 1; + sentPayloads.push(...JSON.parse(String(parameters[parameters.length - 1])) as string[]); + }; + }, 90_000); + afterAll(async () => { + await listener?.$client.end({ timeout: 1 }); + await db?.$client.end({ timeout: 1 }); + await temporary?.cleanup(); + }); + const topic = (payload: string) => (JSON.parse(payload) as { topic: string }).topic; + async function run(action: (root: typeof db) => Promise) { + notifyStatements = 0; + sentPayloads = []; + delivered.length = 0; + let failure: unknown = null; + await action(db).catch(error => { failure = error; }); + await db.execute(sql`select pg_notify(${DATABASE_WORK_CHANNEL}, ${JSON.stringify({ topic: "fence" })})`); + await vi.waitFor(() => expect(delivered.some(payload => topic(payload) === "fence")).toBe(true)); + const received = delivered.filter(payload => topic(payload) !== "fence"); + return { statements: notifyStatements, sent: sentPayloads.map(topic), delivered: received.map(topic), payloads: received, + failure: failure instanceof Error ? failure.message : failure }; + } + const rollback = () => { throw new Error("rollback"); }; + + it("sends every distinct topic of a transaction in one statement at commit, in first-signal order", async () => { + const result = await run(root => root.transaction(async tx => { + await signalDatabaseWork(tx, "a", "one"); + await signalDatabaseWork(tx, "b"); + await signalDatabaseWork(tx, "a", "two"); + await notifyDatabaseWorkOnCommit(tx, "c"); + expect(notifyStatements).toBe(0); + })); + expect(result).toMatchObject({ statements: 1, sent: ["a", "b", "c"], delivered: ["a", "b", "c"], failure: null }); + expect(result.payloads.map(payload => JSON.parse(payload))).toEqual(["a", "b", "c"].map(name => + ({ version: 1, origin: expect.any(String), topic: name }))); + }); + + it("sends nothing for a transaction that signals nothing", async () => { + expect(await run(root => root.transaction(async tx => { await tx.execute(sql`select 1`); }))) + .toMatchObject({ statements: 0, delivered: [] }); + }); + + it("keeps a released savepoint's topics, two levels deep, and drops a rolled-back savepoint's topics", async () => { + expect(await run(root => root.transaction(async tx => { + await tx.transaction(async first => { + await first.transaction(async second => { await signalDatabaseWork(second, "kept"); }); + await first.transaction(async second => { await signalDatabaseWork(second, "dropped"); rollback(); }).catch(() => {}); + }); + await tx.transaction(async nested => { await signalDatabaseWork(nested, "dropped-too"); rollback(); }).catch(() => {}); + }))).toMatchObject({ statements: 1, sent: ["kept"], delivered: ["kept"], failure: null }); + }); + + it("still sends a topic signalled in a rolled-back savepoint when the outer level signals it again", async () => { + expect(await run(root => root.transaction(async tx => { + await tx.transaction(async nested => { await signalDatabaseWork(nested, "a"); rollback(); }).catch(() => {}); + await signalDatabaseWork(tx, "a"); + }))).toMatchObject({ statements: 1, delivered: ["a"] }); + expect(await run(root => root.transaction(async tx => { + await signalDatabaseWork(tx, "a"); + await tx.transaction(async nested => { await signalDatabaseWork(nested, "a"); rollback(); }).catch(() => {}); + }))).toMatchObject({ statements: 1, delivered: ["a"] }); + }); + + it("sends nothing when the callback throws", async () => { + expect(await run(root => root.transaction(async tx => { await signalDatabaseWork(tx, "a"); rollback(); }))) + .toMatchObject({ statements: 0, delivered: [], failure: "rollback" }); + }); + + it("fails and rolls back the transaction when the commit-time send fails", async () => { + await db.execute(sql`create table if not exists work_signal_flush_test (id text primary key)`); + const result = await run(root => root.transaction(async tx => { + await tx.execute(sql`insert into work_signal_flush_test values ('flush')`); + await signalDatabaseWork(tx, "a"); + await tx.execute(sql`select 1 / 0`).catch(() => {}); + })); + expect(result.delivered).toEqual([]); + expect(result.statements).toBe(1); + expect(result.failure).toMatch(/pg_notify/); + expect(await db.execute(sql`select id from work_signal_flush_test where id = 'flush'`)).toHaveLength(0); + }); + + it("sends a large number of distinct topics in one bounded statement", async () => { + const names = Array.from({ length: 500 }, (_, index) => `topic-${index}`); + const result = await run(root => root.transaction(async tx => { for (const name of names) await signalDatabaseWork(tx, name); })); + expect(result.statements).toBe(1); + expect(result.delivered).toEqual(names); + }); + + it("rejects a signal recorded after its transaction or savepoint ended instead of losing it", async () => { + let outer: Parameters[0]>[0] | undefined; + let savepoint: typeof outer; + const result = await run(root => root.transaction(async tx => { + outer = tx; + await signalDatabaseWork(tx, "a"); + await tx.transaction(async nested => { savepoint = nested; await signalDatabaseWork(nested, "b"); }); + await expect(signalDatabaseWork(savepoint!, "late-savepoint")).rejects.toThrow("after its transaction or savepoint ended"); + await expect(notifyDatabaseWorkOnCommit(savepoint!, "late-savepoint")).rejects.toThrow("after its transaction or savepoint ended"); + })); + expect(result).toMatchObject({ statements: 1, delivered: ["a", "b"], failure: null }); + await expect(signalDatabaseWork(outer!, "late-outer")).rejects.toThrow("after its transaction or savepoint ended"); + await expect(notifyDatabaseWorkOnCommit(outer!, "late-outer")).rejects.toThrow("after its transaction or savepoint ended"); + }); + + it("starts every transaction clean, including concurrent transactions and a retried callback", async () => { + expect(await run(async root => { + await root.transaction(async tx => { await signalDatabaseWork(tx, "a"); }); + await root.transaction(async tx => { await signalDatabaseWork(tx, "a"); }); + await Promise.all([1, 2].map(() => root.transaction(async tx => { await signalDatabaseWork(tx, "b"); }))); + let attempts = 0; + const callback = async (tx: Parameters[0]>[0]) => { + attempts += 1; + await signalDatabaseWork(tx, "c"); + if (attempts === 1) rollback(); + }; + await root.transaction(callback).catch(() => {}); + await root.transaction(callback); + })).toMatchObject({ statements: 5, delivered: ["a", "a", "b", "b", "c"] }); + }); +}); diff --git a/packages/db/src/work-signals.ts b/packages/db/src/work-signals.ts index baf4ca24856..05b83a417cf 100644 --- a/packages/db/src/work-signals.ts +++ b/packages/db/src/work-signals.ts @@ -7,7 +7,7 @@ import { randomUUID } from "node:crypto"; type Listener = (event: "intent" | "settled", hints?: ReadonlySet) => void; type Transaction = { topics: Set; hints: Map>; xid?: Promise; uncertain: boolean }; type Scope = { key: object; listeners: Map>; transactions: Set; root: Connection; notificationOrigin: string; notify: boolean }; -type Context = { scope: Scope; transaction?: Transaction }; +type Context = { scope: Scope; transaction?: Transaction; pending?: Map; ended?: boolean }; type Connection = { transaction: (...args: any[]) => Promise; execute: (...args: any[]) => Promise }; const contexts = new WeakMap(); @@ -33,10 +33,21 @@ function install(connection: Connection, context: Context) { // savepoint must not wake a consumer before its parent commits. const state = context.transaction ?? { topics: new Set(), hints: new Map>(), uncertain: false }; try { + let level: Context | undefined; const result = await transaction.call(this, async (tx: Connection) => { - install(tx, { scope: context.scope, transaction: state }); - return callback(tx); + const current: Context = { scope: context.scope, transaction: state, pending: new Map() }; + level = current; + install(tx, current); + try { + const value = await callback(tx); + current.ended = true; + if (!context.transaction) await flushNotifications(tx, current.pending!); + return value; + } finally { current.ended = true; } }, ...options); + if (context.pending && level?.pending) { + for (const [key, payload] of level.pending) if (!context.pending.has(key)) context.pending.set(key, payload); + } if (!context.transaction) context.scope.transactions.delete(state); return result; } catch (error) { @@ -74,11 +85,19 @@ export async function signalDatabaseWork(connection: object, topic: string, hint // Keep a failed acquisition distinguishable from an uncertain queue write. try { await state.xid; } catch (error) { state.xid = undefined; throw error; } - if (context.scope.notify) { - // PostgreSQL delivers only after the outer commit, including savepoints. - // Queue rows remain authoritative; notification payloads contain no data. - await (connection as Connection).execute(sql`select pg_notify(${DATABASE_WORK_CHANNEL}, ${notification(context.scope, topic)})`); - } + if (context.scope.notify) notifyAtCommit(context, notification(context.scope, topic)); +} + +function notifyAtCommit(context: Context, payload: string): void { + if (context.ended) throw new Error("Database work was signalled after its transaction or savepoint ended"); + const key = `${DATABASE_WORK_CHANNEL}\u0000${payload}`; + if (!context.pending!.has(key)) context.pending!.set(key, payload); +} + +async function flushNotifications(connection: Connection, pending: Map): Promise { + if (pending.size === 0) return; + await connection.execute(sql`select pg_notify(${DATABASE_WORK_CHANNEL}, payload) + from jsonb_array_elements_text(${JSON.stringify([...pending.values()])}::jsonb) as notification(payload)`); } export const DATABASE_WORK_CHANNEL = "paperclip_work_v1"; @@ -101,7 +120,7 @@ export async function notifyDatabaseWorkOnCommit(connection: object, topic: stri const context = contexts.get(connection); if (!context?.scope.notify) return; if (!context.transaction) throw new Error("Database work must be registered inside a transaction"); - await (connection as Connection).execute(sql`select pg_notify(${DATABASE_WORK_CHANNEL}, ${notification(context.scope, topic)})`); + notifyAtCommit(context, notification(context.scope, topic)); } /** A post-commit invalidation hint, for already-persisted live UI state. */