@syncular/server 0.15.45 → 0.15.46

package/dist/postgres-storage.js

@@ -1,3 +1,4 @@
+import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
 import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
@@ -63,6 +64,26 @@ CREATE TABLE IF NOT EXISTS sync_push_results(
   client_commit_id TEXT NOT NULL, result JSONB NOT NULL,
   PRIMARY KEY(partition, client_id, client_commit_id)
 );
+CREATE TABLE IF NOT EXISTS sync_reactions(
+  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,
+  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,
+  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,
+  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,
+  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,
+  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,
+  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,
+  last_failure JSONB,
+  PRIMARY KEY(partition, idempotency_key),
+  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))
+);
+CREATE INDEX IF NOT EXISTS sync_reactions_due
+  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_lease
+  ON sync_reactions(partition, status, lease_expires_at_ms);
+CREATE INDEX IF NOT EXISTS sync_reactions_completed
+  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
+  ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
   cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,
@@ -83,6 +104,32 @@ function toBase64(bytes) {
 function fromBase64(text) {
     return new Uint8Array(Buffer.from(text, 'base64'));
 }
+function toStoredReaction(record) {
+    return {
+        idempotencyKey: record.idempotency_key,
+        type: record.type,
+        version: asNumber(record.version),
+        payload: asJson(record.payload),
+        sourceClientId: record.source_client_id,
+        sourceClientCommitId: record.source_client_commit_id,
+        sourceCommitSeq: asNumber(record.source_commit_seq),
+        createdAtMs: asNumber(record.created_at_ms),
+        maxAttempts: asNumber(record.max_attempts),
+        status: record.status,
+        attempts: asNumber(record.attempts),
+        availableAtMs: asNumber(record.available_at_ms),
+        ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
+        ...(record.lease_expires_at_ms !== null
+            ? { leaseExpiresAtMs: asNumber(record.lease_expires_at_ms) }
+            : {}),
+        ...(record.completed_at_ms !== null
+            ? { completedAtMs: asNumber(record.completed_at_ms) }
+            : {}),
+        ...(record.last_failure !== null
+            ? { lastFailure: asJson(record.last_failure) }
+            : {}),
+    };
+}
 /**
  * Serialize a push result to a JSON-able object (stored in a JSONB column).
  * `serverRow` bytes are base64-encoded — JSONB cannot hold raw bytes.
@@ -425,6 +472,27 @@ class PostgresTransaction {
             JSON.stringify(serializePushResult(result)),
         ]);
     }
+    async enqueueReactions(reactions) {
+        this.#assertOpen();
+        for (const reaction of reactions) {
+            await this.#client.query(`INSERT INTO sync_reactions(
+           partition, idempotency_key, type, version, payload,
+           source_client_id, source_client_commit_id, source_commit_seq,
+           created_at_ms, available_at_ms, status, attempts, max_attempts
+         ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$9,'pending',0,$10)`, [
+                this.#partition,
+                reaction.idempotencyKey,
+                reaction.type,
+                reaction.version,
+                JSON.stringify(reaction.payload),
+                reaction.sourceClientId,
+                reaction.sourceClientCommitId,
+                reaction.sourceCommitSeq,
+                reaction.createdAtMs,
+                reaction.maxAttempts,
+            ]);
+        }
+    }
     async commit() {
         this.#assertOpen();
         this.#open = false;
@@ -599,6 +667,23 @@ export class PostgresServerStorage {
         const { rows } = await this.#exec.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].max_commit_seq);
     }
+    async queryAuthoritative(partition, query) {
+        if (this.#tables === undefined) {
+            throw new Error('ensureSchema(schema) must run before registered queries');
+        }
+        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.sql, query.params, query.tables, this.#tables), partition);
+        return this.#exec.transaction(async (client) => {
+            await client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
+            const result = await client.query(postgresPlaceholders(prepared.sql), prepared.params);
+            const cursor = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
+            return {
+                rows: result.rows,
+                maxCommitSeq: cursor.rows[0] === undefined
+                    ? 0
+                    : asNumber(cursor.rows[0].max_commit_seq),
+            };
+        });
+    }
     async getHorizonSeq(partition) {
         const { rows } = await this.#exec.query('SELECT horizon_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].horizon_seq);
@@ -624,6 +709,141 @@ export class PostgresServerStorage {
     getPushResult(partition, clientId, clientCommitId) {
         return getPushResultOn(this.#exec, partition, clientId, clientCommitId);
     }
+    async claimReactions(partition, query) {
+        if (query.types.length === 0 || query.limit <= 0)
+            return [];
+        const typeParams = query.types.map((_, index) => `$${index + 2}`).join(',');
+        const nowParam = query.types.length + 2;
+        const limitParam = nowParam + 1;
+        const workerParam = limitParam + 1;
+        const expiresParam = workerParam + 1;
+        const { rows } = await this.#exec.query(`WITH due AS (
+         SELECT partition, idempotency_key
+           FROM sync_reactions
+          WHERE partition=$1 AND type IN (${typeParams})
+            AND ((status='pending' AND available_at_ms<=$${nowParam})
+              OR (status='leased' AND lease_expires_at_ms<=$${nowParam}))
+          ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
+                        ELSE available_at_ms END,
+                   created_at_ms, idempotency_key
+          FOR UPDATE SKIP LOCKED
+          LIMIT $${limitParam}
+       )
+       UPDATE sync_reactions AS reaction
+          SET status='leased', attempts=reaction.attempts+1,
+              lease_owner=$${workerParam}, lease_expires_at_ms=$${expiresParam},
+              completed_at_ms=NULL
+         FROM due
+        WHERE reaction.partition=due.partition
+          AND reaction.idempotency_key=due.idempotency_key
+      RETURNING reaction.*`, [
+            partition,
+            ...query.types,
+            query.nowMs,
+            query.limit,
+            query.leaseOwner,
+            Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs),
+        ]);
+        return rows
+            .map(toStoredReaction)
+            .sort((a, b) => a.createdAtMs - b.createdAtMs ||
+            a.idempotencyKey.localeCompare(b.idempotencyKey));
+    }
+    async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
+        const result = await this.#exec.query(`UPDATE sync_reactions
+          SET status='completed', completed_at_ms=$4,
+              lease_owner=NULL, lease_expires_at_ms=NULL
+        WHERE partition=$1 AND idempotency_key=$2
+          AND status='leased' AND lease_owner=$3`, [partition, idempotencyKey, leaseOwner, completedAtMs]);
+        return result.rowCount === 1;
+    }
+    async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
+        const result = await this.#exec.query(`UPDATE sync_reactions SET lease_expires_at_ms=$4
+        WHERE partition=$1 AND idempotency_key=$2
+          AND status='leased' AND lease_owner=$3`, [partition, idempotencyKey, leaseOwner, leaseExpiresAtMs]);
+        return result.rowCount === 1;
+    }
+    async failReaction(partition, idempotencyKey, update) {
+        const result = await this.#exec.query(`UPDATE sync_reactions
+          SET status=$4, available_at_ms=$5, last_failure=$6,
+              lease_owner=NULL, lease_expires_at_ms=NULL
+        WHERE partition=$1 AND idempotency_key=$2
+          AND status='leased' AND lease_owner=$3`, [
+            partition,
+            idempotencyKey,
+            update.leaseOwner,
+            update.retryAtMs === undefined ? 'dead-letter' : 'pending',
+            update.retryAtMs ?? update.failure.atMs,
+            JSON.stringify(update.failure),
+        ]);
+        return result.rowCount === 1;
+    }
+    async retryReaction(partition, idempotencyKey, nowMs) {
+        const result = await this.#exec.query(`UPDATE sync_reactions
+          SET status='pending', attempts=0, available_at_ms=$3,
+              last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
+              completed_at_ms=NULL
+        WHERE partition=$1 AND idempotency_key=$2 AND status='dead-letter'`, [partition, idempotencyKey, nowMs]);
+        return result.rowCount === 1;
+    }
+    async getReaction(partition, idempotencyKey) {
+        const { rows } = await this.#exec.query('SELECT * FROM sync_reactions WHERE partition=$1 AND idempotency_key=$2', [partition, idempotencyKey]);
+        return rows[0] === undefined ? undefined : toStoredReaction(rows[0]);
+    }
+    async listReactions(partition, query) {
+        const where = ['partition=$1'];
+        const params = [partition];
+        if (query.statuses !== undefined && query.statuses.length > 0) {
+            const placeholders = query.statuses.map((_, index) => `$${params.length + index + 1}`);
+            where.push(`status IN (${placeholders.join(',')})`);
+            params.push(...query.statuses);
+        }
+        if (query.types !== undefined && query.types.length > 0) {
+            const placeholders = query.types.map((_, index) => `$${params.length + index + 1}`);
+            where.push(`type IN (${placeholders.join(',')})`);
+            params.push(...query.types);
+        }
+        params.push(query.limit);
+        const { rows } = await this.#exec.query(`SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
+        ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT $${params.length}`, params);
+        return rows.map(toStoredReaction);
+    }
+    async pruneReactions(partition, query) {
+        if (query.limit <= 0)
+            return { completed: 0, deadLetter: 0 };
+        const { rows } = await this.#exec.query(`WITH targets AS (
+         SELECT partition, idempotency_key
+           FROM sync_reactions
+          WHERE partition=$1
+            AND ((status='completed' AND completed_at_ms IS NOT NULL
+                  AND completed_at_ms<$2)
+              OR (status='dead-letter' AND available_at_ms<$3))
+          ORDER BY CASE WHEN status='completed' THEN completed_at_ms
+                        ELSE available_at_ms END,
+                   idempotency_key
+          FOR UPDATE SKIP LOCKED
+          LIMIT $4
+       )
+       DELETE FROM sync_reactions AS reaction
+        USING targets
+        WHERE reaction.partition=targets.partition
+          AND reaction.idempotency_key=targets.idempotency_key
+          AND ((reaction.status='completed'
+                AND reaction.completed_at_ms IS NOT NULL
+                AND reaction.completed_at_ms<$2)
+            OR (reaction.status='dead-letter'
+                AND reaction.available_at_ms<$3))
+      RETURNING reaction.status`, [
+            partition,
+            query.completedBeforeMs,
+            query.deadLetterBeforeMs,
+            query.limit,
+        ]);
+        return {
+            completed: rows.filter((row) => row.status === 'completed').length,
+            deadLetter: rows.filter((row) => row.status === 'dead-letter').length,
+        };
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];

package/dist/push.d.ts

@@ -17,11 +17,11 @@
  * merge); a validator throw rejects the whole commit atomically with a
  * host code.
  */
-import { type PushCommitFrame, type PushResultFrame } from '@syncular/core';
+import { type PushCommitFrame, type PushOperation, type PushResultFrame } from '@syncular/core';
 import type { SyncRequestContext } from './context.js';
 import type { CompiledSchema } from './schema.js';
 import type { ResolvedScopes } from './scopes.js';
-import type { StoredCommit } from './storage.js';
+import type { StorageTransaction, StoredCommit } from './storage.js';
 export interface ProcessedPushCommit {
     readonly frame: PushResultFrame;
     /** True when this request observed an already-recorded idempotency outcome. */
@@ -43,3 +43,9 @@ export declare function processPushCommit(ctx: SyncRequestContext, schema: Compi
  * cache provenance needed by structured events and server helpers.
  */
 export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<ProcessedPushCommit>;
+/**
+ * Shared serialized apply path for SSP2 commits and authoritative commands.
+ * The builder runs after the partition lock and idempotency re-check, so its
+ * reads and the returned operations share the transaction that is committed.
+ */
+export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly PushOperation[]>): Promise<ProcessedPushCommit>;

package/dist/push.js

@@ -20,6 +20,8 @@
 import { decodeRow, encodeRow, parseBlobRef, } from '@syncular/core';
 import { clockOf } from './context.js';
 import { SyncError } from './errors.js';
+import { emitEvent } from './events.js';
+import { prepareReactions, toNewReactions, } from './reactions.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
 import { StorageConstraintError } from './storage-errors.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
@@ -514,10 +516,18 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
  * cache provenance needed by structured events and server helpers.
  */
 export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame) {
+    return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations);
+}
+/**
+ * Shared serialized apply path for SSP2 commits and authoritative commands.
+ * The builder runs after the partition lock and idempotency re-check, so its
+ * reads and the returned operations share the transaction that is committed.
+ */
+export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations) {
     const { storage, partition } = ctx;
     let persisted;
     try {
-        persisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+        persisted = await storage.getPushResult(partition, clientId, clientCommitId);
     }
     catch (error) {
         if (error instanceof SyncError &&
@@ -525,28 +535,30 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
             // §6.3: answer the retryable cache-miss for this commit rather than
             // re-applying. Not persisted — a retry may find a readable record.
             return {
-                frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                frame: idempotencyCacheMissFrame(clientCommitId, error),
                 replayed: false,
             };
         }
         throw error;
     }
     if (persisted !== undefined) {
-        return processedPushCommit(frame.clientCommitId, persisted, true);
+        return processedPushCommit(clientCommitId, persisted, true);
     }
     const createdAtMs = clockOf(ctx)();
     const blobCtx = { store: ctx.blobs, partition };
     const crdtMergers = ctx.crdtMergers;
     const validators = ctx.validators;
     const commitValidator = ctx.commitValidator;
+    const reactionPlanner = ctx.reactionPlanner;
     const tx = await storage.begin(partition);
     const lockPartitionForPush = tx.lockPartitionForPush?.bind(tx) ??
         tx.lockPartitionForCommitValidation?.bind(tx);
     const commitRejectedPushResult = tx.commitRejectedPushResult?.bind(tx);
     try {
         if (lockPartitionForPush === undefined ||
-            commitRejectedPushResult === undefined) {
-            throw new Error('storage transaction does not support serialized push apply and atomic rejection finalization');
+            commitRejectedPushResult === undefined ||
+            (reactionPlanner !== undefined && tx.enqueueReactions === undefined)) {
+            throw new Error('storage transaction does not support serialized push apply, atomic rejection finalization, and configured durable reactions');
         }
         await lockPartitionForPush();
         // The optimistic lookup above may have raced another delivery. Re-check
@@ -559,11 +571,11 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
         // transaction-scoped read observes it.
         try {
             const serializedPersisted = tx.getPushResult !== undefined
-                ? await tx.getPushResult(clientId, frame.clientCommitId)
-                : await storage.getPushResult(partition, clientId, frame.clientCommitId);
+                ? await tx.getPushResult(clientId, clientCommitId)
+                : await storage.getPushResult(partition, clientId, clientCommitId);
             if (serializedPersisted !== undefined) {
                 await tx.rollback();
-                return processedPushCommit(frame.clientCommitId, serializedPersisted, true);
+                return processedPushCommit(clientCommitId, serializedPersisted, true);
             }
         }
         catch (error) {
@@ -571,7 +583,7 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 error.code === 'sync.idempotency_cache_miss') {
                 await tx.rollback();
                 return {
-                    frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                    frame: idempotencyCacheMissFrame(clientCommitId, error),
                     replayed: false,
                 };
             }
@@ -581,8 +593,9 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
         const changes = [];
         const validatedOperations = [];
         let terminated;
-        for (let opIndex = 0; opIndex < frame.operations.length; opIndex++) {
-            const op = frame.operations[opIndex];
+        const operations = await buildOperations(tx);
+        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+            const op = operations[opIndex];
             if (op === undefined)
                 continue;
             const outcome = await applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId);
@@ -596,11 +609,22 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 changes.push(outcome.change);
         }
         if (terminated === undefined) {
-            const commitReject = await runCommitValidator(commitValidator, tx, schema, clientId, frame.clientCommitId, ctx.actorId, partition, validatedOperations);
+            const commitReject = await runCommitValidator(commitValidator, tx, schema, clientId, clientCommitId, ctx.actorId, partition, validatedOperations);
             if (commitReject?.kind === 'terminate') {
                 terminated = commitReject.record;
             }
         }
+        let preparedReactions = [];
+        if (terminated === undefined && reactionPlanner !== undefined) {
+            preparedReactions = await prepareReactions(reactionPlanner, {
+                clientId,
+                clientCommitId,
+                actorId: ctx.actorId,
+                partition,
+                operations: validatedOperations,
+                read: commitValidationReader(tx, schema),
+            });
+        }
         if (terminated !== undefined) {
             // §6.3 rejected: only the terminating operation's record; §6.4:
             // every write of the commit rolls back.
@@ -610,27 +634,57 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
             });
             // Discard candidates and persist the rejection while retaining the same
             // partition lock. There is no unlock gap in which a duplicate can rerun.
