agentfootprint 7.24.0 → 7.25.0

package/dist/esm/hosting/webSocketConversation.js

@@ -0,0 +1,341 @@
+/**
+ * hosting/webSocketConversation — one upgraded socket, presented as a
+ * {@link HostConversation}.
+ *
+ * This is the whole adapter side of the conversation port: it takes the
+ * `'upgrade'` event a `node:http` server hands it, answers the handshake, and
+ * turns the frames flowing over the socket into the six-member port a handler
+ * sees. Everything protocol-shaped lives in `webSocketFrames.ts`; everything
+ * port-shaped lives in `types.ts`; this file is the join.
+ *
+ * ── The laws it keeps, all of them pinned by tests ───────────────────────────
+ *  - **A path this door does not own is not touched.** `node:http` calls EVERY
+ *    `'upgrade'` listener for every upgrade, exactly as it calls every
+ *    `'request'` listener — so a caller's own protocol lives beside this one on
+ *    the same socket. Whether an unclaimed path gets an answer is the caller's
+ *    business on a server they own, and this door's only on a server it owns.
+ *  - **Frames that arrive before the handler subscribes are held, up to a
+ *    declared bound.** An `async` handler that awaits before calling `onFrame`
+ *    would otherwise lose the far side's opening frame. The bound is in BYTES
+ *    and overflow ends the conversation with a stated reason, because an
+ *    unbounded queue somebody else fills is a way to kill this process, and an
+ *    undeclared ceiling is the exact thing the declared-ceilings rule exists to
+ *    forbid.
+ *  - **`close()` ends every live conversation before the socket is released.**
+ *    Measured, not assumed: an upgraded socket keeps `server.close()` waiting
+ *    forever, so a door that let go of its conversations would hang the whole
+ *    shutdown.
+ *  - **The port's frame is the whole message.** A message the transport
+ *    delivered in fragments counts against `maxFrameBytes` in total, so
+ *    fragmentation cannot be used to walk around the ceiling.
+ *
+ * Pattern: Adapter. Role: outer ring, one transport.
+ */
+import { ConversationClosedError, FrameTooLargeError } from './errors.js';
+import { lowerCasedHeaders } from './headers.js';
+import { CLOSE_CODE, decodeClose, decodeText, encodeClose, encodeFrame, encodeText, FrameProtocolError, FrameReader, isControlFrame, OPCODE, handshakeResponse, } from './webSocketFrames.js';
+/** How long a politely-closed socket has to say goodbye before it is dropped. */
+const CLOSE_GRACE_MS = 1_000;
+export function conversationDoor(options) {
+    const live = new Set();
+    return {
+        get liveCount() {
+            return live.size;
+        },
+        handleUpgrade(request, socket) {
+            const url = request.url ?? '';
+            if (url.split('?')[0] !== options.path)
+                return false;
+            // From here the upgrade is ours, and every exit answers it.
+            socket.on('error', () => undefined);
+            if (!options.accepting()) {
+                refuse(socket, 503, `the '${options.hostName}' host is closed and is not taking new conversations`);
+                return true;
+            }
+            const headers = lowerCasedHeaders(request.headers);
+            const key = headers['sec-websocket-key'];
+            const upgrade = (headers.upgrade ?? '').toLowerCase();
+            if (upgrade !== 'websocket' || headers['sec-websocket-version'] !== '13' || !key) {
+                refuse(socket, 400, `the '${options.hostName}' host serves version-13 WebSocket conversations on ` +
+                    `${options.path}, and this upgrade did not offer one`);
+                return true;
+            }
+            const facts = {
+                headers,
+                query: new URLSearchParams(url.split('?')[1] ?? ''),
+            };
+            const read = options.readConversation?.(facts) ?? {};
+            socket.write(handshakeResponse(key, read.protocol));
+            const conversation = openConversation(socket, {
+                hostName: options.hostName,
+                limits: options.limits,
+                ...(read.sessionId !== undefined && { sessionId: read.sessionId }),
+                headers: { ...headers, ...read.headers },
+            });
+            live.add(conversation);
+            void conversation.ended.finally(() => live.delete(conversation));
+            // A handler that throws ends THAT conversation and nothing else: one
+            // caller's bad frame is not an outage for everyone else on this door.
+            void (async () => {
+                try {
+                    await options.handler(conversation.port);
+                }
+                catch (err) {
+                    conversation.end(`the conversation handler threw: ${asMessage(err)}`);
+                }
+            })();
+            return true;
+        },
+        async closeAll(reason) {
+            const ending = [...live];
+            for (const conversation of ending)
+                conversation.end(reason);
+            // Waited on, not fired and forgotten: an upgraded socket that is still
+            // open keeps `server.close()` waiting forever, so "the door is closed"
+            // has to mean the sockets are actually gone.
+            await Promise.allSettled(ending.map((conversation) => conversation.ended));
+        },
+    };
+}
+/** Answer an upgrade we will not carry, in the one language a pre-101 socket speaks. */
+function refuse(socket, status, message) {
+    const text = `[hosting] ${message}.`;
+    const reason = status === 503 ? 'Service Unavailable' : 'Bad Request';
+    socket.end(`HTTP/1.1 ${status} ${reason}\r\n` +
+        `content-type: text/plain\r\n` +
+        `content-length: ${Buffer.byteLength(text)}\r\n` +
+        `connection: close\r\n\r\n${text}`);
+}
+/**
+ * One socket, presented as a conversation.
+ *
+ * Written as a closure rather than a class because everything here is one
+ * socket's state and none of it is anybody else's business — there is nothing
+ * to subclass and nothing to inject.
+ */
+function openConversation(socket, options) {
+    const { hostName, limits, sessionId } = options;
+    const maxFrameBytes = limits.maxFrameBytes;
+    const maxPendingBytes = limits.maxPendingBytes;
+    const reader = new FrameReader(maxFrameBytes);
+    const frameSubscribers = new Set();
+    const closeSubscribers = new Set();
+    /** Frames the far side sent before anybody was listening. Bounded (see below). */
+    let pending = [];
+    let pendingBytes = 0;
+    /** The message being assembled out of fragments, if any. */
+    let assembling = [];
+    let assemblingBytes = 0;
+    let assemblingText = false;
+    let ending;
+    let resolveEnded;
+    const ended = new Promise((resolve) => {
+        resolveEnded = resolve;
+    });
+    function finish(close, wireCode, wireReason) {
+        if (ending !== undefined)
+            return;
+        ending = close;
+        if (wireCode !== undefined && socket.writable) {
+            socket.write(encodeClose(wireCode, wireReason ?? close.reason));
+        }
+        // end() flushes what is queued and then sends FIN — the polite half of the
+        // close. The timer is the impolite half, for a peer that never answers.
+        socket.end();
+        const grace = setTimeout(() => socket.destroy(), CLOSE_GRACE_MS);
+        if (typeof grace.unref === 'function')
+            grace.unref();
+        socket.once('close', () => clearTimeout(grace));
+        const subscribers = [...closeSubscribers];
+        closeSubscribers.clear();
+        for (const cb of subscribers) {
+            try {
+                cb(close);
+            }
+            catch {
+                // A close subscriber that throws has nothing left to be told; the
+                // conversation is already over and there is nothing to protect.
+            }
+        }
+        resolveEnded();
+    }
+    function deliver(frame) {
+        if (ending !== undefined)
+            return;
+        if (frameSubscribers.size === 0) {
+            pendingBytes += Buffer.byteLength(frame, 'utf8');
+            if (maxPendingBytes !== undefined && pendingBytes > maxPendingBytes) {
+                pending = [];
+                finish({
+                    by: 'host',
+                    reason: `${pendingBytes} bytes arrived before onFrame(...) was subscribed, past the ` +
+                        `declared maxPendingBytes of ${maxPendingBytes}`,
+                }, CLOSE_CODE.tooBig);
+                return;
+            }
+            pending.push(frame);
+            return;
+        }
+        for (const cb of [...frameSubscribers]) {
+            try {
+                cb(frame);
+            }
+            catch (err) {
+                // Feeding more frames to a consumer whose parser already threw is how a
+                // channel keeps looking healthy while nothing on it is being read.
+                finish({ by: 'host', reason: `a frame subscriber threw: ${asMessage(err)}` });
+                return;
+            }
+        }
+    }
+    function handleFrame(frame) {
+        if (ending !== undefined)
+            return;
+        if (isControlFrame(frame.opcode)) {
+            if (frame.opcode === OPCODE.ping) {
+                // Answered because the protocol says so, and because a peer's liveness
+                // check is not the same thing as this port inventing a heartbeat.
+                if (socket.writable)
+                    socket.write(encodeFrame(OPCODE.pong, frame.payload));
+                return;
+            }
+            if (frame.opcode === OPCODE.pong)
+                return;
+            const said = decodeClose(frame.payload);
+            finish({ by: 'far-side', ...(said.reason !== undefined && { reason: said.reason }) }, said.code === CLOSE_CODE.noStatus ? CLOSE_CODE.normal : said.code, said.reason);
+            return;
+        }
+        if (frame.opcode === OPCODE.binary) {
+            // Refused by name rather than silently stringified: this port carries
+            // text, and binary is a capability nobody has shown evidence for yet.
+            finish({
+                by: 'host',
+                reason: 'a binary frame arrived, and this port carries text frames only — binary is a ' +
+                    'capability that will be minted when a consumer needs it, not guessed at now',
+            }, CLOSE_CODE.unsupportedData);
+            return;
+        }
+        if (frame.opcode === OPCODE.text) {
+            if (assemblingText) {
+                protocolFailure(new FrameProtocolError(CLOSE_CODE.protocolError, 'a new message started before the previous fragmented one finished'));
+                return;
+            }
+            assemblingText = true;
+        }
+        else if (!assemblingText) {
+            protocolFailure(new FrameProtocolError(CLOSE_CODE.protocolError, 'a continuation frame arrived with no message to continue'));
+            return;
+        }
+        assemblingBytes += frame.payload.length;
+        if (maxFrameBytes !== undefined && assemblingBytes > maxFrameBytes) {
+            // The ceiling is on the MESSAGE, so a peer cannot fragment its way past it.
+            protocolFailure(new FrameProtocolError(CLOSE_CODE.tooBig, `a fragmented message reached ${assemblingBytes} bytes, past the declared ` +
+                `maxFrameBytes of ${maxFrameBytes}`));
+            return;
+        }
+        assembling.push(frame.payload);
+        if (!frame.fin)
+            return;
+        const whole = assembling.length === 1 ? assembling[0] : Buffer.concat(assembling);
+        assembling = [];
+        assemblingBytes = 0;
+        assemblingText = false;
+        let text;
+        try {
+            text = decodeText(whole);
+        }
+        catch (err) {
+            protocolFailure(err);
+            return;
+        }
+        deliver(text);
+    }
+    function protocolFailure(err) {
+        const code = err instanceof FrameProtocolError ? err.closeCode : CLOSE_CODE.protocolError;
+        finish({ by: 'far-side', reason: asMessage(err) }, code, asMessage(err));
+    }
+    socket.on('data', (chunk) => {
+        if (ending !== undefined)
+            return;
+        let frames;
+        try {
+            frames = reader.push(chunk);
+        }
+        catch (err) {
+            protocolFailure(err);
+            return;
+        }
+        for (const frame of frames)
+            handleFrame(frame);
+    });
+    socket.on('error', (err) => {
+        finish({ by: 'transport', reason: err.message });
+        socket.destroy();
+    });
+    // BOTH halves, and `'end'` is the one that matters. An upgraded socket is
+    // half-open: when the far side vanishes, node delivers `'end'` and then waits
+    // for THIS side to end too — no `'error'`, and no `'close'` until we act. A
+    // door listening only for `'close'` would never fire onClose for a caller
+    // that walked away, and would hold a socket open that keeps every shutdown
+    // sharing this port waiting. Measured, not assumed.
+    socket.on('end', () => {
+        finish({ by: 'transport', reason: 'the connection ended without a close frame' });
+    });
+    socket.on('close', () => {
+        // No close frame from either side: the connection went away rather than
+        // ended, and those are different facts to whoever is watching.
+        finish({ by: 'transport', reason: 'the connection closed without a close frame' });
+    });
+    const port = {
+        ...(sessionId !== undefined && { sessionId }),
+        headers: options.headers,
+        send(frame) {
+            if (ending !== undefined)
+                throw new ConversationClosedError(hostName, sessionId);
+            const bytes = Buffer.byteLength(frame, 'utf8');
+            if (maxFrameBytes !== undefined && bytes > maxFrameBytes) {
+                throw new FrameTooLargeError(hostName, bytes, maxFrameBytes);
+            }
+            socket.write(encodeText(frame));
+        },
+        onFrame(cb) {
+            frameSubscribers.add(cb);
+            if (pending.length > 0) {
+                const held = pending;
+                pending = [];
+                pendingBytes = 0;
+                for (const frame of held)
+                    cb(frame);
+            }
+            return () => {
+                frameSubscribers.delete(cb);
+            };
+        },
+        onClose(cb) {
+            // Already over? Say so now. A subscriber that arrives late is asking the
+            // same question as one that arrived early, and "never" is a wrong answer.
+            if (ending !== undefined) {
+                cb(ending);
+                return () => undefined;
+            }
+            closeSubscribers.add(cb);
+            return () => {
+                closeSubscribers.delete(cb);
+            };
+        },
+        close(reason) {
+            finish({ by: 'host', ...(reason !== undefined && { reason }) }, CLOSE_CODE.normal, reason);
+        },
+    };
+    return {
+        port,
+        ended,
+        end(reason) {
+            finish({ by: 'host', reason }, CLOSE_CODE.goingAway, reason);
+        },
+    };
+}
+function asMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=webSocketConversation.js.map

