@driftengine/network 3.61.0

package/src/snapshotter.ts

@@ -0,0 +1,98 @@
+/**
+ * The snapshotters this package ships, and the composition that makes them enough.
+ *
+ * **A tick's state is rarely one thing.** It is the world, and the generator anything random drew
+ * from, and whatever the consumer keeps outside both. Restoring two of those three is not a rewind;
+ * it is a rewind plus a source of divergence that will not show up until something draws a random
+ * number during a replayed tick. So `combineSnapshotters` exists, and the ordinary shape of a
+ * session is a combination rather than a single snapshotter.
+ */
+import { type WorldSnapshot, type World, createWorldSnapshot } from '@driftengine/entities';
+import { Fingerprint, fingerprintSnapshot } from './fingerprint.ts';
+import type { Snapshotter } from './rewind.ts';
+
+/** A world, through the identity-preserving snapshot `@driftengine/entities` owns. */
+export function worldSnapshotter(world: World): Snapshotter<WorldSnapshot> {
+  const shared = new Fingerprint();
+  return {
+    create: () => createWorldSnapshot(),
+    save: (into) => world.saveInto(into),
+    restore: (from) => world.loadFrom(from),
+    digest: (from) => fingerprintSnapshot(from, shared),
+  };
+}
+
+/**
+ * A seeded generator's position.
+ *
+ * **The shape is declared here and no core type is named**, which is the seam `present/` in
+ * `@driftengine/chemistry` uses for the same reason: this package imports `@driftengine/entities`
+ * and nothing else, so that a deterministic host has no renderer in its module graph.
+ * `savableMulberry32` from core satisfies this structurally.
+ */
+export interface SavablePosition {
+  save(): number;
+  restore(state: number): void;
+}
+
+/**
+ * A generator, as one number.
+ *
+ * **Not restoring this is the classic silent rollback bug.** Everything looks correct until a
+ * replayed tick draws from the generator, gets the *next* number instead of the one it got the
+ * first time, and produces a world that is plausible and different. Nothing in a frame can see it.
+ */
+export function randomSnapshotter(rng: SavablePosition): Snapshotter<{ state: number }> {
+  return {
+    create: () => ({ state: rng.save() }),
+    save: (into) => {
+      into.state = rng.save();
+    },
+    restore: (from) => rng.restore(from.state),
+    /* The position is one integer, so its hash is its hex. Two peers whose generators sit at
+       different positions have diverged even when every visible value still matches. */
+    digest: (from) => (from.state >>> 0).toString(16).padStart(8, '0'),
+  };
+}
+
+/**
+ * Several snapshotters as one, saving and restoring in the order given.
+ *
+ * The slot is an array of the parts' slots, so nothing is allocated per save once the ring is
+ * built. **Restore runs in the same order as save**, which matters for a consumer whose parts are
+ * not independent: state derived from the world has to be restored after it.
+ */
+export function combineSnapshotters(
+  parts: readonly Snapshotter<never>[],
+): Snapshotter<readonly unknown[]> {
+  const members = parts as readonly Snapshotter<unknown>[];
+  return {
+    create: () => members.map((part) => part.create()),
+    save: (into) => {
+      for (let i = 0; i < members.length; i++) {
+        (members[i] as Snapshotter<unknown>).save(into[i]);
+      }
+    },
+    restore: (from) => {
+      for (let i = 0; i < members.length; i++) {
+        (members[i] as Snapshotter<unknown>).restore(from[i]);
+      }
+    },
+    /*
+     * Every part's digest, folded into one. A part with none contributes nothing rather than
+     * disabling the whole — a consumer combining a world with a scratch buffer they do not care
+     * about should still get a comparable hash of the world.
+     */
+    digest: (from) => {
+      const combined = new Fingerprint();
+      for (let i = 0; i < members.length; i++) {
+        const part = members[i] as Snapshotter<unknown>;
+        if (part.digest === undefined) continue;
+        const text = part.digest(from[i]);
+        combined.int32(i);
+        for (let at = 0; at < text.length; at++) combined.byte(text.charCodeAt(at));
+      }
+      return combined.digest();
+    },
+  };
+}

package/src/transport.ts

