@aethervtt/shard-net 0.0.0-stage → 0.4.1

package/dist/testing.d.ts

@@ -0,0 +1,60 @@
+import { type ComponentDef, type Entity } from '@aethervtt/shard-core';
+import { App, type Plugin } from '@aethervtt/shard-runtime';
+import { type ConditionsOptions, type NetConditions } from './conditions.js';
+import { type NetOptions } from './plugin.js';
+export interface NetHarnessOptions {
+    /** Plugins every app gets: a function, so each app has its own instances. */
+    plugins?: () => Plugin[];
+    /** Extra plugins for the server only, and for each client. */
+    server?: () => Plugin[];
+    client?: (index: number) => Plugin[];
+    /** Net options both sides share (replicate, commands, events, tickRate…). */
+    net?: Omit<NetOptions, 'role' | 'transport' | 'address' | 'session' | 'code' | 'now'>;
+    /** Per-side overrides (interest and budget for the server, a token for clients…). */
+    serverNet?: Partial<NetOptions>;
+    clientNet?: (index: number) => Partial<NetOptions>;
+    clients?: number;
+    /** Conditions on every client's link (one wrapper per client, both directions). */
+    conditions?: Omit<ConditionsOptions, 'now'>;
+    fixedHz?: number;
+    seed?: number;
+    maxMessage?: number;
+    /**
+     * Makes each app (default `new App`): a project build, say (0092). The harness adds the net
+     * plugin and initializes it; `plugins`, `server` and `client` are added too.
+     */
+    createApp?: (side: 'server' | 'client', index: number) => App;
+    /** Runs after each app's init, before it connects (an asset scan). */
+    afterInit?: (app: App) => Promise<void>;
+}
+export interface NetHarness {
+    readonly server: App;
+    readonly clients: App[];
+    /** The shared fake clock, in ms. */
+    now(): number;
+    /** Advances every app by `ticks` fixed steps on the shared clock: server first, then clients. */
+    step(ticks: number): void;
+    /**
+     * Steps until every client has finished its handshake (at most `maxTicks`), yielding between
+     * ticks so async `accept` and player hooks settle.
+     */
+    connect(maxTicks?: number): Promise<void>;
+    /** Like `step`, but yields to pending promises between ticks. */
+    run(ticks: number): Promise<void>;
+    setConditions(client: number, conditions: Partial<NetConditions>): void;
+    /** Connects one more client mid-game; resolves once its connection is open. */
+    addClient(): Promise<App>;
+    /** Disposes one client (it says goodbye to the server) and removes it from `clients`. */
+    removeClient(index: number): Promise<void>;
+    /** Per client, what differs from the server for these components (empty when converged). */
+    differences(...defs: ComponentDef[]): string[];
+    converged(...defs: ComponentDef[]): boolean;
+    /** The client entity with the server entity's net id, if it has one. */
+    clientEntity(client: number, serverEntity: Entity): Entity | undefined;
+    dispose(): Promise<void>;
+}
+/**
+ * A server and N clients in one process, over a conditioned loopback, stepped on one fake clock
+ * (0086). Deterministic for a given seed.
+ */
+export declare function netHarness(options?: NetHarnessOptions): Promise<NetHarness>;

package/dist/testing.js

