@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -0,0 +1,191 @@
+/**
+ * Reliable lanes. Each is an ordered stream of messages; the lanes are independent of each other.
+ */
+export type Lane = number;
+/**
+ * Reliable lanes. Each is an ordered stream of messages; the lanes are independent of each other.
+ * @readonly
+ * @enum {number}
+ */
+export const Lane: Readonly<{
+    /** Engine control messages, one datagram each: resume answers, DISCONNECT. Not paced. */
+    CONTROL: 0;
+    /**
+     * Action-stream frames too large for a datagram. Not paced: the stream to the peer waits on
+     * them, and it cannot wait longer than its action log's ring.
+     */
+    FRAMES: 1;
+    /** Application messages that must arrive. Paced. */
+    USER: 2;
+    /** Large transfers: snapshot pages, state bursts. Paced, last. */
+    BULK: 3;
+}>;
+/**
+ * One connection to one peer over a datagram {@link Transport}: numbered packets acknowledged by
+ * ranges, unreliable messages of up to a datagram with a delivery notice each, and reliable lanes
+ * that carry messages of any size up to `max_message_bytes`, paced by a token bucket.
+ *
+ * Everything queued goes out on {@link flush}, packed into as few datagrams as fit. Everything
+ * received is handled inside the transport's receive callback. Time is whatever `clock` says; the
+ * connection never reads a clock of its own.
+ *
+ * The design is in `network/MESSAGE_TRANSPORT.md`. Loss detection, RTT and the probe timeout follow
+ * QUIC (RFC 9002), packet numbers and ACK ranges RFC 9000.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Connection {
+    /**
+     * @param {{
+     *   transport: { send(bytes: Uint8Array, length: number): void, onReceive: Signal, max_datagram_bytes?: number },
+     *   clock: function(): number,
+     *   send_rate_bytes_per_second: number,
+     *   max_message_bytes: number,
+     *   receive_window_bytes: number,
+     *   max_queued_bytes: number,
+     *   max_ack_delay_ms: number,
+     *   max_ack_ranges?: number,
+     * }} options
+     *   `clock` returns milliseconds and never runs backwards. `send_rate_bytes_per_second` paces
+     *   the BULK lane. `max_message_bytes` is the largest reliable message either side may send;
+     *   both ends must agree. `receive_window_bytes` bounds what each reliable lane may have in
+     *   flight past its acknowledged prefix, and so what a receiver holds out of order. Both ends
+     *   must agree on these two; a peer that exceeds them is a protocol error.
+     *   `max_queued_bytes` caps what one lane may hold unacknowledged: past it,
+     *   {@link send_reliable} throws rather than grow without bound.
+     *   `max_ack_delay_ms` is how long this side may sit on an ACK and the resolution of its
+     *   clock: its tick period. `max_ack_ranges` is how many ranges this side's ACKs report, at
+     *   most 64.
+     *
+     *   A transport that is itself reliable (`transport.reliable`, e.g. a WebSocket) delivers
+     *   every packet: nothing is declared lost and nothing is probed, or a stalled TCP stream
+     *   would be fed duplicates behind the originals.
+     */
+    constructor({ transport, clock, send_rate_bytes_per_second, max_message_bytes, receive_window_bytes, max_queued_bytes, max_ack_delay_ms, max_ack_ranges, }: {
+        transport: {
+            send(bytes: Uint8Array, length: number): void;
+            onReceive: Signal;
+            max_datagram_bytes?: number;
+        };
+        clock: () => number;
+        send_rate_bytes_per_second: number;
+        max_message_bytes: number;
+        receive_window_bytes: number;
+        max_queued_bytes: number;
+        max_ack_delay_ms: number;
+        max_ack_ranges?: number;
+    });
+    /** @type {number} @readonly */
+    readonly max_message_bytes: number;
+    /**
+     * Largest unreliable message: what fits one datagram after the packet and frame headers.
+     * @type {number} @readonly
+     */
+    readonly max_unreliable_message_bytes: number;
+    /**
+     * A message arrived: `(bytes, offset, length)`. `bytes` is the connection's or the
+     * transport's buffer, valid for the duration of the call only.
+     * @type {Signal}
+     */
+    onMessage: Signal;
+    /**
+     * An unreliable message sent with a token arrived: `(token)`.
+     * @type {Signal}
+     */
+    onMessageAcked: Signal;
+    /**
+     * An unreliable message sent with a token was lost: `(token)`. Lost means not confirmed:
+     * a message whose packet arrived but whose acknowledgement never got through — every ACK
+     * that could report it lost, or crowded out by newer ranges — is reported lost, as QUIC
+     * does.
+     * @type {Signal}
+     */
+    onMessageLost: Signal;
+    /**
+     * A datagram that does not parse, or is of another protocol version, was dropped whole and
+     * unacknowledged: `(reason)`. The connection carries on; anyone can send a stray datagram.
+     * @type {Signal}
+     */
+    onMalformedDatagram: Signal;
+    /**
+     * The connection is no longer whole: `(reason)`. The peer broke the protocol on a reliable
+     * lane — a message longer than `max_message_bytes`, bytes past the receive window, more
+     * holes than a sender keeping to its window makes — and the lane has stopped, so nothing
+     * more will arrive on it; or the peer acknowledged a packet this side never sent, so it
+     * took in a datagram that was not this side's and nothing it acknowledges can be trusted.
+     * The datagram carrying that ACK is dropped, as is every later one that repeats it.
+     *
+     * The connection does not authenticate datagrams: its transport must deliver only the
+     * peer's (DTLS and TLS do; a UDP socket filters by source address). The cure is a new
+     * connection.
+     * @type {Signal}
+     */
+    onProtocolError: Signal;
+    /**
+     * Queue an unreliable message for the next {@link flush}. With `token >= 0` the connection
+     * reports its fate: {@link onMessageAcked} once the packet carrying it is acknowledged, or
+     * {@link onMessageLost} once it is declared lost — exactly one of them.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length at most {@link max_unreliable_message_bytes}
+     * @param {number} token caller's id for the notice, or -1 for none
+     */
+    send_unreliable(bytes: Uint8Array, offset: number, length: number, token: number): void;
+    /**
+     * Queue a reliable message on `lane`. It arrives, whole and in order with the lane's other
+     * messages, unless the connection ends first.
+     *
+     * @param {number} lane one of {@link Lane}
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length at most {@link max_message_bytes}
+     * @returns {number} delivery mark: see {@link is_delivered}
+     */
+    send_reliable(lane: number, bytes: Uint8Array, offset: number, length: number): number;
+    /**
+     * Whether every message on `lane` up to the one whose mark this is has been acknowledged.
+     * @param {number} lane
+     * @param {number} mark from {@link send_reliable}
+     * @returns {boolean}
+     */
+    is_delivered(lane: number, mark: number): boolean;
+    /**
+     * Bytes queued on `lane` the peer has not acknowledged.
+     * @param {number} lane
+     * @returns {number}
+     */
+    unacked_bytes(lane: number): number;
+    /**
+     * Send everything queued that may go now, packed into as few datagrams as fit: the ACK, the
+     * CONTROL lane, unreliable messages, then the BULK lane while the token bucket allows. Also
+     * runs the loss and probe timers.
+     */
+    flush(): void;
+    /** Smoothed round-trip time, ms; RFC 9002's initial 333 ms until the first sample. */
+    get smoothed_rtt(): number;
+    /** Packets sent and not yet acknowledged or declared lost that asked for an ACK. */
+    get in_flight_count(): number;
+    /** Most bytes one reliable lane may hold unacknowledged; {@link send_reliable} throws past it. */
+    get max_queued_bytes(): number;
+    /**
+     * @returns {{packets_sent: number, packets_received: number, packets_lost: number, packets_dropped: number, bytes_sent: number, bytes_received: number}}
+     */
+    getStats(): {
+        packets_sent: number;
+        packets_received: number;
+        packets_lost: number;
+        packets_dropped: number;
+        bytes_sent: number;
+        bytes_received: number;
+    };
+    /**
+     * Stop: no more receiving, and nothing queued will be sent. Call {@link flush} first for a
+     * last send.
+     */
+    dispose(): void;
+    #private;
+}
+import Signal from "../../../../core/events/signal/Signal.js";
+//# sourceMappingURL=Connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Connection.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/connection/Connection.js"],"names":[],"mappings":";;;mBAWU,MAAM;AAHhB;;;;GAIG;AACH;IACI,yFAAyF;;IAEzF;;;OAGG;;IAEH,oDAAoD;;IAEpD,kEAAkE;;GAEnE;AA+DH;;;;;;;;;;;;;;GAcG;AACH;IA+HI;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,4JAzBW;QACV,SAAa,EAAE;YAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACjH,KAAS,QAAc,MAAM,CAAC;QAC9B,0BAA8B,EAAE,MAAM,CAAC;QACvC,iBAAqB,EAAE,MAAM,CAAC;QAC9B,oBAAwB,EAAE,MAAM,CAAC;QACjC,gBAAoB,EAAE,MAAM,CAAC;QAC7B,gBAAoB,EAAE,MAAM,CAAC;QAC7B,cAAkB,CAAC,EAAE,MAAM,CAAC;KACzB,EAuHH;IA7DG,+BAA+B;IAC/B,4BADW,MAAM,CACyB;IAE1C;;;OAGG;IACH,uCAFU,MAAM,CAE+E;IAS/F;;;;OAIG;IACH,WAFU,MAAM,CAEa;IAE7B;;;OAGG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;OAMG;IACH,eAFU,MAAM,CAEiB;IAEjC;;;;OAIG;IACH,qBAFU,MAAM,CAEuB;IAEvC;;;;;;;;;;;;OAYG;IACH,iBAFU,MAAM,CAEmB;IAOvC;;;;;;;;;OASG;IACH,uBALW,UAAU,UACV,MAAM,UACN,MAAM,SACN,MAAM,QAqBhB;IAED;;;;;;;;;OASG;IACH,oBANW,MAAM,SACN,UAAU,UACV,MAAM,UACN,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;OAIG;IACH,cAuCC;IAID,sFAAsF;IACtF,2BAEC;IAED,oFAAoF;IACpF,8BAEC;IAED,kGAAkG;IAClG,+BAEC;IAED;;OAEG;IACH,YAFa;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC,CAIvJ;IAED;;;OAGG;IACH,gBAYC;;CAouBJ;mBA5uCkB,0CAA0C"}