@@ -0,0 +1,69 @@
+/**
+ * The seam a caller supplies, and the three roles a session can hold.
+ *
+ * **`AGENTS.md` settles the shape without being asked**: *"Nothing here may call a platform API
+ * directly when a consumer might want a different one ... Same for any clock, network or filesystem
+ * access — take the capability as a parameter, ship a browser implementation as the default."* So
+ * `Transport` is an interface, `LoopbackTransport` is the one that needs no network, and the two
+ * real ones are beside them.
+ *
+ * ---
+ *
+ * ## Three roles, because a relay need not be a simulator
+ *
+ * Most netcode assumes the machine that relays messages is the machine that runs the simulation.
+ * That assumption fails the moment the relay is written in another language — and a service that
+ * forwards messages, hosts rooms and re-simulates replays for anti-cheat is exactly the kind of
+ * thing written in another language. Such a service cannot run this simulation, because this
+ * engine is TypeScript.
+ *
+ * So the roles separate:
+ *
+ * - **Relay** forwards messages and reads none of them. Language-agnostic, and a Rust service is a
+ *   perfectly good one. Lockstep needs nothing more than this.
+ * - **Authority** runs the simulation and its state is the truth. A browser peer today; a Node
+ *   process once the packages can be imported without a bundler.
+ * - **Participant** sends inputs, receives inputs or state, and predicts locally.
+ *
+ * A session declares which it holds. Nothing in the protocol assumes the relay and the authority
+ * are the same process.
+ *
+ * ## Delivery is drained, never pushed into a frame
+ *
+ * A transport does not call back into a simulation. It collects what has arrived and a caller
+ * drains it at a point of their choosing, which is the top of a tick. A callback that fired
+ * mid-frame would deliver an input into the middle of a step that had already read its inputs, and
+ * the resulting world would depend on packet timing — which is the one thing a deterministic
+ * simulation must not do.
+ */
+
+/** Which participant a message is for or from. Small integers, assigned by the host. */
+export type PeerId = number;
+
+/** Send to everyone the transport can reach. */
+export const BROADCAST: PeerId = -1;
+
+export type TransportState = 'connecting' | 'open' | 'closed';
+
+/** What a role means is in this file's header, not in these names. */
+export type SessionRole = 'relay' | 'authority' | 'participant';
+
+/**
+ * Where a drained message goes.
+ *
+ * The bytes are **borrowed**, not given: the array is the transport's and may be reused as soon as
+ * this returns. A sink that needs to keep one copies it. That is the same contract `MessageQueue`
+ * and the render passes use, and it is what keeps a drain allocation-free.
+ */
+export type MessageSink = (from: PeerId, message: Uint8Array) => void;
+
+export interface Transport {
+  readonly state: TransportState;
+  /** This end's own id, or -1 before a host has assigned one. */
+  readonly self: PeerId;
+  /** Queue a message. Whether it arrives, in order, or at all is the implementation's business. */
+  send(to: PeerId, message: Uint8Array): void;
+  /** Hand every message that has arrived to the sink, oldest first, and clear them. */
+  drain(into: MessageSink): void;
+  close(): void;
+}

package/src/webrtc.ts

