agentfootprint 7.24.0 → 7.25.0

package/dist/hosting/webSocketConversation.js

@@ -0,0 +1,345 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conversationDoor = void 0;
+const errors_js_1 = require("./errors.js");
+const headers_js_1 = require("./headers.js");
+const webSocketFrames_js_1 = require("./webSocketFrames.js");
+/** How long a politely-closed socket has to say goodbye before it is dropped. */
+const CLOSE_GRACE_MS = 1_000;
+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 = (0, headers_js_1.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((0, webSocketFrames_js_1.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));
+        },
+    };
+}
+exports.conversationDoor = conversationDoor;
+/** 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 webSocketFrames_js_1.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((0, webSocketFrames_js_1.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}`,
+                }, webSocketFrames_js_1.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 ((0, webSocketFrames_js_1.isControlFrame)(frame.opcode)) {
+            if (frame.opcode === webSocketFrames_js_1.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((0, webSocketFrames_js_1.encodeFrame)(webSocketFrames_js_1.OPCODE.pong, frame.payload));
+                return;
+            }
+            if (frame.opcode === webSocketFrames_js_1.OPCODE.pong)
+                return;
+            const said = (0, webSocketFrames_js_1.decodeClose)(frame.payload);
+            finish({ by: 'far-side', ...(said.reason !== undefined && { reason: said.reason }) }, said.code === webSocketFrames_js_1.CLOSE_CODE.noStatus ? webSocketFrames_js_1.CLOSE_CODE.normal : said.code, said.reason);
+            return;
+        }
+        if (frame.opcode === webSocketFrames_js_1.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',
+            }, webSocketFrames_js_1.CLOSE_CODE.unsupportedData);
+            return;
+        }
+        if (frame.opcode === webSocketFrames_js_1.OPCODE.text) {
+            if (assemblingText) {
+                protocolFailure(new webSocketFrames_js_1.FrameProtocolError(webSocketFrames_js_1.CLOSE_CODE.protocolError, 'a new message started before the previous fragmented one finished'));
+                return;
+            }
+            assemblingText = true;
+        }
+        else if (!assemblingText) {
+            protocolFailure(new webSocketFrames_js_1.FrameProtocolError(webSocketFrames_js_1.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 webSocketFrames_js_1.FrameProtocolError(webSocketFrames_js_1.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 = (0, webSocketFrames_js_1.decodeText)(whole);
+        }
+        catch (err) {
+            protocolFailure(err);
+            return;
+        }
+        deliver(text);
+    }
+    function protocolFailure(err) {
+        const code = err instanceof webSocketFrames_js_1.FrameProtocolError ? err.closeCode : webSocketFrames_js_1.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 errors_js_1.ConversationClosedError(hostName, sessionId);
+            const bytes = Buffer.byteLength(frame, 'utf8');
+            if (maxFrameBytes !== undefined && bytes > maxFrameBytes) {
+                throw new errors_js_1.FrameTooLargeError(hostName, bytes, maxFrameBytes);
+            }
+            socket.write((0, webSocketFrames_js_1.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 }) }, webSocketFrames_js_1.CLOSE_CODE.normal, reason);
+        },
+    };
+    return {
+        port,
+        ended,
+        end(reason) {
+            finish({ by: 'host', reason }, webSocketFrames_js_1.CLOSE_CODE.goingAway, reason);
+        },
+    };
+}
+function asMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=webSocketConversation.js.map

package/dist/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/hosting/webSocketFrames.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeText = exports.FrameReader = exports.isControlFrame = exports.decodeClose = exports.encodeClose = exports.encodeText = exports.encodeFrame = exports.handshakeResponse = exports.acceptKey = exports.FrameProtocolError = exports.CLOSE_CODE = exports.OPCODE = void 0;
+const node_crypto_1 = require("node:crypto");
+/** The frame kinds this door speaks. Numbers, because the wire uses numbers. */
+exports.OPCODE = {
+    continuation: 0x0,
+    text: 0x1,
+    binary: 0x2,
+    close: 0x8,
+    ping: 0x9,
+    pong: 0xa,
+};
+/**
+ * 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.
+ */
+exports.CLOSE_CODE = {
+    /** Ordinary end: the work is done. */
+    normal: 1000,
+    /** The host is shutting down. */
+    goingAway: 1001,
+    /** The peer broke the protocol. */
+    protocolError: 1002,
+    /** Data this endpoint cannot accept — a binary frame, here. */
+    unsupportedData: 1003,
+    /** Reserved: never sent on the wire, used only as "we were not told". */
+    noStatus: 1005,
+    /** Text that is not valid UTF-8. */
+    invalidPayload: 1007,
+    /** Past a declared ceiling. */
+    tooBig: 1009,
+};
+/**
+ * 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.
+ */
+class FrameProtocolError extends Error {
+    closeCode;
+    constructor(closeCode, message) {
+        super(message);
+        this.name = 'FrameProtocolError';
+        this.closeCode = closeCode;
+    }
+}
+exports.FrameProtocolError = FrameProtocolError;
+/** The magic string RFC 6455 §1.3 appends before hashing. Not ours to change. */
+const HANDSHAKE_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+/**
+ * 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.
+ */
+function acceptKey(clientKey) {
+    return (0, node_crypto_1.createHash)('sha1')
+        .update(clientKey + HANDSHAKE_GUID)
+        .digest('base64');
+}
+exports.acceptKey = acceptKey;
+/**
+ * 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.
+ */
+function handshakeResponse(clientKey, protocol) {
+    const lines = [
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${acceptKey(clientKey)}`,
+    ];
+    if (protocol !== undefined && protocol.length > 0) {
+        lines.push(`Sec-WebSocket-Protocol: ${protocol}`);
+    }
+    return Buffer.from(`${lines.join('\r\n')}\r\n\r\n`, 'utf8');
+}
+exports.handshakeResponse = handshakeResponse;
+/**
+ * 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.
+ */
+function encodeFrame(opcode, payload, fin = true) {
+    const length = payload.length;
+    let header;
+    if (length < 126) {
+        header = Buffer.alloc(2);
+        header[1] = length;
+    }
+    else if (length < 0x10000) {
+        header = Buffer.alloc(4);
+        header[1] = 126;
+        header.writeUInt16BE(length, 2);
+    }
+    else {
+        header = Buffer.alloc(10);
+        header[1] = 127;
+        // Two 32-bit halves rather than a BigInt write: the high half is always
+        // zero for anything this door will ever send, and saying so in bytes is
+        // clearer than converting through a type nothing else here uses.
+        header.writeUInt32BE(0, 2);
+        header.writeUInt32BE(length, 6);
+    }
+    header[0] = (fin ? 0x80 : 0x00) | opcode;
+    return Buffer.concat([header, payload]);
+}
+exports.encodeFrame = encodeFrame;
+/** A text frame carrying one whole message. */
+function encodeText(text) {
+    return encodeFrame(exports.OPCODE.text, Buffer.from(text, 'utf8'));
+}
+exports.encodeText = encodeText;
+/**
+ * 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.
+ */
+function encodeClose(code, reason) {
+    const text = reason === undefined ? Buffer.alloc(0) : Buffer.from(reason, 'utf8');
+    const trimmed = text.length > 123 ? text.subarray(0, 123) : text;
+    const payload = Buffer.alloc(2 + trimmed.length);
+    payload.writeUInt16BE(code, 0);
+    trimmed.copy(payload, 2);
+    return encodeFrame(exports.OPCODE.close, payload);
+}
+exports.encodeClose = encodeClose;
+/** Read a close frame's payload. An empty payload is "no status", never an error. */
+function decodeClose(payload) {
+    if (payload.length < 2)
+        return { code: exports.CLOSE_CODE.noStatus };
+    const code = payload.readUInt16BE(0);
+    const reason = payload.length > 2 ? payload.subarray(2).toString('utf8') : undefined;
+    return { code, ...(reason !== undefined && reason.length > 0 && { reason }) };
+}
+exports.decodeClose = decodeClose;
+/** Is this one of the three control opcodes? */
+function isControlFrame(opcode) {
+    return (opcode & 0x8) !== 0;
+}
+exports.isControlFrame = isControlFrame;
+/**
+ * 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.
+ */
+class FrameReader {
+    buffered = Buffer.alloc(0);
+    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) {
+        this.maxFrameBytes = maxFrameBytes;
+    }
+    /** Feed one chunk; get back every frame that completed. */
+    push(chunk) {
+        this.buffered = this.buffered.length === 0 ? chunk : Buffer.concat([this.buffered, chunk]);
+        const frames = [];
+        for (;;) {
+            const frame = this.readOne();
+            if (frame === undefined)
+                return frames;
+            frames.push(frame);
+        }
+    }
+    /** One frame, or `undefined` when the bytes for a whole one are not here yet. */
+    readOne() {
+        const buffer = this.buffered;
+        if (buffer.length < 2)
+            return undefined;
+        const first = buffer[0];
+        const second = buffer[1];
+        const fin = (first & 0x80) !== 0;
+        const reserved = first & 0x70;
+        const opcode = first & 0x0f;
+        const masked = (second & 0x80) !== 0;
+        let length = second & 0x7f;
+        let offset = 2;
+        if (reserved !== 0) {
+            // RSV bits mean an extension, and this door negotiates none — so a peer
+            // that set one is describing a frame we would have to guess at.
+            throw new FrameProtocolError(exports.CLOSE_CODE.protocolError, 'a reserved bit is set, and this door negotiated no extension that would define it');
+        }
+        if (!masked) {
+            // RFC 6455 §5.1: every client frame is masked, and a server that accepts
+            // an unmasked one is a server that can be fed frames by a naive proxy.
+            throw new FrameProtocolError(exports.CLOSE_CODE.protocolError, 'a client frame arrived unmasked, which the protocol does not allow');
+        }
+        if (isControlFrame(opcode) && (length > 125 || !fin)) {
+            throw new FrameProtocolError(exports.CLOSE_CODE.protocolError, 'a control frame was fragmented or longer than 125 bytes');
+        }
+        if (length === 126) {
+            if (buffer.length < offset + 2)
+                return undefined;
+            length = buffer.readUInt16BE(offset);
+            offset += 2;
+        }
+        else if (length === 127) {
+            if (buffer.length < offset + 8)
+                return undefined;
+            const high = buffer.readUInt32BE(offset);
+            const low = buffer.readUInt32BE(offset + 4);
+            if (high !== 0) {
+                throw new FrameProtocolError(exports.CLOSE_CODE.tooBig, 'a frame announced a length above 4 GiB, which no ceiling here permits');
+            }
+            length = low;
+            offset += 8;
+        }
+        if (this.maxFrameBytes !== undefined && length > this.maxFrameBytes) {
+            // Refused on the ANNOUNCED length, before a byte of payload is kept: a
+            // ceiling that only notices after buffering is not a ceiling.
+            throw new FrameProtocolError(exports.CLOSE_CODE.tooBig, `a frame announced ${length} bytes, past the declared maxFrameBytes of ${this.maxFrameBytes}`);
+        }
+        const maskOffset = offset;
+        offset += 4;
+        if (buffer.length < offset + length)
+            return undefined;
+        const payload = Buffer.allocUnsafe(length);
+        buffer.copy(payload, 0, offset, offset + length);
+        for (let i = 0; i < length; i++)
+            payload[i] ^= buffer[maskOffset + (i & 3)];
+        this.buffered = buffer.subarray(offset + length);
+        return { fin, opcode, payload };
+    }
+}
+exports.FrameReader = FrameReader;
+/**
+ * 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.
+ */
+function decodeText(payload) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(payload);
+    }
+    catch {
+        throw new FrameProtocolError(exports.CLOSE_CODE.invalidPayload, 'a text frame carried bytes that are not valid UTF-8');
+    }
+}
+exports.decodeText = decodeText;
+//# sourceMappingURL=webSocketFrames.js.map