@woosh/meep-engine 3.45.0 → 3.47.0

package/src/engine/network/transport/fragments/FragmentRetention.js

@@ -1,191 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import {
-    FRAGMENT_RETENTION_MAX_AGE_MS,
-    FRAGMENT_RETENTION_MAX_MESSAGES,
-    FRAGMENT_RETENTION_MAX_RETRIES,
-} from "./packet_size.js";
-
-/**
- * Per-peer sender-side retention buffer for fragmented message bytes,
- * used to satisfy NACK retransmits from the peer's {@link FragmentAssembler}.
- *
- * Lifecycle:
- *   1. {@link retain} — called on each fragmented send; copies the source
- *      bytes into the retention so they're available to retransmit. If
- *      the per-peer slot cap is hit, the oldest retained entry is FIFO-
- *      evicted.
- *   2. {@link consume_nack} — looks up retained bytes for a NACK target
- *      and bumps the retry counter. Returns `null` if the entry is gone
- *      (aged out, evicted, or out of retry budget — in which case the
- *      entry is dropped here too).
- *   3. {@link service} — call once per tick to age out entries older
- *      than `max_age_ms`.
- *   4. {@link clear} — drop everything; call on peer disconnect.
- *
- * Memory cost: each retained entry holds a fresh copy of its source
- * payload (the upstream send buffer is a reused scratch). With the
- * default 16 slots × up-to-64 KiB cap on the receiver, worst case is
- * 1 MiB per peer; steady-state is empty because steady traffic fits in
- * one packet and bypasses fragmentation.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class FragmentRetention {
-    #entries;
-    /**
-     * FIFO of message_ids in insertion order, for eviction on
-     * overflow and for monotonic age-out.
-     * @type {number[]}
-     * @private
-     */
-    #order = [];
-
-    /**
-     * @param {{
-     *   max_messages?: number,
-     *   max_age_ms?: number,
-     *   max_retries?: number,
-     * }} [options]
-     *   `max_messages` caps simultaneously-retained messages; oldest is
-     *   FIFO-evicted on overflow. `max_age_ms` is the per-entry TTL.
-     *   `max_retries` caps how many NACK retransmit rounds a single
-     *   retained message can satisfy before being dropped.
-     */
-    constructor({
-        max_messages = FRAGMENT_RETENTION_MAX_MESSAGES,
-        max_age_ms = FRAGMENT_RETENTION_MAX_AGE_MS,
-        max_retries = FRAGMENT_RETENTION_MAX_RETRIES,
-    } = {}) {
-        assert.isPositiveInteger(max_messages, 'max_messages');
-        assert.isPositiveInteger(max_age_ms, 'max_age_ms');
-        assert.isNonNegativeInteger(max_retries, 'max_retries');
-
-        /** @type {number} @readonly */
-        this.max_messages = max_messages;
-        /** @type {number} @readonly */
-        this.max_age_ms = max_age_ms;
-        /** @type {number} @readonly */
-        this.max_retries = max_retries;
-
-        /**
-         * message_id → retained entry. `payload` is a fresh copy
-         * (independent of the caller's send buffer).
-         * @type {Map<number, {payload: Uint8Array, length: number, sent_at: number, retries: number}>}
-         * @private
-         */
-        this.#entries = new Map();
-    }
-
-    /**
-     * Copy `payload[0..length)` into retention under `message_id`.
-     * Evicts the oldest retained entry if `max_messages` is exceeded.
-     *
-     * If a retained entry already exists for `message_id` (only legitimate
-     * cause: uint16 wrap), the old entry is dropped first so the FIFO
-     * position and retry budget restart from the new send.
-     *
-     * @param {number} message_id
-     * @param {Uint8Array} payload  source bytes (caller may overwrite after return)
-     * @param {number} length       number of bytes from `payload[0]` to copy
-     * @param {number} now_ms       monotonic timestamp for age-out
-     */
-    retain(message_id, payload, length, now_ms) {
-        assert.isNonNegativeInteger(message_id, 'message_id');
-        assert.isNonNegativeInteger(length, 'length');
-        assert.isNumber(now_ms, 'now_ms');
-
-        if (this.#entries.has(message_id)) {
-            this.#delete(message_id);
-        }
-        if (this.#entries.size >= this.max_messages) {
-            const oldest = this.#order.shift();
-            if (oldest !== undefined) this.#entries.delete(oldest);
-        }
-        const copy = new Uint8Array(length);
-        copy.set(payload.subarray(0, length));
-        this.#entries.set(message_id, {
-            payload: copy,
-            length,
-            sent_at: now_ms,
-            retries: 0,
-        });
-        this.#order.push(message_id);
-    }
-
-    /**
-     * Mark a NACK round for `message_id` and return the retained entry
-     * so the caller can re-emit the missing chunks. Returns `null` if
-     * no entry exists, or if the per-message retry budget is now
-     * exhausted (in which case the entry is dropped).
-     *
-     * @param {number} message_id
-     * @returns {{payload: Uint8Array, length: number}|null}
-     */
-    consume_nack(message_id) {
-        assert.isNonNegativeInteger(message_id, 'message_id');
-        const entry = this.#entries.get(message_id);
-        if (entry === undefined) return null;
-        entry.retries++;
-        if (entry.retries > this.max_retries) {
-            this.#delete(message_id);
-            return null;
-        }
-        return entry;
-    }
-
-    /**
-     * Per-tick maintenance: evict any entry older than `max_age_ms`.
-     *
-     * The FIFO is in strict insertion order, so we can stop at the first
-     * still-fresh entry rather than scanning the whole map.
-     *
-     * @param {number} now_ms
-     */
-    service(now_ms) {
-        assert.isNumber(now_ms, 'now_ms');
-        while (this.#order.length > 0) {
-            const id = this.#order[0];
-            const entry = this.#entries.get(id);
-            if (entry === undefined) {
-                this.#order.shift();
-                continue;
-            }
-            if (now_ms - entry.sent_at < this.max_age_ms) break;
-            this.#order.shift();
-            this.#entries.delete(id);
-        }
-    }
-
-    /**
-     * Number of currently-retained messages.
-     * @returns {number}
-     */
-    size() {
-        return this.#entries.size;
-    }
-
-    /**
-     * Whether `message_id` is currently retained.
-     * @param {number} message_id
-     * @returns {boolean}
-     */
-    has(message_id) {
-        return this.#entries.has(message_id);
-    }
-
-    /**
-     * Drop every retained entry. Use on peer disconnect.
-     */
-    clear() {
-        this.#entries.clear();
-        this.#order.length = 0;
-    }
-
-    /** @private */
-    #delete(message_id) {
-        this.#entries.delete(message_id);
-        const idx = this.#order.indexOf(message_id);
-        if (idx >= 0) this.#order.splice(idx, 1);
-    }
-}