@@ -0,0 +1,141 @@
+/**
+ * `Transport` over a WebRTC data channel, which is what peer lockstep actually wants.
+ *
+ * **Unreliable and unordered, and that is the feature.** An input is only useful for the tick it
+ * names: a frame that took two retransmissions to arrive is a frame whose tick has been simulated,
+ * corrected and forgotten. Reliable ordered delivery makes the input *behind* it wait for that —
+ * head-of-line blocking, paid on every drop, on a link where the sender is about to send a newer
+ * one anyway. `{ ordered: false, maxRetransmits: 0 }` is the configuration, and `unreliableChannel`
+ * below is the one line of it worth not getting wrong.
+ *
+ * ---
+ *
+ * ## Signalling is a service and is not here
+ *
+ * Two peers cannot exchange WebRTC offers over WebRTC. Something else — a WebSocket, a REST
+ * endpoint, a person pasting a string — has to carry the first messages, and that something is a
+ * *service*: it has an address, an operator, and a lifetime longer than a session. Building one
+ * into a transport would make this package own a server.
+ *
+ * So a consumer opens the connection, does whatever signalling they already do, and hands over a
+ * channel. That is the same shape `KeyValueStore` has for persistence and `Transport` has for the
+ * network one level up.
+ *
+ * ## What this limits about testing, stated rather than discovered
+ *
+ * A data channel needs two real peer connections and an ICE exchange. There is no headless harness
+ * for that here, so what is tested is everything on this side of the channel — queueing, draining,
+ * the state mapping, and that the channel is configured unreliably — against a double. **The
+ * channel itself is exercised by `demo/dev/network.html`, in a browser, against a loopback pair.**
+ * That is a weaker guarantee than the loopback transport has, and it is why WebSocket is the
+ * default rather than this.
+ */
+import {
+  BROADCAST,
+  type MessageSink,
+  type PeerId,
+  type Transport,
+  type TransportState,
+} from './transport.ts';
+
+/** What an `RTCDataChannel` satisfies. Declared rather than imported; see `websocket.ts`. */
+export interface DataChannelLike {
+  readonly readyState: string;
+  binaryType?: string;
+  send(data: ArrayBufferView | ArrayBuffer): void;
+  close(): void;
+  addEventListener(type: string, listener: (event: unknown) => void): void;
+}
+
+/** The part of `RTCPeerConnection` `unreliableChannel` needs. */
+export interface PeerConnectionLike {
+  createDataChannel(label: string, options: Record<string, unknown>): DataChannelLike;
+}
+
+/**
+ * A channel configured the way a simulation wants one.
+ *
+ * **`maxRetransmits: 0` and `ordered: false` together**, and both matter. Unordered alone still
+ * retransmits, so a drop still costs a round trip before the data arrives — late, for a tick that
+ * has gone. Zero retransmissions alone still delivers in order, so a lost frame still blocks the
+ * ones behind it. Either on its own reads like the fix and is half of it.
+ */
+export function unreliableChannel(
+  connection: PeerConnectionLike,
+  label = 'drift',
+): DataChannelLike {
+  return connection.createDataChannel(label, { ordered: false, maxRetransmits: 0 });
+}
+
+export interface WebRtcTransportOptions {
+  readonly channel: DataChannelLike;
+  readonly self?: PeerId;
+  /** See `WebSocketTransportOptions.maxQueued`; the oldest goes for the same reason. */
+  readonly maxQueued?: number;
+}
+
+export class WebRtcTransport implements Transport {
+  readonly self: PeerId;
+
+  private readonly channel: DataChannelLike;
+  private readonly maxQueued: number;
+  private readonly arrived: Uint8Array[] = [];
+  private closedByUs = false;
+  private droppedCount = 0;
+
+  constructor(options: WebRtcTransportOptions) {
+    this.channel = options.channel;
+    this.self = options.self ?? -1;
+    this.maxQueued = Math.max(1, options.maxQueued ?? 1024);
+
+    if ('binaryType' in this.channel) this.channel.binaryType = 'arraybuffer';
+
+    this.channel.addEventListener('message', (event) => {
+      const data = (event as { data?: unknown }).data;
+      const bytes = toBytes(data);
+      if (bytes === null) return;
+      if (this.arrived.length >= this.maxQueued) {
+        this.arrived.shift();
+        this.droppedCount += 1;
+      }
+      this.arrived.push(bytes);
+    });
+  }
+
+  get state(): TransportState {
+    if (this.closedByUs) return 'closed';
+    const ready = this.channel.readyState;
+    if (ready === 'open') return 'open';
+    if (ready === 'connecting') return 'connecting';
+    return 'closed';
+  }
+
+  get dropped(): number {
+    return this.droppedCount;
+  }
+
+  send(_to: PeerId, message: Uint8Array): void {
+    if (this.state !== 'open') return;
+    this.channel.send(message);
+  }
+
+  drain(into: MessageSink): void {
+    for (const message of this.arrived) into(BROADCAST, message);
+    this.arrived.length = 0;
+  }
+
+  close(): void {
+    this.closedByUs = true;
+    this.arrived.length = 0;
+    this.channel.close();
+  }
+}
+
+function toBytes(data: unknown): Uint8Array | null {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return null;
+}

package/src/websocket.ts

