@driftengine/network 3.61.0

package/dist/lockstep.js

@@ -0,0 +1,291 @@
+/**
+ * Every peer simulates every tick, and a wrong guess is unwound.
+ *
+ * **Classic lockstep stalls; this predicts.** The original design waits until every participant's
+ * input for a tick has arrived and only then advances, which makes the whole session run at the
+ * latency of its worst link and turns a single dropped packet into a visible freeze for everyone.
+ * With a rewind loop underneath, a missing input can be guessed and corrected — so the session runs
+ * at local speed and pays for a wrong guess only when the guess was wrong.
+ *
+ * ---
+ *
+ * ## The input delay, and why it is not just latency tolerance
+ *
+ * A local input for tick *T* is published for tick *T + delay*. That buys `delay` ticks for it to
+ * reach everyone before anybody needs it, so on a link inside that budget **nobody predicts and
+ * nobody rewinds** — the session is exact, not merely convergent.
+ *
+ * What it costs is that a player's own control is `delay` ticks late on their own screen. That is a
+ * real cost and it is a game's to choose: two ticks is 33 ms and unnoticeable in a racing game,
+ * and unacceptable in a fighting game where it is the whole argument for rollback.
+ *
+ * ## Halting is a feature
+ *
+ * Two things stop the session rather than degrade it, because both mean the local world can no
+ * longer be made correct:
+ *
+ * - **An input arrives for a tick outside the rewind window.** It cannot be applied, so this peer's
+ *   world is permanently different from the one that input describes.
+ * - **A fingerprint disagrees at a confirmed tick.** Two peers computed different worlds from the
+ *   same inputs, which is a determinism bug rather than a networking one, and continuing produces
+ *   two games that both believe they are right.
+ *
+ * A session that carried on would be showing each player a plausible world with no relationship to
+ * anyone else's. Halting names the tick, which is where the debugging starts.
+ */
+import { Fingerprint } from './fingerprint.js';
+import { BROADCAST } from './transport.js';
+import { MESSAGE_FINGERPRINT, MESSAGE_INPUT, createDecoded, decode, encodeFingerprint, encodeInput, } from './wire.js';
+export class LockstepSession {
+    self;
+    participants;
+    inputDelay;
+    transport;
+    loop;
+    inputs;
+    fingerprintEvery;
+    compareStates;
+    /** One buffer for the process. Sized for the largest message this session sends. */
+    outgoing;
+    /** The last `redundancy` inputs this peer submitted, oldest first, flat. */
+    recent;
+    redundancy;
+    /** The tick the first payload in `recent` belongs to, or -1 before anything is submitted. */
+    recentFrom = -1;
+    recentCount = 0;
+    decoded = createDecoded();
+    scratchDigest = new Fingerprint();
+    /** Digests we published, by tick, so a peer's claim has something to be compared against. */
+    ourDigests = new Map();
+    statusValue = 'running';
+    desyncValue = null;
+    haltReason = '';
+    confirmedValue = -1;
+    /**
+     * The highest tick this world has ever had every participant's real input for.
+     *
+     * **Separate from `confirmedValue`, and monotonic where that one is not.** `confirmedThrough`
+     * answers for the window the log currently holds, and the session moves that window forward every
+     * tick — so the moment retention passes a tick, the log stops being able to say anything about it
+     * and the live watermark can drop. What was applied stays applied, which is the fact a redundant
+     * copy has to be judged against, so it is kept here rather than asked of the log.
+     */
+    appliedThrough = -1;
+    constructor(options) {
+        this.transport = options.transport;
+        this.loop = options.loop;
+        this.inputs = options.inputs;
+        this.self = options.self;
+        this.participants = Math.max(1, options.participants);
+        this.inputDelay = Math.max(0, Math.trunc(options.inputDelay ?? 2));
+        this.fingerprintEvery = Math.max(1, Math.trunc(options.fingerprintEvery ?? 8));
+        this.compareStates = options.compareStates ?? true;
+        this.redundancy = Math.max(1, Math.trunc(options.redundancy ?? 4));
+        this.recent = new Uint8Array(this.redundancy * this.inputs.inputBytes);
+        this.outgoing = new Uint8Array(64 + this.redundancy * this.inputs.inputBytes);
+    }
+    get status() {
+        return this.statusValue;
+    }
+    /** Why the session halted, or an empty string. */
+    get reason() {
+        return this.haltReason;
+    }
+    /** The disagreement that halted it, naming the tick it began at. */
+    get desync() {
+        return this.desyncValue;
+    }
+    /** The highest tick every participant's real input has arrived for. */
+    get confirmed() {
+        return this.confirmedValue;
+    }
+    /**
+     * Publish this peer's input for `tick + inputDelay`, and record it locally at the same tick.
+     *
+     * **Recorded locally as well as sent, and that is not redundancy.** A peer's own input is not
+     * echoed back to it, so without this the local simulation would predict its own controls — and a
+     * player would feel their own input arrive late and get corrected, which is the one thing
+     * prediction is supposed to prevent.
+     */
+    submit(tick, payload) {
+        if (this.statusValue !== 'running')
+            return;
+        const at = tick + this.inputDelay;
+        if (!this.inputs.holds(at)) {
+            this.halt(`an input for tick ${at} is outside the log's window`);
+            return;
+        }
+        this.inputs.set(this.self, at, payload);
+        this.remember(at, payload);
+        const length = encodeInput(this.outgoing, this.self, this.recentFrom, this.recent, this.inputs.inputBytes, this.recentCount);
+        if (length < 0) {
+            this.halt(`an input of ${payload.length} bytes does not fit this session's buffer`);
+            return;
+        }
+        this.transport.send(BROADCAST, this.outgoing.subarray(0, length));
+    }
+    /**
+     * Keep this input, and the few before it, for the next packet to carry.
+     *
+     * Shifted rather than kept in a ring, because the run has to be **contiguous and in order** on
+     * the wire: a receiver reads it as "these are the inputs for ticks `firstTick` onward", and a ring
+     * would have to be unwrapped before sending anyway. `redundancy` is four, so the shift is three
+     * copies of a handful of bytes.
+     */
+    remember(tick, payload) {
+        const stride = this.inputs.inputBytes;
+        /* A gap — a tick submitted out of order, or the first one — restarts the run. */
+        if (this.recentFrom < 0 || tick !== this.recentFrom + this.recentCount) {
+            this.recentFrom = tick;
+            this.recentCount = 0;
+        }
+        if (this.recentCount === this.redundancy) {
+            this.recent.copyWithin(0, stride);
+            this.recentFrom += 1;
+            this.recentCount -= 1;
+        }
+        const at = this.recentCount * stride;
+        for (let i = 0; i < stride; i++)
+            this.recent[at + i] = payload[i] ?? 0;
+        this.recentCount += 1;
+    }
+    /**
+     * Take everything the transport has and apply it.
+     *
+     * Called once per tick, before advancing. Never from a transport callback — see `transport.ts`
+     * for why a message must not arrive in the middle of a step.
+     */
+    poll() {
+        if (this.statusValue !== 'running')
+            return;
+        this.transport.drain((from, message) => this.receive(from, message));
+    }
+    /**
+     * Advance one tick, then publish a fingerprint if this is a tick to publish one at.
+     *
+     * The rewind loop performs any pending correction first, so a late input that arrived during
+     * `poll` is applied before this tick runs rather than after it.
+     */
+    advance(dt, tick) {
+        if (this.statusValue !== 'running')
+            return;
+        this.loop.advance(dt, tick);
+        this.confirmedValue = this.inputs.confirmedThrough(tick);
+        if (this.confirmedValue > this.appliedThrough)
+            this.appliedThrough = this.confirmedValue;
+        /* Everything below the oldest tick a rewind can reach is never needed again. */
+        const earliest = this.loop.earliest;
+        if (earliest > 0)
+            this.inputs.retain(earliest);
+        this.publishDigest();
+    }
+    /**
+     * Publish a hash of the state at a **confirmed** tick, which is the only state worth comparing.
+     *
+     * **Not the live world, and this cost a healthy session at tick 32 during development.** The
+     * newest tick is speculative: each peer has predicted inputs the other already knows, so their
+     * live worlds differ constantly and correctly. A snapshot at a tick every participant's input has
+     * arrived for was computed from the same inputs on both ends, and a disagreement there is a real
+     * one.
+     *
+     * The slot for tick *T* holds the state as *T* began, so it is final once every input below *T*
+     * is confirmed — which is what `confirmedThrough` answers.
+     */
+    publishDigest() {
+        if (!this.compareStates)
+            return;
+        const at = this.confirmedValue;
+        if (at < 0 || at % this.fingerprintEvery !== 0)
+            return;
+        if (this.ourDigests.has(at))
+            return;
+        const digest = this.loop.digestOf(at);
+        if (digest === null)
+            return;
+        this.ourDigests.set(at, digest);
+        this.forgetDigestsBefore(this.loop.earliest);
+        const length = encodeFingerprint(this.outgoing, this.self, at, digest);
+        if (length > 0)
+            this.transport.send(BROADCAST, this.outgoing.subarray(0, length));
+    }
+    /** Stop the session with a reason. Public so a consumer can halt on their own condition. */
+    halt(reason) {
+        if (this.statusValue === 'halted')
+            return;
+        this.statusValue = 'halted';
+        this.haltReason = reason;
+    }
+    receive(from, message) {
+        if (!decode(message, this.decoded))
+            return;
+        if (this.decoded.kind === MESSAGE_INPUT) {
+            const participant = this.decoded.participant;
+            if (participant === this.self)
+                return;
+            const stride = this.decoded.payloadBytes;
+            for (let i = 0; i < this.decoded.count; i++) {
+                const tick = this.decoded.tick + i;
+                const at = this.decoded.payloadAt + i * stride;
+                const payload = message.subarray(at, at + stride);
+                /*
+                 * **A tick already past the window is skipped rather than fatal, when the rest of the run
+                 * is still usable.** Redundancy means most of what arrives is a repeat, and the oldest entry
+                 * of a run naturally falls out of the window first — halting on that would end every
+                 * session the moment the redundancy window outran the rewind window. What is fatal is an
+                 * input this peer never had and can no longer apply, which is the case below.
+                 */
+                if (this.inputs.isConfirmed(participant, tick))
+                    continue;
+                /*
+                 * **And the same skip for a tick the log can no longer answer for, which is the common
+                 * case rather than the edge one.** `isConfirmed` speaks for the window the log holds, and
+                 * retention drops everything below the oldest tick a rewind can reach — so on any session
+                 * whose redundancy reaches further back than that, the oldest word of a run arrives after
+                 * the slot that would have recognised it is gone, and a link that lost nothing halts.
+                 * A tick at or below this watermark had every participant's real input and was stepped
+                 * with it: a second copy cannot change this world and so cannot be evidence of a
+                 * divergence. Above the watermark nothing changes, halt included, and there it is right —
+                 * an input this peer never had and can no longer apply really is fatal.
+                 */
+                if (tick <= this.appliedThrough)
+                    continue;
+                if (this.loop.supply(participant, tick, payload))
+                    continue;
+                if (!this.inputs.holds(tick)) {
+                    this.halt(`an input from peer ${participant} for tick ${tick} arrived after the rewind window ` +
+                        'had passed it, so this world can no longer be made to match theirs');
+                    return;
+                }
+            }
+            return;
+        }
+        if (this.decoded.kind === MESSAGE_FINGERPRINT) {
+            const ours = this.ourDigests.get(this.decoded.tick);
+            /* A tick we never published a digest for, or have already forgotten. Not a disagreement. */
+            if (ours === undefined)
+                return;
+            if (ours === this.decoded.digest)
+                return;
+            this.desyncValue = {
+                tick: this.decoded.tick,
+                peer: from === BROADCAST ? this.decoded.participant : from,
+                ours,
+                theirs: this.decoded.digest,
+            };
+            this.halt(`state diverged at tick ${this.decoded.tick}: this peer has ${ours}, peer ` +
+                `${this.decoded.participant} has ${this.decoded.digest}`);
+        }
+    }
+    forgetDigestsBefore(tick) {
+        if (tick <= 0)
+            return;
+        for (const at of this.ourDigests.keys()) {
+            if (at < tick)
+                this.ourDigests.delete(at);
+        }
+    }
+    /** The shared digest builder, for a consumer whose `digestAt` wants one without allocating. */
+    get digestBuilder() {
+        return this.scratchDigest;
+    }
+}

