experimental-a2 0.10.0 → 0.11.0

package/src/errors.ts

@@ -1,12 +1,4 @@
-/**
- * a2 errors — one class, discriminated by `code`.
- *
- * See specs/a2-implementation.md §10 and docs/reference/02-errors.mdx.
- * A single class serializes cleanly across the push-route boundary and
- * keeps `instanceof` checks working after bundling.
- */
-
-export type A2ErrorCode =
+export type A2ServerErrorCode =
   | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written
   | 'FORBIDDEN' // external ingress was denied by server.fetch authorization
   | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map
@@ -18,6 +10,9 @@ export type A2ErrorCode =
   | 'UNKNOWN_PRESENCE_FIELD' // presence field not in the contract's `presence` map
   | 'PRESENCE_NOT_SUPPORTED' // contract declares presence but the store lacks the capability
 
+export type A2ErrorCode =
+  A2ServerErrorCode | 'TIMEOUT' | 'HTTP_ERROR' | 'CONNECTION_FAILED' | 'UNKNOWN'
+
 export class A2Error extends Error {
   readonly code: A2ErrorCode
   /** e.g. the Standard Schema issues for INVALID_PAYLOAD */

package/src/index.ts

@@ -24,7 +24,7 @@ export type {
 export type { Reducer, ReducerBuilder } from './reducer.ts'
 
 export { A2Error, NonRetriableError } from './errors.ts'
-export type { A2ErrorCode } from './errors.ts'
+export type { A2ErrorCode, A2ServerErrorCode } from './errors.ts'
 
 export type {
   A2AttributeValue,

package/src/internal.ts

@@ -289,7 +289,7 @@ export const POLL_TIMINGS: {
   idleCeilingMs: number
 } = {
   activeFloorMs: 25,
-  idleCeilingMs: 250,
+  idleCeilingMs: 2_000,
 }
 
 /**

package/src/postgres-notification-scope.ts

@@ -0,0 +1,134 @@
+import { A2Error } from './errors.ts'
+import { retryableLazy } from './retryable-lazy.ts'
+import { NOTIFY_TIMINGS } from './internal.ts'
+import { defaultSleep, type Sleeper } from './store-polling.ts'
+import type { Event } from './store.ts'
+import type {
+  PostgresNotifications,
+  ResourceLease,
+} from './postgres-resources.ts'
+
+type ScopedNotifications = PostgresNotifications & {
+  stream(options: {
+    channel: string
+    read: (after: number) => Promise<Event[]>
+    startAfter: number
+  }): AsyncIterable<Event>
+}
+
+const failure = (error: unknown): A2Error =>
+  error instanceof A2Error
+    ? error
+    : new A2Error('STORE_UNAVAILABLE', 'Postgres subscription failed', {
+        cause: error,
+      })
+
+export function postgresNotificationScope(
+  load: () => Promise<ResourceLease<PostgresNotifications>>,
+): ScopedNotifications {
+  const state = {
+    shared: retryableLazy(load),
+    stops: new Set<() => void>(),
+    closed: false,
+  }
+
+  const scope: ScopedNotifications = {
+    watch(options) {
+      let stopped = false
+      let cancel!: () => void
+      const cancelled = new Promise<void>((resolve) => {
+        cancel = resolve
+      })
+      let subscription: ReturnType<PostgresNotifications['watch']> | undefined
+      const stop = (): void => {
+        stopped = true
+        cancel()
+        subscription?.stop()
+        state.stops.delete(stop)
+      }
+      state.stops.add(stop)
+      const ready = Promise.race([
+        cancelled,
+        state.shared.get().then(async ({ value }) => {
+          if (stopped || state.closed) return
+          subscription = value.watch(options)
+          await subscription.ready
+          return undefined
+        }),
+      ]).catch((error: unknown) => {
+        if (!stopped && !state.closed) throw failure(error)
+      })
+      return { ready, stop }
+    },
+    stream({ channel, read, startAfter }) {
+      return {
+        [Symbol.asyncIterator]() {
+          let stopped = false
+          let after = startAfter
+          let buffer: Event[] = []
+          let version = 0
+          let waiting: Sleeper | undefined
+          let lease: ReturnType<PostgresNotifications['watch']> | undefined
+          const stop = (): void => {
+            stopped = true
+            waiting?.cancel()
+            lease?.stop()
+            state.stops.delete(stop)
+          }
+          state.stops.add(stop)
+          return {
+            async next(): Promise<IteratorResult<Event>> {
+              try {
+                if (stopped || state.closed)
+                  return { done: true, value: undefined }
+                lease ??= scope.watch({
+                  channel,
+                  notify: () => {
+                    version += 1
+                    waiting?.cancel()
+                  },
+                })
+                await lease.ready
+                for (;;) {
+                  if (stopped || state.closed)
+                    return { done: true, value: undefined }
+                  const row = buffer.shift()
+                  if (row) {
+                    after = row.index
+                    return { done: false, value: row }
+                  }
+                  const before = version
+                  // oxlint-disable-next-line no-await-in-loop -- cursor catch-up
+                  buffer = await read(after)
+                  if (stopped || state.closed)
+                    return { done: true, value: undefined }
+                  if (buffer.length || before !== version) continue
+                  waiting = defaultSleep(NOTIFY_TIMINGS.safetyReadMs)
+                  // oxlint-disable-next-line no-await-in-loop -- wait for a hint or the safety read
+                  await waiting.promise
+                }
+              } catch (error) {
+                if (stopped || state.closed)
+                  return { done: true, value: undefined }
+                stop()
+                throw failure(error)
+              }
+            },
+            async return(): Promise<IteratorResult<Event>> {
+              stop()
+              return { done: true, value: undefined }
+            },
+          }
+        },
+      }
+    },
+    async close() {
+      if (state.closed) return
+      state.closed = true
+      for (const stop of state.stops) stop()
+      const lease = await state.shared.peek()?.catch(() => undefined)
+      await lease?.release()
+    },
+  }
+  return scope
+}

package/src/postgres-notifications.ts

@@ -0,0 +1,244 @@
+import { createHash } from 'node:crypto'
+import { NOTIFY_TIMINGS } from './internal.ts'
+import { defaultSleep, type Sleeper } from './store-polling.ts'
+
+export const postgresNotificationChannel = ({
+  kind,
+  sessionId,
+}: {
+  kind: 'events' | 'presence'
+  sessionId: string
+}): string => `a2_${kind}_${createHash('md5').update(sessionId).digest('hex')}`
+
+export type PostgresListenerConnection = {
+  connect(): Promise<unknown>
+  query(text: string): Promise<unknown>
+  end(): Promise<void>
+  onNotification(
+    listener: (message: {
+      channel: string
+      payload?: string | undefined
+    }) => void,
+  ): void
+  onError(listener: (error: Error) => void): void
+  onEnd(listener: () => void): void
+}
+
+type Watcher = {
+  notify(payload: string): void
+  resolve(): void
+  reject(error: unknown): void
+}
+
+type WatchOptions = { channel: string; notify: (payload: string) => void }
+
+export function postgresNotifications(
+  createConnection: () => Promise<PostgresListenerConnection>,
+): {
+  watch(options: WatchOptions): { ready: Promise<void>; stop(): void }
+  close(): Promise<void>
+} {
+  const channels = new Map<
+    string,
+    { listening: boolean; ready?: Promise<unknown>; watchers: Set<Watcher> }
+  >()
+  const ending = new Set<Promise<void>>()
+  const end = (connection: PostgresListenerConnection | undefined): void => {
+    if (!connection) return
+    const pending = connection
+      .end()
+      .catch(() => {})
+      .finally(() => {
+        ending.delete(pending)
+      })
+    ending.add(pending)
+  }
+  let current: PostgresListenerConnection | undefined
+  let task: Promise<void> | undefined
+  let retry: Sleeper | undefined
+  let delay = 100
+  let connectedAt = 0
+  let closed = false
+  const queues = new WeakMap<PostgresListenerConnection, Promise<unknown>>()
+  const query = ({
+    connection,
+    text,
+  }: {
+    connection: PostgresListenerConnection
+    text: string
+  }): Promise<unknown> => {
+    const result = (queues.get(connection) ?? Promise.resolve()).then(() => {
+      if (current !== connection)
+        throw new Error('Postgres listener disconnected')
+      return connection.query(text)
+    })
+    queues.set(
+      connection,
+      result.catch(() => {}),
+    )
+    return result
+  }
+
+  const fail = ({
+    connection,
+    error,
+  }: {
+    connection: PostgresListenerConnection | undefined
+    error: unknown
+  }): void => {
+    if (connection !== current) return
+    current = undefined
+    end(connection)
+    for (const entry of channels.values()) {
+      entry.listening = false
+      for (const watcher of entry.watchers) watcher.reject(error)
+    }
+    if (closed || channels.size === 0 || retry) return
+    if (Date.now() - connectedAt >= NOTIFY_TIMINGS.safetyReadMs) delay = 100
+    retry = defaultSleep(delay)
+    delay = Math.min(delay * 2, NOTIFY_TIMINGS.safetyReadMs)
+    void retry.promise.then(() => {
+      retry = undefined
+      reconcile()
+      return undefined
+    })
+  }
+
+  const reconcile = (): void => {
+    if (closed || task || retry || channels.size === 0) return
+    let attempt: PostgresListenerConnection | undefined
+    task = (async () => {
+      if (!current) {
+        connectedAt = Date.now()
+        const connection = await createConnection()
+        if (closed || channels.size === 0) {
+          await connection.end()
+          return
+        }
+        current = connection
+        attempt = connection
+        connectedAt = Date.now()
+        connection.onNotification(({ channel, payload }) => {
+          if (current !== connection) return
+          for (const watcher of channels.get(channel)?.watchers ?? [])
+            watcher.notify(payload ?? '')
+        })
+        connection.onError((error) => fail({ connection, error }))
+        connection.onEnd(() =>
+          fail({
+            connection,
+            error: new Error('Postgres listener disconnected'),
+          }),
+        )
+        await connection.connect()
+        if (current !== connection) return
+      }
+      const connection = current
+      attempt = connection
+      for (const [channel, entry] of channels) {
+        if (entry.listening) continue
+        entry.listening = true
+        // oxlint-disable-next-line no-await-in-loop -- one session owns the LISTEN commands
+        entry.ready = query({
+          connection,
+          text: `LISTEN "${channel.replaceAll('"', '""')}"`,
+        })
+        // oxlint-disable-next-line no-await-in-loop -- wait for subscription registration
+        await entry.ready
+        if (current !== connection) return
+        for (const watcher of entry.watchers) {
+          watcher.resolve()
+          watcher.notify('')
+        }
+      }
+    })()
+      .catch((error: unknown) => {
+        if (attempt === current) fail({ connection: attempt, error })
+      })
+      .finally(() => {
+        task = undefined
+        if ([...channels.values()].some((entry) => !entry.listening))
+          reconcile()
+      })
+  }
+
+  const manager = {
+    watch({ channel, notify }: WatchOptions) {
+      let resolve!: () => void
+      let reject!: (error: unknown) => void
+      const ready = new Promise<void>((yes, no) => {
+        resolve = yes
+        reject = no
+      })
+      const watcher = { notify, resolve, reject }
+      let entry = channels.get(channel)
+      if (!entry) {
+        entry = { listening: false, watchers: new Set() }
+        channels.set(channel, entry)
+      }
+      entry.watchers.add(watcher)
+      if (entry.listening) void entry.ready?.then(resolve, reject)
+      reconcile()
+      let stopped = false
+      return {
+        ready,
+        stop() {
+          if (stopped) return
+          stopped = true
+          resolve()
+          entry.watchers.delete(watcher)
+          if (entry.watchers.size > 0) return
+          channels.delete(channel)
+          if (channels.size === 0) {
+            retry?.cancel()
+            const connection = current
+            current = undefined
+            end(connection)
+          } else if (entry.listening) {
+            const connection = current
+            if (connection)
+              void query({
+                connection,
+                text: `UNLISTEN "${channel.replaceAll('"', '""')}"`,
+              }).catch((error: unknown) => fail({ connection, error }))
+          }
+        },
+      }
+    },
+    async close() {
+      closed = true
+      retry?.cancel()
+      for (const entry of channels.values()) {
+        for (const watcher of entry.watchers) watcher.resolve()
+      }
+      channels.clear()
+      const connection = current
+      current = undefined
+      end(connection)
+      await Promise.all(ending)
+    },
+  }
+  return manager
+}
+
+export const POSTGRES_NOTIFICATIONS_SQL = `
+create or replace function a2_notify_events() returns trigger language plpgsql as $$
+begin
+  perform pg_notify('a2_events_' || md5(new.session_id), '');
+  return null;
+end $$;
+create or replace function a2_notify_presence() returns trigger language plpgsql as $$
+begin
+  perform pg_notify('a2_presence_' || md5(case when TG_OP = 'DELETE' then old.ns else new.ns end),
+    coalesce(current_setting('a2.presence_source', true), ''));
+  return null;
+end $$;
+do $$ begin
+  if not exists (select 1 from pg_trigger where tgname = 'a2_notify_events' and tgrelid = 'a2_events'::regclass) then
+    create trigger a2_notify_events after insert on a2_events for each row execute function a2_notify_events();
+  end if;
+  if not exists (select 1 from pg_trigger where tgname = 'a2_notify_presence' and tgrelid = 'a2_presence'::regclass) then
+    create trigger a2_notify_presence after insert or update or delete on a2_presence for each row execute function a2_notify_presence();
+  end if;
+end $$;
+`

package/src/postgres-pool.ts

@@ -0,0 +1,65 @@
+import type { Pool } from 'pg'
+import { platformWaitUntil } from './platform.ts'
+import type { PostgresClient } from './store-postgres.ts'
+
+export function postgresPoolClient(pool: Pool): PostgresClient {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let resolve: (() => void) | undefined
+  const finish = () => {
+    clearTimeout(timer)
+    timer = undefined
+    resolve?.()
+    resolve = undefined
+  }
+  const keepAlive = () => {
+    const idleTimeout = pool.options.idleTimeoutMillis
+    if (
+      pool.ending ||
+      pool.idleCount === 0 ||
+      typeof idleTimeout !== 'number' ||
+      !Number.isFinite(idleTimeout) ||
+      idleTimeout <= 0
+    )
+      return
+    finish()
+    const pending = new Promise<void>((done) => {
+      resolve = done
+      timer = setTimeout(finish, idleTimeout + 100)
+      timer.unref()
+    })
+    platformWaitUntil(pending)
+  }
+  pool.on('remove', () => {
+    if (pool.totalCount === 0) finish()
+  })
+  return {
+    async query(text, values) {
+      try {
+        return await pool.query<Record<string, unknown>>(text, values)
+      } finally {
+        keepAlive()
+      }
+    },
+    async connect() {
+      const client = await pool.connect()
+      return {
+        query: (text, values) =>
+          client.query<Record<string, unknown>>(text, values),
+        release() {
+          try {
+            client.release()
+          } finally {
+            keepAlive()
+          }
+        },
+      }
+    },
+    async end() {
+      try {
+        await pool.end()
+      } finally {
+        finish()
+      }
+    },
+  }
+}

package/src/postgres-resources.ts

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto'
+import type { PostgresClient } from './store-postgres.ts'
+import type { postgresNotifications } from './postgres-notifications.ts'
+
+export type PostgresNotifications = ReturnType<typeof postgresNotifications>
+export type ResourceLease<T> = { value: T; release(): Promise<void> }
+type Entry<T> = { value: T; refs: number }
+type Cache<K, T> = {
+  get(key: K): Entry<T> | undefined
+  set(key: K, entry: Entry<T>): unknown
+  delete(key: K): boolean
+}
+
+export type PostgresQueries = {
+  client: PostgresClient
+  raw: PostgresClient
+  exclusive<T>(fn: () => Promise<T>): Promise<T>
+  initialize(options: {
+    schema: string
+    run: () => Promise<void>
+  }): Promise<void>
+  close(): Promise<void>
+}
+
+type Registry = {
+  pools: Map<string, Entry<PostgresQueries>>
+  injected: WeakMap<PostgresClient, Entry<PostgresQueries>>
+  listeners: Map<string, Entry<PostgresNotifications>>
+  identities: WeakMap<object, number>
+  nextIdentity: number
+}
+
+const registryKey = Symbol.for('experimental-a2.postgres-resources.v3')
+const registry = (): Registry => {
+  let value = Reflect.get(globalThis, registryKey) as Registry | undefined
+  if (!value) {
+    value = {
+      pools: new Map(),
+      injected: new WeakMap(),
+      listeners: new Map(),
+      identities: new WeakMap(),
+      nextIdentity: 0,
+    }
+    Reflect.set(globalThis, registryKey, value)
+  }
+  return value
+}
+
+const acquire = <K, T extends { close(): Promise<void> }>({
+  cache,
+  key,
+  create,
+}: {
+  cache: Cache<K, T>
+  key: K
+  create: () => T
+}): ResourceLease<T> => {
+  let entry = cache.get(key)
+  if (!entry) {
+    entry = { value: create(), refs: 0 }
+    cache.set(key, entry)
+  }
+  entry.refs += 1
+  const held = entry
+  let released = false
+  const lease = {
+    value: entry.value,
+    async release() {
+      if (released) return
+      released = true
+      held.refs -= 1
+      if (held.refs !== 0) return
+      if (cache.get(key) === held) cache.delete(key)
+      await held.value.close()
+    },
+  }
+  return lease
+}
+
+export function postgresConnectionKey({
+  connectionString,
+  defaults,
+}: {
+  connectionString: string
+  defaults: object
+}): string {
+  const shared = registry()
+  const visited = new Set<object>()
+  const identity = (value: object): number => {
+    let id = shared.identities.get(value)
+    if (id === undefined) {
+      id = ++shared.nextIdentity
+      shared.identities.set(value, id)
+    }
+    return id
+  }
+  const encode = (value: unknown): unknown => {
+    if (typeof value === 'function') return ['reference', identity(value)]
+    if (value === null || typeof value !== 'object')
+      return [typeof value, String(value)]
+    if (Buffer.isBuffer(value)) return ['buffer', value.toString('base64')]
+    const prototype: unknown = Object.getPrototypeOf(value)
+    if (
+      visited.has(value) ||
+      (prototype !== Object.prototype &&
+        prototype !== null &&
+        !Array.isArray(value))
+    )
+      return ['reference', identity(value)]
+    visited.add(value)
+    const result = [
+      Array.isArray(value) ? 'array' : 'object',
+      Object.getOwnPropertyNames(value)
+        .toSorted()
+        .map((key) => [key, encode(Reflect.get(value, key))]),
+    ]
+    visited.delete(value)
+    return result
+  }
+  const environment = Object.keys(process.env)
+    .filter((key) => key.startsWith('PG'))
+    .toSorted()
+    .map((key) => [key, process.env[key]])
+  return createHash('sha256')
+    .update(JSON.stringify([connectionString, environment, encode(defaults)]))
+    .digest('hex')
+}
+
+const queries = (raw: PostgresClient): PostgresQueries => {
+  let pending: Promise<unknown> = Promise.resolve()
+  const schemas = new Map<string, Promise<void>>()
+  const exclusive = <T>(fn: () => Promise<T>): Promise<T> => {
+    const result = pending.then(fn)
+    pending = result.catch(() => {})
+    return result
+  }
+  return {
+    raw,
+    client: raw.connect
+      ? raw
+      : { query: (text, values) => exclusive(() => raw.query(text, values)) },
+    exclusive,
+    initialize({ schema, run }) {
+      const existing = schemas.get(schema)
+      if (existing) return existing
+      const attempt = run()
+      schemas.set(schema, attempt)
+      void attempt.catch(() => {
+        if (schemas.get(schema) === attempt) schemas.delete(schema)
+      })
+      return attempt
+    },
+    async close() {
+      await pending
+      await raw.end?.()
+    },
+  }
+}
+
+export const sharePostgresPool = ({
+  key,
+  create,
+}: {
+  key: string
+  create: () => PostgresClient
+}): ResourceLease<PostgresQueries> =>
+  acquire({ cache: registry().pools, key, create: () => queries(create()) })
+
+export const sharePostgresClient = (
+  client: PostgresClient,
+): ResourceLease<PostgresQueries> =>
+  acquire({
+    cache: registry().injected,
+    key: client,
+    create: () => queries(client),
+  })
+
+export const sharePostgresListener = ({
+  key,
+  create,
+}: {
+  key: string
+  create: () => PostgresNotifications
+}): ResourceLease<PostgresNotifications> =>
+  acquire({ cache: registry().listeners, key, create })