@@ -0,0 +1,200 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { App } from "@aethervtt/shard-runtime";
+import { NetId, NetRole } from "./components.js";
+import {
+  simulateConditions
+} from "./conditions.js";
+import { loopback } from "./loopback.js";
+import { netPlugin, netSession } from "./plugin.js";
+async function netHarness(options = {}) {
+  const fixedHz = options.fixedHz ?? 60;
+  const seed = options.seed ?? 1;
+  let clock = 0;
+  const now = () => clock;
+  const network = loopback({ maxMessage: options.maxMessage ?? 1 << 20 });
+  const address = "harness";
+  const make = (side, index, appSeed) => options.createApp?.(side, index) ?? new App({ fixedHz, seed: appSeed, now });
+  const server = make("server", 0, seed);
+  for (const p of options.plugins?.() ?? []) server.addPlugin(p);
+  for (const p of options.server?.() ?? []) server.addPlugin(p);
+  server.addPlugin(
+    netPlugin({
+      ...options.net,
+      ...options.serverNet,
+      role: "server",
+      transport: network,
+      address,
+      now
+    })
+  );
+  await server.init();
+  await options.afterInit?.(server);
+  await netSession(server.world).ready;
+  const clients = [];
+  const links = [];
+  async function addClient() {
+    const index = clients.length;
+    const link = simulateConditions(network, {
+      ...options.conditions,
+      seed: (options.conditions?.seed ?? seed) + index * 7919,
+      now
+    });
+    const app = make("client", index, seed + index + 1);
+    for (const p of options.plugins?.() ?? []) app.addPlugin(p);
+    for (const p of options.client?.(index) ?? []) app.addPlugin(p);
+    app.addPlugin(
+      netPlugin({
+        ...options.net,
+        ...options.clientNet?.(index),
+        role: "client",
+        transport: link,
+        address,
+        now
+      })
+    );
+    await app.init();
+    await options.afterInit?.(app);
+    await netSession(app.world).ready;
+    clients.push(app);
+    links.push(link);
+    return app;
+  }
+  for (let i = 0; i < (options.clients ?? 1); i++) await addClient();
+  const step = (ticks) => {
+    for (let i = 0; i < ticks; i++) {
+      clock += 1e3 / fixedHz;
+      server.update(1 / fixedHz);
+      for (const c of clients) c.update(1 / fixedHz);
+    }
+  };
+  function clientEntity(client, serverEntity) {
+    const world = server.world;
+    if (!world.isAlive(serverEntity) || !world.has(serverEntity, NetId)) return void 0;
+    const id = world.get(serverEntity, NetId).id;
+    return netSession(clients[client].world).client.byNetId.get(id);
+  }
+  function differences(...defs) {
+    const out = [];
+    const session = netSession(server.world);
+    const entries = session.manifest.components;
+    clients.forEach((app, index) => {
+      const client = netSession(app.world).client;
+      const peerId = app.world.resource(NetRole).peer;
+      const peer = session.server.peers.get(peerId);
+      if (!peer) {
+        out.push(`client ${index}: not connected`);
+        return;
+      }
+      for (const e of peer.relevant.entities) {
+        const id = server.world.get(e, NetId).id;
+        const local = client.byNetId.get(id);
+        if (local === void 0) {
+          out.push(`client ${index}: missing net id ${id}`);
+          continue;
+        }
+        for (const def of defs) {
+          const entry = entries.find((c) => c.def === def);
+          const visible = server.world.has(e, def) && (!entry?.visibleTo || entry.visibleTo(server.world, peerId, e));
+          const has = app.world.has(local, def);
+          if (visible !== has) {
+            out.push(
+              `client ${index}: net id ${id} ${def.name} ${visible ? "missing" : "should be absent"}`
+            );
+            continue;
+          }
+          if (!visible) continue;
+          const a = def.serialize(server.world.get(e, def));
+          const b = def.serialize(app.world.get(local, def));
+          for (const c of def.layout) {
+            const step2 = entry?.quantize[c.name]?.step ?? 0;
+            const diff = c.field.kind === "quat" ? compareQuat(a[c.name], b[c.name], `/${c.name}`) : compare(a[c.name], b[c.name], `/${c.name}`, step2);
+            if (diff) {
+              out.push(`client ${index}: net id ${id} ${def.name}${diff}`);
+              break;
+            }
+          }
+        }
+      }
+      for (const [id] of client.byNetId) {
+        const e = session.server.byNetId.get(id);
+        if (e === void 0 || !peer.relevant.has(e))
+          out.push(`client ${index}: extra net id ${id}`);
+      }
+    });
+    return out;
+  }
+  return {
+    server,
+    clients,
+    now,
+    step,
+    async connect(maxTicks = 600) {
+      for (let i = 0; i < maxTicks; i++) {
+        if (clients.every((c) => c.world.resource(NetRole).connected)) return;
+        step(1);
+        await yieldToPromises();
+      }
+      const failed = clients.find((c) => !c.world.resource(NetRole).connected);
+      throw netSession(failed.world).client.lastError ?? new ShardError("net/connect-failed", `A client didn't connect within ${maxTicks} ticks`);
+    },
+    async run(ticks) {
+      for (let i = 0; i < ticks; i++) {
+        step(1);
+        await yieldToPromises();
+      }
+    },
+    setConditions(client, conditions) {
+      links[client].setConditions(conditions);
+    },
+    addClient,
+    async removeClient(index) {
+      const [app] = clients.splice(index, 1);
+      links.splice(index, 1);
+      await app?.dispose();
+    },
+    differences,
+    converged: (...defs) => differences(...defs).length === 0,
+    clientEntity,
+    async dispose() {
+      for (const c of clients) await c.dispose();
+      await server.dispose();
+    }
+  };
+}
+function yieldToPromises() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function compareQuat(a, b, path) {
+  const dot = Math.abs(a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]);
+  return dot >= 1 - 1e-5 ? "" : ` ${path}: ${JSON.stringify(a)} vs ${JSON.stringify(b)}`;
+}
+function compare(a, b, path, step) {
+  if (typeof a === "number" && typeof b === "number") {
+    const tolerance = Math.max(step / 2 + 1e-6, 1e-3);
+    return Math.abs(a - b) <= tolerance ? "" : ` ${path}: ${a} vs ${b}`;
+  }
+  if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+    for (let i = 0; i < a.length; i++) {
+      const d = compare(a[i], b[i], `${path}/${i}`, step);
+      if (d) return d;
+    }
+    return "";
+  }
+  if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a)) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const k of keys) {
+      const d = compare(
+        a[k],
+        b[k],
+        `${path}/${k}`,
+        step
+      );
+      if (d) return d;
+    }
+    return "";
+  }
+  return JSON.stringify(a) === JSON.stringify(b) ? "" : ` ${path}: ${JSON.stringify(a)} vs ${JSON.stringify(b)}`;
+}
+export {
+  netHarness
+};

