bunsane 0.2.8 → 0.2.10

package/core/remote/health.ts

@@ -0,0 +1,139 @@
+/**
+ * Remote Communication: Health check
+ *
+ * Aggregates health signals from Redis, the consumer group PEL, the outbox
+ * table, the DLQ, and the circuit breaker. Exposed via `/health/remote`
+ * and callable directly through `RemoteManager.health()`.
+ */
+
+import type Redis from "ioredis";
+import type { SQL } from "bun";
+import type { CircuitBreaker } from "./CircuitBreaker";
+
+export interface RemoteHealthCheck {
+    healthy: boolean;
+    checks: {
+        redis: { ok: boolean; latencyMs?: number; error?: string };
+        consumer: {
+            streamKey: string;
+            pelCount?: number;
+            error?: string;
+        };
+        dlq: { stream: string; length?: number; error?: string };
+        outbox?: { pendingCount?: number; error?: string };
+        circuitBreaker: {
+            state: string;
+            failures: number;
+        };
+    };
+    timestamp: string;
+}
+
+export interface HealthInputs {
+    publisher: Redis | null;
+    consumerRedis: Redis | null;
+    streamKey: string;
+    consumerGroup: string;
+    dlqStream: string;
+    outboxEnabled: boolean;
+    db: SQL;
+    breaker: CircuitBreaker;
+}
+
+export async function collectRemoteHealth(
+    inputs: HealthInputs
+): Promise<RemoteHealthCheck> {
+    const result: RemoteHealthCheck = {
+        healthy: true,
+        checks: {
+            redis: { ok: false },
+            consumer: { streamKey: inputs.streamKey },
+            dlq: { stream: inputs.dlqStream },
+            circuitBreaker: {
+                state: inputs.breaker.getState(),
+                failures: inputs.breaker.getStats().failures,
+            },
+        },
+        timestamp: new Date().toISOString(),
+    };
+
+    // Redis ping via publisher connection
+    if (inputs.publisher) {
+        const start = Date.now();
+        try {
+            await inputs.publisher.ping();
+            result.checks.redis = {
+                ok: true,
+                latencyMs: Date.now() - start,
+            };
+        } catch (error: any) {
+            result.checks.redis = {
+                ok: false,
+                error: error?.message ?? String(error),
+            };
+            result.healthy = false;
+        }
+    } else {
+        result.checks.redis = { ok: false, error: "publisher not started" };
+        result.healthy = false;
+    }
+
+    // PEL count (pending entries in consumer group)
+    if (inputs.publisher) {
+        try {
+            const pending: any = await inputs.publisher.xpending(
+                inputs.streamKey,
+                inputs.consumerGroup
+            );
+            // XPENDING summary: [total, smallest-id, largest-id, consumers]
+            const count = Array.isArray(pending)
+                ? (pending[0] as number) ?? 0
+                : 0;
+            result.checks.consumer.pelCount = count;
+        } catch (error: any) {
+            result.checks.consumer.error = error?.message ?? String(error);
+        }
+    }
+
+    // DLQ length
+    if (inputs.publisher) {
+        try {
+            const len = await inputs.publisher.xlen(inputs.dlqStream);
+            result.checks.dlq.length = len ?? 0;
+        } catch (error: any) {
+            const msg = error?.message ?? String(error);
+            // ERR no such key = stream hasn't been created yet, that's fine
+            if (String(msg).toLowerCase().includes("no such key")) {
+                result.checks.dlq.length = 0;
+            } else {
+                result.checks.dlq.error = msg;
+            }
+        }
+    }
+
+    // Outbox pending count
+    if (inputs.outboxEnabled) {
+        try {
+            const db = inputs.db as any;
+            const rows = await db`
+                SELECT COUNT(*)::int AS pending
+                FROM remote_outbox
+                WHERE published_at IS NULL
+            `;
+            result.checks.outbox = {
+                pendingCount: rows?.[0]?.pending ?? 0,
+            };
+        } catch (error: any) {
+            result.checks.outbox = {
+                error: error?.message ?? String(error),
+            };
+        }
+    }
+
+    // Circuit breaker open -> degrade health
+    if (result.checks.circuitBreaker.state === "open") {
+        result.healthy = false;
+    }
+
+    return result;
+}

