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

package/dist/cjs/channels/data-channel.d.ts

@@ -0,0 +1,181 @@
+import { AgentMessage } from '../protocol/envelope';
+import { DataChannelState, DataChannelCloseReason, MessageHandler } from './types';
+/**
+ * Inbound frame ceiling enforced by the transport, in bytes.
+ *
+ * `ws` checks this against the *decompressed* message length as well as the
+ * frame length, so a compressed payload cannot inflate past it.
+ */
+export declare const MAX_INBOUND_FRAME_BYTES: 16777216;
+/** RFC 6455 close code for a message that exceeded the negotiated limit. */
+export declare const CLOSE_MESSAGE_TOO_BIG = 1009;
+/**
+ * Safety margin applied to `data_channel_token_expires_at` before connecting.
+ *
+ * The token is spent on a TLS handshake plus a round trip; refusing slightly
+ * early is cheaper than a data channel that 401s mid-session.
+ */
+export declare const TOKEN_EXPIRY_SAFETY_MARGIN_MS = 5000;
+/**
+ * Watermark above which the socket is considered back-pressured, in bytes.
+ *
+ * At or below this the relay is keeping up and the producer may keep sending.
+ * Above it the producer waits instead of pushing more bytes into a buffer that
+ * is already draining slower than it is fed.
+ */
+export declare const SEND_BUFFER_HIGH_WATER_MARK_BYTES: number;
+/**
+ * Hard ceiling on unsent bytes, in bytes.
+ *
+ * Above the watermark a send is deferred, never rejected — but a producer that
+ * never gets a drain signal (a relay that has stopped reading) must not be able
+ * to grow the daemon's heap without limit. Past this the send fails closed with
+ * a `payload_invalid` ProtocolError, which the caller's error path reports
+ * terminally instead of silently truncating a stream.
+ */
+export declare const SEND_BUFFER_HARD_CAP_BYTES: 16777216;
+/** Current send-buffer occupancy. Diagnostics only. */
+export interface DataChannelSendStats {
+    /** Bytes the socket has accepted but not yet written. */
+    buffered: number;
+    /** Bytes handed to `ws.send` whose callback has not fired yet. */
+    pending: number;
+    /** Watermark at or below which the producer is unblocked. */
+    high_water_mark: number;
+    /** Ceiling past which a send is refused. */
+    hard_cap: number;
+}
+export interface DataChannelOptions {
+    /** Cloud URL, e.g. "wss://api.schemaweaver.dev". Plaintext schemes are refused. */
+    cloudUrl: string;
+    /** Short-lived data channel token from wake event. */
+    dataChannelToken: string;
+    /**
+     * Epoch ms at which `dataChannelToken` expires (from the wake event).
+     *
+     * Required: the client is the only party that can check it before the
+     * handshake, so an absent value is treated as a malformed credential.
+     */
+    dataChannelTokenExpiresAt: number;
+    /** Agent ID for routing. */
+    agentId: string;
+    /** Browser session ID this channel serves. */
+    browserSessionId: string;
+    /** Incoming message handler. */
+    onMessage: MessageHandler;
+    /** Called when channel state changes. */
+    onStateChange?: (state: DataChannelState, reason?: DataChannelCloseReason, error?: string) => void;
+    /** Idle timeout in ms. Default 60_000. Set to 0 to disable. */
+    idleTimeoutMs?: number;
+    /** Optional: abort signal. */
+    abortSignal?: AbortSignal;
+    /**
+     * Allow a cleartext `ws:`/`http:` target. Only wire this to an explicit,
+     * non-persisted operator flag (`--insecure-transport`).
+     */
+    allowInsecureTransport?: boolean;
+}
+export declare class DataChannel {
+    private state;
+    private ws?;
+    private idleTimer?;
+    private closeReason?;
+    private transportError?;
+    private readonly opts;
+    /** Bytes handed to `ws.send` whose completion callback has not fired yet. */
+    private pendingSendBytes;
+    /** Producers blocked in {@link DataChannel.waitForDrain}. */
+    private readonly drainWaiters;
+    private drainPollTimer?;
+    /**
+     * Safety net for a close that the peer never answers. Held so it can be
+     * cancelled the moment the close settles: a timer left armed here outlives
+     * the close it belongs to and would tear down the *next* connection opened on
+     * this instance (token rotation reconnects on the same object), and it also
+     * holds the process open for its whole backoff window.
+     */
+    private closeSafetyTimer?;
+    constructor(opts: DataChannelOptions);
+    /** Open the WSS connection. Resolves when handshake completes. */
+    connect(): Promise<void>;
+    /**
+     * Refuse to authenticate with an unusable data channel token (audit H-12).
+     *
+     * Runs before the handshake so an expired token is never presented, and
+     * reports through onStateChange so the operator sees why the channel refused.
+     */
+    private assertTokenUsable;
+    /**
+     * Send a message, applying backpressure instead of rejecting a busy socket.
+     *
+     * Above {@link SEND_BUFFER_HIGH_WATER_MARK_BYTES} the send waits for the
+     * socket to drain. It used to throw `payload_invalid` here, which aborted the
+     * producer mid-stream and left the browser waiting for a `stream_end` that
+     * never came (audit H-10). A slow relay is a condition to wait out, not an
+     * error. Past {@link SEND_BUFFER_HARD_CAP_BYTES} the wait has demonstrably not
+     * been satisfied and the send fails closed so unbounded growth stays impossible.
+     *
+     * Concurrent callers are serialised through the gate: the drain condition is
+     * re-tested after every wait, and the check and the hand-off to `ws.send` sit
+     * in one synchronous step. Without that, N producers resuming from the same
+     * microtask batch would all observe an empty buffer and push N messages into
+     * the socket anyway — the gate would throttle nothing.
+     *
+     * Throws `channel_closed` if the channel is not open, or if it closes while
+     * this call is waiting to drain.
+     */
+    send(msg: AgentMessage): Promise<void>;
+    /**
+     * Resolve once the socket has caught up: `bufferedAmount` is at or below
+     * {@link SEND_BUFFER_HIGH_WATER_MARK_BYTES} and no earlier send is still in
+     * flight. Returns immediately when that is already true, and also when the
+     * channel is not open — a socket that will never drain again must not strand a
+     * producer, and the caller still observes the closed channel on its next send.
+     *
+     * This is the hook to hand to a cursor fetch loop so the producer stops asking
+     * PostgreSQL for more rows while the relay is behind:
+     *
+     * ```ts
+     * await queryRunner.runStreaming(payload, { waitForDrain: () => channel.waitForDrain(), ... });
+     * ```
+     *
+     * Every waiter is released when the channel leaves `open`, so a stalled relay
+     * is bounded by the idle timeout rather than by this promise.
+     */
+    waitForDrain(): Promise<void>;
+    /** Current send-buffer occupancy against the watermark and hard cap. */
+    getSendBufferStats(): DataChannelSendStats;
+    private bufferedBytes;
+    /**
+     * True while the socket is behind. `pendingSendBytes` is included because a
+     * `ws.send` callback has not yet fired for it, so the bytes are still in
+     * flight and the producer should not run ahead of them.
+     */
+    private drainPending;
+    /** True when queueing `incomingBytes` more would reach the cap `send` refuses at. */
+    private sendBufferExceeded;
+    /**
+     * Release every blocked producer, then stop polling. A single shared interval
+     * serves all waiters so N blocked producers cost one timer, not N.
+     */
+    private notifyDrainWaiters;
+    private startDrainPoll;
+    private stopDrainPoll;
+    /**
+     * Release every blocked producer unconditionally: the channel is leaving
+     * `open`, so no amount of draining can satisfy them.
+     */
+    private releaseDrainWaiters;
+    /** Graceful close. */
+    close(reason?: DataChannelCloseReason): Promise<void>;
+    /** Cancel the pending close safety net, if any. */
+    private cancelCloseSafety;
+    /** Force close (e.g. on fatal error). */
+    forceClose(reason: DataChannelCloseReason, error?: string): void;
+    /** Current state. */
+    getState(): DataChannelState;
+    /** Reset idle timer (called when activity occurs). */
+    private pingActivity;
+    private setState;
+}
+//# sourceMappingURL=data-channel.d.ts.map

package/dist/cjs/channels/data-channel.d.ts.map

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