experimental-a2 0.0.0

package/dist/log-postgres.js

@@ -0,0 +1,628 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
+import { t as pollingStream } from "./log-polling-RO7kclzR.js";
+//#region src/log-postgres.ts
+/**
+* a2/log-postgres — postgres log backend (the production path).
+*
+* Implements the A2Log interface over any client that speaks the tiny
+* `PostgresClient` shape below — a `pg` Pool matches it structurally
+* (and is what `connectionString` creates, lazily; `pg` is an optional
+* peer dependency). The conformance suite in test/conformance is the
+* executable contract, run against PGlite (real Postgres, in-process)
+* and against a real server when `TEST_DATABASE_URL` is set.
+*
+* 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
+* `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,
+  processed_at bigint,
+  processed_by_attempt integer,
+  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,
+  primary key (session_id, idx)
+);
+
+-- CREATE TABLE IF NOT EXISTS leaves an older A2 table untouched. Keep
+-- additive lifecycle changes self-healing: an old warm deployment can recreate
+-- its embedded schema after an operator drops the tables during a rollout.
+alter table a2_events add column if not exists cause jsonb;
+alter table a2_events add column if not exists processed_by_attempt integer;
+alter table a2_events add column if not exists first_claimed_at bigint;
+alter table a2_events add column if not exists last_claimed_at bigint;
+alter table a2_events
+  add column if not exists attempt_count integer not null default 0;
+alter table a2_events
+  add column if not exists failure_count integer not null default 0;
+alter table a2_events add column if not exists last_failed_at bigint;
+alter table a2_events add column if not exists last_failed_attempt integer;
+
+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 table if not exists a2_leases (
+  session_id text   primary key,
+  holder     text   not null,
+  expires_at bigint not 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)
+);
+`;
+const asNumber = (value) => Number(value);
+const toDate = (ms) => ms === null || ms === void 0 ? null : new Date(asNumber(ms));
+const toCause = (raw) => {
+	if (raw === null || raw === void 0) return null;
+	const value = typeof raw === "string" ? JSON.parse(raw) : raw;
+	if (!Number.isInteger(value.index) || Number(value.index) < 1 || !Number.isInteger(value.attempt) || Number(value.attempt) < 1) throw new TypeError("stored event has an invalid cause");
+	return {
+		index: Number(value.index),
+		attempt: Number(value.attempt)
+	};
+};
+const toStored = (row) => ({
+	id: row["event_id"],
+	type: row["event_type"],
+	payload: row["payload"],
+	index: asNumber(row["idx"]),
+	sessionId: row["session_id"],
+	createdAt: new Date(asNumber(row["created_at"])),
+	cause: toCause(row["cause"]),
+	processedAt: toDate(row["processed_at"]),
+	processedByAttempt: row["processed_by_attempt"] === null || row["processed_by_attempt"] === void 0 ? null : asNumber(row["processed_by_attempt"]),
+	firstClaimedAt: toDate(row["first_claimed_at"]),
+	lastClaimedAt: toDate(row["last_claimed_at"]),
+	attemptCount: asNumber(row["attempt_count"]),
+	failureCount: asNumber(row["failure_count"]),
+	lastFailedAt: toDate(row["last_failed_at"]),
+	lastFailedAttempt: row["last_failed_attempt"] === null || row["last_failed_attempt"] === void 0 ? null : asNumber(row["last_failed_attempt"]),
+	lastError: row["last_error"] ?? null,
+	failedAt: toDate(row["failed_at"])
+});
+const toEvent = (row) => ({
+	id: row["event_id"],
+	type: row["event_type"],
+	payload: row["payload"],
+	index: asNumber(row["idx"]),
+	sessionId: row["session_id"],
+	createdAt: new Date(asNumber(row["created_at"]))
+});
+const wrap = async (fn) => {
+	try {
+		return await fn();
+	} catch (err) {
+		if (err instanceof A2Error || err instanceof TypeError) throw err;
+		throw new A2Error("LOG_UNAVAILABLE", "postgres log operation failed", { cause: err });
+	}
+};
+const jsonb = (value) => JSON.stringify(value) ?? "null";
+const initializeSchema = async (client) => {
+	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();
+	}
+};
+function postgres(options = {}) {
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const generateId = options.ids ?? RANDOM_IDS;
+	if (!options.client && !options.connectionString) throw new TypeError("postgres() needs a connectionString or an injected client");
+	const connection = retryableLazy(async () => {
+		let owned = null;
+		try {
+			let c = options.client;
+			if (!c) {
+				c = new (await (import("pg").catch(() => {
+					throw new A2Error("LOG_NOT_CONFIGURED", "a2/log-postgres with a connectionString needs the 'pg' package (optional peer dependency) — install it, or inject a client");
+				}))).default.Pool({ connectionString: options.connectionString });
+				owned = c;
+			}
+			await initializeSchema(c);
+			return c;
+		} catch (err) {
+			if (owned?.end) await owned.end().catch(() => {});
+			throw err;
+		}
+	});
+	const client = connection.get;
+	let mutex = Promise.resolve();
+	const withTx = async (fn) => {
+		const c = await client();
+		if (c.connect) {
+			const conn = await c.connect();
+			try {
+				await conn.query("begin");
+				const result = await fn((text, values) => conn.query(text, values));
+				await conn.query("commit");
+				return result;
+			} catch (err) {
+				await conn.query("rollback").catch(() => {});
+				throw err;
+			} finally {
+				conn.release();
+			}
+		}
+		const run = mutex.then(async () => {
+			await c.query("begin");
+			try {
+				const result = await fn((text, values) => c.query(text, values));
+				await c.query("commit");
+				return result;
+			} catch (err) {
+				await c.query("rollback").catch(() => {});
+				throw err;
+			}
+		});
+		mutex = run.catch(() => {});
+		return run;
+	};
+	return {
+		async append(sessionId, events) {
+			if (events.length === 0) return [];
+			return wrap(() => withTx(async (query) => {
+				await query("select pg_advisory_xact_lock(hashtext($1))", [sessionId]);
+				const suppliedIds = events.filter((e) => e.id !== void 0).map((e) => e.id);
+				if (new Set(suppliedIds).size !== suppliedIds.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "batch contains the same event id more than once");
+				if (suppliedIds.length > 0) {
+					const { rows: existing } = await query("select * from a2_events where event_id = any($1) order by idx", [suppliedIds]);
+					if (existing.length > 0) {
+						const foreign = existing.find((row) => row["session_id"] !== sessionId);
+						if (foreign) throw new A2Error("PARTIAL_DUPLICATE_BATCH", `event id '${String(foreign["event_id"])}' already exists in another session`);
+						if (existing.length === events.length) return existing.map(toStored);
+						throw new A2Error("PARTIAL_DUPLICATE_BATCH", `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`);
+					}
+				}
+				const { rows: maxRows } = await query("select coalesce(max(idx), 0) as max from a2_events where session_id = $1", [sessionId]);
+				const base = asNumber(maxRows[0]?.["max"]);
+				const now = clock.now().getTime();
+				const inserted = [];
+				for (let i = 0; i < events.length; i += 1) {
+					const e = events[i];
+					const id = e.id ?? generateId();
+					const index = base + 1 + i;
+					await query(`insert into a2_events
+                 (session_id, idx, event_type, payload, event_id, created_at,
+                  cause)
+               values ($1, $2, $3, $4::jsonb, $5, $6, $7::jsonb)`, [
+						sessionId,
+						index,
+						e.type,
+						jsonb(e.payload),
+						id,
+						now,
+						e.cause ? jsonb(e.cause) : null
+					]);
+					inserted.push({
+						id,
+						type: e.type,
+						payload: structuredClone(e.payload),
+						index,
+						sessionId,
+						createdAt: new Date(now),
+						cause: e.cause ? { ...e.cause } : null,
+						processedAt: null,
+						processedByAttempt: null,
+						firstClaimedAt: null,
+						lastClaimedAt: null,
+						attemptCount: 0,
+						failureCount: 0,
+						lastFailedAt: null,
+						lastFailedAttempt: null,
+						lastError: null,
+						failedAt: null
+					});
+				}
+				return inserted;
+			}));
+		},
+		async read(sessionId, opts) {
+			return wrap(async () => {
+				const c = await client();
+				const conditions = ["session_id = $1"];
+				const params = [sessionId];
+				if (opts?.afterIndex !== void 0) {
+					params.push(opts.afterIndex);
+					conditions.push(`idx > $${params.length}`);
+				}
+				if (opts?.unprocessedOnly) conditions.push("processed_at is null");
+				const { rows } = await c.query(`select * from a2_events where ${conditions.join(" and ")} order by idx`, params);
+				return rows.map(toStored);
+			});
+		},
+		async claimNext({ sessionId, holder, ttlMs, expiresAtMs, maxIndex }) {
+			return wrap(async () => {
+				const c = await client();
+				const now = clock.now().getTime();
+				const expiresAt = expiresAtMs ?? now + ttlMs;
+				const { rows } = await c.query(`with head as materialized (
+             select e.* from a2_events e
+             where e.session_id = $1 and e.processed_at is null
+             order by e.idx limit 1 for update of e
+           ), eligible as materialized (
+             select * from head
+             where failed_at is null
+               and ($5::bigint is null or idx <= $5)
+           ), won as (
+             insert into a2_leases (session_id, holder, expires_at)
+             select $1, $2, $3 from eligible
+             on conflict (session_id) do update set
+               holder = excluded.holder,
+               expires_at = excluded.expires_at
+             where a2_leases.expires_at <= $4 or a2_leases.holder = $2
+             returning holder
+           ), claimed as (
+             update a2_events e set
+               attempt_count = e.attempt_count + 1,
+               first_claimed_at = coalesce(e.first_claimed_at, $4),
+               last_claimed_at = $4
+             from eligible, won
+             where e.session_id = $1
+               and e.idx = eligible.idx
+               and e.processed_at is null
+             returning e.*
+           )
+           select case
+             when exists (select 1 from claimed) then 'claimed'
+             when exists (select 1 from eligible) then 'busy'
+             else 'settled'
+           end as outcome, claimed.*
+           from (values (1)) as singleton(n)
+           left join claimed on true`, [
+					sessionId,
+					holder,
+					expiresAt,
+					now,
+					maxIndex ?? null
+				]);
+				const row = rows[0];
+				if (row["outcome"] === "claimed") return {
+					outcome: "claimed",
+					event: toStored(row)
+				};
+				return { outcome: row["outcome"] };
+			});
+		},
+		async completeAndClaimNext({ sessionId, holder, completedIndex, attempt, maxIndex }) {
+			return wrap(async () => {
+				const c = await client();
+				const now = clock.now().getTime();
+				const { rows } = await c.query(`with current as materialized (
+             select e.* from a2_events e
+             where e.session_id = $1 and e.idx = $3
+             for update of e
+           ), completed as (
+             update a2_events e set
+               processed_at = $5,
+               processed_by_attempt = $4
+             from current
+             where e.session_id = $1
+               and e.idx = $3
+               and current.processed_at is null
+               and current.attempt_count = $4
+             returning e.idx
+           ), head as materialized (
+             select e.* from a2_events e, completed
+             where e.session_id = $1
+               and e.idx > $3
+               and e.processed_at is null
+             order by e.idx limit 1 for update of e
+           ), eligible as materialized (
+             select * from head
+             where failed_at is null
+               and ($6::bigint is null or idx <= $6)
+           ), owned as materialized (
+             select l.session_id from a2_leases l, eligible
+             where l.session_id = $1
+               and l.holder = $2
+               and l.expires_at > $5
+             for update of l
+           ), claimed as (
+             update a2_events e set
+               attempt_count = e.attempt_count + 1,
+               first_claimed_at = coalesce(e.first_claimed_at, $5),
+               last_claimed_at = $5
+             from eligible, owned
+             where e.session_id = $1
+               and e.idx = eligible.idx
+               and e.processed_at is null
+             returning e.*
+           )
+           select case
+             when not exists (select 1 from current) then 'missing'
+             when not exists (select 1 from completed) then 'superseded'
+             when exists (select 1 from claimed) then 'claimed'
+             when not exists (select 1 from eligible) then 'settled'
+             else 'busy'
+           end as outcome, claimed.*
+           from (values (1)) as singleton(n)
+           left join claimed on true`, [
+					sessionId,
+					holder,
+					completedIndex,
+					attempt,
+					now,
+					maxIndex ?? null
+				]);
+				const row = rows[0];
+				if (row["outcome"] === "missing") throw new TypeError(`no event at index ${completedIndex} in session '${sessionId}'`);
+				if (row["outcome"] === "claimed") return {
+					outcome: "claimed",
+					event: toStored(row)
+				};
+				return { outcome: row["outcome"] };
+			});
+		},
+		async markProcessed(sessionId, index) {
+			await wrap(async () => {
+				const { rows } = await (await client()).query(`update a2_events
+           set processed_at = coalesce(processed_at, $1)
+           where session_id = $2 and idx = $3
+           returning idx`, [
+					clock.now().getTime(),
+					sessionId,
+					index
+				]);
+				if (rows.length === 0) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+			});
+		},
+		async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+			return wrap(async () => {
+				const { rows } = await (await client()).query(`with current as materialized (
+             select e.* from a2_events e
+             where e.session_id = $1 and e.idx = $2
+             for update of e
+           ), updated as (
+             update a2_events e set
+               failure_count = e.failure_count + 1,
+               last_error = $4,
+               last_failed_at = $6,
+               last_failed_attempt = $3,
+               failed_at = case
+                 when e.failure_count + 1 >= $5 then $6
+                 else e.failed_at
+               end
+             from current
+             where e.session_id = $1
+               and e.idx = $2
+               and current.processed_at is null
+               and current.failed_at is null
+               and current.attempt_count = $3
+             returning e.failure_count, e.failed_at
+           )
+           select case
+             when not exists (select 1 from current) then 'missing'
+             when exists (
+               select 1 from updated where failed_at is not null
+             ) then 'dead_lettered'
+             when exists (select 1 from updated) then 'failed'
+             when exists (
+               select 1 from current
+               where processed_at is not null or attempt_count <> $3
+             ) then 'superseded'
+             when exists (
+               select 1 from current where failed_at is not null
+             ) then 'dead_lettered'
+             else 'superseded'
+           end as outcome,
+           coalesce(
+             (select failure_count from updated),
+             (select failure_count from current)
+           ) as failure_count`, [
+					sessionId,
+					index,
+					attempt,
+					error,
+					maxFailures,
+					clock.now().getTime()
+				]);
+				const row = rows[0];
+				if (!row || row["outcome"] === "missing") throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				return {
+					outcome: row["outcome"],
+					failureCount: asNumber(row["failure_count"])
+				};
+			});
+		},
+		async markFailed(sessionId, index) {
+			await wrap(async () => {
+				const { rows } = await (await client()).query("update a2_events set failed_at = $1 where session_id = $2 and idx = $3 returning idx", [
+					clock.now().getTime(),
+					sessionId,
+					index
+				]);
+				if (rows.length === 0) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+			});
+		},
+		async readState(sessionId, reducerName) {
+			return wrap(async () => {
+				const { rows } = await (await client()).query(`with snapshot as materialized (
+             select up_to_index, state
+             from a2_snapshots
+             where session_id = $1 and reducer_name = $2
+           )
+           select 0 as row_order, 'snapshot' as row_kind,
+                  snapshot.up_to_index as snapshot_index,
+                  snapshot.state as snapshot_state,
+                  null::text as session_id, null::bigint as idx,
+                  null::text as event_type, null::jsonb as payload,
+                  null::text as event_id, null::bigint as created_at
+           from snapshot
+           union all
+           select 1 as row_order, 'event' as row_kind,
+                  null::bigint as snapshot_index,
+                  null::jsonb as snapshot_state,
+                  event.session_id, event.idx, event.event_type,
+                  event.payload, event.event_id, event.created_at
+           from a2_events event
+           where event.session_id = $1
+             and event.idx > coalesce((select up_to_index from snapshot), 0)
+           order by row_order, idx`, [sessionId, reducerName]);
+				const snapshot = rows.find((row) => row["row_kind"] === "snapshot");
+				return {
+					snapshot: snapshot ? {
+						index: asNumber(snapshot["snapshot_index"]),
+						state: snapshot["snapshot_state"]
+					} : null,
+					events: rows.filter((row) => row["row_kind"] === "event").map(toEvent)
+				};
+			});
+		},
+		async putSnapshot(sessionId, reducerName, index, state) {
+			await wrap(async () => {
+				await (await client()).query(`insert into a2_snapshots (session_id, reducer_name, up_to_index, state, updated_at)
+           values ($1, $2, $3, $4::jsonb, $5)
+           on conflict (session_id, reducer_name) do update set
+             up_to_index = excluded.up_to_index,
+             state = excluded.state,
+             updated_at = excluded.updated_at
+           where excluded.up_to_index > a2_snapshots.up_to_index`, [
+					sessionId,
+					reducerName,
+					index,
+					jsonb(state),
+					clock.now().getTime()
+				]);
+			});
+		},
+		inspect: {
+			async listSessions(inspectionOptions) {
+				return wrap(async () => {
+					const c = await client();
+					const conditions = ["left(session_id, length($1)) = $1"];
+					const params = [inspectionOptions.prefix];
+					if (inspectionOptions.cursor !== void 0) {
+						params.push(inspectionOptions.cursor);
+						conditions.push(`session_id > $${params.length}`);
+					}
+					params.push(inspectionOptions.limit + 1);
+					const { rows } = await c.query(`select
+               session_id,
+               count(*) as event_count,
+               count(*) filter (where processed_at is null and failed_at is null) as pending_count,
+               count(*) filter (where failed_at is not null) as failed_count,
+               sum(attempt_count) as attempt_count,
+               sum(failure_count) as failure_count,
+               min(created_at) as first_event_at,
+               max(greatest(
+                 created_at,
+                 coalesce(first_claimed_at, 0),
+                 coalesce(last_claimed_at, 0),
+                 coalesce(last_failed_at, 0),
+                 coalesce(processed_at, 0),
+                 coalesce(failed_at, 0)
+               )) as updated_at
+             from a2_events
+             where ${conditions.join(" and ")}
+             group by session_id
+             order by session_id
+             limit $${params.length}`, params);
+					const hasMore = rows.length > inspectionOptions.limit;
+					const visible = rows.slice(0, inspectionOptions.limit);
+					return {
+						sessions: visible.map((row) => ({
+							sessionId: row["session_id"],
+							eventCount: asNumber(row["event_count"]),
+							pendingCount: asNumber(row["pending_count"]),
+							failedCount: asNumber(row["failed_count"]),
+							attemptCount: asNumber(row["attempt_count"]),
+							failureCount: asNumber(row["failure_count"]),
+							firstEventAt: new Date(asNumber(row["first_event_at"])),
+							updatedAt: new Date(asNumber(row["updated_at"]))
+						})),
+						cursor: hasMore ? visible.at(-1)?.["session_id"] ?? null : null
+					};
+				});
+			},
+			async listSnapshots(sessionId) {
+				return wrap(async () => {
+					const { rows } = await (await client()).query(`select reducer_name, up_to_index, updated_at
+             from a2_snapshots where session_id = $1 order by reducer_name`, [sessionId]);
+					return rows.map((row) => ({
+						reducerName: row["reducer_name"],
+						index: asNumber(row["up_to_index"]),
+						updatedAt: new Date(asNumber(row["updated_at"]))
+					}));
+				});
+			}
+		},
+		stream(sessionId, opts) {
+			const readAfter = (afterIndex) => wrap(async () => {
+				const { rows } = await (await client()).query("select * from a2_events where session_id = $1 and idx > $2 order by idx", [sessionId, afterIndex]);
+				return rows.map(toStored);
+			});
+			return pollingStream(readAfter, opts?.startAt !== void 0 ? { startAt: opts.startAt } : {});
+		},
+		lease: {
+			async acquire({ sessionId, holder, ttlMs, expiresAtMs }) {
+				return wrap(async () => {
+					const c = await client();
+					const now = clock.now().getTime();
+					const expiresAt = expiresAtMs ?? now + ttlMs;
+					const { rows } = await c.query(`insert into a2_leases (session_id, holder, expires_at)
+             values ($1, $2, $3)
+             on conflict (session_id) do update set
+               holder = excluded.holder,
+               expires_at = excluded.expires_at
+             where a2_leases.expires_at <= $4 or a2_leases.holder = $2
+             returning holder`, [
+						sessionId,
+						holder,
+						expiresAt,
+						now
+					]);
+					return rows.length === 1;
+				});
+			},
+			async release({ sessionId, holder }) {
+				await wrap(async () => {
+					await (await client()).query("delete from a2_leases where session_id = $1 and holder = $2", [sessionId, holder]);
+				});
+			}
+		},
+		async close() {
+			const current = connection.peek();
+			if (!current) return;
+			await (await current).end?.();
+		}
+	};
+}
+//#endregion
+export { postgres };

package/dist/log-redis.d.ts

@@ -0,0 +1,31 @@
+import { c as IdSource, i as Clock, t as A2Log } from "./log-Dg1I8NRr.js";
+//#region src/log-redis.d.ts
+/**
+ * The minimal client this backend needs — `ioredis` matches it
+ * structurally. `call` issues any command; `duplicate` opens the
+ * dedicated connection each blocking live feed holds.
+ */
+type RedisConnection = {
+  call(command: string, ...args: Array<string | number>): Promise<unknown>;
+  duplicate(): RedisConnection;
+  disconnect(): void;
+};
+type RedisLogOptions = {
+  /** Creates an `ioredis` client lazily (optional peer dep `ioredis`). */
+  url?: string | undefined;
+  /** Bring your own client — anything `call`/`duplicate`/`disconnect`. */
+  client?: RedisConnection;
+  /** Key prefix — isolates multiple apps on one Redis. Default `'a2'`. */
+  keyPrefix?: string;
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+type RedisLog = A2Log & {
+  /** Disconnect the client and every live stream connection. */
+  close(): Promise<void>;
+};
+declare function redis(options?: RedisLogOptions): RedisLog;
+//#endregion
+export { RedisConnection, RedisLog, RedisLogOptions, redis };