@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/esm/channels/wake-channel.d.ts

@@ -0,0 +1,232 @@
+import { WakeChannelState, WakeEvent } from './types';
+/**
+ * Hard ceiling on the incremental SSE parser buffer, in characters.
+ *
+ * A stream that never emits a blank line would otherwise grow this buffer
+ * monotonically for the lifetime of the daemon. JavaScript string length counts
+ * UTF-16 code units, which never exceeds the UTF-8 byte length of the same
+ * text, so a character cap is strictly tighter than a byte cap on
+ * LIMITS.MAX_PAYLOAD_BYTES.
+ */
+export declare const SSE_BUFFER_MAX_CHARS: 16777216;
+/** Maximum characters of `data:` payload parsed out of one SSE event. */
+export declare const SSE_EVENT_DATA_MAX_CHARS: 16777216;
+/** Maximum events queued from a single TCP chunk before the stream is failed. */
+export declare const SSE_MAX_QUEUED_EVENTS = 4096;
+/** Maximum events processed per event-loop turn before yielding. */
+export declare const SSE_MAX_EVENTS_PER_TICK = 64;
+export interface WakeChannelOptions {
+    /** Cloud URL, e.g. "wss://api.schemaweaver.dev" — wss/https are the only accepted schemes. */
+    cloudUrl: string;
+    /** Agent token (sent as Bearer header). */
+    token: string;
+    /** Agent ID (sent as X-Agent-Id header for routing). */
+    agentId: string;
+    /** Optional: returns configured database list from databases.config.json. */
+    getDatabases?: () => Array<{
+        db_alias: string;
+        database: string;
+    }>;
+    /** Called when a wake event arrives. */
+    onWake: (event: WakeEvent) => void;
+    /** Called when channel state changes. */
+    onStateChange?: (state: WakeChannelState, error?: string) => void;
+    /** Optional: custom backoff schedule (for tests). */
+    backoffSchedule?: readonly number[];
+    /** Optional: disable keepalive (for tests). Default true. */
+    enableKeepalive?: boolean;
+    /** Optional: abort signal for clean shutdown. */
+    abortSignal?: AbortSignal;
+    /** Optional: custom backoff schedule for consecutive 401/403 responses. */
+    authBackoffSchedule?: readonly number[];
+    /** Optional: consecutive auth failures tolerated before stopping. Default 5. */
+    maxAuthFailures?: number;
+    /**
+     * Allow a cleartext `http:`/`ws:` target. Only wire this to an explicit,
+     * non-persisted operator flag (`--insecure-transport`).
+     */
+    allowInsecureTransport?: boolean;
+    /** Clock injection point for replay/freshness checks. Defaults to `Date.now`. */
+    now?: () => number;
+    /**
+     * Age of an acceptable wake event, from `queued_at`. Defaults to
+     * DEFAULTS.WAKE_MAX_EVENT_AGE_MS.
+     */
+    maxEventAgeMs?: number;
+    /**
+     * Clock skew tolerated on the cloud-stamped `queued_at` and
+     * `data_channel_token_expires_at`. Defaults to DEFAULTS.WAKE_CLOCK_SKEW_MS.
+     */
+    clockSkewMs?: number;
+    /**
+     * Capacity of the `wake_id` replay cache. Defaults to
+     * LIMITS.WAKE_REPLAY_CACHE_MAX_ENTRIES. The cache is hard-bounded: an
+     * unbounded set of cloud-supplied ids is itself a memory-exhaustion vector.
+     */
+    replayCacheEntries?: number;
+    /** Called when a wake event is refused, for operator-visible reporting. */
+    onWakeRejected?: (reason: WakeRejectionReason, detail: string, event: unknown) => void;
+}
+/** Why a wake event was refused without being dispatched. */
+export type WakeRejectionReason = 'malformed' | 'expired_token' | 'stale' | 'future_dated' | 'replayed' | 'cache_full';
+/** Counters for the wake-event admission checks. Diagnostics only. */
+export interface WakeAdmissionStats {
+    /** Wake ids currently held in the replay cache. Never exceeds the bound. */
+    cached: number;
+    /** Events refused as replays of a cached `wake_id`. */
+    duplicates: number;
+    /** Events refused because the cache was already at its bound. */
+    denied_cache_full: number;
+    /** Events refused for any other reason (malformed, stale, expired token). */
+    refused: number;
+    accepted: number;
+}
+export interface SseBufferStats {
+    /** Current parser buffer size in characters. */
+    current: number;
+    /** High-water mark of the parser buffer since process start. */
+    peak: number;
+    /** Events waiting to be dispatched. */
+    queued: number;
+}
+export declare class WakeChannel {
+    private state;
+    private backoff;
+    private authBackoff;
+    private currentReq?;
+    private shutdownRequested;
+    private readonly opts;
+    private keepaliveTimer?;
+    private lastEventTime;
+    private sleepTimer?;
+    private sleepReject?;
+    private loopPromise?;
+    private loopRunning;
+    private firstAttemptResolver?;
+    private currentReject?;
+    private authFailures;
+    private sseBuffer;
+    private sseQueue;
+    private sseDrainScheduled;
+    private ssePeakChars;
+    private sseFailure?;
+    /**
+     * Admission limits for wake events (audit M-14). Frozen at construction so a
+     * later mutation of `opts` cannot widen them mid-stream.
+     */
+    private readonly wakeLimits;
+    /**
+     * `wake_id` -> first-seen timestamp, insertion-ordered so the oldest entry is
+     * the eviction candidate. Hard-bounded by `wakeLimits.replayCacheEntries`:
+     * when the bound is reached a new id is refused rather than evicting, so a
+     * flood of ids cannot shrink the defence applied to ids already seen.
+     */
+    private readonly seenWakeIds;
+    private wakeDuplicates;
+    private wakeCacheFullDenials;
+    private wakeRefusals;
+    private wakeAccepted;
+    constructor(opts: WakeChannelOptions);
+    /** Start the wake channel. Returns immediately; runs in background. */
+    start(): Promise<void>;
+    /** Graceful shutdown. Waits for current request to abort. */
+    stop(): Promise<void>;
+    /** Current state. */
+    getState(): WakeChannelState;
+    /** Get current backoff reconnect attempts. */
+    getReconnectAttempts(): number;
+    /** Consecutive auth failures observed since the last successful connect. */
+    getAuthFailures(): number;
+    /** Diagnostics: current/peak SSE parser buffer size and pending events. */
+    getSseBufferStats(): SseBufferStats;
+    /** Last SSE stream failure reason, if any. Diagnostics only. */
+    getSseFailureReason(): string | undefined;
+    /**
+     * Wake-event admission counters. `cached` is the current occupancy of the
+     * bounded replay cache and never exceeds the configured bound.
+     */
+    getWakeAdmissionStats(): WakeAdmissionStats;
+    /** Forget every cached `wake_id`. Used when the stream is re-established. */
+    private resetWakeReplayCache;
+    /** Force a reconnect (e.g. after token rotation). Restarts a stopped loop. */
+    reconnect(): Promise<void>;
+    private ensureLoop;
+    /**
+     * Start the liveness checker that tears down a stream the cloud stopped
+     * feeding. Opaque unless the operator disabled it.
+     */
+    private startKeepalive;
+    private stopKeepalive;
+    private abortCurrentRequest;
+    private setState;
+    /**
+     * Report an error even when the state is already `error`, so an escalating
+     * failure (repeated auth rejections, repeated stream violations) stays
+     * visible to the operator instead of going silent on the first message.
+     */
+    private reportError;
+    private sleepNextJittered;
+    private runLoop;
+    private connectOnce;
+    /**
+     * Drop all untrusted partial state. The buffer is never carried into the
+     * next connection: it is entirely cloud-controlled bytes.
+     */
+    private resetSseState;
+    /**
+     * Drop every untrusted partial state on reconnect, INCLUDING the replay cache.
+     *
+     * The cloud is the only producer of a legitimate `wake_id`, so a reconnect can
+     * re-deliver ids the previous connection already consumed (at-least-once SSE);
+     * keeping the cache across reconnects turns that into a denial of service. The
+     * cloud's own expiry on `data_channel_token_expires_at` remains the durable
+     * backstop: a token that was valid before the reconnect has not become valid
+     * again.
+     */
+    private resetStreamState;
+    /**
+     * Feed one decoded chunk into the incremental SSE parser (audit H-09).
+     *
+     * Bounded on every axis: the carry-over buffer, the number of events a
+     * single chunk may enqueue, and (in {@link drainSseQueue}) how many events
+     * run per event-loop turn.
+     */
+    private ingestSseChunk;
+    /** Queue a drain on the next event-loop turn (never inline in `data`). */
+    private scheduleSseDrain;
+    /**
+     * Dispatch queued events, capped per turn and yielding in between so a burst
+     * cannot starve the event loop the rest of the daemon runs on.
+     */
+    private drainSseQueue;
+    /**
+     * Handle one event block. Only a well-formed frame counts as liveness, so a
+     * flood of unparseable bytes cannot keep a dead stream looking healthy.
+     */
+    private dispatchSseBlock;
+    /**
+     * Fail the current stream: discard untrusted state, report, and force a
+     * reconnect through the normal (backed-off) retry path.
+     */
+    private failSseStream;
+    /**
+     * Parse one SSE event block per the SSE grammar. Returns what the block was:
+     * a keepalive comment, a dispatched wake event, a well-formed event that is
+     * not a wake, or a protocol error.
+     */
+    private parseEventBlock;
+    /**
+     * Shape plus freshness plus replay. Returns true only when the event was
+     * dispatched to `onWake`.
+     *
+     * Audit M-14. `data_channel_token_expires_at` used to be type-checked and then
+     * ignored, so a captured SSE event could be replayed indefinitely to re-open a
+     * data channel with a token the relay had already expired. Every check here
+     * denies by default: an event that fails any of them is never dispatched, and
+     * no path re-checks or relaxes them downstream.
+     */
+    private validateAndTriggerWake;
+    /** Record and report a refusal. Always returns false so callers can `return`. */
+    private reject;
+}
+//# sourceMappingURL=wake-channel.d.ts.map

package/dist/esm/channels/wake-channel.d.ts.map

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