experimental-a2 0.18.1 → 0.20.0

package/dist/server.js

@@ -1,2 +1,2 @@
-import { i as handler, n as deliverSchedulerAppend, r as deliverSchedulerClear, t as createServer } from "./server-D-Y4pqwu.js";
+import { i as handler, n as deliverSchedulerAppend, r as deliverSchedulerClear, t as createServer } from "./server-qyb5aJJG.js";
 export { createServer, deliverSchedulerAppend, deliverSchedulerClear, handler };

package/dist/session-clear-DGI4jTQ5.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-clear-DGI4jTQ5.js","names":[],"sources":["../src/errors.ts","../src/session-clear.ts"],"sourcesContent":["export type A2ServerErrorCode =\n  | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written\n  | 'FORBIDDEN' // external ingress was denied by server.fetch authorization\n  | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map\n  | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events\n  | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim or a clear replaced\n  | 'SESSION_CLEARED' // a read or call reached across the session's latest clear\n  | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal\n  | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written\n  | 'STORE_NOT_CONFIGURED' // production boot with no `store` passed\n  | 'UNKNOWN_PRESENCE_FIELD' // presence field not in the contract's `presence` map\n  | 'PRESENCE_NOT_SUPPORTED' // contract declares presence but the store lacks the capability\n\nexport type A2ErrorCode =\n  A2ServerErrorCode | 'TIMEOUT' | 'HTTP_ERROR' | 'CONNECTION_FAILED' | 'UNKNOWN'\n\nexport class A2Error extends Error {\n  readonly code: A2ErrorCode\n  /** e.g. the Standard Schema issues for INVALID_PAYLOAD */\n  readonly details: unknown\n\n  constructor(\n    code: A2ErrorCode,\n    message: string,\n    options?: { details?: unknown; cause?: unknown },\n  ) {\n    super(\n      message,\n      options && 'cause' in options ? { cause: options.cause } : undefined,\n    )\n    this.name = 'A2Error'\n    this.code = code\n    this.details = options?.details\n  }\n}\n\n/** A handler write whose attempt no longer owns its triggering event. */\nexport function supersededAttemptError(\n  sessionId: string,\n  cause: { index: number; attempt: number },\n): A2Error {\n  return new A2Error(\n    'SUPERSEDED_ATTEMPT',\n    `attempt ${cause.attempt} no longer owns event ${cause.index} in session '${sessionId}'`,\n  )\n}\n\n/**\n * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the\n * original as `cause`. A2Errors pass through untouched — they already\n * carry their own meaning.\n */\nexport function asStoreUnavailable(err: unknown): A2Error {\n  if (err instanceof A2Error) return err\n  return new A2Error('STORE_UNAVAILABLE', 'the store backend failed', {\n    cause: err,\n  })\n}\n\n/**\n * Throw from a handler to reject retrying: the failure is adjudicated\n * terminal immediately (dead-lettered on the first throw) instead of\n * consuming the ten-failure retry budget. For deterministic failures —\n * a guard that will refuse identically on every attempt — retrying is\n * waste and dead-lettering is the honest outcome. Matched by\n * `instanceof`, so subclasses carry domain meaning.\n */\nexport class NonRetriableError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'NonRetriableError'\n  }\n}\n","import { A2Error } from './errors.ts'\nimport type { Event } from './store.ts'\n\n/** A2's own event types start with this; application contracts cannot. */\nexport const RESERVED_EVENT_PREFIX = 'a2.'\n\n/** Reserved type of the marker a clear appends. */\nexport const CLEAR_EVENT_TYPE = 'a2.cleared'\n\n/** The marker `session.stream()` yields where a clear ended a lifetime. */\nexport type SessionCleared = Event & {\n  type: typeof CLEAR_EVENT_TYPE\n  payload: null\n}\n\n/** Accepts any stream item, including presence patches and snapshots. */\nexport function isSessionCleared(item: object): item is SessionCleared {\n  return (item as { type?: unknown }).type === CLEAR_EVENT_TYPE\n}\n\nexport function sessionClearedError(message: string): A2Error {\n  return new A2Error('SESSION_CLEARED', message)\n}\n"],"mappings":";AAgBA,IAAa,UAAb,cAA6B,MAAM;CACjC;;CAEA;CAEA,YACE,MACA,SACA,SACA;EACA,MACE,SACA,WAAW,WAAW,UAAU,EAAE,OAAO,QAAQ,MAAM,IAAI,KAAA,CAC7D;EACA,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,UAAU,SAAS;CAC1B;AACF;;AAGA,SAAgB,uBACd,WACA,OACS;CACT,OAAO,IAAI,QACT,sBACA,WAAW,MAAM,QAAQ,wBAAwB,MAAM,MAAM,eAAe,UAAU,EACxF;AACF;;;;;;AAOA,SAAgB,mBAAmB,KAAuB;CACxD,IAAI,eAAe,SAAS,OAAO;CACnC,OAAO,IAAI,QAAQ,qBAAqB,4BAA4B,EAClE,OAAO,IACT,CAAC;AACH;;;;;;;;;AAUA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS,OAAO;EACtB,KAAK,OAAO;CACd;AACF;;;;ACjEA,MAAa,mBAAmB;;AAShC,SAAgB,iBAAiB,MAAsC;CACrE,OAAQ,KAA4B,SAAS;AAC/C;AAEA,SAAgB,oBAAoB,SAA0B;CAC5D,OAAO,IAAI,QAAQ,mBAAmB,OAAO;AAC/C"}
+{"version":3,"file":"session-clear-DGI4jTQ5.js","names":[],"sources":["../src/errors.ts","../src/session-clear.ts"],"sourcesContent":["export type A2ServerErrorCode =\n  | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written\n  | 'FORBIDDEN' // external ingress was denied by server.fetch authorization\n  | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map\n  | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events\n  | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim or a clear replaced\n  | 'SESSION_CLEARED' // a read or call reached across the session's latest clear\n  | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal\n  | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written\n  | 'STORE_NOT_CONFIGURED' // no `store` in production, a missing peer dependency, or Postgres lacks A2's tables\n  | 'UNKNOWN_PRESENCE_FIELD' // presence field not in the contract's `presence` map\n  | 'PRESENCE_NOT_SUPPORTED' // contract declares presence but the store lacks the capability\n\nexport type A2ErrorCode =\n  A2ServerErrorCode | 'TIMEOUT' | 'HTTP_ERROR' | 'CONNECTION_FAILED' | 'UNKNOWN'\n\nexport class A2Error extends Error {\n  readonly code: A2ErrorCode\n  /** e.g. the Standard Schema issues for INVALID_PAYLOAD */\n  readonly details: unknown\n\n  constructor(\n    code: A2ErrorCode,\n    message: string,\n    options?: { details?: unknown; cause?: unknown },\n  ) {\n    super(\n      message,\n      options && 'cause' in options ? { cause: options.cause } : undefined,\n    )\n    this.name = 'A2Error'\n    this.code = code\n    this.details = options?.details\n  }\n}\n\n/** A handler write whose attempt no longer owns its triggering event. */\nexport function supersededAttemptError(\n  sessionId: string,\n  cause: { index: number; attempt: number },\n): A2Error {\n  return new A2Error(\n    'SUPERSEDED_ATTEMPT',\n    `attempt ${cause.attempt} no longer owns event ${cause.index} in session '${sessionId}'`,\n  )\n}\n\n/**\n * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the\n * original as `cause`. A2Errors pass through untouched — they already\n * carry their own meaning.\n */\nexport function asStoreUnavailable(err: unknown): A2Error {\n  if (err instanceof A2Error) return err\n  return new A2Error('STORE_UNAVAILABLE', 'the store backend failed', {\n    cause: err,\n  })\n}\n\n/**\n * Throw from a handler to reject retrying: the failure is adjudicated\n * terminal immediately (dead-lettered on the first throw) instead of\n * consuming the ten-failure retry budget. For deterministic failures —\n * a guard that will refuse identically on every attempt — retrying is\n * waste and dead-lettering is the honest outcome. Matched by\n * `instanceof`, so subclasses carry domain meaning.\n */\nexport class NonRetriableError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'NonRetriableError'\n  }\n}\n","import { A2Error } from './errors.ts'\nimport type { Event } from './store.ts'\n\n/** A2's own event types start with this; application contracts cannot. */\nexport const RESERVED_EVENT_PREFIX = 'a2.'\n\n/** Reserved type of the marker a clear appends. */\nexport const CLEAR_EVENT_TYPE = 'a2.cleared'\n\n/** The marker `session.stream()` yields where a clear ended a lifetime. */\nexport type SessionCleared = Event & {\n  type: typeof CLEAR_EVENT_TYPE\n  payload: null\n}\n\n/** Accepts any stream item, including presence patches and snapshots. */\nexport function isSessionCleared(item: object): item is SessionCleared {\n  return (item as { type?: unknown }).type === CLEAR_EVENT_TYPE\n}\n\nexport function sessionClearedError(message: string): A2Error {\n  return new A2Error('SESSION_CLEARED', message)\n}\n"],"mappings":";AAgBA,IAAa,UAAb,cAA6B,MAAM;CACjC;;CAEA;CAEA,YACE,MACA,SACA,SACA;EACA,MACE,SACA,WAAW,WAAW,UAAU,EAAE,OAAO,QAAQ,MAAM,IAAI,KAAA,CAC7D;EACA,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,UAAU,SAAS;CAC1B;AACF;;AAGA,SAAgB,uBACd,WACA,OACS;CACT,OAAO,IAAI,QACT,sBACA,WAAW,MAAM,QAAQ,wBAAwB,MAAM,MAAM,eAAe,UAAU,EACxF;AACF;;;;;;AAOA,SAAgB,mBAAmB,KAAuB;CACxD,IAAI,eAAe,SAAS,OAAO;CACnC,OAAO,IAAI,QAAQ,qBAAqB,4BAA4B,EAClE,OAAO,IACT,CAAC;AACH;;;;;;;;;AAUA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS,OAAO;EACtB,KAAK,OAAO;CACd;AACF;;;;ACjEA,MAAa,mBAAmB;;AAShC,SAAgB,iBAAiB,MAAsC;CACrE,OAAQ,KAA4B,SAAS;AAC/C;AAEA,SAAgB,oBAAoB,SAA0B;CAC5D,OAAO,IAAI,QAAQ,mBAAmB,OAAO;AAC/C"}

