@end-close/relay 0.12.0

package/dist/engine/settings.js

@@ -0,0 +1,13 @@
+// Tuning knobs shared by createRelay() and the Dispatcher. One shape, camelCase.
+export const DEFAULT_DISPATCH = {
+    batchMax: 100,
+    pollIntervalMs: 250,
+    backoffBaseMs: 1000,
+    backoffCapMs: 600_000,
+    parkAfterMs: 7 * 24 * 3600 * 1000,
+    leaseMs: 600_000,
+    recoverIntervalMs: 60_000,
+    enrichTimeoutMs: 5_000,
+};
+export const DEFAULT_RETENTION = { deliveredDays: 7, ledgerDays: 30 };
+//# sourceMappingURL=settings.js.map

package/dist/engine/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/engine/settings.ts"],"names":[],"mappings":"AAAA,iFAAiF;AA8BjF,MAAM,CAAC,MAAM,gBAAgB,GAAqB;IAChD,QAAQ,EAAE,GAAG;IACb,cAAc,EAAE,GAAG;IACnB,aAAa,EAAE,IAAI;IACnB,YAAY,EAAE,OAAO;IACrB,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI;IACjC,OAAO,EAAE,OAAO;IAChB,iBAAiB,EAAE,MAAM;IACzB,eAAe,EAAE,KAAK;CACvB,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAsB,EAAE,aAAa,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAA"}

package/dist/engine/store.d.ts

