@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -0,0 +1,90 @@
+/**
+ * Send half of one reliable lane: an ordered byte stream of `[varint length][bytes]` messages.
+ *
+ * A message is copied once, into {@link #buffer}, when it is queued. What goes on the wire is byte
+ * ranges of the stream, and what a lost packet costs is the ranges it carried: they are queued for
+ * re-sending, minus anything acknowledged since. Bytes are released once every byte before them is
+ * acknowledged.
+ *
+ * Flow control needs no frames. The sender never sends a byte at or past `acked_prefix + window`.
+ * The receiver delivers each message the moment its bytes are contiguous and its contiguous point is
+ * never behind the sender's acked prefix, so what the receiver must hold out of order is bounded by
+ * the window, and what it holds in order is bounded by the largest message.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class TxStream {
+    /**
+     * @param {number} window bytes the sender may have past its acked prefix
+     */
+    constructor(window: number);
+    /** @type {number} @readonly */
+    readonly window: number;
+    /** Stream offset one past the last byte queued. */
+    get end(): number;
+    /** Every byte below this is acknowledged. */
+    get acked_prefix(): number;
+    /**
+     * Whether anything is waiting to go out: a re-send, or new bytes the window lets through.
+     * @returns {boolean}
+     */
+    has_sendable(): boolean;
+    /**
+     * Whether bytes are queued that the receiver has not acknowledged.
+     * @returns {boolean}
+     */
+    has_unacked(): boolean;
+    /**
+     * Queue one message.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length
+     * @returns {number} stream offset one past the message: delivered once the acked prefix reaches it
+     */
+    append(bytes: Uint8Array, offset: number, length: number): number;
+    /**
+     * Pick the next range to send, at most `max_length` bytes: the lowest pending re-send first,
+     * then new bytes up to the window. Writes `[offset, length]` into `out`; length 0 means nothing
+     * to send. The range is not marked sent until {@link mark_sent}.
+     *
+     * @param {number} max_length
+     * @param {Float64Array} out
+     */
+    peek(max_length: number, out: Float64Array): void;
+    /**
+     * The range {@link peek} returned has gone out.
+     * @param {number} offset
+     * @param {number} length
+     */
+    mark_sent(offset: number, length: number): void;
+    /**
+     * Copy stream bytes `[offset, offset + length)` into `out` at `out_offset`.
+     * @param {number} offset
+     * @param {number} length
+     * @param {Uint8Array} out
+     * @param {number} out_offset
+     */
+    copy_out(offset: number, length: number, out: Uint8Array, out_offset: number): void;
+    /**
+     * A packet carrying `[offset, offset + length)` was acknowledged.
+     * @param {number} offset
+     * @param {number} length
+     */
+    on_acked(offset: number, length: number): void;
+    /**
+     * A packet carrying `[offset, offset + length)` was declared lost, or is being probed: send what
+     * of it is still unacknowledged again.
+     * @param {number} offset
+     * @param {number} length
+     * @returns {boolean} whether any of it is still unacknowledged, and so queued to go again
+     */
+    on_lost(offset: number, length: number): boolean;
+    /**
+     * Forget everything: the connection is gone.
+     */
+    clear(): void;
+    #private;
+}
+//# sourceMappingURL=TxStream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TxStream.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/connection/TxStream.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IA4CI;;OAEG;IACH,oBAFW,MAAM,EAMhB;IAHG,+BAA+B;IAC/B,iBADW,MAAM,CACG;IAIxB,mDAAmD;IACnD,kBAEC;IAED,6CAA6C;IAC7C,2BAEC;IAED;;;OAGG;IACH,gBAFa,OAAO,CAKnB;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,cALW,UAAU,UACV,MAAM,UACN,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;OAOG;IACH,iBAHW,MAAM,OACN,YAAY,QAatB;IAED;;;;OAIG;IACH,kBAHW,MAAM,UACN,MAAM,QAQhB;IAED;;;;;;OAMG;IACH,iBALW,MAAM,UACN,MAAM,OACN,UAAU,cACV,MAAM,QAKhB;IAED;;;;OAIG;IACH,iBAHW,MAAM,UACN,MAAM,QAahB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,UACN,MAAM,GACJ,OAAO,CAgBnB;IAED;;OAEG;IACH,cAIC;;CA8BJ"}

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