-            await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-            const canonical = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+            await commitRejectedPushResult(clientId, clientCommitId, stored);
+            const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
             if (canonical === undefined) {
                 throw new Error('push rejection finalization did not persist an outcome');
             }
-            return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
+            return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
         }
         const commitSeq = await tx.appendCommit({
             clientId,
-            clientCommitId: frame.clientCommitId,
+            clientCommitId,
             actorId: ctx.actorId,
             createdAtMs,
             changes,
         });
+        const newReactions = toNewReactions(preparedReactions, {
+            clientId,
+            clientCommitId,
+            commitSeq,
+            createdAtMs,
+        });
+        if (newReactions.length > 0) {
+            const enqueueReactions = tx.enqueueReactions;
+            if (enqueueReactions === undefined) {
+                throw new Error('storage lost durable reaction enqueue support');
+            }
+            await enqueueReactions.call(tx, newReactions);
+        }
         const stored = newStoredPushResult(createdAtMs, {
             status: 'applied',
             commitSeq,
             results,
         });
-        await tx.putPushResult(clientId, frame.clientCommitId, stored);
+        await tx.putPushResult(clientId, clientCommitId, stored);
         await tx.commit();
+        if (ctx.events !== undefined) {
+            const atMs = clockOf(ctx)();
+            for (const reaction of newReactions) {
+                emitEvent(ctx.events, {
+                    type: 'reaction.queued',
+                    atMs,
+                    partition,
+                    actorId: ctx.actorId,
+                    clientId,
+                    clientCommitId,
+                    commitSeq,
+                    idempotencyKey: reaction.idempotencyKey,
+                    reactionType: reaction.type,
+                    version: reaction.version,
+                });
+            }
+        }
         if (ctx.realtime !== undefined && changes.length > 0) {
             await ctx.realtime.notifyCommit(partition, {
                 commitSeq,
@@ -639,7 +693,7 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 changes,
             });
         }