package/dist/store-postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-postgres.d.ts","names":[],"sources":["../src/store-postgres.ts"],"mappings":";;;KAuDY;EAAwB,MAAM;;;KAG9B;EACV,MAAM,cAAc,qBAAqB,QAAQ;EACjD;;;;;;;;KASU;EACV,MAAM,cAAc,qBAAqB,QAAQ;EACjD,YAAY,QAAQ;EACpB,QAAQ;;KAGE;;EAEV;;EAEA;;EAEA,SAAS;;EAET,QAAQ;;EAER,MAAM;;KAGI,gBAAgB;;;EAG1B,SAAS;;iBAiSK,SAAS,UAAS,uBAA4B"}
+{"version":3,"file":"store-postgres.d.ts","names":[],"sources":["../src/store-postgres.ts"],"mappings":";;;KAuDY;EAAwB,MAAM;;;KAG9B;EACV,MAAM,cAAc,qBAAqB,QAAQ;EACjD;;;;;;;;KASU;EACV,MAAM,cAAc,qBAAqB,QAAQ;EACjD,YAAY,QAAQ;EACpB,QAAQ;;KAGE;;EAEV;;EAEA;;EAEA,SAAS;;EAET,QAAQ;;EAER,MAAM;;KAGI,gBAAgB;;;EAG1B,SAAS;;iBA6KK,SAAS,UAAS,uBAA4B"}

