experimental-a2 0.20.0 → 0.22.0

package/sql/postgres/schema.sql

@@ -1,13 +1,24 @@
--- A2's tables for experimental-a2/store-postgres.
+-- A2's tables for experimental-a2/store-postgres. drizzle-schema.ts, next to
+-- this file, shows the same tables as Drizzle definitions, as an example.
 --
--- Apply this file once before the first deploy, and again whenever a release
--- raises the schema version. Every statement creates only what is missing and
--- leaves existing data alone, so the file is safe to re-run on any A2
--- database, whichever release created it.
+-- Apply this file before the first deploy, and again when a release's
+-- changelog says the tables changed. Every statement creates only what is
+-- missing and leaves existing data alone, so the file is safe to re-run on any
+-- A2 database, whichever release created it. A2 checks nothing up front: a
+-- query that finds a table or column missing throws STORE_NOT_CONFIGURED.
+--
+-- On a database from a release that ran handlers, it drops the work those
+-- handlers hadn't finished, and the columns they dispatched by, so drain
+-- earlier deployments and apply it while none is running.
 --
 -- Each index sits behind a catalog check: `create index if not exists` takes
 -- a share lock on its table, and requires owning it, even when the index
 -- exists. The check makes a re-run on a live database wait for no writer.
+--
+-- The file works as a migration as it ships: copy it into your migration
+-- tool's folder. The breakpoint comment after each statement splits it for
+-- tools that send one statement per query, like Drizzle on PGlite; to every
+-- other tool, psql included, it's only a comment.
 
 create table if not exists a2_events (
   session_id   text    not null,
@@ -17,47 +28,53 @@ create table if not exists a2_events (
   event_id     text    not null,
   created_at   bigint  not null,
   cause        jsonb,
+  primary key (session_id, idx)
+);
+--> statement-breakpoint
+
+-- One row per run of a cursor: an event cursor's one event, a lane's run of
+-- queued events, or a log cursor's position. A run is keyed by the head it
+-- started at (`epoch`), so a clear starts new runs instead of rewriting old
+-- ones.
+create table if not exists a2_cursors (
+  session_id   text    not null,
+  consumer     text    not null,
+  cursor_key   text    not null,
+  epoch        bigint  not null,
   lane         text,
-  lane_ready   boolean not null default false,
-  processed_at bigint,
-  processed_by_attempt integer,
-  returned_event_ids jsonb,
+  kind         text    not null,
+  position     bigint  not null,
+  head         bigint,
+  types        jsonb,
+  attempt_count integer not null default 0,
   first_claimed_at bigint,
   last_claimed_at bigint,
-  attempt_count integer not null default 0,
+  claim_holder text,
+  claim_expires_at bigint,
   failure_count integer not null default 0,
   last_failed_at bigint,
   last_failed_attempt integer,
   last_error   text,
   failed_at    bigint,
-  claim_holder text,
-  claim_expires_at bigint,
-  primary key (session_id, idx)
+  completed_idx bigint,
+  completed_attempt integer,
+  returned_event_ids jsonb,
+  primary key (session_id, cursor_key, consumer, epoch)
 );
+--> statement-breakpoint
 
-do $$ begin
-  if to_regclass('a2_events_event_id') is null then
-    create unique index if not exists a2_events_event_id on a2_events (event_id);
-  end if;
-  if to_regclass('a2_events_unprocessed') is null then
-    create index if not exists a2_events_unprocessed
-      on a2_events (session_id, idx) where processed_at is null;
-  end if;
-  if to_regclass('a2_events_lane_pending') is null then
-    create index if not exists a2_events_lane_pending
-      on a2_events (session_id, lane, idx) where processed_at is null;
-  end if;
-  if to_regclass('a2_events_dispatch_ready') is null then
-    create index if not exists a2_events_dispatch_ready
-      on a2_events (session_id, idx)
-      where lane_ready and processed_at is null and failed_at is null;
-  end if;
-  if to_regclass('a2_events_claim_expiry') is null then
-    create index if not exists a2_events_claim_expiry
-      on a2_events (session_id, claim_expires_at)
-      where lane_ready and processed_at is null and failed_at is null;
-  end if;
-end $$;
+-- A lane cursor's queue: the events appended for the lane, in log order.
+create table if not exists a2_lane_events (
+  session_id   text    not null,
+  consumer     text    not null,
+  lane         text    not null,
+  idx          bigint  not null,
+  done         boolean not null default false,
+  completed_attempt integer,
+  returned_event_ids jsonb,
+  primary key (session_id, consumer, lane, idx)
+);
+--> statement-breakpoint
 
 create table if not exists a2_snapshots (
   session_id   text   not null,
@@ -67,6 +84,7 @@ create table if not exists a2_snapshots (
   updated_at   bigint not null,
   primary key (session_id, reducer_name)
 );
+--> statement-breakpoint
 
 create table if not exists a2_snapshot_history (
   session_id   text   not null,
@@ -76,26 +94,37 @@ create table if not exists a2_snapshot_history (
   updated_at   bigint not null,
   primary key (session_id, reducer_name, up_to_index)
 );
+--> statement-breakpoint
+
+-- Earlier releases pinned snapshots per event; this one pins them per
+-- cursor head. Pins only hold history for work in flight, so old ones go.
+do $$ begin
+  if to_regclass('a2_snapshot_pins') is not null and not exists (
+    select 1 from pg_attribute
+     where attrelid = to_regclass('a2_snapshot_pins')
+       and attname = 'cursor_key' and not attisdropped
+  ) then
+    drop table a2_snapshot_pins;
+  end if;
+end $$;
+--> statement-breakpoint
 
 create table if not exists a2_snapshot_pins (
   session_id   text   not null,
   event_index  bigint not null,
+  consumer     text   not null,
+  cursor_key   text   not null,
   reducer_name text   not null,
   up_to_index  bigint not null,
-  primary key (session_id, event_index, reducer_name, up_to_index)
+  primary key (session_id, event_index, consumer, cursor_key, reducer_name, up_to_index)
 );
-
-do $$ begin
-  if to_regclass('a2_snapshot_pins_checkpoint') is null then
-    create index if not exists a2_snapshot_pins_checkpoint
-      on a2_snapshot_pins (session_id, reducer_name, up_to_index);
-  end if;
-end $$;
+--> statement-breakpoint
 
 create table if not exists a2_clears (
   session_id  text   primary key,
   clear_index bigint not null
 );
+--> statement-breakpoint
 
 create table if not exists a2_presence (
   ns          text   not null,
@@ -107,31 +136,162 @@ create table if not exists a2_presence (
   expires_at  bigint not null,
   primary key (ns, participant, field)
 );
+--> statement-breakpoint
 
-create table if not exists a2_schema (
-  only_row boolean primary key default true check (only_row),
-  version  integer not null
-);
+-- From an earlier release: work its handlers hadn't finished is dropped,
+-- since this release runs no handlers to finish it. Every event is kept.
+-- Causes gain the dispatcher that appended them, the handlers table
+-- (`a2.handlers`), and its lane. Then the old dispatch columns go, and
+-- their indexes with them. The block locks the events first, so an earlier
+-- release still writing waits and then fails, rather than committing between
+-- its statements, and it commits whole, or not at all.
+do $$ begin
+  if exists (
+    select 1 from pg_attribute
+     where attrelid = to_regclass('a2_events')
+       and attname = 'processed_at' and not attisdropped
+  ) then
+    lock table a2_events in access exclusive mode;
+
+    update a2_events child
+       set cause = jsonb_build_object(
+             'consumer', 'a2.handlers',
+             'lane', (select parent.lane from a2_events parent
+                       where parent.session_id = child.session_id
+                         and parent.idx = (child.cause ->> 'index')::bigint)
+           ) || child.cause
+     where child.cause is not null and not child.cause ? 'consumer';
 
--- The version is recorded last, and only once everything above exists, so a
--- run that skipped a failed statement records nothing, whichever tool ran it.
+    alter table a2_events
+      drop column lane,
+      drop column lane_ready,
+      drop column processed_at,
+      drop column processed_by_attempt,
+      drop column returned_event_ids,
+      drop column first_claimed_at,
+      drop column last_claimed_at,
+      drop column attempt_count,
+      drop column failure_count,
+      drop column last_failed_at,
+      drop column last_failed_attempt,
+      drop column last_error,
+      drop column failed_at,
+      drop column claim_holder,
+      drop column claim_expires_at;
+  end if;
+end $$;
+--> statement-breakpoint
+
+-- Earlier releases recorded a schema version here and checked it before
+-- their first query. This one checks nothing up front.
+drop table if exists a2_schema;
+--> statement-breakpoint
+
+-- Runs an operation's statements in one round trip: A2 sends each write that
+-- takes a session's lock as one call, the lock and then the statements that
+-- need it, so it holds the lock only while the server runs them. Each
+-- statement takes its snapshot when it starts, so those after the lock see
+-- what its last holder committed; a single statement can't, since its
+-- snapshot predates the lock. Each statement is a select of jsonb rows: a row
+-- with an `abort` key fails the call and rolls it back, and one with a `stop`
+-- key ends it. It needs read committed, the default: under a stricter level
+-- every statement would share the first one's snapshot, so it refuses to run.
+-- Created only if missing, as the indexes are: a later release that changes it
+-- adds a function with a new name.
+do $$ declare grantee text; begin
+  if to_regprocedure('a2_batch(text[], jsonb)') is null then
+    create function a2_batch(statements text[], params jsonb)
+    returns setof jsonb
+    language plpgsql
+    volatile
+    as $batch$
+    declare
+      statement text;
+      result jsonb;
+    begin
+      if current_setting('transaction_isolation') <> 'read committed' then
+        raise exception using errcode = 'A2002',
+          message = 'a2_batch needs the read committed isolation level';
+      end if;
+      foreach statement in array statements loop
+        for result in execute statement using params loop
+          if result ? 'abort' then
+            raise exception using errcode = 'A2001',
+              message = 'a2_batch aborted', detail = result::text;
+          end if;
+          return next result;
+          if result ? 'stop' then
+            return;
+          end if;
+        end loop;
+      end loop;
+    end
+    $batch$;
+    -- Default privileges can grant a new function to roles besides PUBLIC, as
+    -- platforms that serve functions over an API grant theirs: it starts with
+    -- none but its owner's. Grants made after it exist are left alone.
+    for grantee in
+      select acl.grantee::regrole::text
+        from pg_proc proc, aclexplode(proc.proacl) acl
+       where proc.oid = to_regprocedure('a2_batch(text[], jsonb)')
+         and acl.grantee not in (0, proc.proowner)
+    loop
+      execute format('revoke execute on function a2_batch(text[], jsonb) from %s', grantee);
+    end loop;
+  end if;
+  -- It runs any statement it's handed, as its caller: only its owner, the role
+  -- that applies this file, may call it, and not every role, as Postgres lets
+  -- by default. Platforms that serve functions over an API would serve it too.
+  if pg_has_role(
+    current_user,
+    (select proowner from pg_proc
+      where oid = to_regprocedure('a2_batch(text[], jsonb)')),
+    'usage'
+  ) then
+    revoke execute on function a2_batch(text[], jsonb) from public;
+  end if;
+end $$;
+--> statement-breakpoint
+
+do $$ begin
+  if to_regclass('a2_events_types') is null then
+    create index if not exists a2_events_types
+      on a2_events (session_id, event_type, idx);
+  end if;
+  if to_regclass('a2_cursors_heads') is null then
+    create index if not exists a2_cursors_heads
+      on a2_cursors (session_id, head) where head is not null;
+  end if;
+  if to_regclass('a2_cursors_lanes') is null then
+    create index if not exists a2_cursors_lanes
+      on a2_cursors (session_id) where kind = 'lane';
+  end if;
+  if to_regclass('a2_snapshot_pins_checkpoint') is null then
+    create index if not exists a2_snapshot_pins_checkpoint
+      on a2_snapshot_pins (session_id, reducer_name, up_to_index);
+  end if;
+end $$;
+--> statement-breakpoint
+
+-- Event ids are unique per session, through the index on (session_id,
+-- event_id). It replaces a2_events_event_id, on event_id alone. The swap
+-- locks the table before it builds, so it waits for running queries instead
+-- of deadlocking with a writer when the whole file runs as one transaction.
+-- The old index goes only once the new one is valid, so a session's ids
+-- always have a unique index.
 do $$ begin
-  if to_regclass('a2_events') is null
-    or to_regclass('a2_events_event_id') is null
-    or to_regclass('a2_events_unprocessed') is null
-    or to_regclass('a2_events_lane_pending') is null
-    or to_regclass('a2_events_dispatch_ready') is null
-    or to_regclass('a2_events_claim_expiry') is null
-    or to_regclass('a2_snapshots') is null
-    or to_regclass('a2_snapshot_history') is null
-    or to_regclass('a2_snapshot_pins') is null
-    or to_regclass('a2_snapshot_pins_checkpoint') is null
-    or to_regclass('a2_clears') is null
-    or to_regclass('a2_presence') is null
-  then
-    raise exception 'A2 schema incomplete: an earlier statement in schema.sql failed. Fix it and apply the file again.';
+  if to_regclass('a2_events_session_event_id') is null then
+    if to_regclass('a2_events_event_id') is not null then
+      lock table a2_events in access exclusive mode;
+    end if;
+    create unique index if not exists a2_events_session_event_id
+      on a2_events (session_id, event_id);
+  end if;
+  if to_regclass('a2_events_event_id') is not null and exists (
+    select 1 from pg_index
+     where indexrelid = to_regclass('a2_events_session_event_id')
+       and indisvalid and indisunique
+  ) then
+    drop index a2_events_event_id;
   end if;
-  insert into a2_schema (version) values (1)
-  on conflict (only_row)
-  do update set version = greatest(a2_schema.version, excluded.version);
 end $$;

package/src/actor-shared.ts

@@ -131,7 +131,11 @@ export type ActorScheduleSend<E> = {
 export type ActorContext<D extends ActorProtocol> = {
   /** Mutable draft, committed atomically with the handler's completion. */
   state: D['state']
-  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  /**
+   * The message id — stable across re-runs and unique within the instance;
+   * the idempotency key for external I/O. An explicit send id that repeats
+   * in another instance repeats here too.
+   */
   id: string
   /** Durable 1-based dispatch ordinal of this message. */
   attempt: number
@@ -150,7 +154,11 @@ export type ActorContext<D extends ActorProtocol> = {
  * whose serial handlers decide against fresh state.
  */
 export type ActorConcurrentContext<D extends ActorProtocol> = {
-  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  /**
+   * The message id — stable across re-runs and unique within the instance;
+   * the idempotency key for external I/O. An explicit send id that repeats
+   * in another instance repeats here too.
+   */
   id: string
   /** Durable 1-based dispatch ordinal of this message. */
   attempt: number

package/src/actor.ts

@@ -82,7 +82,14 @@ import { setServerFetchHooks } from './server-fetch.ts'
 import { sseResponse } from './sse.ts'
 import { isSessionCleared, sessionClearedError } from './session-clear.ts'
 import type { SessionCleared } from './session-clear.ts'
-import type { A2Scheduler, A2Server, HandlerEntry, Session } from './server.ts'
+import type {
+  A2Scheduler,
+  A2Server,
+  ConsumerContext,
+  ConsumerResult,
+  Session,
+} from './server.ts'
+import { runtimeConsumer } from './runtime-consumer.ts'
 import type { A2Store } from './store.ts'
 import type { StandardSchemaV1 } from './standard-schema.ts'
 import type { A2Telemetry } from './telemetry.ts'
@@ -460,14 +467,16 @@ export function actor<D extends ActorProtocol>(
     return send as ActorSend<D['events']>
   }
 
-  const handlers: Record<string, HandlerEntry<EventDefs>> = {}
+  type Run = (ctx: ConsumerContext<EventDefs>) => ConsumerResult<EventDefs>
+  const concurrentRuns = new Map<string, Run>()
+  const serialRuns = new Map<string, Run>()
   for (const [eventName, def] of handlersByEvent) {
     if (def.kind === 'concurrent') {
       // No lane: concurrent handlers run in parallel — with the lane
       // and with each other. They cannot write state (no draft to
       // commit), so no serialization is needed for correctness; slow
       // I/O lives here without blocking the actor.
-      handlers[eventName] = async (ctx) => {
+      concurrentRuns.set(eventName, async (ctx) => {
         const sends: { type: string; payload: unknown }[] = []
         try {
           await def.handle(
@@ -509,78 +518,70 @@ export function actor<D extends ActorProtocol>(
         }
         // Sends commit atomically with settlement; re-runs converge on
         // the same deterministic message ids.
-        return sends
-      }
+        return sends as never
+      })
       continue
     }
-    handlers[eventName] = {
-      // One lane for every serial handler of one instance: the next
-      // message starts only after the previous one completed, and
-      // completion commits the state event atomically —
-      // read-modify-write on `ctx.state` is safe by exclusion, not by
-      // liveness.
-      lane: ACTOR_LANE,
-      handler: async (ctx) => {
-        // Explicitly 'latest', not the event-relative default: prior
-        // lane messages commit *after* this message was appended, so
-        // their state commits carry higher indexes than the trigger —
-        // an event-relative read would miss them and lose updates.
-        // 'latest' is deterministic here because the lane makes this
-        // attempt the only possible writer while it runs.
-        const { state, clearIndex } = await ctx.session.state(serverReducer, {
-          through: 'latest',
-        })
-        const draft = structuredClone(state)
-        const sends: { type: string; payload: unknown }[] = []
-        try {
-          await def.handle(
-            {
-              state: draft,
-              id: ctx.event.id,
-              attempt: ctx.attempt,
-              signal: ctx.signal,
-              send: makeSend(sends),
-              schedule: makeSchedule((taskName, timing, event) =>
-                ctx.session.schedule(
-                  taskName,
-                  timing as Parameters<typeof ctx.session.schedule>[1],
-                  event,
-                ),
+    serialRuns.set(eventName, async (ctx) => {
+      // Explicitly 'latest', not the event-relative default: prior
+      // lane messages commit *after* this message was appended, so
+      // their state commits carry higher indexes than the trigger —
+      // an event-relative read would miss them and lose updates.
+      // 'latest' is deterministic here because the lane makes this
+      // attempt the only possible writer while it runs.
+      const { state, clearIndex } = await ctx.session.state(serverReducer, {
+        through: 'latest',
+      })
+      const draft = structuredClone(state)
+      const sends: { type: string; payload: unknown }[] = []
+      try {
+        await def.handle(
+          {
+            state: draft,
+            id: ctx.event.id,
+            attempt: ctx.attempt,
+            signal: ctx.signal,
+            send: makeSend(sends),
+            schedule: makeSchedule((taskName, timing, event) =>
+              ctx.session.schedule(
+                taskName,
+                timing as Parameters<typeof ctx.session.schedule>[1],
+                event,
               ),
-            },
-            ctx.event.payload,
-          )
-        } catch (error) {
-          // A NonRetriableError is an answer: settle the message,
-          // record the refusal, deliver it to the waiting caller —
-          // no retry, no failure budget spent (buffered sends are
-          // discarded with the draft: refusals are total). Every
-          // other throw is an ordinary A2 handler failure: rethrown
-          // into core's retry machinery (backoff, ten-failure
-          // budget, dead letter) — including surrendered lease
-          // aborts, which core recognizes by identity.
-          if (!(error instanceof NonRetriableError)) throw error
-          const payload: ActorFailedPayload = {
-            message: ctx.event.id,
-            event: eventName,
-            error: describeError(error),
-          }
-          return { type: ACTOR_FAILED_EVENT, payload }
-        }
-        // One returned batch: buffered sends plus the state commit —
-        // committed atomically with completion, so a reserve and its
-        // trigger can never half-happen. The state event stays the
-        // outcome marker a waiting call resolves on. (Unconditional
-        // for now; a dirty check is a compatible later optimization.)
-        const payload: ActorStatePayload<D['state']> = {
-          state: draft,
-          event: eventName,
+            ),
+          },
+          ctx.event.payload,
+        )
+      } catch (error) {
+        // A NonRetriableError is an answer: settle the message,
+        // record the refusal, deliver it to the waiting caller —
+        // no retry, no failure budget spent (buffered sends are
+        // discarded with the draft: refusals are total). Every
+        // other throw is an ordinary A2 handler failure: rethrown
+        // into core's retry machinery (backoff, ten-failure
+        // budget, dead letter) — including surrendered lease
+        // aborts, which core recognizes by identity.
+        if (!(error instanceof NonRetriableError)) throw error
+        const payload: ActorFailedPayload = {
           message: ctx.event.id,
-          ...(clearIndex === undefined ? {} : { clearIndex }),
+          event: eventName,
+          error: describeError(error),
         }
-        return [...sends, { type: ACTOR_STATE_EVENT, payload }]
-      },
-    }
+        return { type: ACTOR_FAILED_EVENT, payload }
+      }
+      // One returned batch: buffered sends plus the state commit —
+      // committed atomically with completion, so a reserve and its
+      // trigger can never half-happen. The state event stays the
+      // outcome marker a waiting call resolves on. (Unconditional
+      // for now; a dirty check is a compatible later optimization.)
+      const payload: ActorStatePayload<D['state']> = {
+        state: draft,
+        event: eventName,
+        message: ctx.event.id,
+        ...(clearIndex === undefined ? {} : { clearIndex }),
+      }
+      return [...sends, { type: ACTOR_STATE_EVENT, payload }] as never
+    })
   }
 
   const presenceEnabled = (options as { presence?: unknown }).presence === true
@@ -590,9 +591,38 @@ export function actor<D extends ActorProtocol>(
   const contract = presenceEnabled
     ? createContract({ name, events, presence: openPresenceDefs })
     : createContract({ name, events })
+  // Serial messages share one lane per instance: the next starts only after
+  // the previous one completed, and completion commits the state event
+  // atomically, so read-modify-write on `ctx.state` is safe by exclusion,
+  // not by liveness. The lane is a function, so each message is queued on
+  // it as it's appended. Concurrent messages run alongside it and each
+  // other: they write no state.
+  const serialTypes = [...serialRuns.keys()]
+  const concurrentTypes = [...concurrentRuns.keys()]
+  const consumers = [
+    ...(serialTypes.length === 0
+      ? []
+      : [
+          runtimeConsumer({
+            contract,
+            name: 'a2.actor',
+            types: serialTypes,
+            lane: () => ACTOR_LANE,
+          }).run((ctx) => serialRuns.get(ctx.event.type)!(ctx as never)),
+        ]),
+    ...(concurrentTypes.length === 0
+      ? []
+      : [
+          runtimeConsumer({
+            contract,
+            name: 'a2.actor.concurrent',
+            types: concurrentTypes,
+          }).run((ctx) => concurrentRuns.get(ctx.event.type)!(ctx as never)),
+        ]),
+  ]
   const server = createServer({
     contract,
-    handlers,
+    consumers,
     ...(options.store ? { store: options.store } : {}),
     ...(options.scheduler ? { scheduler: options.scheduler } : {}),
     ...(options.telemetry ? { telemetry: options.telemetry } : {}),