-        return processedPushCommit(frame.clientCommitId, stored, false);
+        return processedPushCommit(clientCommitId, stored, false);
     }
     catch (error) {
         if (error instanceof StorageConstraintError) {
@@ -660,12 +714,12 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 throw new Error('storage transaction lost atomic push rejection finalization support');
             }
             try {
-                await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-                const canonical = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+                await commitRejectedPushResult(clientId, clientCommitId, stored);
+                const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
                 if (canonical === undefined) {
                     throw new Error('push rejection finalization did not persist an outcome');
                 }
-                return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
+                return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
             }
             catch (finalizationError) {
                 // A failed finalization must still release the transaction: on

package/dist/reactions.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Durable post-commit reactions. Planning runs inside the authoritative push
+ * transaction and may only produce bounded data. Delivery runs later under a
+ * lease and is at-least-once, so handlers receive the stable idempotency key.
+ */
+import type { SyncularServerEvents } from './events.js';
+import type { DurableJsonValue, NewReaction, ServerStorage } from './storage.js';
+import type { CommitValidationReader, ValidateCommitOperation } from './validate.js';
+export declare const MAX_REACTIONS_PER_COMMIT = 100;
+export declare const MAX_REACTION_PAYLOAD_BYTES: number;
+export declare const MAX_REACTION_FAILURE_DETAILS_BYTES: number;
+export declare const DEFAULT_REACTION_MAX_ATTEMPTS = 10;
+export declare const DEFAULT_REACTION_LEASE_MS = 30000;
+export declare const DEFAULT_REACTION_INITIAL_BACKOFF_MS = 1000;
+export declare const DEFAULT_REACTION_MAX_BACKOFF_MS: number;
+export interface ReactionRetentionPolicy {
+    /** Keep completed rows for at least this duration (default 30 days). */
+    readonly completedRetentionMs: number;
+    /** Keep dead letters for at least this duration (default 90 days). */
+    readonly deadLetterRetentionMs: number;
+    /** Maximum terminal rows removed by one pass (default 1000). */
+    readonly batchSize: number;
+}
+export declare const DEFAULT_REACTION_RETENTION: ReactionRetentionPolicy;
+export type ReactionTypeMap = Readonly<Record<string, DurableJsonValue>>;
+export interface ReactionPlan {
+    /** Unique within the source client commit. */
+    readonly key: string;
+    readonly type: string;
+    readonly version: number;
+    readonly payload: DurableJsonValue;
+    readonly maxAttempts?: number;
+}
+export type PlannedReaction<Reactions extends ReactionTypeMap = ReactionTypeMap> = {
+    [Type in keyof Reactions & string]: {
+        /** Unique within the source client commit. */
+        readonly key: string;
+        readonly type: Type;
+        readonly version: number;
+        readonly payload: Reactions[Type];
+        readonly maxAttempts?: number;
+    };
+}[keyof Reactions & string];
+export interface ReactionPlannerInput {
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly actorId: string;
+    readonly partition: string;
+    readonly operations: readonly ValidateCommitOperation[];
+    /** Candidate-state reads from the still-open authoritative transaction. */
+    readonly read: CommitValidationReader;
+}
+/**
+ * A pure planner over an accepted candidate commit. It may read candidate
+ * state and return durable data. It must not execute user-visible side effects.
+ */
+export type ReactionPlanner<Reactions extends ReactionTypeMap = ReactionTypeMap> = (input: ReactionPlannerInput) => readonly PlannedReaction<Reactions>[] | Promise<readonly PlannedReaction<Reactions>[]>;
+/** Erased planner shape stored on non-generic server configuration. */
+export type AnyReactionPlanner = (input: ReactionPlannerInput) => readonly ReactionPlan[] | Promise<readonly ReactionPlan[]>;
+export interface ReactionHandlerInput<Payload extends DurableJsonValue> {
+    readonly partition: string;
+    readonly idempotencyKey: string;
+    readonly type: string;
+    readonly version: number;
+    readonly payload: Payload;
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly sourceClientId: string;
+    readonly sourceClientCommitId: string;
+    readonly sourceCommitSeq: number;
+    /** Extend a long-running handler's lease; throws after ownership is lost. */
+    readonly extendLease: () => Promise<void>;
+}
+export type ReactionHandler<Payload extends DurableJsonValue> = (input: ReactionHandlerInput<Payload>) => void | Promise<void>;
+export type ReactionHandlers<Reactions extends ReactionTypeMap = ReactionTypeMap> = {
+    readonly [Type in keyof Reactions & string]: ReactionHandler<Reactions[Type]>;
+};
+/** Stable handler idempotency key for one planned item in a client commit. */
+export declare function reactionIdempotencyKey(partition: string, clientId: string, clientCommitId: string, plannerKey: string): string;
+export interface PreparedReaction {
+    readonly idempotencyKey: string;
+    readonly type: string;
+    readonly version: number;
+    readonly payload: DurableJsonValue;
+    readonly maxAttempts: number;
+}
+/** Internal push seam, exported for focused planner tests and custom hosts. */
+export declare function prepareReactions(planner: AnyReactionPlanner, input: ReactionPlannerInput): Promise<PreparedReaction[]>;
+declare class ReactionDeliveryError extends Error {
+    readonly code: string;
+    readonly details?: {
+        readonly [key: string]: DurableJsonValue;
+    };
+    constructor(name: string, code: string, details?: {
+        readonly [key: string]: DurableJsonValue;
+    });
+}
+/** A handler failure that should be retried until its attempt limit. */
+export declare class RetryableReactionError extends ReactionDeliveryError {
+    constructor(code: string, details?: {
+        readonly [key: string]: DurableJsonValue;
+    });
+}
+/** A handler failure that should be dead-lettered immediately. */
+export declare class PermanentReactionError extends ReactionDeliveryError {
+    constructor(code: string, details?: {
+        readonly [key: string]: DurableJsonValue;
+    });
+}
+export interface ReactionRunnerOptions<Reactions extends ReactionTypeMap = ReactionTypeMap> {
+    readonly storage: ServerStorage;
+    readonly partition: string;
+    readonly workerId: string;
+    readonly handlers: ReactionHandlers<Reactions>;
+    readonly events?: SyncularServerEvents;
+    readonly clock?: () => number;
+    readonly leaseDurationMs?: number;
+    readonly batchSize?: number;
+    readonly initialBackoffMs?: number;
+    readonly maxBackoffMs?: number;
+}
+export interface ReactionRunResult {
+    readonly claimed: number;
+    readonly completed: number;
+    readonly retried: number;
+    readonly deadLettered: number;
+    /** Lease ownership changed before this worker could persist its outcome. */
+    readonly lostLeases: number;
+}
+export interface PruneReactionsOptions {
+    readonly storage: ServerStorage;
+    readonly partition: string;
+    readonly nowMs: number;
+    readonly retention?: Partial<ReactionRetentionPolicy>;
+    readonly events?: SyncularServerEvents;
+}
+export interface ReactionPruneResult {
+    readonly completedBeforeMs: number;
+    readonly deadLetterBeforeMs: number;
+    readonly removedCompleted: number;
+    readonly removedDeadLetter: number;
+    /** True when the bounded pass filled its batch and another pass may help. */
+    readonly mayHaveMore: boolean;
+}
+/** Host-driven worker. Call `runOnce` from the host scheduler or queue wake. */
+export declare class ReactionRunner<Reactions extends ReactionTypeMap = ReactionTypeMap> {
+    #private;
+    constructor(options: ReactionRunnerOptions<Reactions>);
+    runOnce(): Promise<ReactionRunResult>;
+}
+/** Explicit operator action for a dead-lettered reaction. */
+export declare function retryDeadLetterReaction(options: {
+    readonly storage: ServerStorage;
+    readonly partition: string;
+    readonly idempotencyKey: string;
+    readonly nowMs?: number;
+}): Promise<boolean>;
+/** Delete one bounded batch of aged completed and dead-lettered rows. */
+export declare function pruneReactions(options: PruneReactionsOptions): Promise<ReactionPruneResult>;
+/** Helper used by the push path after commit sequence allocation. */
+export declare function toNewReactions(prepared: readonly PreparedReaction[], source: {
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly commitSeq: number;
+    readonly createdAtMs: number;
+}): NewReaction[];
+export {};