@memberjunction/server 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/realtimeProxy/RealtimeRelayTunnel.d.ts

@@ -0,0 +1,171 @@
+import { WebSocket as WsClient } from 'ws';
+import { type IRealtimeRelayPolicy } from '@memberjunction/ai';
+/** The relay's deadlines, pings, buffers and caps. */
+export interface RealtimeRelayLimits {
+    /** How long the browser has to send its first frame after the upgrade, in ms. */
+    FirstFrameTimeoutMs: number;
+    /** How long the upstream has to open, from the header fetch to the end of its handshake, in ms. */
+    UpstreamOpenTimeoutMs: number;
+    /** How often the relay pings each leg, in ms. */
+    PingIntervalMs: number;
+    /**
+     * Pings a leg may leave unanswered in a row. At the next ping a leg that answered none of them is terminated and the
+     * other leg is closed (any pong resets the count).
+     */
+    MaxMissedPongs: number;
+    /** Client frames held while the upstream opens; past this the oldest are dropped. */
+    MaxPendingFrames: number;
+    /** Bytes of client frames held while the upstream opens; past this the oldest are dropped. */
+    MaxPendingBytes: number;
+    /**
+     * Bytes the browser leg may have queued after a downstream send. Past this the browser cannot keep up: the tunnel
+     * closes (1013 to the browser, 1001 upstream) and the client resumes on a new connection.
+     */
+    MaxBrowserBufferedBytes: number;
+    /**
+     * Bytes the upstream leg may have queued after an upstream send. Past this the provider has stopped reading: the
+     * tunnel closes (1013 to the browser, 1001 upstream) and the client resumes on a new connection.
+     */
+    MaxUpstreamBufferedBytes: number;
+}
+/** The limits MJAPI runs the relay with. */
+export declare const REALTIME_RELAY_LIMITS: Readonly<RealtimeRelayLimits>;
+/**
+ * The largest client message the relay accepts (2 MiB). The relay's websocket server enforces it while reading, so a
+ * larger message closes the browser leg with 1009 before it is buffered.
+ */
+export declare const REALTIME_RELAY_MAX_CLIENT_FRAME_BYTES: number;
+/** How a relay tunnel reports to the server that owns it. */
+export interface RealtimeRelayTunnelHost {
+    /** The session granted this connection: the server makes it the session's live one and closes the older one. */
+    OnGranted(tunnel: RealtimeRelayTunnel): void;
+    /** The tunnel closed; called once. */
+    OnClosed(tunnel: RealtimeRelayTunnel): void;
+}
+/** The first 8 characters of a ticket id, safe to log (never the whole id). */
+export declare function RelayTicketPrefix(id: string): string;
+/**
+ * One browser connection through MJAPI's realtime relay (`/realtime/relay/<ticket>/…`).
+ *
+ * It waits for the browser's first frame, asks the session's policy what that frame opens, and lets the registry
+ * decide (one fresh connection, then resumes with a forwarded handle). Then it opens the upstream with headers the
+ * policy mints for this connection, sends the policy's opening frames before anything else, and pumps both ways: client
+ * frames through the policy's filter (text only; binary client frames are dropped), server frames unchanged once the
+ * policy has looked for a resumption handle. It pings both legs and terminates one that stops answering, closes a
+ * browser that cannot keep up with what it is sent and an upstream that stops reading, passes close codes through, and closes when the session ends. Logs
+ * carry counts, sizes, codes and an 8-character ticket prefix, never payloads, headers or tokens.
+ */
+export declare class RealtimeRelayTunnel {
+    private readonly browser;
+    private readonly sessionId;
+    private readonly policy;
+    private readonly limits;
+    private readonly host;
+    private upstream;
+    private grant;
+    private intent;
+    /** Client frames that passed the filter before the upstream opened, in arrival order. */
+    private readonly pending;
+    private pendingBytes;
+    /** Dropped client frames per type label. */
+    private readonly drops;
+    private readonly traffic;
+    /** Pings each leg has left unanswered since its last pong. */
+    private readonly unanswered;
+    private firstFrameTimer;
+    private upstreamTimer;
+    private lifetimeTimer;
+    private pingTimer;
+    private openedAtMs;
+    private browserCloseCode;
+    private upstreamCloseNote;
+    private closed;
+    constructor(browser: WsClient, sessionId: string, policy: IRealtimeRelayPolicy, limits: RealtimeRelayLimits, host: RealtimeRelayTunnelHost);
+    /** The relay session this connection belongs to. */
+    get SessionID(): string;
+    /** Starts the first-frame deadline and the pings, and listens to the browser leg. */
+    Start(): void;
+    /** Closes both legs with `code` and `reason` (no code: a close frame without one). Idempotent. */
+    Close(code?: number, reason?: string): void;
+    private onBrowserMessage;
+    /** Reads the first frame's intent, asks the registry, and opens the upstream when the connection is granted. */
+    private openFromFirstFrame;
+    /** The policy's reading of the first frame; a policy that throws opens nothing (only the error's name is logged). */
+    private readIntent;
+    /** Opens the upstream with headers the policy mints now, under the upstream deadline. */
+    private openUpstream;
+    /** Asks the policy for this connection's upstream headers; a failure closes the tunnel with 1011. */
+    private fetchHeaders;
+    /** Starts the upstream handshake; a refused URL closes the tunnel with 1014. */
+    private connectUpstream;
+    /** The upstream is open: the policy's opening frames go first, then what the browser sent meanwhile. */
+    private onUpstreamOpen;
+    /** The policy's opening frames; a policy that throws closes the tunnel with 1011. */
+    private openingFrames;
+    /** A client frame after the first: binary is dropped, text goes through the policy's filter. */
+    private fromBrowser;
+    /** The policy's verdict on a client frame; a policy that throws drops the frame. */
+    private filter;
+    /**
+     * Holds a frame until the upstream opens; past either cap (frames or bytes) the oldest go (stale audio is worthless
+     * anyway). A frame larger than the byte cap on its own is dropped.
+     */
+    private hold;
+    /**
+     * A server frame: a handle it carries is recorded before the frame goes to the browser, unchanged; then the browser
+     * leg's queue is checked against the cap.
+     */
+    private onUpstreamMessage;
+    /**
+     * A browser that cannot keep up (its queued bytes pass `MaxBrowserBufferedBytes` after a downstream send) is closed
+     * with 1013 and the upstream with 1001; the client resumes on a new connection.
+     */
+    private closeIfBrowserBehind;
+    /** The resumption handle the policy finds in a server frame, if any; a policy that throws finds none. */
+    private observe;
+    /** Sends one text frame upstream and counts it; then the upstream leg's queue is checked against the cap. */
+    private sendUp;
+    /**
+     * An upstream that has stopped reading (its queued bytes pass `MaxUpstreamBufferedBytes` after an upstream send) is
+     * closed with 1001 and the browser with 1013, before the ping watchdog would notice; the client resumes on a new
+     * connection.
+     */
+    private closeIfUpstreamBehind;
+    /** Sends on a leg that is open, keeping text as text and binary as binary; a failed send closes the tunnel. */
+    private send;
+    /**
+     * Pings each open leg, so idle timeouts on load balancers and ingresses do not close it. A leg that answered none of
+     * its last `MaxMissedPongs` pings is gone: it is terminated and the other leg closed.
+     */
+    private pingBoth;
+    /** A leg stopped answering pings: it is terminated, and the other leg closes (1001 upstream, 1014 to the browser). */
+    private closeSilentLeg;
+    /** The upstream closed: the browser gets the same code and reason (1014 when the upstream sent none). */
+    private onUpstreamClose;
+    /** The browser closed: the upstream gets the same code and reason (1001 when the browser sent none). */
+    private onBrowserClose;
+    /** The upstream failed (a refused handshake, a dropped socket): the browser gets 1014. */
+    private onUpstreamError;
+    /** The browser leg failed; `ws` has already closed it with the right code (1009 for an oversized frame). */
+    private onBrowserError;
+    /**
+     * Closes both legs (the upstream with the browser's close unless it gets its own), stops the timers and reports to
+     * the server. Idempotent.
+     */
+    private closeWith;
+    /** Closes one leg unless it is already closing; `Terminate`, or a handshake in progress, drops the socket. */
+    private static closeLeg;
+    private static terminate;
+    /** Refuses the connection with 1008; the reason is logged, the browser only learns it was refused. */
+    private refuse;
+    private static after;
+    private static cancel;
+    private stopTimers;
+    /** Counts a dropped client frame under a sanitized label (the label is the policy's, never the payload). */
+    private countDrop;
+    private get label();
+    private warn;
+    private logOpened;
+    private logClosed;
+}
+//# sourceMappingURL=RealtimeRelayTunnel.d.ts.map

package/dist/realtimeProxy/RealtimeRelayTunnel.d.ts.map

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