package/dist/esm/hosting/webSocketConversation.js.map

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

package/dist/esm/hosting/webSocketFrames.d.ts

@@ -0,0 +1,164 @@
+/**
+ * hosting/webSocketFrames — the frame codec the conversation door speaks, and
+ * nothing else.
+ *
+ * Pure bytes in, pure bytes out: no socket, no session, no handler, no port
+ * vocabulary. That is what makes it testable the only way protocol code is
+ * worth testing — against the byte sequences the specification itself
+ * publishes, rather than against a client we also wrote.
+ *
+ * ── Why this file exists instead of a dependency ─────────────────────────────
+ * The alternative was an optional peer dependency carrying a complete
+ * implementation. It was rejected for a reason that is about honesty rather
+ * than about lines of code: `capabilities` is declared at CONSTRUCTION and is
+ * static thereafter, so a host whose conversation door only works when an
+ * optional package happens to be installed can only either claim
+ * `'conversation'` and then refuse to do it — the library declaring a promise
+ * it cannot keep, which is the one thing the capability union forbids — or
+ * probe `node_modules` and let feature detection depend on install state, so a
+ * deployment that forgot the dependency silently gets a host that quietly does
+ * not do conversations. The shipped adapter honours what it declares, always,
+ * with nothing to install. That was worth these bytes.
+ *
+ * ── What is implemented, exactly ─────────────────────────────────────────────
+ * The server half of RFC 6455 for a text channel: the handshake, text frames,
+ * continuation frames, ping/pong, and close. Payloads are unmasked on the way
+ * in (client frames MUST be masked) and written unmasked on the way out (server
+ * frames MUST NOT be), which is the asymmetry the RFC requires.
+ *
+ * ── What is NOT, and how far the verification goes ───────────────────────────
+ * No extensions and no compression: `permessage-deflate` is negotiated, and
+ * this door never negotiates it, so the RSV bits must always be zero and a peer
+ * that sets one is refused. No binary frames — the port carries text, and
+ * binary is a capability nobody has minted evidence for. No client role.
+ *
+ * Verification is: the byte vectors published in RFC 6455 §5.7, which were
+ * authored by the specification and not by this repository, plus a live
+ * exchange against the platform's own WebSocket client where the runtime has
+ * one, plus the conversation conformance suite over a real socket. It is **not**
+ * run against the Autobahn test suite, and this file does not claim more
+ * coverage than the tests beside it actually execute.
+ *
+ * Pattern: pure codec. Role: innermost ring — imports nothing from this package.
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+/** The frame kinds this door speaks. Numbers, because the wire uses numbers. */
+export declare const OPCODE: {
+    readonly continuation: 0;
+    readonly text: 1;
+    readonly binary: 2;
+    readonly close: 8;
+    readonly ping: 9;
+    readonly pong: 10;
+};
+/**
+ * Close codes this door produces. The RFC's own numbers, named — a bare `1009`
+ * in a branch is a fact nobody can check without opening the specification.
+ */
+export declare const CLOSE_CODE: {
+    /** Ordinary end: the work is done. */
+    readonly normal: 1000;
+    /** The host is shutting down. */
+    readonly goingAway: 1001;
+    /** The peer broke the protocol. */
+    readonly protocolError: 1002;
+    /** Data this endpoint cannot accept — a binary frame, here. */
+    readonly unsupportedData: 1003;
+    /** Reserved: never sent on the wire, used only as "we were not told". */
+    readonly noStatus: 1005;
+    /** Text that is not valid UTF-8. */
+    readonly invalidPayload: 1007;
+    /** Past a declared ceiling. */
+    readonly tooBig: 1009;
+};
+/** One frame, as it came off the wire, already unmasked. */
+export interface WebSocketFrame {
+    /** Last frame of its message? */
+    readonly fin: boolean;
+    /** One of {@link OPCODE}. */
+    readonly opcode: number;
+    /** The unmasked payload. */
+    readonly payload: Buffer;
+}
+/**
+ * A peer that broke the protocol, carrying the close code the RFC names for
+ * that breakage — so the caller does not have to re-derive which number means
+ * what at the point it has to write one.
+ */
+export declare class FrameProtocolError extends Error {
+    readonly closeCode: number;
+    constructor(closeCode: number, message: string);
+}
+/**
+ * The `Sec-WebSocket-Accept` value for a client's `Sec-WebSocket-Key`:
+ * base64(sha1(key + GUID)). Deterministic, and pinned against the RFC's own
+ * worked example.
+ */
+export declare function acceptKey(clientKey: string): string;
+/**
+ * The 101 response, as bytes.
+ *
+ * `protocol` is echoed only when the caller selected one. Echoing a subprotocol
+ * the client did not offer would make the client fail the connection, so
+ * choosing one is the wire's job (it read the offer) and not this function's.
+ */
+export declare function handshakeResponse(clientKey: string, protocol?: string): Buffer;
+/**
+ * One frame, ready to write. **Never masked**: a server that masks its frames
+ * is a server the client closes on, per RFC 6455 §5.1.
+ */
+export declare function encodeFrame(opcode: number, payload: Buffer, fin?: boolean): Buffer;
+/** A text frame carrying one whole message. */
+export declare function encodeText(text: string): Buffer;
+/**
+ * A close frame carrying a code and, when there is one, a reason.
+ *
+ * The reason is truncated to 123 bytes because a control frame's payload may
+ * not exceed 125 and the code takes two of them. Truncating a REASON is safe in
+ * a way truncating a message never is: it is diagnostic prose about an ending
+ * that has already been decided.
+ */
+export declare function encodeClose(code: number, reason?: string): Buffer;
+/** What a close frame said, pulled apart. */
+export interface CloseFramePayload {
+    /** The peer's code, or `noStatus` when it sent none — which is legal. */
+    readonly code: number;
+    /** The peer's words, when it sent any. */
+    readonly reason?: string;
+}
+/** Read a close frame's payload. An empty payload is "no status", never an error. */
+export declare function decodeClose(payload: Buffer): CloseFramePayload;
+/** Is this one of the three control opcodes? */
+export declare function isControlFrame(opcode: number): boolean;
+/**
+ * Turns a stream of TCP chunks into whole frames.
+ *
+ * Stateful by necessity — a frame arrives in as many pieces as the network
+ * feels like, and two frames arrive in one piece just as often. Every branch
+ * that gives up does so by throwing a {@link FrameProtocolError} carrying the
+ * code to close with, so the layer above never has to invent one.
+ */
+export declare class FrameReader {
+    private buffered;
+    private readonly maxFrameBytes;
+    /**
+     * @param maxFrameBytes The declared ceiling, when there is one. Checked
+     * against the length in the HEADER — before the payload is buffered, so an
+     * announced 4GB frame costs nothing to refuse.
+     */
+    constructor(maxFrameBytes?: number);
+    /** Feed one chunk; get back every frame that completed. */
+    push(chunk: Buffer): WebSocketFrame[];
+    /** One frame, or `undefined` when the bytes for a whole one are not here yet. */
+    private readOne;
+}
+/**
+ * Decode a whole message's bytes as UTF-8, refusing anything that is not.
+ *
+ * Strict on purpose (RFC 6455 §8.1): a text frame that is not valid UTF-8 is a
+ * protocol violation, and the lenient alternative silently replaces the bad
+ * bytes with `U+FFFD` — handing the consumer a string the far side never sent
+ * and no way to know it happened.
+ */
+export declare function decodeText(payload: Buffer): string;