@@ -0,0 +1,141 @@
+import type { RouteConfig } from '../config/schema.js';
+export type EventStatus = 'pending' | 'retry' | 'delivering' | 'delivered' | 'parked' | 'dropped_by_filter';
+export interface EventRecord {
+    /** Opaque store-assigned id. */
+    id: string;
+    route_id: string;
+    source: string;
+    event_id: string;
+    event_type: string | null;
+    /** Whatever the PayloadCodec produced; opaque to the store. */
+    payload: Buffer;
+    payload_iv: Buffer | null;
+    headers_json: string;
+    received_at: string;
+    status: EventStatus;
+    attempts: number;
+    next_attempt_at: string | null;
+    delivered_at: string | null;
+    bulk_request_id: string | null;
+    last_error: string | null;
+    idempotency_key: string;
+    claimed_by: string | null;
+    lease_until: string | null;
+}
+export interface NewEvent {
+    route_id: string;
+    source: string;
+    event_id: string;
+    event_type: string | null;
+    payload: Buffer;
+    payload_iv: Buffer | null;
+    headers_json: string;
+    received_at: string;
+    status: EventStatus;
+    idempotency_key: string;
+}
+export interface RouteStats {
+    route_id: string;
+    counts: Partial<Record<EventStatus, number>>;
+    last_delivered_at: string | null;
+    oldest_pending_at: string | null;
+}
+export type EventSummary = Omit<EventRecord, 'payload' | 'payload_iv' | 'headers_json' | 'idempotency_key' | 'claimed_by' | 'lease_until'>;
+export type InsertResult = {
+    duplicate: false;
+    id: string;
+} | {
+    duplicate: true;
+};
+/** A store operation failed. `op` names the operation for logs and hooks. */
+export declare class StoreError extends Error {
+    readonly op: string;
+    constructor(message: string, op: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The store is temporarily unable to serve a request (lock contention, connection
+ * loss). Ingest answers 503 so the processor retries; any other StoreError is 500.
+ */
+export declare class StoreUnavailableError extends StoreError {
+    constructor(message: string, op: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function storeOp(err: unknown): string | undefined;
+/** What the engine needs from event storage. */
+export interface EventStore {
+    /** Persist a new event; `duplicate: true` when the idempotency key already exists. */
+    insert(e: NewEvent): Promise<InsertResult>;
+    /**
+     * Routes with `pending`/`retry` events whose next attempt is at or before `now`.
+     * Called with a far-future `now` it answers "which routes hold any backlog at all".
+     */
+    routesWithDueEvents(now: string): Promise<string[]>;
+    /**
+     * Atomically select up to `limit` due events for a route (oldest first), mark them
+     * `delivering` and record the lease. Concurrent callers must never receive overlapping
+     * rows (a SQL store would use SELECT ... FOR UPDATE SKIP LOCKED).
+     */
+    claimDue(routeId: string, now: string, limit: number, lease: Lease): Promise<EventRecord[]>;
+    markDelivered(ids: string[], deliveredAt: string, bulkRequestId: string | null): Promise<void>;
+    markFailed(ids: string[], nextAttemptAt: string, error: string): Promise<void>;
+    markParked(ids: string[], error: string): Promise<void>;
+    /** Return the given rows to `retry` if (and only if) they are still `delivering`. */
+    releaseDelivering(ids: string[], nextAttemptAt: string, error: string): Promise<number>;
+    /**
+     * Return `delivering` rows whose lease has expired — or that were claimed by `owner`,
+     * so a restarted instance reclaims its own work immediately — to `retry`.
+     */
+    recoverDelivering(now: string, owner?: string): Promise<number>;
+    /** Park events that have been retrying longer than `maxAgeMs`. */
+    parkExpired(now: string, maxAgeMs: number): Promise<number>;
+    /** One bounded retention step; callers loop until it returns zeros. */
+    pruneBatch(now: string, deliveredDays: number, ledgerDays: number, limit: number): Promise<{
+        wiped: number;
+        deleted: number;
+    }>;
+    close?(): Promise<void>;
+}
+export interface Lease {
+    owner: string;
+    until: string;
+}
+/** Optional inspection/replay capability used by an operator surface. */
+export interface EventStoreAdmin {
+    getById(id: string): Promise<EventRecord | undefined>;
+    list(filter: {
+        status?: EventStatus;
+        route?: string;
+        limit?: number;
+    }): Promise<EventSummary[]>;
+    countByStatus(): Promise<Record<string, number>>;
+    perRouteStats(): Promise<RouteStats[]>;
+    replay(id: string): Promise<boolean>;
+    replayAllParked(): Promise<number>;
+}
+export declare function hasAdmin(store: EventStore): store is EventStore & EventStoreAdmin;
+export type Killswitch = 'none' | 'pause' | 'panic';
+/** Runtime-mutable operator state: the global killswitch and per-route pauses. */
+export interface ControlStore {
+    getKillswitch(): Promise<Killswitch>;
+    setKillswitch(state: Killswitch): Promise<void>;
+    isRoutePaused(routeId: string): Promise<boolean>;
+    setRoutePaused(routeId: string, paused: boolean): Promise<void>;
+}
+/** Where the engine reads route definitions. Static for an embedding app; live for the application. */
+export interface RouteProvider {
+    get(id: string): Promise<RouteConfig | undefined>;
+    all(): Promise<RouteConfig[]>;
+}
+export declare function staticRoutes(routes: RouteConfig[]): RouteProvider;
+export declare class MemoryControlStore implements ControlStore {
+    private killswitch;
+    private paused;
+    getKillswitch(): Promise<Killswitch>;
+    setKillswitch(state: Killswitch): Promise<void>;
+    isRoutePaused(routeId: string): Promise<boolean>;
+    setRoutePaused(routeId: string, paused: boolean): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/engine/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/engine/store.ts"],"names":[],"mappings":"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"}

package/dist/engine/store.js

@@ -0,0 +1,52 @@
+/** A store operation failed. `op` names the operation for logs and hooks. */
+export class StoreError extends Error {
+    op;
+    constructor(message, op, options) {
+        super(message, options);
+        this.op = op;
+        this.name = 'StoreError';
+    }
+}
+/**
+ * The store is temporarily unable to serve a request (lock contention, connection
+ * loss). Ingest answers 503 so the processor retries; any other StoreError is 500.
+ */
+export class StoreUnavailableError extends StoreError {
+    constructor(message, op, options) {
+        super(message, op, options);
+        this.name = 'StoreUnavailableError';
+    }
+}
+export function storeOp(err) {
+    return err instanceof StoreError ? err.op : undefined;
+}
+export function hasAdmin(store) {
+    return typeof store.list === 'function';
+}
+export function staticRoutes(routes) {
+    const byId = new Map(routes.map((r) => [r.id, r]));
+    return {
+        get: async (id) => byId.get(id),
+        all: async () => [...byId.values()],
+    };
+}
+export class MemoryControlStore {
+    killswitch = 'none';
+    paused = new Set();
+    async getKillswitch() {
+        return this.killswitch;
+    }
+    async setKillswitch(state) {
+        this.killswitch = state;
+    }
+    async isRoutePaused(routeId) {
+        return this.paused.has(routeId);
+    }
+    async setRoutePaused(routeId, paused) {
+        if (paused)
+            this.paused.add(routeId);
+        else
+            this.paused.delete(routeId);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/engine/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/engine/store.ts"],"names":[],"mappings":"AAgEA,6EAA6E;AAC7E,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGxB;IAFX,YACE,OAAe,EACN,EAAU,EACnB,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAHd,OAAE,GAAF,EAAE,CAAQ;QAInB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;IAC1B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,UAAU;IACnD,YAAY,OAAe,EAAE,EAAU,EAAE,OAA6B;QACpE,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,MAAM,UAAU,OAAO,CAAC,GAAY;IAClC,OAAO,GAAG,YAAY,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AACvD,CAAC;AAsDD,MAAM,UAAU,QAAQ,CAAC,KAAiB;IACxC,OAAO,OAAQ,KAAkC,CAAC,IAAI,KAAK,UAAU,CAAA;AACvE,CAAC;AAkBD,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAClD,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;KACpC,CAAA;AACH,CAAC;AAED,MAAM,OAAO,kBAAkB;IACrB,UAAU,GAAe,MAAM,CAAA;IAC/B,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAClC,KAAK,CAAC,aAAa;QACjB,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,KAAiB;QACnC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAA;IACzB,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,OAAe;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACjC,CAAC;IACD,KAAK,CAAC,cAAc,CAAC,OAAe,EAAE,MAAe;QACnD,IAAI,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;;YAC/B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;CACF"}

package/dist/forward/backoff.d.ts

@@ -0,0 +1,3 @@
+export declare function backoffMs(attempts: number, baseMs?: number, capMs?: number): number;
+export declare function nextAttemptAt(attempts: number, baseMs?: number, capMs?: number): string;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/forward/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/forward/backoff.ts"],"names":[],"mappings":"AACA,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAO,EAAE,KAAK,SAAU,GAAG,MAAM,CAIlF;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvF"}

package/dist/forward/backoff.js

@@ -0,0 +1,10 @@
+// Exponential backoff with ±20% jitter, Sequin-style: base * 2^attempts, capped.
+export function backoffMs(attempts, baseMs = 1000, capMs = 600_000) {
+    const raw = Math.min(baseMs * 2 ** Math.min(attempts, 30), capMs);
+    const jitter = 0.8 + Math.random() * 0.4;
+    return Math.round(raw * jitter);
+}
+export function nextAttemptAt(attempts, baseMs, capMs) {
+    return new Date(Date.now() + backoffMs(attempts, baseMs, capMs)).toISOString();
+}
+//# sourceMappingURL=backoff.js.map

package/dist/forward/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/forward/backoff.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,GAAG,OAAO;IACxE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;IACjE,MAAM,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAA;IACxC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,CAAA;AACjC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,MAAe,EAAE,KAAc;IAC7E,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;AAChF,CAAC"}

package/dist/forward/dispatcher.d.ts

@@ -0,0 +1,98 @@
+import type { EventEmitter } from 'node:events';
+import { type ControlStore, type EventStore, type RouteProvider } from '../engine/store.js';
+import type { PayloadCodec } from '../engine/codec.js';
+import type { DispatchSettings, RetentionSettings } from '../engine/settings.js';
+import { RelayHooks } from '../engine/hooks.js';
+import { type Logger } from '../logger.js';
+import { type Enrichment } from './enrich.js';
+import { EndCloseClient } from './endclose-client.js';
+export interface DispatcherDeps {
+    store: EventStore;
+    control: ControlStore;
+    routes: RouteProvider;
+    dispatch: DispatchSettings;
+    /** null disables retention pruning. */
+    retention: RetentionSettings | null;
+    client: EndCloseClient;
+    codec: PayloadCodec;
+    maskingKey: Buffer;
+    /** Lease owner recorded on claimed rows; a stable id lets a restarted instance reclaim its own. */
+    instanceId: string;
+    signal: EventEmitter;
+    hooks?: RelayHooks;
+    logger?: Logger;
+    /** Host functions routes may name with `enrich:`; run per event after mapping. */
+    enrichments?: Record<string, Enrichment>;
+}
+export interface DispatchCounts {
+    delivered: number;
+    retried: number;
+    parked: number;
+}
+/** What one dispatch cycle did, and what it deliberately left alone. */
+export interface CycleSummary extends DispatchCounts {
+    /** Routes that had due events when the cycle started. */
+    due: string[];
+    /** Due routes the cycle did not touch, and why. */
+    skipped: {
+        routeId: string;
+        reason: 'paused' | 'unknown_route';
+    }[];
+    /** True when the global killswitch stopped the cycle before any forwarding. */
+    halted: boolean;
+}
+export declare class Dispatcher {
+    private deps;
+    private log;
+    private hooks;
+    private running;
+    private wakeRequested;
+    private reclaimOwner;
+    private lastSweepAt;
+    private inFlight;
+    private pruneWork;
+    private timer;
+    private pruneTimer;
+    private stopped;
+    constructor(deps: DispatcherDeps);
+    start(): void;
+    private onSignal;
+    /**
+     * Run exactly one dispatch cycle, serialised with the background loop if it is running.
+     * Errors propagate to the caller (they are also emitted as hooks).
+     */
+    runOnce(): Promise<CycleSummary>;
+    /** Run retention pruning to completion, serialised with any scheduled prune. */
+    pruneNow(): Promise<{
+        wiped: number;
+        deleted: number;
+    }>;
+    /** Stop accepting new work and wait for the in-flight cycle and prune to drain. */
+    stop(): Promise<void>;
+    private wake;
+    private reportCycleError;
+    private cycle;
+    private deliverBatch;
+    /**
+     * Fill the fields mapEvent left to the host, one enrichment at a time. Throws
+     * EnrichmentError for a bad reference or return value (park); rethrows anything else
+     * the host threw, including a timeout (retry).
+     */
+    private resolveEnrichments;
+    /** Schedule one event for redelivery with backoff, leaving the rest of its batch alone. */
+    private retryOne;
+    private postWithRetries;
+    /**
+     * Bulk processing is async server-side: poll briefly for per-row results. Rows the API
+     * rejected park; everything else is delivered. If results don't settle in time, mark
+     * delivered with the bulk_request_id recorded for later inspection.
+     */
+    private settleResults;
+    private recordDelivered;
+    private recordParked;
+    private schedulePrune;
+    /** Bounded batches with a yield between them so ingest and dispatch keep running. */
+    private runPrune;
+    private releaseLeftover;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/forward/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/forward/dispatcher.ts"],"names":[],"mappings":"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"}