@@ -0,0 +1,243 @@
+import { bytes_copy } from "./bytes_copy.js";
+import { RangeSet } from "./RangeSet.js";
+import { varint_size, varint_write } from "./varint.js";
+
+/**
+ * Send half of one reliable lane: an ordered byte stream of `[varint length][bytes]` messages.
+ *
+ * A message is copied once, into {@link #buffer}, when it is queued. What goes on the wire is byte
+ * ranges of the stream, and what a lost packet costs is the ranges it carried: they are queued for
+ * re-sending, minus anything acknowledged since. Bytes are released once every byte before them is
+ * acknowledged.
+ *
+ * Flow control needs no frames. The sender never sends a byte at or past `acked_prefix + window`.
+ * The receiver delivers each message the moment its bytes are contiguous and its contiguous point is
+ * never behind the sender's acked prefix, so what the receiver must hold out of order is bounded by
+ * the window, and what it holds in order is bounded by the largest message.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class TxStream {
+    /**
+     * Stream bytes from {@link #base} on. Grows to a high-watermark.
+     * @type {Uint8Array}
+     */
+    #buffer;
+
+    /**
+     * Stream offset of `#buffer[0]`.
+     * @type {number}
+     */
+    #base = 0;
+
+    /**
+     * Stream offset one past the last byte queued.
+     * @type {number}
+     */
+    #end = 0;
+
+    /**
+     * First offset never sent.
+     * @type {number}
+     */
+    #next_new = 0;
+
+    /**
+     * Every byte below this is acknowledged.
+     * @type {number}
+     */
+    #acked_prefix = 0;
+
+    /**
+     * Acknowledged ranges at or above {@link #acked_prefix}.
+     * @type {RangeSet}
+     */
+    #acked = new RangeSet();
+
+    /**
+     * Ranges carried by packets declared lost, still unacknowledged, to be sent again before any
+     * new byte.
+     * @type {RangeSet}
+     */
+    #retransmit = new RangeSet();
+
+    /**
+     * @param {number} window bytes the sender may have past its acked prefix
+     */
+    constructor(window) {
+        /** @type {number} @readonly */
+        this.window = window;
+        this.#buffer = new Uint8Array(1024);
+    }
+
+    /** Stream offset one past the last byte queued. */
+    get end() {
+        return this.#end;
+    }
+
+    /** Every byte below this is acknowledged. */
+    get acked_prefix() {
+        return this.#acked_prefix;
+    }
+
+    /**
+     * Whether anything is waiting to go out: a re-send, or new bytes the window lets through.
+     * @returns {boolean}
+     */
+    has_sendable() {
+        if (!this.#retransmit.is_empty()) return true;
+        return this.#next_new < this.#end && this.#next_new < this.#acked_prefix + this.window;
+    }
+
+    /**
+     * Whether bytes are queued that the receiver has not acknowledged.
+     * @returns {boolean}
+     */
+    has_unacked() {
+        return this.#acked_prefix < this.#end;
+    }
+
+    /**
+     * Queue one message.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length
+     * @returns {number} stream offset one past the message: delivered once the acked prefix reaches it
+     */
+    append(bytes, offset, length) {
+        const header = varint_size(length);
+        this.#reserve(header + length);
+        let at = this.#end - this.#base;
+        at = varint_write(this.#buffer, at, length);
+        bytes_copy(bytes, offset, this.#buffer, at, length);
+        this.#end += header + length;
+        return this.#end;
+    }
+
+    /**
+     * Pick the next range to send, at most `max_length` bytes: the lowest pending re-send first,
+     * then new bytes up to the window. Writes `[offset, length]` into `out`; length 0 means nothing
+     * to send. The range is not marked sent until {@link mark_sent}.
+     *
+     * @param {number} max_length
+     * @param {Float64Array} out
+     */
+    peek(max_length, out) {
+        if (!this.#retransmit.is_empty()) {
+            const s = this.#retransmit.start(0);
+            const e = this.#retransmit.end(0);
+            out[0] = s;
+            out[1] = Math.min(e - s, max_length);
+            return;
+        }
+        const limit = Math.min(this.#end, this.#acked_prefix + this.window);
+        out[0] = this.#next_new;
+        out[1] = Math.max(0, Math.min(limit - this.#next_new, max_length));
+    }
+
+    /**
+     * The range {@link peek} returned has gone out.
+     * @param {number} offset
+     * @param {number} length
+     */
+    mark_sent(offset, length) {
+        if (offset < this.#next_new) {
+            this.#retransmit.remove(offset, offset + length);
+        } else {
+            this.#next_new = offset + length;
+        }
+    }
+
+    /**
+     * Copy stream bytes `[offset, offset + length)` into `out` at `out_offset`.
+     * @param {number} offset
+     * @param {number} length
+     * @param {Uint8Array} out
+     * @param {number} out_offset
+     */
+    copy_out(offset, length, out, out_offset) {
+        const from = offset - this.#base;
+        bytes_copy(this.#buffer, from, out, out_offset, length);
+    }
+
+    /**
+     * A packet carrying `[offset, offset + length)` was acknowledged.
+     * @param {number} offset
+     * @param {number} length
+     */
+    on_acked(offset, length) {
+        const end = offset + length;
+        if (end <= this.#acked_prefix) return;
+        this.#retransmit.remove(offset, end);
+        this.#acked.add(Math.max(offset, this.#acked_prefix), end);
+        if (this.#acked.min() <= this.#acked_prefix) {
+            this.#acked_prefix = this.#acked.run_end(this.#acked.min());
+            this.#acked.remove_below(this.#acked_prefix);
+            // bytes are moved out of the way only when room is needed (#reserve): releasing on
+            // every ack would slide a large message's tail down once per packet
+        }
+    }
+
+    /**
+     * A packet carrying `[offset, offset + length)` was declared lost, or is being probed: send what
+     * of it is still unacknowledged again.
+     * @param {number} offset
+     * @param {number} length
+     * @returns {boolean} whether any of it is still unacknowledged, and so queued to go again
+     */
+    on_lost(offset, length) {
+        let start = Math.max(offset, this.#acked_prefix);
+        const end = offset + length;
+        if (end <= start) return false;
+        this.#retransmit.add(start, end);
+        // take back out whatever has been acknowledged meanwhile
+        const acked = this.#acked;
+        for (let i = 0; i < acked.count; i++) {
+            const s = acked.start(i);
+            if (s >= end) break;
+            const e = acked.end(i);
+            if (e > start) this.#retransmit.remove(s, e);
+        }
+        return !this.#acked.contains_range(start, end);
+    }
+
+    /**
+     * Forget everything: the connection is gone.
+     */
+    clear() {
+        this.#base = this.#end = this.#next_new = this.#acked_prefix = 0;
+        this.#acked.clear();
+        this.#retransmit.clear();
+    }
+
+    /**
+     * Make room for `extra` more bytes, first by dropping acknowledged bytes from the front, then
+     * by growing.
+     * @param {number} extra
+     */
+    #reserve(extra) {
+        const used = this.#end - this.#base;
+        if (used + extra <= this.#buffer.length) return;
+        this.#release();
+        const kept = this.#end - this.#base;
+        if (kept + extra <= this.#buffer.length) return;
+        let size = this.#buffer.length * 2;
+        while (size < kept + extra) size *= 2;
+        const next = new Uint8Array(size);
+        next.set(this.#buffer.subarray(0, kept));
+        this.#buffer = next;
+    }
+
+    /**
+     * Drop the acknowledged prefix from the front of the buffer.
+     */
+    #release() {
+        const drop = this.#acked_prefix - this.#base;
+        if (drop <= 0) return;
+        const kept = this.#end - this.#acked_prefix;
+        if (kept > 0) this.#buffer.copyWithin(0, drop, drop + kept);
+        this.#base = this.#acked_prefix;
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Copy `length` bytes from `source[source_offset..]` to `target[target_offset..]`.
+ *
+ * `target.set(source.subarray(a, b), at)` allocates a view on every call; on the packet path —
+ * every message in, every message out, every segment — that was nearly all of the connection
+ * layer's allocation. The small copies, which are most of them, allocate nothing here.
+ *
+ * The ranges may not overlap.
+ *
+ * @param {Uint8Array} source
+ * @param {number} source_offset
+ * @param {Uint8Array} target
+ * @param {number} target_offset
+ * @param {number} length
+ */
+export function bytes_copy(source: Uint8Array, source_offset: number, target: Uint8Array, target_offset: number, length: number): void;
+//# sourceMappingURL=bytes_copy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bytes_copy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/connection/bytes_copy.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;GAcG;AACH,mCANW,UAAU,iBACV,MAAM,UACN,UAAU,iBACV,MAAM,UACN,MAAM,QAUhB"}

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

@@ -0,0 +1,34 @@
+/**
+ * Up to this many bytes a plain loop copies; past it, `set` over a `subarray` view does.
+ *
+ * Measured on Node 22 (one copy, warmed up): the loop costs about 1.2 ns a byte, `set` over a view
+ * 50–70 ns whatever the size — 42 against 51 ns at 20 bytes, 127 against 53 at 100, 1,390 against
+ * 69 at 1,100. Below this a loop is as fast and allocates nothing; above it the view's one small,
+ * short-lived allocation buys a memcpy.
+ */
+const LOOP_LIMIT = 64;
+
+/**
+ * Copy `length` bytes from `source[source_offset..]` to `target[target_offset..]`.
+ *
+ * `target.set(source.subarray(a, b), at)` allocates a view on every call; on the packet path —
+ * every message in, every message out, every segment — that was nearly all of the connection
+ * layer's allocation. The small copies, which are most of them, allocate nothing here.
+ *
+ * The ranges may not overlap.
+ *
+ * @param {Uint8Array} source
+ * @param {number} source_offset
+ * @param {Uint8Array} target
+ * @param {number} target_offset
+ * @param {number} length
+ */
+export function bytes_copy(source, source_offset, target, target_offset, length) {
+    if (length > LOOP_LIMIT) {
+        target.set(source.subarray(source_offset, source_offset + length), target_offset);
+        return;
+    }
+    for (let i = 0; i < length; i++) {
+        target[target_offset + i] = source[source_offset + i];
+    }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Bytes `value` takes.
+ * @param {number} value non-negative integer ≤ {@link VARINT_MAX}
+ * @returns {number} 1, 2, 4 or 8
+ */
+export function varint_size(value: number): number;
+/**
+ * Write `value` at `offset`. The caller has checked room: {@link varint_size} bytes.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @param {number} value non-negative integer ≤ {@link VARINT_MAX}
+ * @returns {number} offset past the written bytes
+ */
+export function varint_write(bytes: Uint8Array, offset: number, value: number): number;
+/**
+ * Read a varint at `cursor.position`, advancing it. Returns -1 when the bytes run out before
+ * `end` or the value is past {@link VARINT_MAX}: a truncated or hostile frame, which the caller
+ * drops.
+ *
+ * @param {Uint8Array} bytes
+ * @param {{position: number}} cursor
+ * @param {number} end exclusive bound of readable bytes
+ * @returns {number}
+ */
+export function varint_read(bytes: Uint8Array, cursor: {
+    position: number;
+}, end: number): number;
+/**
+ * Variable-length unsigned integers in the QUIC encoding (RFC 9000 §16): the top two bits of the
+ * first byte give the length — 1, 2, 4 or 8 bytes — and the rest is the value, big-endian.
+ *
+ *   0 .. 63          1 byte
+ *   64 .. 16,383     2 bytes
+ *   .. 2^30 - 1      4 bytes
+ *   .. 2^53 - 1      8 bytes   (2^62 - 1 on the wire; JavaScript numbers stop at 2^53)
+ *
+ * Chosen over LEB128 because the length is known before a byte is written, so a packet builder can
+ * check room for a frame header without trial-encoding it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/** Largest value {@link varint_write} encodes. */
+export const VARINT_MAX: number;
+//# sourceMappingURL=varint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"varint.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/connection/varint.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,mCAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;GAOG;AACH,oCALW,UAAU,UACV,MAAM,SACN,MAAM,GACJ,MAAM,CA8BlB;AAED;;;;;;;;;GASG;AACH,mCALW,UAAU,UACV;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,OAClB,MAAM,GACJ,MAAM,CA2BlB;AA1GD;;;;;;;;;;;;;;GAcG;AAEH,kDAAkD;AAClD,gCAAkD"}

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

@@ -0,0 +1,107 @@
+/**
+ * Variable-length unsigned integers in the QUIC encoding (RFC 9000 §16): the top two bits of the
+ * first byte give the length — 1, 2, 4 or 8 bytes — and the rest is the value, big-endian.
+ *
+ *   0 .. 63          1 byte
+ *   64 .. 16,383     2 bytes
+ *   .. 2^30 - 1      4 bytes
+ *   .. 2^53 - 1      8 bytes   (2^62 - 1 on the wire; JavaScript numbers stop at 2^53)
+ *
+ * Chosen over LEB128 because the length is known before a byte is written, so a packet builder can
+ * check room for a frame header without trial-encoding it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Largest value {@link varint_write} encodes. */
+export const VARINT_MAX = Number.MAX_SAFE_INTEGER;
+
+const TWO_POW_32 = 4294967296;
+
+/**
+ * Bytes `value` takes.
+ * @param {number} value non-negative integer ≤ {@link VARINT_MAX}
+ * @returns {number} 1, 2, 4 or 8
+ */
+export function varint_size(value) {
+    if (value < 64) return 1;
+    if (value < 16384) return 2;
+    if (value < 1073741824) return 4;
+    return 8;
+}
+
+/**
+ * Write `value` at `offset`. The caller has checked room: {@link varint_size} bytes.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @param {number} value non-negative integer ≤ {@link VARINT_MAX}
+ * @returns {number} offset past the written bytes
+ */
+export function varint_write(bytes, offset, value) {
+    if (value < 64) {
+        bytes[offset] = value;
+        return offset + 1;
+    }
+    if (value < 16384) {
+        bytes[offset] = 0x40 | (value >>> 8);
+        bytes[offset + 1] = value & 0xFF;
+        return offset + 2;
+    }
+    if (value < 1073741824) {
+        bytes[offset] = 0x80 | (value >>> 24);
+        bytes[offset + 1] = (value >>> 16) & 0xFF;
+        bytes[offset + 2] = (value >>> 8) & 0xFF;
+        bytes[offset + 3] = value & 0xFF;
+        return offset + 4;
+    }
+    const hi = Math.floor(value / TWO_POW_32);
+    const lo = value - hi * TWO_POW_32;
+    bytes[offset] = 0xC0 | (hi >>> 24);
+    bytes[offset + 1] = (hi >>> 16) & 0xFF;
+    bytes[offset + 2] = (hi >>> 8) & 0xFF;
+    bytes[offset + 3] = hi & 0xFF;
+    bytes[offset + 4] = lo >>> 24;
+    bytes[offset + 5] = (lo >>> 16) & 0xFF;
+    bytes[offset + 6] = (lo >>> 8) & 0xFF;
+    bytes[offset + 7] = lo & 0xFF;
+    return offset + 8;
+}
+
+/**
+ * Read a varint at `cursor.position`, advancing it. Returns -1 when the bytes run out before
+ * `end` or the value is past {@link VARINT_MAX}: a truncated or hostile frame, which the caller
+ * drops.
+ *
+ * @param {Uint8Array} bytes
+ * @param {{position: number}} cursor
+ * @param {number} end exclusive bound of readable bytes
+ * @returns {number}
+ */
+export function varint_read(bytes, cursor, end) {
+    const p = cursor.position;
+    if (p >= end) return -1;
+    const first = bytes[p];
+    const kind = first >>> 6;
+    if (kind === 0) {
+        cursor.position = p + 1;
+        return first;
+    }
+    if (kind === 1) {
+        if (p + 2 > end) return -1;
+        cursor.position = p + 2;
+        return ((first & 0x3F) << 8) | bytes[p + 1];
+    }
+    if (kind === 2) {
+        if (p + 4 > end) return -1;
+        cursor.position = p + 4;
+        return ((first & 0x3F) * 16777216) + (bytes[p + 1] << 16) + (bytes[p + 2] << 8) + bytes[p + 3];
+    }
+    if (p + 8 > end) return -1;
+    const hi = ((first & 0x3F) * 16777216) + (bytes[p + 1] << 16) + (bytes[p + 2] << 8) + bytes[p + 3];
+    if (hi > 0x1FFFFF) return -1; // past 2^53
+    const lo = (bytes[p + 4] * 16777216) + (bytes[p + 5] << 16) + (bytes[p + 6] << 8) + bytes[p + 7];
+    cursor.position = p + 8;
+    return hi * TWO_POW_32 + lo;
+}