experimental-a2 0.9.0 → 0.11.0

package/src/store-postgres.ts

@@ -10,9 +10,8 @@
  *
  * Semantics mirror the sqlite backend: `index` is stored as `idx`,
  * timestamps are epoch milliseconds written from the injected clock —
- * never SQL `now()` — and `stream()` is a poll loop. (A LISTEN/NOTIFY
- * upgrade can land later without any API change; callers never branch
- * on the transport.) Appends serialize per session via
+ * never SQL `now()`. Streams poll by default; an optional direct
+ * connection enables LISTEN/NOTIFY for events and presence. Appends serialize per session via
  * `pg_advisory_xact_lock`, so concurrent writers can't race the index
  * assignment.
  */
@@ -20,8 +19,25 @@
 import { A2Error } from './errors.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
 import { decodeReturnedEventIds } from './store-codec.ts'
-import { pollingStream } from './store-polling.ts'
+import { pollingStream, defaultSleep, type Sleeper } from './store-polling.ts'
+import { NOTIFY_TIMINGS, nullProtoRecord } from './internal.ts'
+import type { PresencePatch } from './contract.ts'
+import { pollPresence } from './store-presence-polling.ts'
+import {
+  postgresNotifications,
+  postgresNotificationChannel,
+  POSTGRES_NOTIFICATIONS_SQL,
+  type PostgresListenerConnection,
+} from './postgres-notifications.ts'
 import { retryableLazy } from './retryable-lazy.ts'