package/dist/transport.d.ts

@@ -0,0 +1,79 @@
+import { type JsonObject, ShardError } from '@aethervtt/shard-core';
+/** `reliable` arrives once and in order; `unreliable` may be lost, duplicated or reordered. */
+export type Channel = 'reliable' | 'unreliable';
+/** Assigned by a listener; unique among its connections. 0 is the server itself. */
+export type PeerId = number;
+export interface TransportCaps {
+    /** False when every message is reliable (WebSocket): unreliable sends go reliable. */
+    readonly unreliable: boolean;
+    /** The largest message `send` accepts, in bytes. The net core splits bigger reliable messages. */
+    readonly maxMessage: number;
+}
+export interface ConnectionStats {
+    /** Round trip in ms, if the transport measures one (the net core measures its own). */
+    rtt: number;
+    sentBytes: number;
+    receivedBytes: number;
+    /** Unreliable messages known lost (sent but dropped), when the transport can tell. */
+    lost: number;
+}
+export interface ConnectOptions {
+    /** Passed to the transport (a relay or lobby may check it). The handshake sends its own. */
+    token?: string;
+}
+export interface ListenOptions {
+    address?: string;
+    maxPeers?: number;
+    /** What a lobby lists for the room (a name, a mode). Transports ignore it. */
+    meta?: JsonObject;
+}
+/**
+ * Moves bytes between peers (0086): loopback, WebSocket, and later WebRTC or Steam. A transport
+ * never touches a world. Messages it receives wait in the connection until the net core drains them.
+ */
+export interface NetTransport {
+    readonly name: string;
+    readonly caps: TransportCaps;
+    connect(address: string, options?: ConnectOptions): Promise<NetConnection>;
+    listen?(options: ListenOptions): Promise<NetListener>;
+}
+export interface NetListener {
+    onConnection(fn: (connection: NetConnection) => void): () => void;
+    close(): Promise<void>;
+}
+export interface NetConnection {
+    readonly peer: PeerId;
+    /** The transport copies `bytes` before returning: the caller reuses its buffer. */
+    send(channel: Channel, bytes: Uint8Array): void;
+    onMessage(fn: (channel: Channel, bytes: Uint8Array) => void): () => void;
+    onClose(fn: (reason: ShardError | undefined) => void): () => void;
+    close(reason?: string): void;
+    stats(): ConnectionStats;
+    /**
+     * Delivers messages that are due. The net core calls it once per frame before draining; a
+     * transport that delivers on its own (a socket) leaves it out.
+     */
+    pump?(): void;
+}
+/** Room codes, lobbies, relays and signaling: how peers find each other (0086). */
+export interface NetSessionProvider {
+    readonly name: string;
+    /** Limits of the connections it makes, when they differ from a plain transport's. */
+    readonly caps?: TransportCaps;
+    host(options: ListenOptions): Promise<{
+        code: string;
+        listener: NetListener;
+    }>;
+    join(code: string, options?: ConnectOptions): Promise<NetConnection>;
+    list?(filter?: JsonObject): Promise<readonly SessionInfo[]>;
+}
+export interface SessionInfo {
+    code: string;
+    name?: string;
+    peers?: number;
+    maxPeers?: number;
+    meta?: JsonObject;
+}
+/** A session whose code is the transport address: no lobby, peers share a URL. */
+export declare function directSession(transport: NetTransport, address?: string): NetSessionProvider;
+export declare function notListening(transport: NetTransport): ShardError;