package/dist/loopback.d.ts

@@ -0,0 +1,115 @@
+/**
+ * A transport with no network, and a link you can make as bad as you like on purpose.
+ *
+ * **This is the load-bearing piece of the whole track's testing.** A rollback test run against a
+ * real network is not a test: it cannot be run twice, a failure cannot be reproduced, and a green
+ * result says only that this minute's conditions did not happen to trigger anything. Every
+ * interesting property here — that a late input replays to the same world, that a lockstep pair
+ * converges, that a desync is caught at the right tick — needs a link whose every delay, drop and
+ * reordering is decided by a seed.
+ *
+ * Track O's `packages/ai/src/provider/latency.ts` is the precedent, and for the same reason: a
+ * deterministic provider with programmable latency is what made an agent loop testable without a
+ * model behind it.
+ *
+ * ---
+ *
+ * ## Time is supplied, not read
+ *
+ * `advance(ms)` moves this transport's clock. It never reads one. A transport that called
+ * `performance.now()` would make every test depend on how fast the machine running it happened to
+ * be, which is the property that makes a suite flaky on a loaded CI box and green on a laptop.
+ *
+ * ## The generator here is not the engine's
+ *
+ * A small xorshift, deliberately **not** `mulberry32`. The engine's seeded sequence is a frozen
+ * promise about stored replays and ghosts; this is a test instrument's schedule. Sharing the
+ * algorithm would invite somebody to assume the two are related, and the day one of them has to
+ * change, the other would be dragged along.
+ */
+import { type MessageSink, type PeerId, type Transport, type TransportState } from './transport.ts';
+export interface Impairment {
+    /** One-way delay in milliseconds, before jitter. */
+    readonly latencyMs?: number;
+    /** Delay varies uniformly by ± this many milliseconds. */
+    readonly jitterMs?: number;
+    /** Fraction of messages dropped, 0 to 1. */
+    readonly loss?: number;
+    /** Fraction of messages delivered a further `reorderMs` late, which is what reorders them. */
+    readonly reorder?: number;
+    readonly reorderMs?: number;
+    /** Fraction of messages delivered twice. */
+    readonly duplicate?: number;
+}
+export interface LoopbackOptions {
+    readonly self: PeerId;
+    readonly impairment?: Impairment;
+    /** Anything reproducible. The same seed gives the same delivery schedule, exactly. */
+    readonly seed?: number;
+}
+interface Pending {
+    from: PeerId;
+    to: PeerId;
+    at: number;
+    bytes: Uint8Array;
+    live: boolean;
+}
+/**
+ * A set of endpoints that can reach each other, holding the clock they share.
+ *
+ * The network owns the clock rather than each endpoint owning one, because two endpoints whose
+ * clocks advanced separately would let a test deliver a message before it was sent.
+ */
+export declare class LoopbackNetwork {
+    private readonly endpoints;
+    private nowMs;
+    get now(): number;
+    /** Make an endpoint. Its impairment is its own, so a link can be bad in one direction only. */
+    open(options: LoopbackOptions): LoopbackTransport;
+    /**
+     * Move the shared clock, delivering everything whose time has come.
+     *
+     * Delivery happens in **send order among messages due at the same instant**, which is what makes
+     * a schedule reproducible: two messages with identical arrival times would otherwise be delivered
+     * in whatever order a queue happened to hold them.
+     */
+    advance(ms: number): void;
+    /** Every endpoint, for a caller draining them all. */
+    reach(to: PeerId): LoopbackTransport[];
+}
+export declare class LoopbackTransport implements Transport {
+    readonly self: PeerId;
+    private readonly network;
+    private readonly impairment;
+    private readonly inflight;
+    private readonly arrived;
+    private stateValue;
+    private randomState;
+    /** Sends made, and how many the impairment threw away. For a test asserting the link was bad. */
+    private sentCount;
+    private droppedCount;
+    constructor(network: LoopbackNetwork, options: LoopbackOptions);
+    get state(): TransportState;
+    get sent(): number;
+    get dropped(): number;
+    /**
+     * Queue a message for everyone it is addressed to, impaired.
+     *
+     * **The bytes are copied here and nowhere else.** A caller sending from a reusable buffer — which
+     * every caller in this package does — would otherwise have the buffer overwritten before delivery,
+     * and the message that arrived would be whatever was sent most recently. That bug looks exactly
+     * like a reordering bug and is not one.
+     */
+    send(to: PeerId, message: Uint8Array): void;
+    drain(into: MessageSink): void;
+    close(): void;
+    /** Called by the network. Not for a consumer. */
+    accept(pending: Pending): void;
+    /** Called by the network when the clock moves. Not for a consumer. */
+    deliverDue(nowMs: number): void;
+    /**
+     * A xorshift32 in [0, 1). Deliberately not the engine's generator; see the header.
+     */
+    private random;
+}
+export {};

