experimental-a2 0.19.0 → 0.21.1

package/sql/postgres/drizzle-schema.ts

@@ -0,0 +1,206 @@
+/**
+ * An example: A2's tables for experimental-a2/store-postgres as Drizzle
+ * definitions, the same tables schema.sql next to this file creates. It isn't
+ * an API, and nothing imports it. Use it however fits your setup, for example
+ * as a copy next to your own schema, so your migrations create A2's tables
+ * with yours. Adapt it to your Drizzle version, your ORM, and how you lay out
+ * your schema.
+ *
+ * Whatever creates them, A2 relies on the table and column names, the column
+ * types, the primary keys, and the unique index on a2_events.event_id. The
+ * other indexes keep its queries fast. Every name is spelled out, so Drizzle's
+ * `casing` setting changes none of them.
+ *
+ * A2's tables change only when a release's changelog says so; compare your
+ * copy with that release's file. Drizzle can't declare functions or
+ * triggers: add schema.sql's `a2_batch` function, which A2 runs its writes
+ * through, as a custom migration (`drizzle-kit generate --custom`), and the
+ * triggers `listenConnectionString` needs are in notifications.sql.
+ */
+import { sql } from 'drizzle-orm'
+import {
+  bigint,
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  uniqueIndex,
+} from 'drizzle-orm/pg-core'
+
+const int8 = (name: string) => bigint(name, { mode: 'number' })
+
+export const a2Events = pgTable(
+  'a2_events',
+  {
+    sessionId: text('session_id').notNull(),
+    idx: int8('idx').notNull(),
+    eventType: text('event_type').notNull(),
+    payload: jsonb('payload').notNull(),
+    eventId: text('event_id').notNull(),
+    createdAt: int8('created_at').notNull(),
+    cause: jsonb('cause'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_events_pkey',
+      columns: [table.sessionId, table.idx],
+    }),
+    uniqueIndex('a2_events_event_id').on(table.eventId),
+    index('a2_events_types').on(table.sessionId, table.eventType, table.idx),
+  ],
+)
+
+/**
+ * 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.
+ */
+export const a2Cursors = pgTable(
+  'a2_cursors',
+  {
+    sessionId: text('session_id').notNull(),
+    consumer: text('consumer').notNull(),
+    cursorKey: text('cursor_key').notNull(),
+    epoch: int8('epoch').notNull(),
+    lane: text('lane'),
+    kind: text('kind').notNull(),
+    position: int8('position').notNull(),
+    head: int8('head'),
+    types: jsonb('types'),
+    attemptCount: integer('attempt_count').notNull().default(0),
+    firstClaimedAt: int8('first_claimed_at'),
+    lastClaimedAt: int8('last_claimed_at'),
+    claimHolder: text('claim_holder'),
+    claimExpiresAt: int8('claim_expires_at'),
+    failureCount: integer('failure_count').notNull().default(0),
+    lastFailedAt: int8('last_failed_at'),
+    lastFailedAttempt: integer('last_failed_attempt'),
+    lastError: text('last_error'),
+    failedAt: int8('failed_at'),
+    completedIdx: int8('completed_idx'),
+    completedAttempt: integer('completed_attempt'),
+    returnedEventIds: jsonb('returned_event_ids'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_cursors_pkey',
+      columns: [table.sessionId, table.cursorKey, table.consumer, table.epoch],
+    }),
+    index('a2_cursors_heads')
+      .on(table.sessionId, table.head)
+      .where(sql`head is not null`),
+    index('a2_cursors_lanes')
+      .on(table.sessionId)
+      .where(sql`kind = 'lane'`),
+  ],
+)
+
+/** A lane cursor's queue: the events appended for the lane, in log order. */
+export const a2LaneEvents = pgTable(
+  'a2_lane_events',
+  {
+    sessionId: text('session_id').notNull(),
+    consumer: text('consumer').notNull(),
+    lane: text('lane').notNull(),
+    idx: int8('idx').notNull(),
+    done: boolean('done').notNull().default(false),
+    completedAttempt: integer('completed_attempt'),
+    returnedEventIds: jsonb('returned_event_ids'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_lane_events_pkey',
+      columns: [table.sessionId, table.consumer, table.lane, table.idx],
+    }),
+  ],
+)
+
+export const a2Snapshots = pgTable(
+  'a2_snapshots',
+  {
+    sessionId: text('session_id').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+    state: jsonb('state').notNull(),
+    updatedAt: int8('updated_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshots_pkey',
+      columns: [table.sessionId, table.reducerName],
+    }),
+  ],
+)
+
+export const a2SnapshotHistory = pgTable(
+  'a2_snapshot_history',
+  {
+    sessionId: text('session_id').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+    state: jsonb('state').notNull(),
+    updatedAt: int8('updated_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshot_history_pkey',
+      columns: [table.sessionId, table.reducerName, table.upToIndex],
+    }),
+  ],
+)
+
+export const a2SnapshotPins = pgTable(
+  'a2_snapshot_pins',
+  {
+    sessionId: text('session_id').notNull(),
+    eventIndex: int8('event_index').notNull(),
+    consumer: text('consumer').notNull(),
+    cursorKey: text('cursor_key').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshot_pins_pkey',
+      columns: [
+        table.sessionId,
+        table.eventIndex,
+        table.consumer,
+        table.cursorKey,
+        table.reducerName,
+        table.upToIndex,
+      ],
+    }),
+    index('a2_snapshot_pins_checkpoint').on(
+      table.sessionId,
+      table.reducerName,
+      table.upToIndex,
+    ),
+  ],
+)
+
+export const a2Clears = pgTable('a2_clears', {
+  sessionId: text('session_id').primaryKey(),
+  clearIndex: int8('clear_index').notNull(),
+})
+
+export const a2Presence = pgTable(
+  'a2_presence',
+  {
+    ns: text('ns').notNull(),
+    participant: text('participant').notNull(),
+    field: text('field').notNull(),
+    value: jsonb('value').notNull(),
+    seen: int8('seen').notNull(),
+    at: int8('at').notNull(),
+    expiresAt: int8('expires_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_presence_pkey',
+      columns: [table.ns, table.participant, table.field],
+    }),
+  ],
+)

package/sql/postgres/notifications.sql

@@ -0,0 +1,24 @@
+-- Notification triggers for experimental-a2/store-postgres, needed only with
+-- `listenConnectionString`. Apply after schema.sql. They wake live streams
+-- for every write to A2's event and presence tables, including writes from
+-- stores without the option. Safe to re-run.
+
+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/sql/postgres/schema.sql

@@ -0,0 +1,276 @@
+-- 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 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,
+  idx          bigint  not null,
+  event_type   text    not null,
+  payload      jsonb   not null,
+  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,
+  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,
+  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,
+  completed_idx bigint,
+  completed_attempt integer,
+  returned_event_ids jsonb,
+  primary key (session_id, cursor_key, consumer, epoch)
+);
+--> statement-breakpoint
+
+-- 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,
+  reducer_name text   not null,
+  up_to_index  bigint not null,
+  state        jsonb  not null,
+  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,
+  reducer_name text   not null,
+  up_to_index  bigint not null,
+  state        jsonb  not null,
+  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, consumer, cursor_key, reducer_name, up_to_index)
+);
+--> 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,
+  participant text   not null,
+  field       text   not null,
+  value       jsonb  not null,
+  seen        bigint not null,
+  at          bigint not null,
+  expires_at  bigint not null,
+  primary key (ns, participant, field)
+);
+--> statement-breakpoint
+
+-- 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';
+
+    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_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_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 $$;