package/core/remote/index.ts

@@ -0,0 +1,37 @@
+export {
+    RemoteManager,
+    getRemoteManager,
+    setRemoteManager,
+} from "./RemoteManager";
+export { StreamConsumer } from "./StreamConsumer";
+export { RpcCaller } from "./RpcCaller";
+export { OutboxWorker } from "./OutboxWorker";
+export { ensureOutboxSchema } from "./outboxSchema";
+export { CircuitBreaker, CircuitOpenError } from "./CircuitBreaker";
+export type { CircuitState, CircuitBreakerConfig } from "./CircuitBreaker";
+export { RemoteMetrics } from "./metrics";
+export type { RemoteMetricsSnapshot } from "./metrics";
+export { collectRemoteHealth } from "./health";
+export type { RemoteHealthCheck } from "./health";
+export {
+    RemoteEvent,
+    RemoteRpc,
+    registerRemoteHandlers,
+} from "./decorators";
+export type { RemoteEventOptions, RemoteRpcOptions } from "./decorators";
+export { RemoteError } from "./types";
+export type {
+    RemoteContext,
+    RemoteHandler,
+    RemoteHandlerInfo,
+    RemoteEnvelope,
+    RemoteErrorOptions,
+    RemoteManagerConfig,
+    RemoteKind,
+    RpcHandler,
+    RpcResponse,
+    RpcSuccessResponse,
+    RpcErrorResponse,
+    CallOptions,
+    EmitOptions,
+} from "./types";

package/core/remote/metrics.ts

@@ -0,0 +1,99 @@
+/**
+ * Remote Communication: Metrics
+ *
+ * In-memory counters for the remote subsystem. Exposed via
+ * `RemoteManager.getMetrics()` and the `/metrics` HTTP endpoint.
+ */
+
+export interface RemoteMetricsSnapshot {
+    emit: {
+        direct: number;
+        outbox: number;
+        failed: number;
+    };
+    events: {
+        received: number;
+        handled: number;
+        handlerFailed: number;
+        noHandler: number;
+        dlq: number;
+    };
+    rpc: {
+        called: number;
+        succeeded: number;
+        failed: number;
+        timedOut: number;
+        handlerExecuted: number;
+        handlerFailed: number;
+        pastDeadline: number;
+    };
+    outbox: {
+        claimed: number;
+        published: number;
+        publishFailed: number;
+    };
+    circuitBreaker: {
+        trips: number;
+        rejected: number;
+    };
+}
+
+function emptySnapshot(): RemoteMetricsSnapshot {
+    return {
+        emit: { direct: 0, outbox: 0, failed: 0 },
+        events: { received: 0, handled: 0, handlerFailed: 0, noHandler: 0, dlq: 0 },
+        rpc: {
+            called: 0,
+            succeeded: 0,
+            failed: 0,
+            timedOut: 0,
+            handlerExecuted: 0,
+            handlerFailed: 0,
+            pastDeadline: 0,
+        },
+        outbox: { claimed: 0, published: 0, publishFailed: 0 },
+        circuitBreaker: { trips: 0, rejected: 0 },
+    };
+}
+
+export class RemoteMetrics {
+    private snapshot: RemoteMetricsSnapshot = emptySnapshot();
+
+    // Emit
+    emitDirect(): void { this.snapshot.emit.direct++; }
+    emitOutbox(): void { this.snapshot.emit.outbox++; }
+    emitFailed(): void { this.snapshot.emit.failed++; }
+
+    // Events
+    eventReceived(): void { this.snapshot.events.received++; }
+    eventHandled(): void { this.snapshot.events.handled++; }
+    eventHandlerFailed(): void { this.snapshot.events.handlerFailed++; }
+    eventNoHandler(): void { this.snapshot.events.noHandler++; }
+    eventDlq(): void { this.snapshot.events.dlq++; }
+
+    // RPC
+    rpcCalled(): void { this.snapshot.rpc.called++; }
+    rpcSucceeded(): void { this.snapshot.rpc.succeeded++; }
+    rpcFailed(): void { this.snapshot.rpc.failed++; }
+    rpcTimedOut(): void { this.snapshot.rpc.timedOut++; }
+    rpcHandlerExecuted(): void { this.snapshot.rpc.handlerExecuted++; }
+    rpcHandlerFailed(): void { this.snapshot.rpc.handlerFailed++; }
+    rpcPastDeadline(): void { this.snapshot.rpc.pastDeadline++; }
+
+    // Outbox
+    outboxClaimed(n: number): void { this.snapshot.outbox.claimed += n; }
+    outboxPublished(n: number): void { this.snapshot.outbox.published += n; }
+    outboxPublishFailed(): void { this.snapshot.outbox.publishFailed++; }
+
+    // Circuit Breaker
+    cbTripped(): void { this.snapshot.circuitBreaker.trips++; }
+    cbRejected(): void { this.snapshot.circuitBreaker.rejected++; }
+
+    getSnapshot(): RemoteMetricsSnapshot {
+        return JSON.parse(JSON.stringify(this.snapshot));
+    }
+
+    reset(): void {
+        this.snapshot = emptySnapshot();
+    }
+}