package/dist/store-postgres.js

@@ -171,27 +171,36 @@ function postgresNotifications(createConnection) {
 		}
 	};
 }
-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 $$;
-`;
+const PACKAGE = "node_modules/experimental-a2";
+const apply = (file) => `apply ${PACKAGE}/sql/postgres/${file} to this database`;
+const SEE_DOCS = `See ${PACKAGE}/docs/stores/04-postgres.mdx.`;
+const VERSION = "select version from a2_schema";
+const VERSION_AND_TRIGGERS = `select version, (select count(*) from pg_trigger
+   where (tgname = 'a2_notify_events' and tgrelid = to_regclass('a2_events'))
+      or (tgname = 'a2_notify_presence' and tgrelid = to_regclass('a2_presence')))
+  as notify_triggers from a2_schema`;
+/** Explains a failed version read, or returns undefined when the schema is not the cause. */
+const diagnose = async (client) => {
+	const [found] = (await client.query(`select
+      to_regclass('a2_schema') is not null as marked,
+      to_regclass('a2_events') is not null as installed,
+      has_table_privilege(to_regclass('a2_schema'), 'select') as readable`)).rows;
+	if (!found) return void 0;
+	if (!found["marked"]) return new A2Error("STORE_NOT_CONFIGURED", found["installed"] ? `This Postgres database has A2's tables but no a2_schema version. That is expected once after upgrading from a release that created its tables at runtime, and your events are untouched. A2 doesn't create or change tables at runtime: ${apply("schema.sql")}. ${SEE_DOCS}` : `A2's tables aren't in this Postgres database, and A2 doesn't create tables at runtime: ${apply("schema.sql")}. ${SEE_DOCS}`);
+	if (found["readable"] === false) return new A2Error("STORE_NOT_CONFIGURED", `The role this store connects as can't read a2_schema. Apply schema.sql as that role, or grant it select on a2_schema and select, insert, update, and delete on A2's other tables. ${SEE_DOCS}`);
+};
+/** Reads the schema version (and, with a listener, the triggers) in one query that takes no lock a writer holds. */
+const checkPostgresSchema = async ({ client, listen }) => {
+	let row;
+	try {
+		row = (await client.query(listen ? VERSION_AND_TRIGGERS : VERSION)).rows[0];
+	} catch (err) {
+		throw await diagnose(client).catch(() => void 0) ?? err;
+	}
+	const version = Number(row?.["version"] ?? 0);
+	if (version < 1) throw new A2Error("STORE_NOT_CONFIGURED", `This Postgres database has A2 schema version ${version}, and this release of experimental-a2 needs version 1: ${apply("schema.sql")}. ${SEE_DOCS}`);
+	if (listen && Number(row?.["notify_triggers"]) < 2) throw new A2Error("STORE_NOT_CONFIGURED", `listenConnectionString needs A2's notification triggers, which aren't in this Postgres database. After schema.sql, ${apply("notifications.sql")}. ${SEE_DOCS}`);
+};
 //#endregion
 //#region src/postgres-notification-scope.ts
 const failure = (error) => error instanceof A2Error ? error : new A2Error("STORE_UNAVAILABLE", "Postgres subscription failed", { cause: error });