package/dist/transport.js

@@ -0,0 +1,22 @@
+import { ShardError } from "@aethervtt/shard-core";
+function directSession(transport, address = "") {
+  return {
+    name: `direct:${transport.name}`,
+    caps: transport.caps,
+    async host(options) {
+      if (!transport.listen) throw notListening(transport);
+      const listener = await transport.listen({ ...options, address: options.address ?? address });
+      return { code: options.address ?? address, listener };
+    },
+    join: (code, options) => transport.connect(code, options)
+  };
+}
+function notListening(transport) {
+  return new ShardError("net/cannot-listen", `The ${transport.name} transport can't listen`, {
+    hint: "Servers need a transport with listen(), such as webSocketServer() or loopback()."
+  });
+}
+export {
+  directSession,
+  notListening
+};

package/dist/vec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A growable list of numbers in a Float64Array. `clear` keeps the memory: an array's
+ * `length = 0` lets V8 drop its backing store, so refilling it every tick would allocate.
+ */
+export declare class NumberList {
+    data: Float64Array;
+    length: number;
+    constructor(capacity?: number);
+    push(v: number): void;
+    at(i: number): number;
+    clear(): void;
+    toArray(): number[];
+}

package/dist/vec.js

@@ -0,0 +1,27 @@
+class NumberList {
+  data;
+  length = 0;
+  constructor(capacity = 64) {
+    this.data = new Float64Array(capacity);
+  }
+  push(v) {
+    if (this.length === this.data.length) {
+      const next = new Float64Array(this.data.length * 2);
+      next.set(this.data);
+      this.data = next;
+    }
+    this.data[this.length++] = v;
+  }
+  at(i) {
+    return this.data[i];
+  }
+  clear() {
+    this.length = 0;
+  }
+  toArray() {
+    return Array.from(this.data.subarray(0, this.length));
+  }
+}
+export {
+  NumberList
+};

package/dist/wire.d.ts