package/dist/loopback.js

@@ -0,0 +1,207 @@
+/**
+ * A transport with no network, and a link you can make as bad as you like on purpose.
+ *
+ * **This is the load-bearing piece of the whole track's testing.** A rollback test run against a
+ * real network is not a test: it cannot be run twice, a failure cannot be reproduced, and a green
+ * result says only that this minute's conditions did not happen to trigger anything. Every
+ * interesting property here — that a late input replays to the same world, that a lockstep pair
+ * converges, that a desync is caught at the right tick — needs a link whose every delay, drop and
+ * reordering is decided by a seed.
+ *
+ * Track O's `packages/ai/src/provider/latency.ts` is the precedent, and for the same reason: a
+ * deterministic provider with programmable latency is what made an agent loop testable without a
+ * model behind it.
+ *
+ * ---
+ *
+ * ## Time is supplied, not read
+ *
+ * `advance(ms)` moves this transport's clock. It never reads one. A transport that called
+ * `performance.now()` would make every test depend on how fast the machine running it happened to
+ * be, which is the property that makes a suite flaky on a loaded CI box and green on a laptop.
+ *
+ * ## The generator here is not the engine's
+ *
+ * A small xorshift, deliberately **not** `mulberry32`. The engine's seeded sequence is a frozen
+ * promise about stored replays and ghosts; this is a test instrument's schedule. Sharing the
+ * algorithm would invite somebody to assume the two are related, and the day one of them has to
+ * change, the other would be dragged along.
+ */
+import { BROADCAST, } from './transport.js';
+/**
+ * A set of endpoints that can reach each other, holding the clock they share.
+ *
+ * The network owns the clock rather than each endpoint owning one, because two endpoints whose
+ * clocks advanced separately would let a test deliver a message before it was sent.
+ */
+export class LoopbackNetwork {
+    endpoints = new Map();
+    nowMs = 0;
+    get now() {
+        return this.nowMs;
+    }
+    /** Make an endpoint. Its impairment is its own, so a link can be bad in one direction only. */
+    open(options) {
+        const transport = new LoopbackTransport(this, options);
+        this.endpoints.set(options.self, transport);
+        return transport;
+    }
+    /**
+     * Move the shared clock, delivering everything whose time has come.
+     *
+     * Delivery happens in **send order among messages due at the same instant**, which is what makes
+     * a schedule reproducible: two messages with identical arrival times would otherwise be delivered
+     * in whatever order a queue happened to hold them.
+     */
+    advance(ms) {
+        this.nowMs += ms;
+        for (const endpoint of this.endpoints.values())
+            endpoint.deliverDue(this.nowMs);
+    }
+    /** Every endpoint, for a caller draining them all. */
+    reach(to) {
+        if (to !== BROADCAST) {
+            const one = this.endpoints.get(to);
+            return one === undefined ? [] : [one];
+        }
+        return [...this.endpoints.values()];
+    }
+}
+export class LoopbackTransport {
+    self;
+    network;
+    impairment;
+    inflight = [];
+    arrived = [];
+    stateValue = 'open';
+    randomState;
+    /** Sends made, and how many the impairment threw away. For a test asserting the link was bad. */
+    sentCount = 0;
+    droppedCount = 0;
+    constructor(network, options) {
+        this.network = network;
+        this.self = options.self;
+        this.randomState = (options.seed ?? 1) | 0 || 1;
+        const given = options.impairment ?? {};
+        this.impairment = {
+            latencyMs: given.latencyMs ?? 0,
+            jitterMs: given.jitterMs ?? 0,
+            loss: given.loss ?? 0,
+            reorder: given.reorder ?? 0,
+            reorderMs: given.reorderMs ?? 0,
+            duplicate: given.duplicate ?? 0,
+        };
+    }
+    get state() {
+        return this.stateValue;
+    }
+    get sent() {
+        return this.sentCount;
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    /**
+     * Queue a message for everyone it is addressed to, impaired.
+     *
+     * **The bytes are copied here and nowhere else.** A caller sending from a reusable buffer — which
+     * every caller in this package does — would otherwise have the buffer overwritten before delivery,
+     * and the message that arrived would be whatever was sent most recently. That bug looks exactly
+     * like a reordering bug and is not one.
+     */
+    send(to, message) {
+        if (this.stateValue !== 'open')
+            return;
+        this.sentCount += 1;
+        if (this.random() < this.impairment.loss) {
+            this.droppedCount += 1;
+            return;
+        }
+        const copy = message.slice();
+        let delay = this.impairment.latencyMs;
+        if (this.impairment.jitterMs > 0) {
+            delay += (this.random() * 2 - 1) * this.impairment.jitterMs;
+        }
+        if (this.random() < this.impairment.reorder)
+            delay += this.impairment.reorderMs;
+        if (delay < 0)
+            delay = 0;
+        for (const endpoint of this.network.reach(to)) {
+            if (endpoint === this)
+                continue;
+            endpoint.accept({
+                from: this.self,
+                to,
+                at: this.network.now + delay,
+                bytes: copy,
+                live: true,
+            });
+            if (this.random() < this.impairment.duplicate) {
+                endpoint.accept({
+                    from: this.self,
+                    to,
+                    at: this.network.now + delay,
+                    bytes: copy,
+                    live: true,
+                });
+            }
+        }
+    }
+    drain(into) {
+        for (const message of this.arrived)
+            into(message.from, message.bytes);
+        this.arrived.length = 0;
+    }
+    close() {
+        this.stateValue = 'closed';
+        this.inflight.length = 0;
+        this.arrived.length = 0;
+    }
+    /** Called by the network. Not for a consumer. */
+    accept(pending) {
+        if (this.stateValue !== 'open')
+            return;
+        this.inflight.push(pending);
+    }
+    /** Called by the network when the clock moves. Not for a consumer. */
+    deliverDue(nowMs) {
+        if (this.inflight.length === 0)
+            return;
+        /*
+         * Stable by arrival time, then by the order they were queued. Sorting by time alone leaves two
+         * messages due at the same instant in an order the engine's sort happens to choose, and a
+         * schedule that depends on a sort's stability is a schedule that is not reproducible.
+         */
+        let due = 0;
+        for (const pending of this.inflight)
+            if (pending.at <= nowMs)
+                due += 1;
+        if (due === 0)
+            return;
+        const ready = [];
+        const keep = [];
+        for (const pending of this.inflight) {
+            if (pending.at <= nowMs)
+                ready.push(pending);
+            else
+                keep.push(pending);
+        }
+        ready.sort((a, b) => a.at - b.at);
+        this.inflight.length = 0;
+        for (const pending of keep)
+            this.inflight.push(pending);
+        for (const pending of ready)
+            this.arrived.push({ from: pending.from, bytes: pending.bytes });
+    }
+    /**
+     * A xorshift32 in [0, 1). Deliberately not the engine's generator; see the header.
+     */
+    random() {
+        let x = this.randomState;
+        x ^= x << 13;
+        x ^= x >>> 17;
+        x ^= x << 5;
+        this.randomState = x | 0;
+        return ((x >>> 0) % 0x1000000) / 0x1000000;
+    }
+}