package/core/remote/outboxSchema.ts

@@ -0,0 +1,41 @@
+/**
+ * Remote Communication: Transactional Outbox schema
+ *
+ * The outbox table records `emit()` calls made inside a DB transaction.
+ * A background worker picks pending rows up and publishes them to Redis.
+ * This guarantees that the event is only released to consumers if the
+ * transaction that produced it committed — no "committed write without
+ * matching event" after a crash.
+ *
+ * Schema is intentionally minimal (Gall's Law): id, target, event, data,
+ * created_at, published_at. Retry counts, DLQ tracking, and leases can be
+ * added in later phases when there's a concrete reason.
+ */
+
+import type { SQL } from "bun";
+import { logger } from "../Logger";
+
+const loggerInstance = logger.child({ scope: "OutboxSchema" });
+
+export async function ensureOutboxSchema(db: SQL): Promise<void> {
+    await db`
+        CREATE TABLE IF NOT EXISTS remote_outbox (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            target VARCHAR(255) NOT NULL,
+            event VARCHAR(255) NOT NULL,
+            data JSONB NOT NULL,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+            published_at TIMESTAMPTZ
+        )
+    `;
+
+    // Partial index: only unpublished rows. Keeps the index small even as
+    // the table accumulates historical sent messages.
+    await db`
+        CREATE INDEX IF NOT EXISTS idx_remote_outbox_pending
+        ON remote_outbox (created_at)
+        WHERE published_at IS NULL
+    `;
+
+    loggerInstance.info("remote_outbox schema ensured");
+}