@@ -0,0 +1,60 @@
+import { ByteReader, ByteWriter, ShardError } from '@aethervtt/shard-core';
+import type { NetCommandDef, NetEventDef, ReplicationEntry } from './registry.js';
+import type { Channel, NetConnection } from './transport.js';
+/** Bumped when the message layout changes. */
+export declare const PROTOCOL_VERSION = 1;
+/** The first byte of every message. Each is followed by a u32 tick. */
+export declare const Msg: {
+    readonly hello: 1;
+    readonly welcome: 2;
+    readonly refused: 3;
+    readonly ping: 4;
+    readonly pong: 5;
+    readonly disconnect: 6;
+    readonly fragment: 7;
+    /** Server → client, unreliable: component updates, acked by sequence. */
+    readonly state: 10;
+    /** Server → client, reliable: spawns, reliable components, removals, despawns, answers, events. */
+    readonly reliable: 11;
+    /** Client → server, unreliable: which state messages arrived. */
+    readonly ack: 12;
+    /** Client → server, reliable. */
+    readonly command: 13;
+};
+/** Sections of a `reliable` message, in the order they're written. */
+export declare const Section: {
+    readonly spawn: 1;
+    readonly set: 2;
+    readonly remove: 3;
+    readonly despawn: 4;
+    readonly answer: 5;
+    readonly event: 6;
+    readonly end: 0;
+};
+/** What both sides number by sorted name, and hash to refuse mismatched builds (0086). */
+export interface Manifest {
+    readonly components: readonly ReplicationEntry[];
+    readonly commands: readonly NetCommandDef[];
+    readonly events: readonly NetEventDef[];
+    readonly hash: number;
+}
+export declare function buildManifest(components: readonly ReplicationEntry[], commands: readonly NetCommandDef[], events: readonly NetEventDef[]): Manifest;
+/** Names the first type two manifests disagree on, for `net/schema-mismatch`. */
+export declare function describeManifest(m: Manifest): string[];
+export declare function header(w: ByteWriter, kind: number, tick: number): void;
+/**
+ * Sends a reliable message whole, or split into fragments when it's over the transport's limit.
+ * Fragments travel in order on the reliable channel, so reassembly only needs a count.
+ */
+export declare class Fragmenter {
+    private nextId;
+    private readonly scratch;
+    private parts;
+    private expected;
+    private partId;
+    send(connection: NetConnection, channel: Channel, bytes: Uint8Array, max: number): void;
+    /** Feeds one fragment's body; returns the whole message once the last part arrives. */
+    receive(r: ByteReader): Uint8Array | undefined;
+}
+export declare function badMessage(detail: string): ShardError;
+export { ByteReader, ByteWriter };

package/dist/wire.js

