@woosh/meep-engine 3.46.0 → 3.47.0

package/src/engine/network/transport/connection/RangeSet.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A set of non-negative integers held as sorted, disjoint, non-adjacent half-open ranges
+ * `[start, end)`. Packet numbers a receiver has seen, stream bytes it holds, bytes a sender must
+ * re-send: each is a few long runs, so a range list is both the compact and the cheap form.
+ *
+ * Values are doubles, exact to 2^53, so neither a packet number nor a stream offset ever wraps.
+ * Storage is one `Float64Array` of `[start, end]` pairs that grows to a high-watermark and stays:
+ * nothing is allocated once it is big enough.
+ *
+ * Operations are linear in the number of ranges. Every user bounds that number (an ACK reports at
+ * most a few dozen; a stream's holes are bounded by its window), so linear is the fast form too.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RangeSet {
+    /**
+     * @param {number} [initial_capacity] ranges to make room for up front
+     */
+    constructor(initial_capacity?: number);
+    /**
+     * Number of disjoint ranges.
+     * @returns {number}
+     */
+    get count(): number;
+    /**
+     * @param {number} i range index, `[0, count)`
+     * @returns {number} inclusive start
+     */
+    start(i: number): number;
+    /**
+     * @param {number} i range index, `[0, count)`
+     * @returns {number} exclusive end
+     */
+    end(i: number): number;
+    /**
+     * @returns {boolean}
+     */
+    is_empty(): boolean;
+    /**
+     * Smallest value held. Only meaningful when not empty.
+     * @returns {number}
+     */
+    min(): number;
+    /**
+     * One past the largest value held. Only meaningful when not empty.
+     * @returns {number}
+     */
+    max_end(): number;
+    clear(): void;
+    /**
+     * @param {number} value
+     * @returns {boolean}
+     */
+    contains(value: number): boolean;
+    /**
+     * Whether every value of `[start, end)` is held.
+     * @param {number} start
+     * @param {number} end
+     * @returns {boolean}
+     */
+    contains_range(start: number, end: number): boolean;
+    /**
+     * End of the run that starts at `value`: the largest `e` with `[value, e)` held, or `value`
+     * itself when `value` is not held.
+     * @param {number} value
+     * @returns {number}
+     */
+    run_end(value: number): number;
+    /**
+     * Add `[start, end)`, merging with whatever it touches.
+     * @param {number} start
+     * @param {number} end
+     */
+    add(start: number, end: number): void;
+    /**
+     * Remove `[start, end)`, splitting a range it lands inside.
+     * @param {number} start
+     * @param {number} end
+     */
+    remove(start: number, end: number): void;
+    /**
+     * Remove everything below `value`.
+     * @param {number} value
+     */
+    remove_below(value: number): void;
+    /**
+     * Drop whole ranges from the bottom until at most `max_count` remain.
+     * @param {number} max_count
+     */
+    keep_highest(max_count: number): void;
+    #private;
+}
+//# sourceMappingURL=RangeSet.d.ts.map

package/src/engine/network/transport/connection/RangeSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeSet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/connection/RangeSet.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH;IAaI;;OAEG;IACH,+BAFW,MAAM,EAKhB;IAED;;;OAGG;IACH,oBAEC;IAED;;;OAGG;IACH,SAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,OAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,YAFa,OAAO,CAInB;IAED;;;OAGG;IACH,OAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,WAFa,MAAM,CAIlB;IAED,cAEC;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;;;OAKG;IACH,sBAJW,MAAM,OACN,MAAM,GACJ,OAAO,CAWnB;IAED;;;;;OAKG;IACH,eAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;OAIG;IACH,WAHW,MAAM,OACN,MAAM,QA0ChB;IAED;;;;OAIG;IACH,cAHW,MAAM,OACN,MAAM,QAwChB;IAED;;;OAGG;IACH,oBAFW,MAAM,QAKhB;IAED;;;OAGG;IACH,wBAFW,MAAM,QAQhB;;CAWJ"}

package/src/engine/network/transport/connection/RangeSet.js