package/core/remote/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Remote Communication: Types
+ *
+ * Standalone types for cross-app events over Redis Streams.
+ * RemoteContext is NOT derived from GraphQLContext — remote handlers run
+ * outside request scope.
+ */
+
+export interface RemoteContext {
+    sourceApp: string;
+    messageId: string;
+    timestamp: Date;
+    attempt: number;
+    correlationId?: string;
+    deadline?: Date;
+}
+
+export type RemoteHandler<T = unknown> = (
+    data: T,
+    ctx: RemoteContext
+) => Promise<void> | void;
+
+export type RemoteKind = "event" | "rpc_request";
+
+export interface RemoteHandlerInfo {
+    event: string;
+    methodName: string;
+    handlerId: string;
+    /** "event" for @RemoteEvent, "rpc_request" for @RemoteRpc */
+    kind: RemoteKind;
+}
+
+export interface RemoteEnvelope {
+    /** Discriminator — absent/`"event"` = fire-and-forget, `"rpc_request"` = RPC */
+    kind?: RemoteKind;
+    sourceApp: string;
+    event: string;
+    data: unknown;
+    emittedAt: number;
+
+    /** RPC-only */
+    correlationId?: string;
+    replyTo?: string;
+    deadline?: number;
+}
+
+export type RpcHandler<TIn = unknown, TOut = unknown> = (
+    data: TIn,
+    ctx: RemoteContext
+) => Promise<TOut> | TOut;
+
+export interface RpcSuccessResponse {
+    correlationId: string;
+    sourceApp: string;
+    success: true;
+    result: unknown;
+    respondedAt: number;
+}
+
+export interface RpcErrorResponse {
+    correlationId: string;
+    sourceApp: string;
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        extensions?: Record<string, unknown>;
+    };
+    respondedAt: number;
+}
+
+export type RpcResponse = RpcSuccessResponse | RpcErrorResponse;
+
+export interface CallOptions {
+    /** Timeout in ms (default: 5000) */
+    timeout?: number;
+}
+
+/**
+ * emit() options. Passing `trx` routes the event through the transactional
+ * outbox — the row is inserted within the caller's transaction and
+ * published by the OutboxWorker after commit.
+ */
+export interface EmitOptions {
+    /** Transaction handle from `db.begin()` / `db.transaction()`. */
+    trx?: import("bun").SQL;
+}
+
+export interface RemoteErrorOptions {
+    code: string;
+    sourceApp?: string;
+    extensions?: Record<string, unknown>;
+}
+
+export class RemoteError extends Error {
+    public readonly code: string;
+    public readonly sourceApp?: string;
+    public readonly extensions?: Record<string, unknown>;
+
+    constructor(message: string, options: RemoteErrorOptions) {
+        super(message);
+        this.name = "RemoteError";
+        this.code = options.code;
+        this.sourceApp = options.sourceApp;
+        this.extensions = options.extensions;
+    }
+}
+
+export interface RemoteManagerConfig {
+    /** This app's identity — used as stream name and sourceApp field */
+    appName: string;
+    /** Consumer group (defaults to appName) */
+    consumerGroup?: string;
+    /** Unique consumer id within the group (defaults to pid + timestamp) */
+    consumerId?: string;
+    /** Stream key prefix (default: "remote:") */
+    streamPrefix?: string;
+    /** Enable verbose logging */
+    enableLogging?: boolean;
+    /** Max messages per XREADGROUP batch (default: 10) */
+    batchSize?: number;
+    /** XREADGROUP BLOCK timeout in ms (default: 2000) */
+    blockMs?: number;
+    /** XAUTOCLAIM idle threshold in ms on startup (default: 60000). 0 disables */
+    autoClaimIdleMs?: number;
+    /** Max response stream length cap per XADD MAXLEN ~ (default: 1000) */
+    responseStreamMaxLen?: number;
+    /** Default RPC call timeout in ms (default: 5000) */
+    defaultCallTimeout?: number;
+    /** Grace window for pending RPC calls during shutdown (default: 2000) */
+    shutdownDrainMs?: number;
+    /** Enable transactional outbox (default: false) */
+    enableOutbox?: boolean;
+    /** Outbox polling interval in ms (default: 1000) */
+    outboxPollIntervalMs?: number;
+    /** Max rows processed per outbox tick (default: 100) */
+    outboxBatchSize?: number;
+    /** Circuit breaker failure threshold before opening (default: 5) */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker reset timeout in ms (default: 30000) */
+    circuitBreakerResetMs?: number;
+    /** Max deliveries before routing a message to DLQ (default: 3, 0 disables) */
+    dlqMaxDeliveries?: number;
+    /**
+     * Test-only: override how Redis clients are constructed. Return a
+     * connected client compatible with the ioredis `Redis` interface.
+     * `blocking` is `true` for connections that will issue BLOCK commands
+     * (consumer + RPC listener), `false` for the publisher.
+     */
+    redisFactory?: (blocking: boolean) => any;
+}