@@ -446,7 +455,7 @@ function postgresConnectionKey({ connectionString, defaults }) {
 }
 const queries = (raw) => {
 	let pending = Promise.resolve();
-	const schemas = /* @__PURE__ */ new Map();
+	const initialized = /* @__PURE__ */ new Map();
 	const exclusive = (fn) => {
 		const result = pending.then(fn);
 		pending = result.catch(() => {});
@@ -456,13 +465,13 @@ const queries = (raw) => {
 		raw,
 		client: raw.connect ? raw : { query: (text, values) => exclusive(() => raw.query(text, values)) },
 		exclusive,
-		initialize({ schema, run }) {
-			const existing = schemas.get(schema);
+		initialize({ key, run }) {
+			const existing = initialized.get(key);
 			if (existing) return existing;
 			const attempt = run();
-			schemas.set(schema, attempt);
+			initialized.set(key, attempt);
 			attempt.catch(() => {
-				if (schemas.get(schema) === attempt) schemas.delete(schema);
+				if (initialized.get(key) === attempt) initialized.delete(key);
 			});
 			return attempt;
 		},
@@ -506,90 +515,6 @@ const sharePostgresListener = ({ key, create }) => acquire({
 * `pg_advisory_xact_lock`, so concurrent writers can't race the index
 * assignment.
 */
-const SCHEMA = `
-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,
-  lane         text,
-  lane_ready   boolean not null default false,
-  processed_at bigint,
-  processed_by_attempt integer,
-  returned_event_ids jsonb,
-  first_claimed_at bigint,
-  last_claimed_at bigint,
-  attempt_count integer not null default 0,
-  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)
-);
-
-create unique index if not exists a2_events_event_id on a2_events (event_id);
-create index if not exists a2_events_unprocessed
-  on a2_events (session_id, idx) where processed_at is null;
-create index if not exists a2_events_lane_pending
-  on a2_events (session_id, lane, idx) where processed_at is null;
-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;
-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;
-
-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)
-);
-
-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)
-);
-
-create table if not exists a2_snapshot_pins (
-  session_id   text   not null,
-  event_index  bigint not null,
-  reducer_name text   not null,
-  up_to_index  bigint not null,
-  primary key (session_id, event_index, reducer_name, up_to_index)
-);
-
-create index if not exists a2_snapshot_pins_checkpoint
-  on a2_snapshot_pins (session_id, reducer_name, up_to_index);
-
-create table if not exists a2_clears (
-  session_id  text   primary key,
-  clear_index bigint not null
-);
-
-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)
-);
-`;
 const asNumber = (value) => Number(value);
 /**
 * The session's latest clear marker, or 0, as a primary-key subquery. Read
@@ -651,25 +576,6 @@ const wrap = async (fn) => {
 	}
 };
 const jsonb = (value) => JSON.stringify(value) ?? "null";
-const initializeSchema = async ({ client, listen }) => {
-	const schema = SCHEMA + (listen ? POSTGRES_NOTIFICATIONS_SQL : "");
-	if (!client.connect) {
-		await client.query(schema);
-		return;
-	}
-	const conn = await client.connect();
-	try {
-		await conn.query("begin");
-		await conn.query("select pg_advisory_xact_lock(hashtext('a2:postgres:schema'))");
-		await conn.query(schema);
-		await conn.query("commit");
-	} catch (err) {
-		await conn.query("rollback").catch(() => {});
-		throw err;
-	} finally {
-		conn.release();
-	}
-};
 const loadPg = async () => import("pg").catch(() => {
 	throw new A2Error("STORE_NOT_CONFIGURED", "Postgres connections created by A2 require the optional 'pg' package");
 });
@@ -736,13 +642,9 @@ function postgres(options = {}) {
 		try {
 			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({
+			await resource.initialize({
+				key: listen ? "schema+triggers" : "schema",
+				run: () => checkPostgresSchema({
 					client: resource.client,
 					listen
 				})