@@ -0,0 +1,140 @@
+/**
+ * `Transport` over a WebSocket, which is the browser default.
+ *
+ * **Ordered and reliable, which is the wrong guarantee for inputs and the right one for this
+ * topology.** A dropped input frame blocks the frames behind it while TCP retransmits, and by the
+ * time it arrives the tick it belonged to is usually past — so a lockstep peer waits for news it no
+ * longer needs. The unordered answer is `WebRtcTransport` beside this.
+ *
+ * It is the default anyway, for a reason outside the protocol: WebSocket and WebTransport are what
+ * a relay service realistically speaks, whatever language it is written in. A transport nothing can
+ * connect to is not a default.
+ *
+ * ---
+ *
+ * ## The socket is supplied and its type is declared structurally
+ *
+ * No `WebSocket` type is named. `@driftengine/network` imports `@driftengine/entities` and nothing
+ * else, and that is the property that lets an authoritative host run it — a package that named a
+ * DOM type would compile only where a DOM does. The shape below is what a browser `WebSocket` and
+ * a Node `ws` socket both satisfy, which is also what makes the tests possible.
+ *
+ * The socket is **supplied rather than constructed**, so a consumer owns the URL, the protocols,
+ * the credentials and the reconnection policy. A transport that opened its own connection would be
+ * making four decisions that belong to whoever is paying for the server.
+ */
+import {
+  BROADCAST,
+  type MessageSink,
+  type PeerId,
+  type Transport,
+  type TransportState,
+} from './transport.ts';
+
+/** What a browser `WebSocket` and a Node `ws` both satisfy. Named here so neither is imported. */
+export interface SocketLike {
+  readonly readyState: number;
+  binaryType?: string;
+  send(data: ArrayBufferView | ArrayBuffer): void;
+  close(): void;
+  addEventListener(type: string, listener: (event: unknown) => void): void;
+}
+
+/** The `readyState` values, which are the same three numbers everywhere. */
+const OPEN = 1;
+const CLOSED = 3;
+
+export interface WebSocketTransportOptions {
+  readonly socket: SocketLike;
+  /** This end's id, or -1 to wait for a host to assign one through a welcome. */
+  readonly self?: PeerId;
+  /**
+   * How many messages may queue before the oldest is dropped.
+   *
+   * A bound rather than none, because a socket that stops draining is a socket behind a paused tab
+   * or a stalled link, and an unbounded queue there is a leak that ends the session with a crash
+   * instead of a disconnection. **The oldest goes**, because in a simulation the newest input is
+   * the one still worth having.
+   */
+  readonly maxQueued?: number;
+}
+
+export class WebSocketTransport implements Transport {
+  readonly self: PeerId;
+
+  private readonly socket: SocketLike;
+  private readonly maxQueued: number;
+  private readonly arrived: Uint8Array[] = [];
+  private closedByUs = false;
+  private droppedCount = 0;
+
+  constructor(options: WebSocketTransportOptions) {
+    this.socket = options.socket;
+    this.self = options.self ?? -1;
+    this.maxQueued = Math.max(1, options.maxQueued ?? 1024);
+
+    /* Binary frames, or every message arrives as a string and every payload is corrupted by the
+       round trip through UTF-8. Set before any listener, because a frame can arrive immediately. */
+    if ('binaryType' in this.socket) this.socket.binaryType = 'arraybuffer';
+
+    this.socket.addEventListener('message', (event) => {
+      const data = (event as { data?: unknown }).data;
+      const bytes = toBytes(data);
+      if (bytes === null) return;
+      if (this.arrived.length >= this.maxQueued) {
+        this.arrived.shift();
+        this.droppedCount += 1;
+      }
+      this.arrived.push(bytes);
+    });
+  }
+
+  get state(): TransportState {
+    if (this.closedByUs || this.socket.readyState === CLOSED) return 'closed';
+    return this.socket.readyState === OPEN ? 'open' : 'connecting';
+  }
+
+  /** Messages dropped because nothing drained. A consumer watching for a stalled tab reads this. */
+  get dropped(): number {
+    return this.droppedCount;
+  }
+
+  /**
+   * Send, or do nothing if the socket is not open yet.
+   *
+   * **Nothing is queued while connecting, deliberately.** Every message this package sends is
+   * addressed to a tick, and a tick that has passed by the time the socket opens is a tick nobody
+   * can use. Flushing a backlog of stale inputs on connect is worse than having sent none.
+   */
+  send(_to: PeerId, message: Uint8Array): void {
+    if (this.state !== 'open') return;
+    this.socket.send(message);
+  }
+
+  drain(into: MessageSink): void {
+    for (const message of this.arrived) into(BROADCAST, message);
+    this.arrived.length = 0;
+  }
+
+  close(): void {
+    this.closedByUs = true;
+    this.arrived.length = 0;
+    this.socket.close();
+  }
+}
+
+/**
+ * A message's bytes, whatever the socket handed over, or null.
+ *
+ * Browsers deliver an `ArrayBuffer` when `binaryType` is set, `ws` under Node delivers a `Buffer`,
+ * and a socket left on its default delivers a string. The first two are usable and the third is
+ * not: a payload that has been through UTF-8 has had every byte above 0x7f replaced.
+ */
+function toBytes(data: unknown): Uint8Array | null {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return null;
+}