@haywoodmarx/agent-pager 0.1.0

package/dist/src/operator/transport.js

@@ -0,0 +1,549 @@
+import { createServer } from "node:net";
+import { StringDecoder } from "node:string_decoder";
+import { randomBytes } from "node:crypto";
+import { LOOPBACK_HOST } from "../configuration-defaults.js";
+import { closeServer, listenServer, urlHost } from "../shared/http.js";
+import { OPERATOR_PROTOCOL_VERSION, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "./protocol.js";
+import { OperatorValidationError, validateOperatorCommandResultForCommand, validateOperatorSnapshotByteLength, validateOperatorTransportRequest, } from "./validation.js";
+const INPUT_LIMIT_BYTES = 64 * 1_024;
+const LIVE_QUEUE_LIMIT = 32;
+const DIAGNOSTIC_LIMIT = 256;
+const DEFAULT_MAX_CONNECTIONS = 64;
+const CLIENT_ID_LIMIT = 64;
+/** Bounds distinct serialized snapshot versions retained by active transfers. */
+const OPERATOR_MAX_CONCURRENT_SNAPSHOT_TRANSFERS = 2;
+/**
+ * Start a loopback-only newline-delimited operator stream.
+ * @param updates - Authoritative snapshot, replay, and publication service.
+ * @param options - Explicit bind, clock, identity, scheduler, and liveness policy.
+ * @returns Bound transport handle.
+ */
+export async function startOperatorTransport(updates, options) {
+    const resolvedOptions = {
+        ...options,
+        handshakeTimeoutMs: options.handshakeTimeoutMs ?? options.livenessTimeoutMs,
+        maxConnections: options.maxConnections ?? DEFAULT_MAX_CONNECTIONS,
+        maxSnapshotTransfers: options.maxSnapshotTransfers ?? OPERATOR_MAX_CONCURRENT_SNAPSHOT_TRANSFERS,
+    };
+    validateOptions(resolvedOptions);
+    const diagnostics = [];
+    const connections = new Set();
+    const snapshotTransfers = new SnapshotTransferPool(resolvedOptions.maxSnapshotTransfers);
+    let clientSequence = 0;
+    const record = (type, clientId) => {
+        diagnostics.push({ type, clientId, at: resolvedOptions.now() });
+        if (diagnostics.length > DIAGNOSTIC_LIMIT)
+            diagnostics.shift();
+    };
+    const nextClientId = () => {
+        clientSequence = clientSequence === Number.MAX_SAFE_INTEGER ? 1 : clientSequence + 1;
+        return safeClientId(resolvedOptions.issueClientId, clientSequence);
+    };
+    const server = createServer((socket) => {
+        const clientId = nextClientId();
+        if (connections.size >= resolvedOptions.maxConnections) {
+            record("connection_rejected", clientId);
+            socket.destroy();
+            return;
+        }
+        const connection = new OperatorConnection({
+            socket,
+            updates,
+            snapshotTransfers,
+            options: resolvedOptions,
+            clientId,
+            record,
+            onClose: () => connections.delete(connection),
+        });
+        connections.add(connection);
+    });
+    await listenServer(server, resolvedOptions.port, resolvedOptions.host);
+    const cancelPulse = resolvedOptions.scheduler.recurring(() => {
+        for (const connection of connections)
+            connection.pulse();
+    }, resolvedOptions.heartbeatIntervalMs);
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        cancelPulse();
+        server.close();
+        throw new Error("operator transport did not publish a TCP address");
+    }
+    return {
+        url: `tcp://${urlHost(address.address)}:${String(address.port)}`,
+        diagnostics: () => diagnostics.map((entry) => ({ ...entry })),
+        pulse: () => {
+            for (const connection of connections)
+                connection.pulse();
+        },
+        close: async () => {
+            cancelPulse();
+            for (const connection of [...connections])
+                connection.destroy();
+            await closeServer(server);
+        },
+    };
+}
+/**
+ * Issue one bounded public-safe transport diagnostic identity.
+ * @returns An opaque identity that contains no network address or process binding.
+ */
+export function issueOperatorClientId() {
+    return `operator-client-${randomBytes(12).toString("hex")}`;
+}
+class SnapshotTransferPool {
+    #maxTransfers;
+    #entries = new Map();
+    constructor(maxTransfers) {
+        this.#maxTransfers = maxTransfers;
+    }
+    acquire(snapshot, mode) {
+        const key = snapshotTransferKey(snapshot.cursor);
+        const existing = this.#entries.get(key);
+        if (existing) {
+            existing.references += 1;
+            return { type: "acquired", transfer: { shared: existing, mode, nextFrame: "begin" } };
+        }
+        for (const [entryKey, entry] of this.#entries) {
+            if (entry.references === 0)
+                this.#entries.delete(entryKey);
+        }
+        if (this.#entries.size >= this.#maxTransfers)
+            return { type: "unavailable" };
+        let bytes;
+        try {
+            bytes = Buffer.from(JSON.stringify(snapshot), "utf8");
+            validateOperatorSnapshotByteLength(bytes.byteLength);
+        }
+        catch {
+            return { type: "unavailable" };
+        }
+        const entry = {
+            key,
+            cursor: { ...snapshot.cursor },
+            bytes,
+            chunkCount: Math.ceil(bytes.byteLength / OPERATOR_SNAPSHOT_CHUNK_BYTES),
+            references: 1,
+        };
+        this.#entries.set(key, entry);
+        return { type: "acquired", transfer: { shared: entry, mode, nextFrame: "begin" } };
+    }
+    release(transfer) {
+        const entry = this.#entries.get(transfer.shared.key);
+        if (entry !== transfer.shared || entry.references < 1)
+            return;
+        entry.references -= 1;
+    }
+}
+class OperatorConnection {
+    #socket;
+    #decoder = new StringDecoder("utf8");
+    #updates;
+    #snapshotTransfers;
+    #options;
+    #record;
+    #onClose;
+    #clientId;
+    #buffer = "";
+    #subscribed = false;
+    #closed = false;
+    #blocked = false;
+    #closeAfterFlush = false;
+    #prelude = [];
+    #pending = [];
+    #snapshotTransfer;
+    #unsubscribe;
+    #lastAckAt;
+    #lastAckCursor;
+    #lastSentCursor;
+    constructor({ socket, updates, snapshotTransfers, options, clientId, record, onClose, }) {
+        this.#socket = socket;
+        this.#updates = updates;
+        this.#snapshotTransfers = snapshotTransfers;
+        this.#options = options;
+        this.#record = record;
+        this.#onClose = onClose;
+        this.#clientId = clientId;
+        this.#lastAckAt = options.now();
+        this.#socket.setEncoding("utf8");
+        this.#socket.on("data", (chunk) => {
+            this.#receive(typeof chunk === "string" ? chunk : this.#decoder.write(chunk));
+        });
+        this.#socket.on("drain", () => {
+            this.#drain();
+        });
+        this.#socket.on("error", () => {
+            this.destroy();
+        });
+        this.#socket.on("close", () => {
+            this.#closedBySocket();
+        });
+        this.#record("connected", this.#clientId);
+    }
+    pulse() {
+        if (this.#closed)
+            return;
+        if (!this.#subscribed) {
+            if (this.#options.now() - this.#lastAckAt >= this.#options.handshakeTimeoutMs) {
+                this.#record("handshake_timeout", this.#clientId);
+                this.destroy();
+            }
+            return;
+        }
+        if (this.#options.now() - this.#lastAckAt >= this.#options.livenessTimeoutMs) {
+            this.#record("liveness_timeout", this.#clientId);
+            this.destroy();
+            return;
+        }
+        if (this.#blocked || this.#pending.length > 0) {
+            this.#record("slow_consumer", this.#clientId);
+            this.destroy();
+            return;
+        }
+        this.#enqueue({ type: "heartbeat", cursor: this.#updates.cursor(), sentAt: this.#options.now() }, false);
+        this.#record("heartbeat_sent", this.#clientId);
+    }
+    destroy() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#releaseSnapshotTransfer();
+        this.#prelude = [];
+        this.#pending = [];
+        this.#socket.destroy();
+    }
+    #receive(chunk) {
+        if (this.#closed)
+            return;
+        this.#buffer += chunk;
+        if (Buffer.byteLength(this.#buffer, "utf8") > INPUT_LIMIT_BYTES) {
+            this.#malformed();
+            return;
+        }
+        for (;;) {
+            const newline = this.#buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (!line || Buffer.byteLength(line, "utf8") > INPUT_LIMIT_BYTES) {
+                this.#malformed();
+                return;
+            }
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                this.#malformed();
+                return;
+            }
+            if (!this.#accept(value))
+                return;
+        }
+    }
+    #accept(value) {
+        const version = transportVersion(value);
+        if (version !== undefined && version !== OPERATOR_PROTOCOL_VERSION) {
+            this.#record("incompatible_version", this.#clientId);
+            this.#enqueue({
+                type: "incompatible_version",
+                supportedVersion: OPERATOR_PROTOCOL_VERSION,
+                receivedVersion: version,
+            }, false);
+            this.#finishAfterFlush();
+            return false;
+        }
+        let request;
+        try {
+            request = validateOperatorTransportRequest(value);
+        }
+        catch (error) {
+            if (error instanceof OperatorValidationError) {
+                this.#malformed();
+                return false;
+            }
+            throw error;
+        }
+        if (request.type === "subscribe")
+            return this.#subscribe(request);
+        if (request.type === "ack")
+            return this.#acknowledge(request);
+        return this.#command(request);
+    }
+    #subscribe(request) {
+        if (this.#subscribed) {
+            this.#malformed();
+            return false;
+        }
+        this.#subscribed = true;
+        const opened = this.#updates.open(request.cursor ?? null, (publication) => {
+            this.#publish(publication);
+        });
+        this.#unsubscribe = opened.unsubscribe;
+        this.#record("subscribed", this.#clientId);
+        switch (opened.result.type) {
+            case "initial":
+                if (!this.#beginSnapshotTransfer(opened.result.snapshot, "initial"))
+                    return false;
+                break;
+            case "resumed":
+                for (const envelope of opened.result.events) {
+                    this.#pending.push({ type: "event", envelope });
+                }
+                break;
+            case "replacement":
+                if (!this.#beginSnapshotTransfer(opened.result.snapshot, "replacement"))
+                    return false;
+                this.#record("resync_required", this.#clientId);
+                this.#prelude.push({ type: "resync_required", reason: opened.result.reason });
+                break;
+            case "unavailable":
+                this.#makeStreamUnavailable();
+                this.#flush();
+                return false;
+        }
+        this.#pending.push({ type: "heartbeat", cursor: this.#updates.cursor(), sentAt: this.#options.now() });
+        this.#flush();
+        return true;
+    }
+    #acknowledge(request) {
+        if (!this.#subscribed || !this.#lastSentCursor) {
+            this.#malformed();
+            return false;
+        }
+        const cursor = request.cursor;
+        if (cursor.epoch !== this.#lastSentCursor.epoch ||
+            cursor.sequence > this.#lastSentCursor.sequence ||
+            (this.#lastAckCursor && cursor.sequence < this.#lastAckCursor.sequence)) {
+            this.#malformed();
+            return false;
+        }
+        this.#lastAckCursor = { ...cursor };
+        this.#lastAckAt = this.#options.now();
+        this.#record("liveness_acknowledged", this.#clientId);
+        return true;
+    }
+    #command(request) {
+        if (!this.#subscribed) {
+            this.#malformed();
+            return false;
+        }
+        if (this.#blocked && this.#pending.length >= LIVE_QUEUE_LIMIT) {
+            this.#record("slow_consumer", this.#clientId);
+            this.destroy();
+            return false;
+        }
+        try {
+            const result = this.#options.commands.execute(request.command);
+            const correlated = validateOperatorCommandResultForCommand(request.command, result);
+            this.#enqueue({ type: "command_result", result: correlated.result }, false);
+            return true;
+        }
+        catch {
+            this.#malformed();
+            return false;
+        }
+    }
+    #publish(publication) {
+        if (publication.type === "diagnostic") {
+            this.#enqueue({ type: "diagnostic", diagnostic: publication.diagnostic }, true);
+            return;
+        }
+        if (publication.type === "unavailable") {
+            this.#record("resync_required", this.#clientId);
+            this.#enqueue({ type: "resync_required", reason: "stream_unavailable" }, true);
+            this.#finishAfterFlush();
+            return;
+        }
+        this.#enqueue({ type: "event", envelope: publication.envelope }, true);
+    }
+    #enqueue(frame, live) {
+        if (this.#closed)
+            return;
+        if (live && this.#pending.length >= LIVE_QUEUE_LIMIT) {
+            this.#record("slow_consumer", this.#clientId);
+            this.destroy();
+            return;
+        }
+        this.#pending.push(frame);
+        this.#flush();
+    }
+    #flush() {
+        if (this.#blocked || this.#closed)
+            return;
+        for (;;) {
+            const frame = this.#nextFrame();
+            if (!frame)
+                break;
+            const encoded = `${JSON.stringify(frame)}\n`;
+            if (Buffer.byteLength(encoded, "utf8") > OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES) {
+                this.#makeStreamUnavailable();
+                continue;
+            }
+            this.#observeSentCursor(frame);
+            if (!this.#socket.write(encoded)) {
+                this.#blocked = true;
+                return;
+            }
+        }
+        if (this.#closeAfterFlush)
+            this.#socket.end();
+    }
+    #drain() {
+        if (this.#closed)
+            return;
+        this.#blocked = false;
+        this.#flush();
+    }
+    #observeSentCursor(frame) {
+        if (frame.type === "snapshot_end")
+            this.#lastSentCursor = { ...frame.cursor };
+        if (frame.type === "event") {
+            this.#lastSentCursor = {
+                protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                epoch: frame.envelope.epoch,
+                sequence: frame.envelope.sequence,
+            };
+        }
+        if (frame.type === "heartbeat")
+            this.#lastSentCursor = { ...frame.cursor };
+    }
+    #finishAfterFlush() {
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#closeAfterFlush = true;
+        this.#flush();
+    }
+    #beginSnapshotTransfer(snapshot, mode) {
+        const acquired = this.#snapshotTransfers.acquire(snapshot, mode);
+        if (acquired.type === "unavailable") {
+            this.#makeStreamUnavailable();
+            this.#flush();
+            return false;
+        }
+        this.#snapshotTransfer = acquired.transfer;
+        return true;
+    }
+    #nextFrame() {
+        const prelude = this.#prelude.shift();
+        if (prelude)
+            return prelude;
+        const transfer = this.#snapshotTransfer;
+        if (transfer) {
+            if (transfer.nextFrame === "begin") {
+                transfer.nextFrame = 0;
+                return {
+                    type: "snapshot_begin",
+                    protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                    mode: transfer.mode,
+                    cursor: { ...transfer.shared.cursor },
+                    encoding: "base64",
+                    totalBytes: transfer.shared.bytes.byteLength,
+                    chunkCount: transfer.shared.chunkCount,
+                };
+            }
+            if (typeof transfer.nextFrame === "number") {
+                const index = transfer.nextFrame;
+                if (index < transfer.shared.chunkCount) {
+                    const start = index * OPERATOR_SNAPSHOT_CHUNK_BYTES;
+                    const end = Math.min(start + OPERATOR_SNAPSHOT_CHUNK_BYTES, transfer.shared.bytes.byteLength);
+                    transfer.nextFrame = index + 1 < transfer.shared.chunkCount ? index + 1 : "end";
+                    return {
+                        type: "snapshot_chunk",
+                        protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                        index,
+                        data: transfer.shared.bytes.toString("base64", start, end),
+                    };
+                }
+            }
+            const frame = {
+                type: "snapshot_end",
+                protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                cursor: { ...transfer.shared.cursor },
+                totalBytes: transfer.shared.bytes.byteLength,
+                chunkCount: transfer.shared.chunkCount,
+            };
+            this.#releaseSnapshotTransfer();
+            return frame;
+        }
+        return this.#pending.shift();
+    }
+    #releaseSnapshotTransfer() {
+        if (!this.#snapshotTransfer)
+            return;
+        this.#snapshotTransfers.release(this.#snapshotTransfer);
+        this.#snapshotTransfer = undefined;
+    }
+    #makeStreamUnavailable() {
+        this.#releaseSnapshotTransfer();
+        this.#prelude = [{ type: "resync_required", reason: "stream_unavailable" }];
+        this.#pending = [];
+        this.#record("stream_unavailable", this.#clientId);
+        this.#record("resync_required", this.#clientId);
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#closeAfterFlush = true;
+    }
+    #malformed() {
+        this.#record("malformed_request", this.#clientId);
+        this.destroy();
+    }
+    #closedBySocket() {
+        if (!this.#closed) {
+            this.#closed = true;
+            this.#unsubscribe?.();
+            this.#unsubscribe = undefined;
+            this.#releaseSnapshotTransfer();
+            this.#prelude = [];
+            this.#pending = [];
+        }
+        this.#record("disconnected", this.#clientId);
+        this.#onClose();
+    }
+}
+function transportVersion(value) {
+    if (typeof value !== "object" || value === null || !("protocolVersion" in value))
+        return undefined;
+    const version = value.protocolVersion;
+    return typeof version === "number" && Number.isSafeInteger(version) ? version : undefined;
+}
+function validateOptions(options) {
+    if (options.host !== LOOPBACK_HOST && options.host !== "::1")
+        throw new Error("operator transport must bind loopback");
+    if (!Number.isSafeInteger(options.port) || options.port < 0 || options.port > 65_535) {
+        throw new Error("operator transport port is invalid");
+    }
+    if (!Number.isSafeInteger(options.heartbeatIntervalMs) || options.heartbeatIntervalMs < 1) {
+        throw new Error("operator heartbeat interval is invalid");
+    }
+    if (!Number.isSafeInteger(options.livenessTimeoutMs) || options.livenessTimeoutMs <= options.heartbeatIntervalMs) {
+        throw new Error("operator liveness timeout must exceed its heartbeat interval");
+    }
+    if (!Number.isSafeInteger(options.handshakeTimeoutMs) || options.handshakeTimeoutMs < 1) {
+        throw new Error("operator handshake timeout is invalid");
+    }
+    if (!Number.isSafeInteger(options.maxConnections) || options.maxConnections < 1) {
+        throw new Error("operator connection limit is invalid");
+    }
+    if (!Number.isSafeInteger(options.maxSnapshotTransfers) || options.maxSnapshotTransfers < 1) {
+        throw new Error("operator snapshot transfer limit is invalid");
+    }
+}
+function snapshotTransferKey(cursor) {
+    return JSON.stringify(cursor);
+}
+function safeClientId(issueClientId, sequence) {
+    let candidate;
+    try {
+        candidate = issueClientId();
+    }
+    catch {
+        candidate = undefined;
+    }
+    if (candidate && candidate.length <= CLIENT_ID_LIMIT && /^[a-z0-9][a-z0-9_-]*$/iu.test(candidate)) {
+        return candidate;
+    }
+    return `operator-client-fallback-${String(sequence)}`;
+}