@@ -0,0 +1,141 @@
+import { ByteReader, ByteWriter, ShardError } from "@aethervtt/shard-core";
+const PROTOCOL_VERSION = 1;
+const Msg = {
+  hello: 1,
+  welcome: 2,
+  refused: 3,
+  ping: 4,
+  pong: 5,
+  disconnect: 6,
+  fragment: 7,
+  /** Server → client, unreliable: component updates, acked by sequence. */
+  state: 10,
+  /** Server → client, reliable: spawns, reliable components, removals, despawns, answers, events. */
+  reliable: 11,
+  /** Client → server, unreliable: which state messages arrived. */
+  ack: 12,
+  /** Client → server, reliable. */
+  command: 13
+};
+const Section = {
+  spawn: 1,
+  set: 2,
+  remove: 3,
+  despawn: 4,
+  answer: 5,
+  event: 6,
+  end: 0
+};
+const FRAGMENT_OVERHEAD = 32;
+function buildManifest(components, commands, events) {
+  const byName = (list, what) => {
+    const sorted = [...list].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (let i = 1; i < sorted.length; i++) {
+      if (sorted[i].name === sorted[i - 1].name) {
+        throw new ShardError("net/duplicate-type", `${what} "${sorted[i].name}" is listed twice`);
+      }
+    }
+    return sorted;
+  };
+  const comps = byName(
+    components.map((c) => ({ ...c, name: c.def.name })),
+    "Replicated component"
+  );
+  const cmds = byName(commands, "Command");
+  const evts = byName(events, "Event");
+  let text = `p${PROTOCOL_VERSION}`;
+  for (const c of comps)
+    text += `|c:${describeLayout(c.def)}:${c.mode}:${c.channel}:${JSON.stringify(c.quantize)}`;
+  for (const c of cmds) text += `|q:${describeLayout(c.schema)}`;
+  for (const e of evts) text += `|e:${describeLayout(e.schema)}`;
+  return { components: comps, commands: cmds, events: evts, hash: fnv1a(text) };
+}
+function describeLayout(def) {
+  let s = `${def.name}@${def.version}`;
+  for (const c of def.layout) s += `,${c.name}:${c.field.kind}:${c.storage}:${c.stride}`;
+  return s;
+}
+function describeManifest(m) {
+  return [
+    ...m.components.map((c) => `component ${describeLayout(c.def)}`),
+    ...m.commands.map((c) => `command ${describeLayout(c.schema)}`),
+    ...m.events.map((e) => `event ${describeLayout(e.schema)}`)
+  ];
+}
+function fnv1a(text) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+  return h >>> 0;
+}
+function header(w, kind, tick) {
+  w.reset();
+  w.u8(kind);
+  w.u32(tick >>> 0);
+}
+class Fragmenter {
+  nextId = 1;
+  scratch = new ByteWriter(256);
+  parts = [];
+  expected = 0;
+  partId = 0;
+  send(connection, channel, bytes, max) {
+    if (bytes.length <= max || channel === "unreliable") {
+      connection.send(channel, bytes);
+      return;
+    }
+    const chunk = max - FRAGMENT_OVERHEAD;
+    if (chunk <= 0) throw new ShardError("net/bad-message", `maxMessage ${max} is too small`);
+    const count = Math.ceil(bytes.length / chunk);
+    const id = this.nextId++;
+    for (let i = 0; i < count; i++) {
+      header(this.scratch, Msg.fragment, 0);
+      this.scratch.varuint(id);
+      this.scratch.varuint(i);
+      this.scratch.varuint(count);
+      this.scratch.bytes(bytes.subarray(i * chunk, Math.min(bytes.length, (i + 1) * chunk)));
+      connection.send("reliable", this.scratch.finish());
+    }
+  }
+  /** Feeds one fragment's body; returns the whole message once the last part arrives. */
+  receive(r) {
+    const id = r.varuint();
+    const index = r.varuint();
+    const count = r.varuint();
+    if (index === 0) {
+      this.parts = [];
+      this.expected = count;
+      this.partId = id;
+    } else if (id !== this.partId || index !== this.parts.length) {
+      throw new ShardError("net/bad-message", "A fragment arrived out of order");
+    }
+    this.parts.push(r.bytes(r.remaining).slice());
+    if (this.parts.length < this.expected) return void 0;
+    let size = 0;
+    for (const p of this.parts) size += p.length;
+    const out = new Uint8Array(size);
+    let at = 0;
+    for (const p of this.parts) {
+      out.set(p, at);
+      at += p.length;
+    }
+    this.parts = [];
+    return out;
+  }
+}
+function badMessage(detail) {
+  return new ShardError("net/bad-message", `Malformed network message: ${detail}`, {
+    hint: "Both sides must run the same build; the connection is closed."
+  });
+}
+export {
+  ByteReader,
+  ByteWriter,
+  Fragmenter,
+  Msg,
+  PROTOCOL_VERSION,
+  Section,
+  badMessage,
+  buildManifest,
+  describeManifest,
+  header
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@aethervtt/shard-net",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.4.1",
+    "@aethervtt/shard-runtime": "0.4.1",
+    "@aethervtt/shard-transform": "0.4.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/net"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "0061be4019b2a0af985eada9a60f757a3c6e2ba4"
+  }
+}