@@ -0,0 +1,260 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * A set of non-negative integers held as sorted, disjoint, non-adjacent half-open ranges
+ * `[start, end)`. Packet numbers a receiver has seen, stream bytes it holds, bytes a sender must
+ * re-send: each is a few long runs, so a range list is both the compact and the cheap form.
+ *
+ * Values are doubles, exact to 2^53, so neither a packet number nor a stream offset ever wraps.
+ * Storage is one `Float64Array` of `[start, end]` pairs that grows to a high-watermark and stays:
+ * nothing is allocated once it is big enough.
+ *
+ * Operations are linear in the number of ranges. Every user bounds that number (an ACK reports at
+ * most a few dozen; a stream's holes are bounded by its window), so linear is the fast form too.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RangeSet {
+    /**
+     * `[start0, end0, start1, end1, ...]`, ascending, disjoint and non-adjacent.
+     * @type {Float64Array}
+     */
+    #data;
+
+    /**
+     * Number of ranges held.
+     * @type {number}
+     */
+    #count = 0;
+
+    /**
+     * @param {number} [initial_capacity] ranges to make room for up front
+     */
+    constructor(initial_capacity = 8) {
+        assert.isPositiveInteger(initial_capacity, 'initial_capacity');
+        this.#data = new Float64Array(initial_capacity * 2);
+    }
+
+    /**
+     * Number of disjoint ranges.
+     * @returns {number}
+     */
+    get count() {
+        return this.#count;
+    }
+
+    /**
+     * @param {number} i range index, `[0, count)`
+     * @returns {number} inclusive start
+     */
+    start(i) {
+        return this.#data[i * 2];
+    }
+
+    /**
+     * @param {number} i range index, `[0, count)`
+     * @returns {number} exclusive end
+     */
+    end(i) {
+        return this.#data[i * 2 + 1];
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    is_empty() {
+        return this.#count === 0;
+    }
+
+    /**
+     * Smallest value held. Only meaningful when not empty.
+     * @returns {number}
+     */
+    min() {
+        return this.#data[0];
+    }
+
+    /**
+     * One past the largest value held. Only meaningful when not empty.
+     * @returns {number}
+     */
+    max_end() {
+        return this.#data[this.#count * 2 - 1];
+    }
+
+    clear() {
+        this.#count = 0;
+    }
+
+    /**
+     * @param {number} value
+     * @returns {boolean}
+     */
+    contains(value) {
+        const data = this.#data;
+        for (let i = 0; i < this.#count; i++) {
+            const s = data[i * 2];
+            if (value < s) return false;
+            if (value < data[i * 2 + 1]) return true;
+        }
+        return false;
+    }
+
+    /**
+     * Whether every value of `[start, end)` is held.
+     * @param {number} start
+     * @param {number} end
+     * @returns {boolean}
+     */
+    contains_range(start, end) {
+        if (end <= start) return true;
+        const data = this.#data;
+        for (let i = 0; i < this.#count; i++) {
+            const s = data[i * 2];
+            if (start < s) return false;
+            if (start < data[i * 2 + 1]) return end <= data[i * 2 + 1];
+        }
+        return false;
+    }
+
+    /**
+     * End of the run that starts at `value`: the largest `e` with `[value, e)` held, or `value`
+     * itself when `value` is not held.
+     * @param {number} value
+     * @returns {number}
+     */
+    run_end(value) {
+        const data = this.#data;
+        for (let i = 0; i < this.#count; i++) {
+            const s = data[i * 2];
+            if (value < s) return value;
+            const e = data[i * 2 + 1];
+            if (value < e) return e;
+        }
+        return value;
+    }
+
+    /**
+     * Add `[start, end)`, merging with whatever it touches.
+     * @param {number} start
+     * @param {number} end
+     */
+    add(start, end) {
+        if (end <= start) return;
+        const data = this.#data;
+        const n = this.#count;
+
+        // first range whose end reaches `start` (touching counts: they merge); a binary search, so
+        // the common add — at or past the top — costs nothing for the ranges below it
+        let lo = 0;
+        let top = n;
+        while (lo < top) {
+            const mid = (lo + top) >>> 1;
+            if (data[mid * 2 + 1] < start) lo = mid + 1;
+            else top = mid;
+        }
+
+        // first range that starts strictly past `end`
+        let hi = lo;
+        while (hi < n && data[hi * 2] <= end) hi++;
+
+        if (lo === hi) {
+            // touches nothing: insert at lo
+            this.#ensure_capacity(n + 1);
+            const d = this.#data;
+            d.copyWithin((lo + 1) * 2, lo * 2, n * 2);
+            d[lo * 2] = start;
+            d[lo * 2 + 1] = end;
+            this.#count = n + 1;
+            return;
+        }
+
+        // merge ranges [lo, hi) with [start, end) into slot lo
+        const merged_start = Math.min(start, data[lo * 2]);
+        const merged_end = Math.max(end, data[(hi - 1) * 2 + 1]);
+        data[lo * 2] = merged_start;
+        data[lo * 2 + 1] = merged_end;
+        const removed = hi - lo - 1;
+        if (removed > 0) {
+            data.copyWithin((lo + 1) * 2, hi * 2, n * 2);
+            this.#count = n - removed;
+        }
+    }
+
+    /**
+     * Remove `[start, end)`, splitting a range it lands inside.
+     * @param {number} start
+     * @param {number} end
+     */
+    remove(start, end) {
+        if (end <= start) return;
+        let i = 0;
+        while (i < this.#count) {
+            const data = this.#data;
+            const s = data[i * 2];
+            const e = data[i * 2 + 1];
+            if (e <= start) {
+                i++;
+                continue;
+            }
+            if (s >= end) return;
+
+            if (s < start && e > end) {
+                // split in two
+                const n = this.#count;
+                this.#ensure_capacity(n + 1);
+                const d = this.#data;
+                d.copyWithin((i + 2) * 2, (i + 1) * 2, n * 2);
+                d[i * 2 + 1] = start;
+                d[(i + 1) * 2] = end;
+                d[(i + 1) * 2 + 1] = e;
+                this.#count = n + 1;
+                return;
+            }
+            if (s < start) {
+                data[i * 2 + 1] = start;
+                i++;
+                continue;
+            }
+            if (e > end) {
+                data[i * 2] = end;
+                return;
+            }
+            // fully covered: delete range i
+            data.copyWithin(i * 2, (i + 1) * 2, this.#count * 2);
+            this.#count--;
+        }
+    }
+
+    /**
+     * Remove everything below `value`.
+     * @param {number} value
+     */
+    remove_below(value) {
+        if (this.#count === 0) return;
+        this.remove(this.#data[0], value);
+    }
+
+    /**
+     * Drop whole ranges from the bottom until at most `max_count` remain.
+     * @param {number} max_count
+     */
+    keep_highest(max_count) {
+        const n = this.#count;
+        if (n <= max_count) return;
+        const drop = n - max_count;
+        this.#data.copyWithin(0, drop * 2, n * 2);
+        this.#count = max_count;
+    }
+
+    /**
+     * @param {number} ranges
+     */
+    #ensure_capacity(ranges) {
+        if (ranges * 2 <= this.#data.length) return;
+        const next = new Float64Array(Math.max(ranges * 2, this.#data.length * 2));
+        next.set(this.#data.subarray(0, this.#count * 2));
+        this.#data = next;
+    }
+}

package/src/engine/network/transport/connection/RxStream.d.ts

@@ -0,0 +1,48 @@
+/** {@link RxStream#next_message}: nothing whole yet. */
+export const RX_NONE: -1;
+/** {@link RxStream#next_message}: the stream broke the protocol; stop reading it. */
+export const RX_ERROR: -2;
+export class RxStream {
+    /**
+     * @param {number} max_message_bytes largest message this lane accepts
+     * @param {number} window bytes past the delivered point the sender may have in flight
+     */
+    constructor(max_message_bytes: number, window: number);
+    /** @type {number} @readonly */
+    readonly max_message_bytes: number;
+    /** @type {number} @readonly */
+    readonly window: number;
+    /**
+     * Most disjoint ranges held out of order: one per 256 bytes of window, and never fewer
+     * than 1,024.
+     * @type {number} @readonly
+     */
+    readonly max_ranges: number;
+    /** Whether the stream has broken the protocol. */
+    get failed(): boolean;
+    /** How the stream broke the protocol; empty while it has not. */
+    get failure(): string;
+    /**
+     * Take one segment.
+     *
+     * @param {number} offset stream offset of the segment's first byte
+     * @param {Uint8Array} bytes
+     * @param {number} from index of the first byte in `bytes`
+     * @param {number} length
+     * @returns {boolean} false when the segment breaks the protocol
+     */
+    receive(offset: number, bytes: Uint8Array, from: number, length: number): boolean;
+    /**
+     * The next whole message, consumed. Writes its position in {@link bytes} into `out[0]`; valid until
+     * the next {@link receive}.
+     *
+     * @param {Float64Array|number[]} out
+     * @returns {number} message length, {@link RX_NONE} or {@link RX_ERROR}
+     */
+    next_message(out: Float64Array | number[]): number;
+    /** The buffer {@link next_message} positions are in. */
+    get bytes(): Uint8Array;
+    clear(): void;
+    #private;
+}
+//# sourceMappingURL=RxStream.d.ts.map

package/src/engine/network/transport/connection/RxStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RxStream.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/connection/RxStream.js"],"names":[],"mappings":"AAyBA,wDAAwD;AACxD,yBAA0B;AAE1B,qFAAqF;AACrF,0BAA2B;AAE3B;IAuCI;;;OAGG;IACH,+BAHW,MAAM,UACN,MAAM,EAchB;IAXG,+BAA+B;IAC/B,4BADW,MAAM,CACyB;IAC1C,+BAA+B;IAC/B,iBADW,MAAM,CACG;IACpB;;;;OAIG;IACH,qBAFU,MAAM,CAEyC;IAI7D,kDAAkD;IAClD,sBAEC;IAED,iEAAiE;IACjE,sBAEC;IAED;;;;;;;;OAQG;IACH,gBANW,MAAM,SACN,UAAU,QACV,MAAM,UACN,MAAM,GACJ,OAAO,CAqBnB;IAYD;;;;;;OAMG;IACH,kBAHW,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CA+BlB;IAED,wDAAwD;IACxD,wBAEC;IAED,cAKC;;CAwBJ"}

package/src/engine/network/transport/connection/RxStream.js

@@ -0,0 +1,211 @@
+import { bytes_copy } from "./bytes_copy.js";
+import { RangeSet } from "./RangeSet.js";
+import { varint_read } from "./varint.js";
+
+/**
+ * Receive half of one reliable lane: puts stream segments back in order and hands out whole
+ * `[varint length][bytes]` messages as soon as their bytes are contiguous.
+ *
+ * Memory is bounded by configuration, never by what the peer claims. A segment reaching past
+ * `consumed + max_message_bytes + header + window` cannot come from a sender keeping to its window
+ * (see {@link TxStream}), and a message declaring more than `max_message_bytes` is refused: both
+ * are protocol errors, and the lane stops.
+ *
+ * So is time. What a segment costs to take in grows with the holes held, and a peer sending
+ * one-byte segments two bytes apart would have the receiver hold half a window of them. An honest
+ * sender's holes are packets it lost and has not re-sent yet: a few hundred at the most in a
+ * 256 KiB window, even over small datagrams. More than {@link max_ranges} is a protocol error.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Largest header a message length can have. */
+const MAX_HEADER_BYTES = 8;
+
+/** {@link RxStream#next_message}: nothing whole yet. */
+export const RX_NONE = -1;
+
+/** {@link RxStream#next_message}: the stream broke the protocol; stop reading it. */
+export const RX_ERROR = -2;
+
+export class RxStream {
+    /**
+     * Stream bytes from {@link #buffer_base} on.
+     * @type {Uint8Array}
+     */
+    #buffer;
+
+    /**
+     * Stream offset of `#buffer[0]`.
+     * @type {number}
+     */
+    #buffer_base = 0;
+
+    /**
+     * Every byte below this offset has been handed out.
+     * @type {number}
+     */
+    #consumed = 0;
+
+    /**
+     * Ranges held at or above {@link #consumed}.
+     * @type {RangeSet}
+     */
+    #received = new RangeSet();
+
+    /**
+     * Set once the stream has broken the protocol.
+     * @type {boolean}
+     */
+    #failed = false;
+
+    /**
+     * How it broke the protocol, once {@link #failed}.
+     * @type {string}
+     */
+    #failure = '';
+
+    #cursor = { position: 0 };
+
+    /**
+     * @param {number} max_message_bytes largest message this lane accepts
+     * @param {number} window bytes past the delivered point the sender may have in flight
+     */
+    constructor(max_message_bytes, window) {
+        /** @type {number} @readonly */
+        this.max_message_bytes = max_message_bytes;
+        /** @type {number} @readonly */
+        this.window = window;
+        /**
+         * Most disjoint ranges held out of order: one per 256 bytes of window, and never fewer
+         * than 1,024.
+         * @type {number} @readonly
+         */
+        this.max_ranges = Math.max(1024, Math.ceil(window / 256));
+        this.#buffer = new Uint8Array(1024);
+    }
+
+    /** Whether the stream has broken the protocol. */
+    get failed() {
+        return this.#failed;
+    }
+
+    /** How the stream broke the protocol; empty while it has not. */
+    get failure() {
+        return this.#failure;
+    }
+
+    /**
+     * Take one segment.
+     *
+     * @param {number} offset stream offset of the segment's first byte
+     * @param {Uint8Array} bytes
+     * @param {number} from index of the first byte in `bytes`
+     * @param {number} length
+     * @returns {boolean} false when the segment breaks the protocol
+     */
+    receive(offset, bytes, from, length) {
+        if (this.#failed) return false;
+        let start = offset;
+        const end = offset + length;
+        if (end <= this.#consumed) return true; // all of it handed out already
+        if (start < this.#consumed) {
+            from += this.#consumed - start;
+            start = this.#consumed;
+        }
+        if (end > this.#consumed + this.max_message_bytes + MAX_HEADER_BYTES + this.window) {
+            return this.#fail('segment past the receive window');
+        }
+        this.#reserve(end);
+        bytes_copy(bytes, from, this.#buffer, start - this.#buffer_base, end - start);
+        this.#received.add(start, end);
+        if (this.#received.count > this.max_ranges) {
+            return this.#fail(`more than ${this.max_ranges} holes held out of order`);
+        }
+        return true;
+    }
+
+    /**
+     * @param {string} reason
+     * @returns {boolean} false
+     */
+    #fail(reason) {
+        this.#failed = true;
+        this.#failure = reason;
+        return false;
+    }
+
+    /**
+     * The next whole message, consumed. Writes its position in {@link bytes} into `out[0]`; valid until
+     * the next {@link receive}.
+     *
+     * @param {Float64Array|number[]} out
+     * @returns {number} message length, {@link RX_NONE} or {@link RX_ERROR}
+     */
+    next_message(out) {
+        if (this.#failed) return RX_ERROR;
+        const received = this.#received;
+        if (received.is_empty() || received.min() > this.#consumed) return RX_NONE;
+        const contiguous = received.end(0);
+
+        const read = this.#consumed - this.#buffer_base;
+        const cursor = this.#cursor;
+        cursor.position = read;
+        const length = varint_read(this.#buffer, cursor, contiguous - this.#buffer_base);
+        if (length < 0) {
+            // header not all here yet - unless it is already as long as a header can be
+            if (contiguous - this.#consumed >= MAX_HEADER_BYTES) {
+                this.#fail('message length is not a varint');
+                return RX_ERROR;
+            }
+            return RX_NONE;
+        }
+        if (length > this.max_message_bytes) {
+            this.#fail(`message larger than max_message_bytes ${this.max_message_bytes}`);
+            return RX_ERROR;
+        }
+        const body = cursor.position;
+        if (body + length > contiguous - this.#buffer_base) return RX_NONE;
+
+        out[0] = body;
+        this.#consumed = this.#buffer_base + body + length;
+        received.remove_below(this.#consumed);
+        return length;
+    }
+
+    /** The buffer {@link next_message} positions are in. */
+    get bytes() {
+        return this.#buffer;
+    }
+
+    clear() {
+        this.#buffer_base = this.#consumed = 0;
+        this.#received.clear();
+        this.#failed = false;
+        this.#failure = '';
+    }
+
+    /**
+     * Make the buffer reach stream offset `end`: first by dropping what has been handed out, then
+     * by growing. Bounded by the caller's check against the window.
+     * @param {number} end
+     */
+    #reserve(end) {
+        if (end - this.#buffer_base <= this.#buffer.length) return;
+        const drop = this.#consumed - this.#buffer_base;
+        if (drop > 0) {
+            const held_end = this.#received.is_empty() ? this.#consumed : this.#received.max_end();
+            const kept = held_end - this.#consumed;
+            if (kept > 0) this.#buffer.copyWithin(0, drop, drop + kept);
+            this.#buffer_base = this.#consumed;
+        }
+        const needed = end - this.#buffer_base;
+        if (needed <= this.#buffer.length) return;
+        let size = this.#buffer.length * 2;
+        while (size < needed) size *= 2;
+        const next = new Uint8Array(size);
+        next.set(this.#buffer);
+        this.#buffer = next;
+    }
+}