package/src/engine/network/transport/fragments/fragment_send.js

@@ -1,157 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import {
-    FRAGMENT_HEADER_BYTES,
-    MAX_CHANNEL_PAYLOAD_BYTES,
-    MAX_CHUNKS_PER_MESSAGE,
-    MAX_FRAGMENT_CHUNK_BYTES,
-} from "./packet_size.js";
-
-/**
- * Send a logical payload through a callback, splitting into fragment
- * packets if it exceeds the channel's single-packet capacity.
- *
- * Layout of each emitted fragment packet (before the Channel adds its
- * 8-byte header):
- *
- *   uint8   FRAGMENT_PACKET_TYPE
- *   uint16  message_id   (little-endian)
- *   uint8   chunk_index
- *   uint8   total_chunks
- *   bytes   chunk_payload
- *
- * The chunk_payload bytes are slices of the original logical payload,
- * concatenated in chunk_index order they reconstruct the original
- * payload byte-for-byte. The logical payload's own packet-type byte is
- * the first byte of chunk 0 and is preserved by the reassembly.
- *
- * Single-packet messages (payload <= MAX_CHANNEL_PAYLOAD_BYTES) are sent
- * as-is with NO fragmentation header — the receiver dispatches them
- * normally via the FIRST byte. Fragmentation overhead only applies when
- * the payload genuinely doesn't fit.
- *
- * @param {Uint8Array} payload
- * @param {number} payload_length
- * @param {number} message_id  sender-assigned, unique per logical message
- * @param {number} fragment_packet_type  packet-type byte for fragment packets
- * @param {Uint8Array} scratch  reusable scratch buffer; must be >= MAX_CHANNEL_PAYLOAD_BYTES
- * @param {function(Uint8Array, number): void} send_fn
- *   invoked once per emitted packet — single send for non-fragmented case,
- *   N sends for fragmented case
- */
-export function send_fragmented(
-    payload,
-    payload_length,
-    message_id,
-    fragment_packet_type,
-    scratch,
-    send_fn,
-) {
-    assert.isNonNegativeInteger(payload_length, 'payload_length');
-    assert.isNonNegativeInteger(message_id, 'message_id');
-    assert.ok(message_id <= 0xFFFF, 'message_id must fit in uint16');
-    assert.ok(scratch.length >= MAX_CHANNEL_PAYLOAD_BYTES,
-        'scratch buffer must be at least MAX_CHANNEL_PAYLOAD_BYTES');
-
-    if (payload_length <= MAX_CHANNEL_PAYLOAD_BYTES) {
-        // Fits in one packet; send as-is.
-        send_fn(payload, payload_length);
-        return;
-    }
-
-    const total_chunks = Math.ceil(payload_length / MAX_FRAGMENT_CHUNK_BYTES);
-    if (total_chunks > MAX_CHUNKS_PER_MESSAGE) {
-        throw new Error(
-            `send_fragmented: payload of ${payload_length} bytes would require ` +
-            `${total_chunks} chunks, exceeding the ${MAX_CHUNKS_PER_MESSAGE}-chunk wire limit`
-        );
-    }
-
-    for (let i = 0; i < total_chunks; i++) {
-        const chunk_offset = i * MAX_FRAGMENT_CHUNK_BYTES;
-        const remaining = payload_length - chunk_offset;
-        const chunk_size = remaining < MAX_FRAGMENT_CHUNK_BYTES ? remaining : MAX_FRAGMENT_CHUNK_BYTES;
-
-        // Build the fragment packet inside scratch.
-        scratch[0] = fragment_packet_type;
-        scratch[1] = message_id & 0xFF;
-        scratch[2] = (message_id >> 8) & 0xFF;
-        scratch[3] = i;
-        scratch[4] = total_chunks;
-        scratch.set(
-            payload.subarray(chunk_offset, chunk_offset + chunk_size),
-            FRAGMENT_HEADER_BYTES,
-        );
-
-        send_fn(scratch, FRAGMENT_HEADER_BYTES + chunk_size);
-    }
-}
-
-/**
- * Number of chunks {@link send_fragmented} splits a payload of `payload_length` bytes into — the
- * chunk indices a receiver may ask to have re-sent are `[0, count)`.
- *
- * @param {number} payload_length
- * @returns {number}
- */
-export function fragment_chunk_count(payload_length) {
-    // Payloads short enough to not fragment in the first place are never
-    // retained, so the 1 is defensive consistency rather than a real case.
-    return payload_length <= MAX_FRAGMENT_CHUNK_BYTES
-        ? 1
-        : Math.ceil(payload_length / MAX_FRAGMENT_CHUNK_BYTES);
-}
-
-/**
- * Re-emit a single fragment chunk for a previously-sent fragmented
- * message. Used by the NACK retransmit path: the sender's
- * {@link FragmentRetention} keeps the source bytes so any chunk can be
- * deterministically rebuilt.
- *
- * The wire layout matches what {@link send_fragmented} would have
- * produced for the same `(message_id, chunk_index, total_chunks)` —
- * receivers can't tell a retransmit from an original.
- *
- * @param {Uint8Array} payload  retained source bytes
- * @param {number} payload_length
- * @param {number} message_id
- * @param {number} chunk_index  must be < derived total_chunks; silently ignored otherwise
- * @param {number} fragment_packet_type
- * @param {Uint8Array} scratch  reusable scratch; must be >= MAX_CHANNEL_PAYLOAD_BYTES
- * @param {function(Uint8Array, number): void} send_fn
- */
-export function resend_fragment_chunk(
-    payload,
-    payload_length,
-    message_id,
-    chunk_index,
-    fragment_packet_type,
-    scratch,
-    send_fn,
-) {
-    assert.isNonNegativeInteger(payload_length, 'payload_length');
-    assert.isNonNegativeInteger(message_id, 'message_id');
-    assert.ok(message_id <= 0xFFFF, 'message_id must fit in uint16');
-    assert.isNonNegativeInteger(chunk_index, 'chunk_index');
-    assert.ok(scratch.length >= MAX_CHANNEL_PAYLOAD_BYTES,
-        'scratch buffer must be at least MAX_CHANNEL_PAYLOAD_BYTES');
-
-    // Recover total_chunks from the retained payload length.
-    const total_chunks = fragment_chunk_count(payload_length);
-    if (chunk_index >= total_chunks) return;
-
-    const chunk_offset = chunk_index * MAX_FRAGMENT_CHUNK_BYTES;
-    const remaining = payload_length - chunk_offset;
-    const chunk_size = remaining < MAX_FRAGMENT_CHUNK_BYTES ? remaining : MAX_FRAGMENT_CHUNK_BYTES;
-
-    scratch[0] = fragment_packet_type;
-    scratch[1] = message_id & 0xFF;
-    scratch[2] = (message_id >> 8) & 0xFF;
-    scratch[3] = chunk_index;
-    scratch[4] = total_chunks;
-    scratch.set(
-        payload.subarray(chunk_offset, chunk_offset + chunk_size),
-        FRAGMENT_HEADER_BYTES,
-    );
-
-    send_fn(scratch, FRAGMENT_HEADER_BYTES + chunk_size);
-}