package/dist/src/operator/update-store.d.ts

@@ -0,0 +1,53 @@
+import { type BrokerDatabase } from "../broker/database.js";
+import { type OperatorCursor, type OperatorEventEnvelope, type OperatorStateEvent } from "./protocol.js";
+/** Reports resumable events or the exact replacement condition. */
+export type OperatorReplayResult = {
+    type: "events";
+    events: OperatorEventEnvelope[];
+} | {
+    type: "epoch_changed";
+} | {
+    type: "cursor_gap";
+};
+/** Persists complete event batches before any client can observe their cursors. */
+export interface OperatorEventStorePort {
+    /**
+     * Return the latest durable stream position.
+     * @returns The current epoch-scoped cursor.
+     */
+    currentCursor(): OperatorCursor;
+    /**
+     * Persist and prune one complete change batch atomically.
+     * @param events - Validated state changes in publication order.
+     * @returns Durable envelopes safe to publish after this call succeeds.
+     */
+    append(events: readonly OperatorStateEvent[]): OperatorEventEnvelope[];
+    /**
+     * Read an exact retained suffix after one client cursor.
+     * @param cursor - Last authoritative event already incorporated by the client.
+     * @returns Ordered events or an explicit replacement condition.
+     */
+    replay(cursor: OperatorCursor): OperatorReplayResult;
+    /** Release resources owned by the store. */
+    close(): void;
+}
+/** SQLite-backed bounded replay storage owned by one broker epoch. */
+export declare class SqliteOperatorEventStore implements OperatorEventStorePort {
+    #private;
+    /**
+     * Open replay storage adjacent to the broker's durable state.
+     * @param databasePath - Broker SQLite path containing the operator stream tables.
+     * @param epoch - Current broker generation that owns new event sequence values.
+     * @param replayLimit - Maximum number of event envelopes retained globally.
+     * @param openDatabase - Opens the connection this store owns and closes.
+     */
+    constructor(databasePath: string, epoch: string, replayLimit?: number, openDatabase?: (path: string) => BrokerDatabase);
+    /** @inheritdoc */
+    currentCursor(): OperatorCursor;
+    /** @inheritdoc */
+    append(events: readonly OperatorStateEvent[]): OperatorEventEnvelope[];
+    /** @inheritdoc */
+    replay(cursor: OperatorCursor): OperatorReplayResult;
+    /** @inheritdoc */
+    close(): void;
+}