@steve31415/baselib 2.0.0 → 2.2.0

package/dist/sync/engine.js

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto';
+import { SyncError, } from './types.js';
+const DEFAULT_CATCHUP_LIMIT = 100;
+const DEFAULT_RETENTION_DAYS = 7;
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+const DEFAULT_SCHEMA = {
+    scopesTable: 'sync_scopes',
+    eventsTable: 'sync_events',
+    scopeColumn: 'scope_key',
+};
+function validatedSchema(schema) {
+    const scopesTable = schema.scopesTable;
+    const eventsTable = schema.eventsTable;
+    const scopeColumn = schema.scopeColumn;
+    const validate = (field, identifier) => {
+        if (typeof identifier !== 'string' || !IDENTIFIER.test(identifier)) {
+            throw new Error(`invalid SQL identifier for ${field}`);
+        }
+        return identifier;
+    };
+    return {
+        scopesTable: validate('scopesTable', scopesTable),
+        eventsTable: validate('eventsTable', eventsTable),
+        scopeColumn: validate('scopeColumn', scopeColumn),
+    };
+}
+function syncEventFromRow(row) {
+    return {
+        seq: Number(row.seq),
+        eventGuid: row.event_guid,
+        ts: row.ts.getTime(),
+        type: row.type,
+        payload: row.payload,
+    };
+}
+export class EventLogEngine {
+    pool;
+    logger;
+    prepareMutation;
+    schema;
+    catchupLimit;
+    retentionDays;
+    randomGuid;
+    now;
+    constructor(options) {
+        this.pool = options.pool;
+        this.logger = options.logger;
+        this.prepareMutation = options.prepareMutation;
+        this.schema = validatedSchema(options.schema ?? DEFAULT_SCHEMA);
+        this.catchupLimit = options.catchupLimit ?? DEFAULT_CATCHUP_LIMIT;
+        this.retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+        this.randomGuid = options.randomGuid ?? randomUUID;
+        this.now = options.now ?? Date.now;
+    }
+    /** Apply one event. Domain validation failures are stable rejections; an
+     * unexpected failure is retried once because event GUID dedupe makes an
+     * ambiguous commit safe to replay. */
+    async apply(scopeKey, clientGuid, event) {
+        try {
+            return await this.applyOnce(scopeKey, clientGuid, event);
+        }
+        catch (error) {
+            if (error instanceof SyncError)
+                return this.rejectedOutcome(scopeKey, event, error);
+            this.logger.warn('sync.apply_retry', {
+                scopeKey,
+                eventGuid: event.eventGuid,
+                eventType: event.type,
+                error,
+            });
+            try {
+                return await this.applyOnce(scopeKey, clientGuid, event);
+            }
+            catch (retryError) {
+                if (retryError instanceof SyncError) {
+                    return this.rejectedOutcome(scopeKey, event, retryError);
+                }
+                this.logger.error('sync.apply_failed', {
+                    scopeKey,
+                    eventGuid: event.eventGuid,
+                    eventType: event.type,
+                    error: retryError,
+                });
+                return {
+                    kind: 'rejected',
+                    error: { code: 'internal', message: 'internal error applying event' },
+                };
+            }
+        }
+    }
+    rejectedOutcome(scopeKey, event, error) {
+        this.logger.warn('sync.rejected', {
+            scopeKey,
+            eventGuid: event.eventGuid,
+            eventType: event.type,
+            error,
+        });
+        return { kind: 'rejected', error: { code: error.code, message: error.message } };
+    }
+    async applyOnce(scopeKey, clientGuid, event) {
+        const client = await this.pool.connect();
+        const { scopesTable, eventsTable, scopeColumn } = this.schema;
+        try {
+            await client.query('begin');
+            await client.query(`insert into ${scopesTable} (${scopeColumn}) values ($1) on conflict do nothing`, [scopeKey]);
+            await client.query(`select last_seq from ${scopesTable} where ${scopeColumn} = $1 for update`, [scopeKey]);
+            const duplicate = await client.query(`select ${scopeColumn} as scope_key, seq, event_guid, ts, type, payload
+         from ${eventsTable} where event_guid = $1`, [event.eventGuid]);
+            if (duplicate.rows.length > 0) {
+                await client.query('commit');
+                const row = duplicate.rows[0];
+                if (row.scope_key !== scopeKey) {
+                    return {
+                        kind: 'rejected',
+                        error: { code: 'guid_conflict', message: 'event guid already used' },
+                    };
+                }
+                return { kind: 'duplicate', event: syncEventFromRow(row) };
+            }
+            const prepared = await this.prepareMutation(client, scopeKey, event);
+            if (prepared.filter((candidate) => candidate.trigger === true).length !== 1) {
+                throw new Error('mutation preparer must return exactly one trigger event');
+            }
+            const eventCount = prepared.length;
+            const bump = await client.query(`update ${scopesTable} set last_seq = last_seq + $2
+         where ${scopeColumn} = $1 returning last_seq`, [scopeKey, eventCount]);
+            let seq = Number(bump.rows[0].last_seq) - eventCount;
+            const timestamp = this.now();
+            const events = prepared.map((candidate) => {
+                return {
+                    seq: ++seq,
+                    eventGuid: candidate.trigger ? event.eventGuid : this.randomGuid(),
+                    ts: timestamp,
+                    type: candidate.type,
+                    payload: candidate.payload,
+                };
+            });
+            for (let index = 0; index < events.length; index++) {
+                const appended = events[index];
+                await client.query(`insert into ${eventsTable}
+             (${scopeColumn}, seq, event_guid, client_guid, ts, type, payload)
+           values ($1, $2, $3, $4, $5, $6, $7)`, [
+                    scopeKey,
+                    appended.seq,
+                    appended.eventGuid,
+                    prepared[index].trigger ? clientGuid : null,
+                    new Date(appended.ts),
+                    appended.type,
+                    JSON.stringify(appended.payload),
+                ]);
+            }
+            await client.query('commit');
+            return { kind: 'applied', events };
+        }
+        catch (error) {
+            await client.query('rollback').catch(() => { });
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async currentSeq(scopeKey) {
+        const { scopesTable, scopeColumn } = this.schema;
+        const result = await this.pool.query(`select last_seq from ${scopesTable} where ${scopeColumn} = $1`, [scopeKey]);
+        return result.rows.length === 0 ? 0 : Number(result.rows[0].last_seq);
+    }
+    async catchup(scopeKey, afterSeq) {
+        const currentSeq = await this.currentSeq(scopeKey);
+        if (afterSeq > currentSeq)
+            return { kind: 'reload' };
+        if (afterSeq === currentSeq)
+            return { kind: 'events', events: [], currentSeq };
+        if (currentSeq - afterSeq > this.catchupLimit)
+            return { kind: 'reload' };
+        const { eventsTable, scopeColumn } = this.schema;
+        const result = await this.pool.query(`select seq, event_guid, ts, type, payload from ${eventsTable}
+       where ${scopeColumn} = $1 and seq > $2 and seq <= $3 order by seq`, [scopeKey, afterSeq, currentSeq]);
+        if (result.rows.length === 0 || Number(result.rows[0].seq) !== afterSeq + 1) {
+            return { kind: 'reload' };
+        }
+        if (result.rows.length !== currentSeq - afterSeq ||
+            result.rows.some((row, index) => Number(row.seq) !== afterSeq + index + 1)) {
+            return { kind: 'reload' };
+        }
+        return {
+            kind: 'events',
+            events: result.rows.map((row) => syncEventFromRow(row)),
+            currentSeq,
+        };
+    }
+    async pruneOldEvents() {
+        const result = await this.pool.query(`delete from ${this.schema.eventsTable}
+       where ts < now() - make_interval(days => $1)`, [this.retentionDays]);
+        return result.rowCount ?? 0;
+    }
+}

package/dist/sync/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './schema.js';
+export * from './engine.js';
+export * from './broadcaster.js';
+export * from './session.js';

package/dist/sync/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './schema.js';
+export * from './engine.js';
+export * from './broadcaster.js';
+export * from './session.js';

package/dist/sync/schema.d.ts

@@ -0,0 +1,13 @@
+/** Names of the protocol tables and scope column used by an event log. */
+export interface EventLogSchema {
+    scopesTable: string;
+    eventsTable: string;
+    scopeColumn: string;
+}
+/**
+ * Default PostgreSQL schema for the generic event log.
+ *
+ * Applications with an existing event-log schema can retain it by passing a
+ * validated EventLogSchema to the sync engine instead of applying this DDL.
+ */
+export declare const SYNC_SCHEMA_SQL = "\ncreate table if not exists sync_scopes (\n  scope_key text primary key,\n  last_seq bigint not null default 0\n);\n\ncreate table if not exists sync_events (\n  scope_key text not null,\n  seq bigint not null,\n  event_guid uuid not null unique,\n  client_guid text,\n  ts timestamptz not null default now(),\n  type text not null,\n  payload jsonb not null,\n  primary key (scope_key, seq),\n  foreign key (scope_key) references sync_scopes(scope_key)\n);\n";

package/dist/sync/schema.js

@@ -0,0 +1,24 @@
+/**
+ * Default PostgreSQL schema for the generic event log.
+ *
+ * Applications with an existing event-log schema can retain it by passing a
+ * validated EventLogSchema to the sync engine instead of applying this DDL.
+ */
+export const SYNC_SCHEMA_SQL = `
+create table if not exists sync_scopes (
+  scope_key text primary key,
+  last_seq bigint not null default 0
+);
+
+create table if not exists sync_events (
+  scope_key text not null,
+  seq bigint not null,
+  event_guid uuid not null unique,
+  client_guid text,
+  ts timestamptz not null default now(),
+  type text not null,
+  payload jsonb not null,
+  primary key (scope_key, seq),
+  foreign key (scope_key) references sync_scopes(scope_key)
+);
+`;

package/dist/sync/session.d.ts

@@ -0,0 +1,29 @@
+import { ScopeBroadcaster } from './broadcaster.js';
+import { EventLogEngine } from './engine.js';
+import { type ClientEvent, type EventBody, type HttpEventOutcome, type WsServerMessage } from './types.js';
+export interface SyncSocketSessionOptions<C extends EventBody, S extends EventBody> {
+    scopeKey: string;
+    engine: EventLogEngine<C, S>;
+    broadcaster: ScopeBroadcaster<WsServerMessage<S>>;
+    send(message: WsServerMessage<S>): void;
+    buildId: string;
+    parseClientEvent(value: unknown): ClientEvent<C>;
+}
+export declare class SyncSocketSession<C extends EventBody, S extends EventBody> {
+    private readonly scopeKey;
+    private readonly engine;
+    private readonly broadcaster;
+    private readonly send;
+    private readonly buildId;
+    private readonly parseClientEvent;
+    private readonly broadcastListener;
+    private readonly unsubscribe;
+    private clientGuid;
+    private closed;
+    constructor(options: SyncSocketSessionOptions<C, S>);
+    onMessage(message: unknown): Promise<void>;
+    close(): void;
+    private reject;
+    private sendToSocket;
+}
+export declare function applyHttpEventBatch<C extends EventBody, S extends EventBody>(engine: EventLogEngine<C, S>, scopeKey: string, request: unknown, parseClientEvent: (value: unknown) => ClientEvent<C>): Promise<HttpEventOutcome[]>;

package/dist/sync/session.js

@@ -0,0 +1,189 @@
+import { SyncError, } from './types.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function eventGuid(value) {
+    const candidate = record(value);
+    return typeof candidate?.eventGuid === 'string' ? candidate.eventGuid : '';
+}
+function parserError(error) {
+    return error instanceof SyncError
+        ? { code: error.code, message: error.message }
+        : { code: 'invalid_payload', message: 'invalid event' };
+}
+export class SyncSocketSession {
+    scopeKey;
+    engine;
+    broadcaster;
+    send;
+    buildId;
+    parseClientEvent;
+    broadcastListener;
+    unsubscribe;
+    clientGuid = null;
+    closed = false;
+    constructor(options) {
+        this.scopeKey = options.scopeKey;
+        this.engine = options.engine;
+        this.broadcaster = options.broadcaster;
+        this.send = options.send;
+        this.buildId = options.buildId;
+        this.parseClientEvent = options.parseClientEvent;
+        this.broadcastListener = (message) => this.sendToSocket(message);
+        this.unsubscribe = this.broadcaster.subscribe(this.scopeKey, this.broadcastListener);
+    }
+    async onMessage(message) {
+        if (this.closed)
+            return;
+        const envelope = record(message);
+        if (!envelope || typeof envelope.type !== 'string') {
+            this.reject('', 'bad_message', 'invalid client message');
+            return;
+        }
+        if (envelope.type === 'ping') {
+            this.sendToSocket({ type: 'pong', buildId: this.buildId });
+            return;
+        }
+        if (envelope.type === 'connect') {
+            if (typeof envelope.clientGuid !== 'string' ||
+                envelope.clientGuid.length === 0 ||
+                !Number.isSafeInteger(envelope.lastSeq) ||
+                envelope.lastSeq < 0 ||
+                (this.clientGuid !== null && this.clientGuid !== envelope.clientGuid)) {
+                this.reject('', 'bad_message', 'invalid connect message');
+                return;
+            }
+            this.clientGuid = envelope.clientGuid;
+            const outcome = await this.engine.catchup(this.scopeKey, envelope.lastSeq);
+            if (this.closed)
+                return;
+            if (outcome.kind === 'reload') {
+                this.sendToSocket({ type: 'reload' });
+            }
+            else {
+                this.sendToSocket({
+                    type: 'catchup',
+                    events: outcome.events,
+                    currentSeq: outcome.currentSeq,
+                    buildId: this.buildId,
+                });
+            }
+            return;
+        }
+        if (envelope.type !== 'event' ||
+            typeof envelope.clientGuid !== 'string' ||
+            envelope.clientGuid.length === 0 ||
+            !('event' in envelope)) {
+            this.reject('', 'bad_message', 'invalid client message');
+            return;
+        }
+        const guid = eventGuid(envelope.event);
+        let parsedEvent;
+        try {
+            parsedEvent = this.parseClientEvent(envelope.event);
+        }
+        catch (error) {
+            const parsedError = parserError(error);
+            this.reject(guid, parsedError.code, parsedError.message);
+            return;
+        }
+        if (this.clientGuid === null) {
+            this.reject(guid, 'not_connected', 'connect before sending events');
+            return;
+        }
+        if (envelope.clientGuid !== this.clientGuid) {
+            this.reject(guid, 'client_guid_mismatch', 'event client guid does not match socket');
+            return;
+        }
+        const outcome = await this.engine.apply(this.scopeKey, this.clientGuid, parsedEvent);
+        if (outcome.kind === 'applied') {
+            // A committed event must reach every healthy peer even when this socket
+            // or another peer is stale. Report delivery failures only after fan-out.
+            const deliveryErrors = [];
+            for (const appliedEvent of outcome.events) {
+                const outgoing = { type: 'event', event: appliedEvent };
+                if (!this.closed) {
+                    try {
+                        this.sendToSocket(outgoing);
+                    }
+                    catch (error) {
+                        deliveryErrors.push(error);
+                    }
+                }
+                try {
+                    this.broadcaster.publish(this.scopeKey, outgoing, this.broadcastListener);
+                }
+                catch (error) {
+                    deliveryErrors.push(error);
+                }
+            }
+            if (deliveryErrors.length === 1)
+                throw deliveryErrors[0];
+            if (deliveryErrors.length > 1) {
+                throw new AggregateError(deliveryErrors, 'sync event delivery failed');
+            }
+        }
+        else if (outcome.kind === 'duplicate') {
+            if (!this.closed)
+                this.sendToSocket({ type: 'event', event: outcome.event });
+        }
+        else if (!this.closed) {
+            this.sendToSocket({
+                type: 'rejection',
+                eventGuid: parsedEvent.eventGuid,
+                error: outcome.error,
+            });
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.unsubscribe();
+    }
+    reject(eventGuid, code, message) {
+        this.sendToSocket({ type: 'rejection', eventGuid, error: { code, message } });
+    }
+    sendToSocket(message) {
+        if (this.closed)
+            return;
+        try {
+            this.send(message);
+        }
+        catch (error) {
+            this.close();
+            throw error;
+        }
+    }
+}
+export async function applyHttpEventBatch(engine, scopeKey, request, parseClientEvent) {
+    const envelope = record(request);
+    if (!envelope ||
+        typeof envelope.clientGuid !== 'string' ||
+        envelope.clientGuid.length === 0 ||
+        !Array.isArray(envelope.events)) {
+        throw new SyncError('bad_request', 'invalid event batch');
+    }
+    const outcomes = [];
+    for (const value of envelope.events) {
+        const guid = eventGuid(value);
+        let event;
+        try {
+            event = parseClientEvent(value);
+        }
+        catch (error) {
+            outcomes.push({ eventGuid: guid, status: 'rejected', error: parserError(error) });
+            continue;
+        }
+        const outcome = await engine.apply(scopeKey, envelope.clientGuid, event);
+        if (outcome.kind === 'rejected') {
+            outcomes.push({ eventGuid: event.eventGuid, status: 'rejected', error: outcome.error });
+        }
+        else {
+            outcomes.push({ eventGuid: event.eventGuid, status: 'applied' });
+        }
+    }
+    return outcomes;
+}

package/dist/sync/types.d.ts

@@ -0,0 +1,79 @@
+export interface EventBody<TType extends string = string, TPayload = unknown> {
+    type: TType;
+    payload: TPayload;
+}
+export type ClientEvent<TBody extends EventBody> = {
+    eventGuid: string;
+} & TBody;
+export type PreparedEvent<TBody extends EventBody> = TBody & {
+    trigger: boolean;
+};
+export type SyncEvent<TBody extends EventBody> = {
+    seq: number;
+    eventGuid: string;
+    ts: number;
+} & TBody;
+export declare class SyncError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface WsConnect {
+    type: 'connect';
+    clientGuid: string;
+    lastSeq: number;
+}
+export interface WsClientEvent<T extends EventBody> {
+    type: 'event';
+    clientGuid: string;
+    event: ClientEvent<T>;
+}
+export interface WsPing {
+    type: 'ping';
+}
+export type WsClientMessage<T extends EventBody> = WsConnect | WsClientEvent<T> | WsPing;
+export interface WsEventBroadcast<T extends EventBody> {
+    type: 'event';
+    event: SyncEvent<T>;
+}
+export interface WsCatchup<T extends EventBody> {
+    type: 'catchup';
+    events: SyncEvent<T>[];
+    currentSeq: number;
+    buildId?: string;
+}
+export interface WsReload {
+    type: 'reload';
+}
+export interface WsRejection {
+    type: 'rejection';
+    eventGuid: string;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export interface WsPong {
+    type: 'pong';
+    buildId?: string;
+}
+/** Prompt to verify the canonical traffic build over authenticated HTTP. */
+export interface WsBuildChanged {
+    type: 'build_changed';
+}
+/** Durable events may have advanced; answer with connect(lastSeq). */
+export interface WsSyncAvailable {
+    type: 'sync_available';
+}
+export type WsServerMessage<T extends EventBody> = WsEventBroadcast<T> | WsCatchup<T> | WsReload | WsRejection | WsPong | WsBuildChanged | WsSyncAvailable;
+export interface HttpEventsRequest<T extends EventBody> {
+    clientGuid: string;
+    events: ClientEvent<T>[];
+}
+export interface HttpEventOutcome {
+    eventGuid: string;
+    status: 'applied' | 'rejected';
+    error?: {
+        code: string;
+        message: string;
+    };
+}

package/dist/sync/types.js

@@ -0,0 +1,8 @@
+export class SyncError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SyncError';
+    }
+}