package/src/engine/network/transport/fragments/packet_size.js

@@ -1,107 +0,0 @@
-/**
- * Packet-size constants for the fragmentation layer.
- *
- * The target transport MTU is 1200 bytes (Quake / Source / Glenn Fiedler's
- * Networked Physics recommend ~1200 to stay under typical PMTU after IP/UDP
- * headers; ethernet 1500 - 40 IPv6 - 8 UDP = 1452 in the best case, but
- * intermediate hops with tunnelling, IPv6 extension headers, or DSLite
- * routinely shave this down — 1200 is the safe number).
- *
- * Above this, the application's logical payload must be split into chunks
- * via {@link send_fragmented} and reassembled on the receiver via
- * {@link FragmentAssembler}.
- *
- * Header overhead breakdown for a fragment packet, from the transport's
- * point of view:
- *   - {@link Channel} adds 9 bytes (seq + ack_latest + ack_bitfield + ack_present).
- *   - The FRAGMENT packet type byte = 1 byte.
- *   - Fragment header (message_id uint16 + chunk_index uint8 + total_chunks
- *     uint8) = 4 bytes.
- * Total overhead per fragment = 14 bytes; payload capacity per fragment =
- * 1200 - 14 = 1186 bytes.
- *
- * For a logical message that fits in a single packet (no fragmentation
- * needed), only the Channel header overhead applies — the payload starts
- * with its own packet-type byte (e.g. ACTION_STREAM) and is sent directly.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/** Target transport MTU. */
-export const MTU_BYTES = 1200;
-
-/** Channel layer's per-packet header size. Must match {@link Channel}'s HEADER_SIZE. */
-export const CHANNEL_HEADER_BYTES = 9;
-
-/**
- * Bytes the Channel reserves for the actual payload (no fragmentation):
- * MTU minus the channel header.
- */
-export const MAX_CHANNEL_PAYLOAD_BYTES = MTU_BYTES - CHANNEL_HEADER_BYTES;
-
-/**
- * Fragment header bytes within the channel payload:
- *   - 1 byte for the FRAGMENT packet-type marker
- *   - 2 bytes for message_id (uint16)
- *   - 1 byte for chunk_index (uint8)
- *   - 1 byte for total_chunks (uint8)
- */
-export const FRAGMENT_HEADER_BYTES = 5;
-
-/** Maximum number of payload bytes per fragment packet. */
-export const MAX_FRAGMENT_CHUNK_BYTES = MAX_CHANNEL_PAYLOAD_BYTES - FRAGMENT_HEADER_BYTES;
-
-/** Maximum number of chunks in a single logical message (limited by uint8 total_chunks). */
-export const MAX_CHUNKS_PER_MESSAGE = 255;
-
-/** Largest single logical payload supportable by this fragmentation scheme. */
-export const MAX_LOGICAL_MESSAGE_BYTES = MAX_FRAGMENT_CHUNK_BYTES * MAX_CHUNKS_PER_MESSAGE;
-
-/**
- * NACK retransmit timing.
- *
- *   FRAGMENT_NACK_INITIAL_DELAY_MS  — how long the receiver waits after the
- *     first chunk of a message arrives before NACKing the missing chunks.
- *     Trades off latency-of-recovery against premature NACKs for chunks
- *     that were just slightly late.
- *   FRAGMENT_NACK_RESEND_INTERVAL_MS — period between NACK retries when a
- *     message remains incomplete.
- *   FRAGMENT_NACK_MAX_ROUNDS — after this many NACK rounds without
- *     completion, the receiver drops the message; the sender's retention
- *     ages out independently.
- *
- * 75 ms initial delay is sized for the consumer mobile RTT bands measured
- * across US / EU / China in 2024–2025: 5G median 15–45 ms, 4G median
- * 30–55 ms, per-path jitter <10 ms for the majority of long-lived
- * connections. 75 ms sits comfortably above worst-case (4G median + jitter
- * + wire time for a small burst) so legitimate stragglers land before the
- * NACK fires, while keeping recovery latency on real loss to ~75 ms + 1
- * RTT. On worst-case paths the receiver may occasionally NACK chunks
- * still in transit; the receiver-side dedup absorbs the duplicate
- * retransmits.
- */
-export const FRAGMENT_NACK_INITIAL_DELAY_MS = 75;
-export const FRAGMENT_NACK_RESEND_INTERVAL_MS = 75;
-export const FRAGMENT_NACK_MAX_ROUNDS = 3;
-
-/**
- * Sender-side retention bounds. The sender keeps a copy of each fragmented
- * message's bytes so it can satisfy NACK retransmits. Retention is
- * FIFO-evicted at `FRAGMENT_RETENTION_MAX_MESSAGES` and age-evicted at
- * `FRAGMENT_RETENTION_MAX_AGE_MS`.
- *
- * Worst-case memory per peer: `FRAGMENT_RETENTION_MAX_MESSAGES *
- * max_message_size` bytes. With the FragmentAssembler default of 64 KiB,
- * that's 1 MiB per peer at saturation; steady-state retention is empty
- * because steady traffic fits in one packet and bypasses fragmentation.
- *
- * `FRAGMENT_RETENTION_MAX_RETRIES` is how many NACKs a retained message is
- * repaired for. A NACK re-sends each chunk of the message at most once, so
- * whatever a peer asks, repair costs at most this many copies of a message
- * the sender chose to send. It matches the receiver's
- * `FRAGMENT_NACK_MAX_ROUNDS`: an honest receiver never asks more often.
- */
-export const FRAGMENT_RETENTION_MAX_AGE_MS = 1500;
-export const FRAGMENT_RETENTION_MAX_MESSAGES = 16;
-export const FRAGMENT_RETENTION_MAX_RETRIES = 3;