+import { postgresNotificationScope } from './postgres-notification-scope.ts'
+import { postgresPoolClient } from './postgres-pool.ts'
+import {
+  postgresConnectionKey,
+  sharePostgresClient,
+  sharePostgresPool,
+  sharePostgresListener,
+} from './postgres-resources.ts'
 import {
   RANDOM_IDS,
   SYSTEM_CLOCK,
@@ -57,8 +73,10 @@ export type PostgresClient = {
 }
 
 export type PostgresStoreOptions = {
-  /** Creates a `pg` Pool lazily (requires the optional peer dep `pg`). */
+  /** Shares a lazy `pg` Pool for matching connection configuration (optional peer `pg`). */
   connectionString?: string | undefined
+  /** Direct connection to the same database, shared by live LISTEN subscriptions. */
+  listenConnectionString?: string | undefined
   /** Bring your own client — a `pg` Pool, PGlite, a pooler wrapper. */
   client?: PostgresClient
   /** Injectable clock — every stored timestamp comes from here. */
@@ -68,8 +86,8 @@ export type PostgresStoreOptions = {
 }
 
 export type PostgresStore = A2Store & {
-  /** End the underlying pool/client (when this backend created it, or
-   * the injected client has `end`). */
+  /** Release this store’s subscriptions and resource references. Shared
+   * connections remain available to other stores. */
   close(): Promise<void>
 }
 
@@ -246,9 +264,16 @@ const wrap = async <T>(fn: () => Promise<T>): Promise<T> => {
 
 const jsonb = (value: unknown): string => JSON.stringify(value) ?? 'null'
 
-const initializeSchema = async (client: PostgresClient): Promise<void> => {
+const initializeSchema = async ({
+  client,
+  listen,
+}: {
+  client: PostgresClient
+  listen: boolean
+}): Promise<void> => {
+  const schema = SCHEMA + (listen ? POSTGRES_NOTIFICATIONS_SQL : '')
   if (!client.connect) {
-    await client.query(SCHEMA)
+    await client.query(schema)
     return
   }
 
@@ -260,7 +285,7 @@ const initializeSchema = async (client: PostgresClient): Promise<void> => {
     await conn.query(
       "select pg_advisory_xact_lock(hashtext('a2:postgres:schema'))",
     )
-    await conn.query(SCHEMA)
+    await conn.query(schema)
     await conn.query('commit')
   } catch (err) {
     await conn.query('rollback').catch(() => {})
@@ -270,9 +295,54 @@ const initializeSchema = async (client: PostgresClient): Promise<void> => {
   }
 }
 
+const loadPg = async () =>
+  import('pg').catch(() => {
+    throw new A2Error(
+      'STORE_NOT_CONFIGURED',
+      "Postgres connections created by A2 require the optional 'pg' package",
+    )
+  })
+
+const createListener = ({
+  pg,
+  connectionString,
+}: {
+  pg: Awaited<ReturnType<typeof loadPg>>
+  connectionString: string
+}): ReturnType<typeof postgresNotifications> =>
+  postgresNotifications(async () => {
+    const listener = new pg.default.Client({
+      connectionString,
+      application_name: 'a2-listener',
+      connectionTimeoutMillis: 10_000,
+    })
+    const listenerConnection: PostgresListenerConnection = {
+      connect: () => listener.connect(),
+      query: (text) => listener.query(text),
+      end: () => listener.end(),
+      onNotification: (callback) => {
+        listener.on('notification', callback)
+      },
+      onError: (callback) => {
+        listener.on('error', callback)
+      },
+      onEnd: (callback) => {
+        listener.on('end', callback)
+      },
+    }
+    return listenerConnection
+  })
+
 export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
   const clock = options.clock ?? SYSTEM_CLOCK
   const generateId = options.ids ?? RANDOM_IDS
+  // oxlint-disable-next-line a2/adapter-time-is-injected -- ephemeral notification source, never a stored event ID
+  const instanceId = crypto.randomUUID()
+  let closed = false
+  if (options.listenConnectionString === '')
+    throw new TypeError(
+      'listenConnectionString must be a direct Postgres connection string',
+    )
 
   if (!options.client && !options.connectionString) {
     throw new TypeError(
@@ -280,33 +350,74 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     )
   }
 
-  // Lazy init: the first operation creates the client (dynamic import
-  // of the optional peer dep `pg`) and the schema. Constructing the
-  // backend does no I/O — same contract as every other adapter.
+  const injected = options.client
+    ? sharePostgresClient(options.client)
+    : undefined
   const connection = retryableLazy(async () => {
-    let owned: PostgresClient | null = null
+    let lease = injected
+    if (!lease) {
+      const pg = await loadPg()
+      const connectionString = options.connectionString!
+      const key = postgresConnectionKey({
+        connectionString,
+        defaults: pg.default.defaults,
+      })
+      lease = sharePostgresPool({
+        key,
+        create: () => {
+          const pool = new pg.default.Pool({ connectionString })
+          // pg removes failed idle clients; active queries report their own errors.
+          pool.on('error', () => {})
+          return postgresPoolClient(pool)
+        },
+      })
+    }
     try {
-      let c = options.client
-      if (!c) {
-        const pg = await import('pg').catch(() => {
-          throw new A2Error(
-            'STORE_NOT_CONFIGURED',
-            "experimental-a2/store-postgres with a connectionString needs the 'pg' package (optional peer dependency) — install it, or inject a client",
-          )
+      const listen = Boolean(options.listenConnectionString)
+      const resource = lease.value
+      if (injected) await initializeSchema({ client: resource.client, listen })
+      else
+        await resource.initialize({
+          schema: SCHEMA + (listen ? POSTGRES_NOTIFICATIONS_SQL : ''),
+          run: () => initializeSchema({ client: resource.client, listen }),
         })
-        c = new pg.default.Pool({
-          connectionString: options.connectionString,
-        }) as unknown as PostgresClient
-        owned = c
-      }
-      await initializeSchema(c)
-      return c
-    } catch (err) {
-      if (owned?.end) await owned.end().catch(() => {})
-      throw err
+      return lease
+    } catch (error) {
+      if (!injected) await lease.release().catch(() => {})
+      throw error
     }
   })
-  const client = connection.get
+  const client = async (): Promise<PostgresClient> => {
+    if (closed) throw new A2Error('STORE_UNAVAILABLE', 'the store was closed')
+    const lease = await connection.get()
+    if (closed) throw new A2Error('STORE_UNAVAILABLE', 'the store was closed')
+    return lease.value.client
+  }
+
+  const notifications = options.listenConnectionString
+    ? postgresNotificationScope(async () => {
+        await client()
+        const pg = await loadPg()
+        const connectionString = options.listenConnectionString!
+        const key = postgresConnectionKey({
+          connectionString,
+          defaults: pg.default.defaults,
+        })
+        return sharePostgresListener({
+          key,
+          create: () => createListener({ pg, connectionString }),
+        })
+      })
+    : undefined
+  const presenceSubscriptions = new Map<
+    string,
+    {
+      listeners: Set<(patch: PresencePatch) => void>
+      ready: Promise<void>
+      poll: ReturnType<typeof pollPresence>
+      stop(): void
+    }
+  >()
 
   const readStateBatch = async (
     requests: readonly StoreStateReadRequest[],
@@ -405,9 +516,9 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     return reads
   }
 
-  // Transactions run on one connection. Pools check one out; a
-  // single-connection client (PGlite) serializes on this mutex instead.
-  let mutex: Promise<unknown> = Promise.resolve()
+  const begin = notifications
+    ? `begin; set local a2.presence_source = '${instanceId}'`
+    : 'begin'
   const withTx = async <T>(
     fn: (query: PostgresConnection['query']) => Promise<T>,
   ): Promise<T> => {
@@ -415,7 +526,7 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     if (c.connect) {
       const conn = await c.connect()
       try {
-        await conn.query('begin')
+        await conn.query(begin)
         const result = await fn((text, values) => conn.query(text, values))
         await conn.query('commit')
         return result
@@ -426,22 +537,22 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
         conn.release()
       }
     }
-    const run = mutex.then(async () => {
-      await c.query('begin')
+    const resource = (await connection.get()).value
+    return resource.exclusive(async () => {
+      const raw = resource.raw
+      await raw.query(begin)
       try {
-        const result = await fn((text, values) => c.query(text, values))
-        await c.query('commit')
+        const result = await fn((text, values) => raw.query(text, values))
+        await raw.query('commit')
         return result
       } catch (err) {
-        await c.query('rollback').catch(() => {})
+        await raw.query('rollback').catch(() => {})
         throw err
       }
     })
-    mutex = run.catch(() => {})
-    return run
   }
 
-  return {
+  const store: PostgresStore = {
     async append(sessionId, events) {
       if (events.length === 0) {
         return wrap(async () => {
@@ -1233,24 +1344,27 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
         const entries = Object.entries(values)
         if (entries.length === 0) return
         await wrap(async () => {
-          const c = await client()
           const atMs = meta.at.getTime()
           // Expiry anchors on the storage clock — the sender's `at`
           // orders writes but never anchors their lifetime.
           const expiresAtMs = clock.now().getTime() + meta.ttlMs
-          for (const [field, value] of entries) {
-            // Field-wise LWW: a stored row with a strictly newer `at`
-            // survives; ties go to the incoming write (memory parity).
-            // oxlint-disable-next-line no-await-in-loop -- independent per-field registers
-            await (value === null
-              ? c.query(
-                  `delete from a2_presence
+          const applied: Record<string, unknown> = nullProtoRecord()
+          const write = async (
+            query: PostgresConnection['query'],
+          ): Promise<void> => {
+            for (const [field, value] of entries) {
+              // Field-wise LWW: a stored row with a strictly newer `at`
+              // survives; ties go to the incoming write (memory parity).
+              // oxlint-disable-next-line no-await-in-loop -- independent per-field registers
+              const result = await (value === null
+                ? query(
+                    `delete from a2_presence
                     where ns = $1 and participant = $2 and field = $3
-                      and at <= $4`,
-                  [ns, participant, field, atMs],
-                )
-              : c.query(
-                  `insert into a2_presence
+                      and at <= $4${notifications ? ' returning field' : ''}`,
+                    [ns, participant, field, atMs],
+                  )
+                : query(
+                    `insert into a2_presence
                      (ns, participant, field, value, seen, at, expires_at)
                    values ($1, $2, $3, $4::jsonb, $5, $6, $7)
                    on conflict (ns, participant, field) do update set
@@ -1258,17 +1372,36 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
                      seen = excluded.seen,
                      at = excluded.at,
                      expires_at = excluded.expires_at
-                   where a2_presence.at <= excluded.at`,
-                  [
-                    ns,
-                    participant,
-                    field,
-                    jsonb(value),
-                    meta.seen,
-                    atMs,
-                    expiresAtMs,
-                  ],
-                ))
+                   where a2_presence.at <= excluded.at${notifications ? ' returning field' : ''}`,
+                    [
+                      ns,
+                      participant,
+                      field,
+                      jsonb(value),
+                      meta.seen,
+                      atMs,
+                      expiresAtMs,
+                    ],
+                  ))
+              if (result.rows.length) applied[field] = structuredClone(value)
+            }
+          }
+          if (notifications) await withTx(write)
+          else {
+            const c = await client()
+            await write((text, parameters) => c.query(text, parameters))
+          }
+          if (Object.keys(applied).length) {
+            const patch = {
+              participant,
+              values: applied,
+              seen: meta.seen,
+              at: new Date(atMs),
+            }
+            const subscription = presenceSubscriptions.get(ns)
+            subscription?.poll.update(patch)
+            for (const listener of subscription?.listeners ?? [])
+              listener(patch)
           }
         })
       },
@@ -1304,14 +1437,23 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     },
 
     stream(sessionId, opts) {
-      const readAfter = (afterIndex: number): Promise<StoredEvent[]> =>
+      const readAfter = (afterIndex: number): Promise<Event[]> =>
         wrap(async () => {
           const c = await client()
           const { rows } = await c.query(
-            'select * from a2_events where session_id = $1 and idx > $2 order by idx',
+            `select session_id, idx, event_type, payload, event_id, created_at
+               from a2_events
+              where session_id = $1 and idx > $2
+              order by idx`,
             [sessionId, afterIndex],
           )
-          return rows.map(toStored)
+          return rows.map(toEvent)
+        })
+      if (notifications)
+        return notifications.stream({
+          channel: postgresNotificationChannel({ kind: 'events', sessionId }),
+          read: readAfter,
+          startAfter: opts?.startAfter ?? 0,
         })
       return pollingStream(
         readAfter,
@@ -1320,10 +1462,85 @@ export function postgres(options: PostgresStoreOptions = {}): PostgresStore {
     },
 
     async close() {
-      const current = connection.peek()
-      if (!current) return
-      const c = await current
-      await c.end?.()
+      if (closed) return
+      closed = true
+      for (const subscription of presenceSubscriptions.values())
+        subscription.stop()
+      presenceSubscriptions.clear()
+      await notifications?.close()
+      const lease = await connection.peek()?.catch(() => undefined)
+      await (injected ?? lease)?.release()
     },
   }
+  if (notifications) {
+    const presence = store.presence!
+    const read = presence.read
+    presence.read = async (ns) => {
+      const subscription = presenceSubscriptions.get(ns)
+      await subscription?.ready
+      await subscription?.poll.ready
+      return read(ns)
+    }
+    presence.subscribe = (ns, onPatch) => {
+      if (closed) throw new A2Error('STORE_UNAVAILABLE', 'the store was closed')
+      let subscription = presenceSubscriptions.get(ns)
+      if (!subscription) {
+        const listeners = new Set<(patch: PresencePatch) => void>()
+        let dirty = false
+        let ended = false
+        let waiting: Sleeper | undefined
+        const lease = notifications.watch({
+          channel: postgresNotificationChannel({
+            kind: 'presence',
+            sessionId: ns,
+          }),
+          notify: (source) => {
+            if (source === instanceId) return
+            dirty = true
+            waiting?.cancel()
+          },
+        })
+        const poll = pollPresence({
+          read: async () => {
+            await lease.ready
+            if (ended || closed) return []
+            dirty = false
+            return read(ns)
+          },
+          deliver: (patch) => {
+            for (const listener of listeners) listener(patch)
+          },
+          sleep: () => {
+            waiting = defaultSleep(dirty ? 0 : NOTIFY_TIMINGS.safetyReadMs)
+            return waiting
+          },
+        })
+        void lease.ready.catch(() => poll.stop())
+        subscription = {
+          listeners,
+          ready: lease.ready,
+          poll,
+          stop() {
+            ended = true
+            poll.stop()
+            lease.stop()
+            waiting?.cancel()
+          },
+        }
+        presenceSubscriptions.set(ns, subscription)
+      }
+      subscription.listeners.add(onPatch)
+      let stopped = false
+      return () => {
+        if (stopped) return
+        stopped = true
+        subscription.listeners.delete(onPatch)
+        if (subscription.listeners.size === 0) {
+          presenceSubscriptions.delete(ns)
+          subscription.stop()
+        }
+      }
+    }
+  }
+  return store
 }

package/src/store-presence-polling.ts

@@ -0,0 +1,125 @@
+import type { PresencePatch } from './contract.ts'
+import { POLL_TIMINGS } from './internal.ts'
+import { defaultSleep, type Sleeper } from './store-polling.ts'
+import type { PresenceRow } from './store.ts'
+
+const key = ({
+  participant,
+  field,
+}: Pick<PresenceRow, 'participant' | 'field'>): string =>
+  JSON.stringify([participant, field])
+
+export function pollPresence({
+  read,
+  deliver,
+  sleep = defaultSleep,
+}: {
+  read: () => Promise<PresenceRow[]>
+  deliver: (patch: PresencePatch) => void
+  sleep?: (ms: number) => Sleeper
+}): {
+  ready: Promise<void>
+  update(patch: PresencePatch): void
+  wake(): void
+  stop(): void
+} {
+  let stopped = false
+  let pending: Sleeper | undefined
+  let interval = Math.min(
+    POLL_TIMINGS.activeFloorMs,
+    POLL_TIMINGS.idleCeilingMs,
+  )
+  let version = 0
+  const seen = new Map<string, Omit<PresenceRow, 'expiresAt'>>()
+  const activate = (): void => {
+    version += 1
+    interval = Math.min(POLL_TIMINGS.activeFloorMs, POLL_TIMINGS.idleCeilingMs)
+    pending?.cancel()
+  }
+  const ready = read()
+    .then((rows) => {
+      if (stopped) return
+      for (const row of rows) seen.set(key(row), row)
+      return undefined
+    })
+    // Seeding is best effort; foreground snapshots still report read errors.
+    .catch(() => undefined)
+
+  const run = async (): Promise<void> => {
+    await ready
+    for (;;) {
+      if (stopped) return
+      const before = version
+      pending = sleep(interval)
+      // oxlint-disable-next-line no-await-in-loop -- adaptive presence polling
+      await pending.promise
+      if (stopped) return
+      try {
+        const reading = version
+        // oxlint-disable-next-line no-await-in-loop -- read each new presence snapshot
+        const rows = await read()
+        if (stopped) return
+        if (version !== reading) continue
+        const live = new Set<string>()
+        let changed = false
+        for (const row of rows) {
+          const id = key(row)
+          live.add(id)
+          const prior = seen.get(id)
+          seen.set(id, row)
+          if (
+            prior?.seen === row.seen &&
+            prior.at.getTime() === row.at.getTime() &&
+            JSON.stringify(prior.value) === JSON.stringify(row.value)
+          )
+            continue
+          changed = true
+          deliver({
+            participant: row.participant,
+            values: { [row.field]: row.value },
+            seen: row.seen,
+            at: row.at,
+          })
+        }
+        for (const [id, row] of seen) {
+          if (live.has(id)) continue
+          seen.delete(id)
+          changed = true
+          deliver({
+            participant: row.participant,
+            values: { [row.field]: null },
+            seen: row.seen,
+            at: new Date(),
+          })
+        }
+        if (changed) activate()
+        else if (version === before)
+          interval = Math.min(interval * 2, POLL_TIMINGS.idleCeilingMs)
+      } catch {
+        interval = POLL_TIMINGS.idleCeilingMs
+      }
+    }
+  }
+  void run()
+  return {
+    ready,
+    wake: activate,
+    update(patch) {
+      for (const [field, value] of Object.entries(patch.values)) {
+        seen.set(key({ participant: patch.participant, field }), {
+          participant: patch.participant,
+          field,
+          value,
+          seen: patch.seen,
+          at: patch.at,
+        })
+      }
+      activate()
+    },
+    stop() {
+      stopped = true
+      pending?.cancel()
+      seen.clear()
+    },
+  }
+}