@floegence/flowersec-core 0.1.1

package/dist/ws-client/binaryTransport.js

@@ -0,0 +1,301 @@
+import { normalizeObserver } from "../observability/observer.js";
+import { AbortError, TimeoutError, throwIfAborted } from "../utils/errors.js";
+export class WsCloseError extends Error {
+    code;
+    reason;
+    constructor(code, reason) {
+        const extra = code !== undefined && reason !== undefined && reason !== ""
+            ? ` (code=${code} reason=${reason})`
+            : code !== undefined
+                ? ` (code=${code})`
+                : reason !== undefined && reason !== ""
+                    ? ` (reason=${reason})`
+                    : "";
+        super(`websocket closed${extra}`);
+        this.name = "WsCloseError";
+        this.code = code;
+        this.reason = reason;
+    }
+}
+// WebSocketBinaryTransport adapts WebSocket messages to binary reads/writes.
+export class WebSocketBinaryTransport {
+    // Underlying WebSocket instance (browser or polyfill).
+    ws;
+    // Observer for websocket-level errors.
+    observer;
+    // Buffered inbound frames when no reader is waiting.
+    queue = [];
+    // Read cursor for queue to avoid Array.shift() O(n).
+    queueHead = 0;
+    // Current buffered byte count for backpressure.
+    queueBytes = 0;
+    // Maximum buffered bytes before closing the socket.
+    maxQueuedBytes;
+    // Pending readers waiting for the next frame.
+    waiters = [];
+    // Read cursor for waiters to avoid Array.shift() O(n).
+    waitersHead = 0;
+    // Tracks how many waiters have settled (timeout/abort) without being compacted away yet.
+    waitersSettled = 0;
+    // Serialize message handling to preserve arrival order across async Blob decoding.
+    messageChain = Promise.resolve();
+    // Sticky error state to fail all future reads/writes.
+    error = null;
+    // Tracks whether the close is initiated locally to avoid double-reporting.
+    localCloseRequested = false;
+    constructor(ws, opts = {}) {
+        this.ws = ws;
+        this.observer = normalizeObserver(opts.observer);
+        this.maxQueuedBytes = Math.max(0, opts.maxQueuedBytes ?? 4 * (1 << 20));
+        this.ws.binaryType = "arraybuffer";
+        this.ws.addEventListener("message", this.onMessage);
+        this.ws.addEventListener("error", this.onError);
+        this.ws.addEventListener("close", this.onClose);
+    }
+    // readBinary resolves with the next queued binary message.
+    readBinary(opts = {}) {
+        if (opts.signal?.aborted)
+            return Promise.reject(new AbortError("read aborted"));
+        if (this.error != null)
+            return Promise.reject(this.error);
+        const b = this.shiftQueue();
+        if (b != null) {
+            this.queueBytes -= b.length;
+            return Promise.resolve(b);
+        }
+        return new Promise((resolve, reject) => {
+            if (opts.signal?.aborted) {
+                reject(new AbortError("read aborted"));
+                return;
+            }
+            if (this.error != null) {
+                reject(this.error);
+                return;
+            }
+            const waiter = {
+                resolve,
+                reject,
+                settled: false,
+                cleanup: () => { }
+            };
+            let timeout;
+            const onAbort = () => {
+                if (waiter.settled)
+                    return;
+                waiter.settled = true;
+                waiter.cleanup();
+                this.waitersSettled++;
+                this.compactWaitersMaybe();
+                reject(new AbortError("read aborted"));
+            };
+            const cleanup = () => {
+                if (timeout != null)
+                    clearTimeout(timeout);
+                timeout = undefined;
+                opts.signal?.removeEventListener("abort", onAbort);
+            };
+            waiter.cleanup = cleanup;
+            opts.signal?.addEventListener("abort", onAbort);
+            const timeoutMs = Math.max(0, opts.timeoutMs ?? 0);
+            if (timeoutMs > 0) {
+                timeout = setTimeout(() => {
+                    if (waiter.settled)
+                        return;
+                    waiter.settled = true;
+                    cleanup();
+                    this.waitersSettled++;
+                    this.compactWaitersMaybe();
+                    reject(new TimeoutError("read timeout"));
+                }, timeoutMs);
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    // writeBinary sends a binary frame over the websocket.
+    async writeBinary(frame, opts = {}) {
+        throwIfAborted(opts.signal, "write aborted");
+        if (this.error != null)
+            throw this.error;
+        this.ws.send(frame);
+    }
+    // close tears down listeners and rejects pending readers.
+    close() {
+        if (!this.localCloseRequested) {
+            this.localCloseRequested = true;
+            if (this.error == null)
+                this.observer.onWsClose("local");
+        }
+        this.fail(new Error("websocket closed"));
+        this.ws.removeEventListener("message", this.onMessage);
+        this.ws.removeEventListener("error", this.onError);
+        this.ws.removeEventListener("close", this.onClose);
+        this.queue.length = 0;
+        this.queueHead = 0;
+        this.queueBytes = 0;
+        this.ws.close();
+    }
+    // handleMessage normalizes browser message payloads into Uint8Array.
+    async handleMessage(data) {
+        if (this.error != null)
+            return;
+        if (typeof data === "string") {
+            this.fail(new Error("unexpected text frame"), "unexpected_text_frame");
+            return;
+        }
+        if (data instanceof Uint8Array) {
+            this.push(data);
+            return;
+        }
+        if (data instanceof ArrayBuffer) {
+            if (this.maxQueuedBytes > 0 && this.queueBytes + data.byteLength > this.maxQueuedBytes) {
+                this.fail(new Error("ws recv buffer exceeded"), "recv_buffer_exceeded");
+                this.localCloseRequested = true;
+                this.observer.onWsClose("local");
+                this.ws.close();
+                return;
+            }
+            this.push(new Uint8Array(data));
+            return;
+        }
+        if (ArrayBuffer.isView(data)) {
+            const view = data;
+            if (this.maxQueuedBytes > 0 && this.queueBytes + view.byteLength > this.maxQueuedBytes) {
+                this.fail(new Error("ws recv buffer exceeded"), "recv_buffer_exceeded");
+                this.localCloseRequested = true;
+                this.observer.onWsClose("local");
+                this.ws.close();
+                return;
+            }
+            this.push(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+            return;
+        }
+        if (typeof Blob !== "undefined" && data instanceof Blob) {
+            if (this.maxQueuedBytes > 0 && this.queueBytes + data.size > this.maxQueuedBytes) {
+                this.fail(new Error("ws recv buffer exceeded"), "recv_buffer_exceeded");
+                this.localCloseRequested = true;
+                this.observer.onWsClose("local");
+                this.ws.close();
+                return;
+            }
+            const ab = await data.arrayBuffer();
+            if (this.error != null)
+                return;
+            this.push(new Uint8Array(ab));
+            return;
+        }
+        this.fail(new Error("unexpected message type"), "unexpected_message_type");
+    }
+    onMessage = (ev) => {
+        const data = ev.data;
+        this.messageChain = this.messageChain.then(() => this.handleMessage(data)).catch((err) => {
+            const e = err instanceof Error ? err : new Error(String(err));
+            this.fail(e, "error");
+        });
+    };
+    onError = () => {
+        this.fail(new Error("websocket error"), "error");
+    };
+    onClose = (ev) => {
+        if (!this.localCloseRequested) {
+            const code = typeof ev?.code === "number" ? ev.code : undefined;
+            const reason = typeof ev?.reason === "string" ? ev.reason : undefined;
+            this.observer.onWsClose("peer_or_error", code);
+            this.fail(new WsCloseError(code, reason));
+            return;
+        }
+        this.fail(new Error("websocket closed"));
+    };
+    // push enqueues a frame or delivers it to a waiting reader.
+    push(b) {
+        const w = this.shiftWaiter();
+        if (w != null) {
+            if (!w.settled) {
+                w.settled = true;
+                w.cleanup();
+            }
+            w.resolve(b);
+            return;
+        }
+        if (this.maxQueuedBytes > 0 && this.queueBytes + b.length > this.maxQueuedBytes) {
+            this.fail(new Error("ws recv buffer exceeded"), "recv_buffer_exceeded");
+            this.localCloseRequested = true;
+            this.observer.onWsClose("local");
+            this.ws.close();
+            return;
+        }
+        this.queue.push(b);
+        this.queueBytes += b.length;
+    }
+    shiftQueue() {
+        if (this.queueHead >= this.queue.length)
+            return undefined;
+        const b = this.queue[this.queueHead];
+        this.queueHead++;
+        // Periodic compaction to release references and keep array bounded.
+        if (this.queueHead > 1024 && this.queueHead * 2 > this.queue.length) {
+            this.queue.splice(0, this.queueHead);
+            this.queueHead = 0;
+        }
+        return b;
+    }
+    shiftWaiter() {
+        while (this.waitersHead < this.waiters.length) {
+            const w = this.waiters[this.waitersHead];
+            this.waitersHead++;
+            if (w != null && !w.settled) {
+                if (this.waitersHead > 1024 && this.waitersHead * 2 > this.waiters.length) {
+                    this.waiters.splice(0, this.waitersHead);
+                    this.waitersHead = 0;
+                    this.waitersSettled = 0;
+                }
+                return w;
+            }
+        }
+        if (this.waitersHead > 1024 && this.waitersHead * 2 > this.waiters.length) {
+            this.waiters.splice(0, this.waitersHead);
+            this.waitersHead = 0;
+            this.waitersSettled = 0;
+        }
+        return undefined;
+    }
+    compactWaitersMaybe() {
+        // Timeouts/cancellations can settle waiters without any incoming messages,
+        // so we compact based on how many settled entries we're carrying around.
+        if (this.waiters.length < 64)
+            return;
+        if (this.waitersSettled < 32)
+            return;
+        if (this.waitersSettled * 2 <= this.waiters.length)
+            return;
+        const next = [];
+        for (let i = this.waitersHead; i < this.waiters.length; i++) {
+            const w = this.waiters[i];
+            if (!w.settled)
+                next.push(w);
+        }
+        this.waiters = next;
+        this.waitersHead = 0;
+        this.waitersSettled = 0;
+    }
+    // fail transitions the transport into a permanent error state.
+    fail(err, reason) {
+        if (this.error != null)
+            return;
+        this.error = err;
+        if (reason != null) {
+            this.observer.onWsError(reason);
+        }
+        const ws = this.waiters;
+        const start = this.waitersHead;
+        this.waiters = [];
+        this.waitersHead = 0;
+        for (let i = start; i < ws.length; i++) {
+            const w = ws[i];
+            if (w == null || w.settled)
+                continue;
+            w.settled = true;
+            w.cleanup();
+            w.reject(err);
+        }
+    }
+}

package/dist/yamux/byteReader.d.ts

@@ -0,0 +1,10 @@
+export declare class ByteReader {
+    private readonly readChunk;
+    private readonly chunks;
+    private chunkHead;
+    private headOff;
+    private buffered;
+    constructor(readChunk: () => Promise<Uint8Array | null>);
+    readExactly(n: number): Promise<Uint8Array>;
+    bufferedBytes(): number;
+}

package/dist/yamux/byteReader.js

@@ -0,0 +1,50 @@
+// ByteReader buffers incoming chunks and supports exact reads.
+export class ByteReader {
+    readChunk;
+    chunks = [];
+    chunkHead = 0;
+    headOff = 0;
+    buffered = 0;
+    constructor(readChunk) {
+        this.readChunk = readChunk;
+    }
+    // readExactly reads n bytes or throws on EOF.
+    async readExactly(n) {
+        if (n < 0)
+            throw new Error("invalid length");
+        while (this.buffered < n) {
+            const chunk = await this.readChunk();
+            if (chunk == null)
+                throw new Error("eof");
+            if (chunk.length === 0)
+                continue;
+            this.chunks.push(chunk);
+            this.buffered += chunk.length;
+        }
+        const out = new Uint8Array(n);
+        let outOff = 0;
+        while (outOff < n) {
+            const head = this.chunks[this.chunkHead];
+            const avail = head.length - this.headOff;
+            const need = n - outOff;
+            const take = Math.min(avail, need);
+            out.set(head.subarray(this.headOff, this.headOff + take), outOff);
+            outOff += take;
+            this.headOff += take;
+            this.buffered -= take;
+            if (this.headOff === head.length) {
+                this.chunkHead++;
+                this.headOff = 0;
+                if (this.chunkHead > 1024 && this.chunkHead * 2 > this.chunks.length) {
+                    this.chunks.splice(0, this.chunkHead);
+                    this.chunkHead = 0;
+                }
+            }
+        }
+        return out;
+    }
+    // bufferedBytes returns the number of bytes currently buffered.
+    bufferedBytes() {
+        return this.buffered;
+    }
+}

package/dist/yamux/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const YAMUX_VERSION: 0;
+export declare const TYPE_DATA: 0;
+export declare const TYPE_WINDOW_UPDATE: 1;
+export declare const TYPE_PING: 2;
+export declare const TYPE_GO_AWAY: 3;
+export declare const FLAG_SYN: 1;
+export declare const FLAG_ACK: 2;
+export declare const FLAG_FIN: 4;
+export declare const FLAG_RST: 8;
+export declare const DEFAULT_MAX_STREAM_WINDOW: number;

package/dist/yamux/constants.js

@@ -0,0 +1,14 @@
+// YAMUX protocol version.
+export const YAMUX_VERSION = 0;
+// Frame types.
+export const TYPE_DATA = 0;
+export const TYPE_WINDOW_UPDATE = 1;
+export const TYPE_PING = 2;
+export const TYPE_GO_AWAY = 3;
+// Frame flags.
+export const FLAG_SYN = 1;
+export const FLAG_ACK = 2;
+export const FLAG_FIN = 4;
+export const FLAG_RST = 8;
+// Default flow-control window for streams.
+export const DEFAULT_MAX_STREAM_WINDOW = 256 * 1024;

package/dist/yamux/header.d.ts

@@ -0,0 +1,17 @@
+export declare const HEADER_LEN = 12;
+export type YamuxHeader = Readonly<{
+    /** Protocol version byte. */
+    version: number;
+    /** Frame type (data, window update, ping, go away). */
+    type: number;
+    /** 16-bit flags field (ACK/SYN/FIN/RST). */
+    flags: number;
+    /** Stream identifier (0 reserved for session-level frames). */
+    streamId: number;
+    /** Frame payload length in bytes. */
+    length: number;
+}>;
+export declare function encodeHeader(h: Omit<YamuxHeader, "version"> & {
+    version?: number;
+}): Uint8Array;
+export declare function decodeHeader(buf: Uint8Array, off: number): YamuxHeader;

package/dist/yamux/header.js

@@ -0,0 +1,26 @@
+import { readU32be, u32be } from "../utils/bin.js";
+import { YAMUX_VERSION } from "./constants.js";
+// YAMUX header length in bytes.
+export const HEADER_LEN = 12;
+// encodeHeader serializes a header with an optional version override.
+export function encodeHeader(h) {
+    const out = new Uint8Array(HEADER_LEN);
+    out[0] = (h.version ?? YAMUX_VERSION) & 0xff;
+    out[1] = h.type & 0xff;
+    out[2] = (h.flags >>> 8) & 0xff;
+    out[3] = h.flags & 0xff;
+    out.set(u32be(h.streamId >>> 0), 4);
+    out.set(u32be(h.length >>> 0), 8);
+    return out;
+}
+// decodeHeader parses a header from a byte buffer at the given offset.
+export function decodeHeader(buf, off) {
+    if (buf.length - off < HEADER_LEN)
+        throw new Error("header too short");
+    const version = buf[off];
+    const type = buf[off + 1];
+    const flags = ((buf[off + 2] << 8) | buf[off + 3]) >>> 0;
+    const streamId = readU32be(buf, off + 4);
+    const length = readU32be(buf, off + 8);
+    return { version, type, flags, streamId, length };
+}

package/dist/yamux/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./constants.js";
+export * from "./byteReader.js";
+export * from "./header.js";
+export * from "./session.js";
+export * from "./stream.js";

package/dist/yamux/index.js

@@ -0,0 +1,5 @@
+export * from "./constants.js";
+export * from "./byteReader.js";
+export * from "./header.js";
+export * from "./session.js";
+export * from "./stream.js";

package/dist/yamux/session.d.ts

@@ -0,0 +1,44 @@
+import { YamuxStream } from "./stream.js";
+export type ByteDuplex = {
+    /** Reads the next chunk from the underlying connection. */
+    read(): Promise<Uint8Array>;
+    /** Writes a chunk to the underlying connection. */
+    write(chunk: Uint8Array): Promise<void>;
+    /** Closes the underlying connection. */
+    close(): void;
+};
+export type YamuxSessionOptions = Readonly<{
+    /** True when acting as the client side (odd stream IDs). */
+    client: boolean;
+    /** Optional callback for newly accepted inbound streams. */
+    onIncomingStream?: (s: YamuxStream) => void;
+    /** Maximum frame payload bytes accepted per stream frame. */
+    maxFrameBytes?: number;
+}>;
+export declare class YamuxSession {
+    private readonly conn;
+    private readonly reader;
+    private readonly streams;
+    private readonly onIncomingStream;
+    private readonly maxFrameBytes;
+    private readonly client;
+    private nextStreamId;
+    private closed;
+    private readonly sendWindowWaiters;
+    constructor(conn: ByteDuplex, opts: YamuxSessionOptions);
+    openStream(): Promise<YamuxStream>;
+    getStream(id: number): YamuxStream | undefined;
+    writeRaw(chunk: Uint8Array): Promise<void>;
+    sendRst(id: number): Promise<void>;
+    notifySendWindow(streamId: number): void;
+    waitForSendWindow(streamId: number): Promise<void>;
+    onStreamEstablished(_streamId: number): void;
+    onStreamClosed(streamId: number): void;
+    close(): void;
+    private wakeSendWindowWaiters;
+    private readLoop;
+    private handlePing;
+    private handleDataFrame;
+    private handleWindowUpdateFrame;
+    private isInboundStreamIdValid;
+}