onelobby 0.0.0-stage → 0.2.0

package/dist/socket.d.ts

@@ -0,0 +1,63 @@
+import type { Lobby } from "./lobby.js";
+/**
+ * A WebSocket-shaped view of one peer link, so code written against `WebSocket` runs on a lobby unchanged:
+ * `lobby.asWebSocket()` on a joiner (the link to the host), `lobby.onConnection(conn => ...)` on the host (one per
+ * joiner). Not a real WebSocket: no URL, no subprotocols, no `addEventListener`; `bufferedAmount` is always 0.
+ */
+export interface LobbySocket {
+    /** The peer at the other end (the host for a joiner's socket, the joiner for a host's connection). */
+    readonly peerId: number;
+    /** 0 CONNECTING (joiner, before `lobby.ready`), 1 OPEN, 3 CLOSED (there is no CLOSING). */
+    readonly readyState: 0 | 1 | 3;
+    readonly bufferedAmount: 0;
+    /** A string is sent as UTF-8; bytes as they are. Ignored unless OPEN. */
+    send(data: string | Uint8Array): void;
+    /**
+     * Closes this socket locally and fires `onclose` with `code` (default 1000). On a joiner it also leaves the lobby.
+     * On the host it only stops this connection's events: to remove the player too, call `lobby.kick(conn.peerId)`.
+     */
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: {
+        type: "open";
+    }) => void) | null;
+    /** `data` is a string (UTF-8 decoded), or the bytes with `{ binary: true }`. */
+    onmessage: ((ev: {
+        type: "message";
+        data: string | Uint8Array;
+    }) => void) | null;
+    /** `reason` is the lobby's reason ("host_left", "timeout", "kicked", ...) unless `close()` gave one. */
+    onclose: ((ev: {
+        type: "close";
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    }) => void) | null;
+    /** Never called (errors surface as `onclose` with code 1006); present so WebSocket code that assigns it works. */
+    onerror: ((ev: {
+        type: "error";
+    }) => void) | null;
+}
+export interface LobbySocketOptions {
+    /** Deliver `onmessage` data as bytes (Uint8Array) instead of UTF-8 text. Default false. */
+    binary?: boolean;
+    /** Channel for `send` (default "reliable"). "fast" is unordered and may drop, like UDP. */
+    channel?: "reliable" | "fast";
+}
+/**
+ * Close codes: 1000 a normal leave or `close()`, 1001 the other end went away (`host_left`, the host closing, a
+ * player who left), 4000 kicked, 1006 anything abnormal (`timeout`, `ice_failed`, `server_lost`, ...).
+ */
+export declare function closeCodeFor(reason: string): number;
+/**
+ * Joiner: the link to the host as a socket. OPEN once `lobby.ready` resolves (at once if it already has), with
+ * `onopen` one microtask later;
+ * closed when the session ends, or with 1001 "host_changed" when a server-backed lobby migrates to a new host.
+ */
+export declare function joinerSocket(lobby: Lobby, o?: LobbySocketOptions): LobbySocket;
+/**
+ * Host: calls `handler(conn)` once per joiner, as soon as its link is ready (and right away for joiners already
+ * connected). A message from a joiner the handler has not seen yet creates its connection first, so nothing is lost.
+ * `conn.onclose` fires when that peer leaves (code from closeCodeFor) or the host's session ends. Returns a function
+ * that stops new connections (existing ones keep working).
+ */
+export declare function hostConnections(lobby: Lobby, handler: (conn: LobbySocket) => void, o?: LobbySocketOptions): () => void;

package/dist/socket.js

@@ -0,0 +1,142 @@
+/**
+ * Close codes: 1000 a normal leave or `close()`, 1001 the other end went away (`host_left`, the host closing, a
+ * player who left), 4000 kicked, 1006 anything abnormal (`timeout`, `ice_failed`, `server_lost`, ...).
+ */
+export function closeCodeFor(reason) {
+    if (reason === "left")
+        return 1000;
+    if (reason === "host_left" || reason === "closed")
+        return 1001;
+    if (reason === "kicked")
+        return 4000;
+    return 1006;
+}
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+class PeerSocket {
+    peerId;
+    out;
+    binary;
+    onLocalClose;
+    readyState = 0;
+    bufferedAmount = 0;
+    onopen = null;
+    onmessage = null;
+    onclose = null;
+    onerror = null;
+    /** Unsubscribes from the lobby; set by the factory. */
+    detach = () => { };
+    constructor(peerId, out, binary, onLocalClose) {
+        this.peerId = peerId;
+        this.out = out;
+        this.binary = binary;
+        this.onLocalClose = onLocalClose;
+    }
+    send(data) {
+        if (this.readyState !== 1)
+            return;
+        this.out(typeof data === "string" ? enc.encode(data) : data);
+    }
+    close(code = 1000, reason = "left") {
+        if (this.readyState === 3)
+            return;
+        this.closed(code, reason);
+        this.onLocalClose();
+    }
+    /** @internal OPEN now; `onopen` now, or one microtask later so a handler assigned right after creation still runs. */
+    open(later = false) {
+        if (this.readyState !== 0)
+            return;
+        this.readyState = 1;
+        if (!later)
+            this.onopen?.({ type: "open" });
+        else
+            queueMicrotask(() => this.readyState === 1 && this.onopen?.({ type: "open" }));
+    }
+    /** @internal */
+    deliver(bytes) {
+        if (this.readyState === 1)
+            this.onmessage?.({ type: "message", data: this.binary ? bytes : dec.decode(bytes) });
+    }
+    /** @internal */
+    closed(code, reason) {
+        if (this.readyState === 3)
+            return;
+        this.readyState = 3;
+        this.detach();
+        this.onclose?.({ type: "close", code, reason, wasClean: code === 1000 || code === 1001 });
+    }
+}
+/**
+ * Joiner: the link to the host as a socket. OPEN once `lobby.ready` resolves (at once if it already has), with
+ * `onopen` one microtask later;
+ * closed when the session ends, or with 1001 "host_changed" when a server-backed lobby migrates to a new host.
+ */
+export function joinerSocket(lobby, o = {}) {
+    if (lobby.isHost)
+        throw new Error("asWebSocket() is for joiners; the host uses lobby.onConnection()");
+    const channel = o.channel ?? "reliable";
+    const s = new PeerSocket(lobby.hostPeerId, (b) => lobby.send(lobby.hostPeerId, b, { channel }), !!o.binary, () => void lobby.leave());
+    const offs = [
+        lobby.on("message", (from, bytes) => {
+            if (from === lobby.hostPeerId)
+                s.deliver(bytes);
+        }),
+        lobby.on("sessionEnded", (reason) => s.closed(closeCodeFor(reason), reason)),
+        // The socket's far end is the host it opened to; after a migration that server is gone (direct lobbies end instead).
+        lobby.on("hostChanged", () => s.closed(1001, "host_changed")),
+    ];
+    s.detach = () => offs.forEach((f) => f());
+    // Already connected (made after `await lobby.ready`): OPEN at once, so a send() right away goes out.
+    if (lobby.connectedPeers.includes(lobby.hostPeerId))
+        s.open(true);
+    else
+        lobby.ready.then(() => s.open(true), () => { });
+    return s;
+}
+/**
+ * Host: calls `handler(conn)` once per joiner, as soon as its link is ready (and right away for joiners already
+ * connected). A message from a joiner the handler has not seen yet creates its connection first, so nothing is lost.
+ * `conn.onclose` fires when that peer leaves (code from closeCodeFor) or the host's session ends. Returns a function
+ * that stops new connections (existing ones keep working).
+ */
+export function hostConnections(lobby, handler, o = {}) {
+    if (!lobby.isHost)
+        throw new Error("onConnection() is for the host; a joiner uses lobby.asWebSocket()");
+    const channel = o.channel ?? "reliable";
+    const conns = new Map();
+    let stopped = false;
+    const ensure = (peerId) => {
+        if (peerId === lobby.localPeerId)
+            return undefined;
+        let c = conns.get(peerId);
+        if (c || stopped)
+            return c;
+        c = new PeerSocket(peerId, (b) => lobby.send(peerId, b, { channel }), !!o.binary, () => { });
+        const conn = c;
+        conn.detach = () => {
+            if (conns.get(peerId) === conn)
+                conns.delete(peerId);
+        };
+        conns.set(peerId, conn);
+        conn.open();
+        handler(conn);
+        return conn;
+    };
+    const offs = [
+        lobby.on("peerReady", (p) => void ensure(p.peerId)),
+        lobby.on("message", (from, bytes) => ensure(from)?.deliver(bytes)),
+        lobby.on("peerLeft", (p, reason) => conns.get(p.peerId)?.closed(reason === "left" ? 1001 : closeCodeFor(reason), reason)),
+        lobby.on("sessionEnded", (reason) => {
+            for (const c of [...conns.values()])
+                c.closed(reason === "left" ? 1001 : closeCodeFor(reason), reason);
+            offs.forEach((f) => f());
+        }),
+    ];
+    for (const id of lobby.connectedPeers)
+        ensure(id);
+    return () => {
+        stopped = true;
+    };
+}
+//# sourceMappingURL=socket.js.map

package/dist/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Lobby, Peer } from \"./lobby.js\";\n\n/**\n * A WebSocket-shaped view of one peer link, so code written against `WebSocket` runs on a lobby unchanged:\n * `lobby.asWebSocket()` on a joiner (the link to the host), `lobby.onConnection(conn => ...)` on the host (one per\n * joiner). Not a real WebSocket: no URL, no subprotocols, no `addEventListener`; `bufferedAmount` is always 0.\n */\nexport interface LobbySocket {\n  /** The peer at the other end (the host for a joiner's socket, the joiner for a host's connection). */\n  readonly peerId: number;\n  /** 0 CONNECTING (joiner, before `lobby.ready`), 1 OPEN, 3 CLOSED (there is no CLOSING). */\n  readonly readyState: 0 | 1 | 3;\n  readonly bufferedAmount: 0;\n  /** A string is sent as UTF-8; bytes as they are. Ignored unless OPEN. */\n  send(data: string | Uint8Array): void;\n  /**\n   * Closes this socket locally and fires `onclose` with `code` (default 1000). On a joiner it also leaves the lobby.\n   * On the host it only stops this connection's events: to remove the player too, call `lobby.kick(conn.peerId)`.\n   */\n  close(code?: number, reason?: string): void;\n  onopen: ((ev: { type: \"open\" }) => void) | null;\n  /** `data` is a string (UTF-8 decoded), or the bytes with `{ binary: true }`. */\n  onmessage: ((ev: { type: \"message\"; data: string | Uint8Array }) => void) | null;\n  /** `reason` is the lobby's reason (\"host_left\", \"timeout\", \"kicked\", ...) unless `close()` gave one. */\n  onclose: ((ev: { type: \"close\"; code: number; reason: string; wasClean: boolean }) => void) | null;\n  /** Never called (errors surface as `onclose` with code 1006); present so WebSocket code that assigns it works. */\n  onerror: ((ev: { type: \"error\" }) => void) | null;\n}\n\nexport interface LobbySocketOptions {\n  /** Deliver `onmessage` data as bytes (Uint8Array) instead of UTF-8 text. Default false. */\n  binary?: boolean;\n  /** Channel for `send` (default \"reliable\"). \"fast\" is unordered and may drop, like UDP. */\n  channel?: \"reliable\" | \"fast\";\n}\n\n/**\n * Close codes: 1000 a normal leave or `close()`, 1001 the other end went away (`host_left`, the host closing, a\n * player who left), 4000 kicked, 1006 anything abnormal (`timeout`, `ice_failed`, `server_lost`, ...).\n */\nexport function closeCodeFor(reason: string): number {\n  if (reason === \"left\") return 1000;\n  if (reason === \"host_left\" || reason === \"closed\") return 1001;\n  if (reason === \"kicked\") return 4000;\n  return 1006;\n}\n\nconst enc = new TextEncoder();\nconst dec = new TextDecoder();\n\nclass PeerSocket implements LobbySocket {\n  readyState: 0 | 1 | 3 = 0;\n  readonly bufferedAmount = 0 as const;\n  onopen: LobbySocket[\"onopen\"] = null;\n  onmessage: LobbySocket[\"onmessage\"] = null;\n  onclose: LobbySocket[\"onclose\"] = null;\n  onerror: LobbySocket[\"onerror\"] = null;\n  /** Unsubscribes from the lobby; set by the factory. */\n  detach: () => void = () => {};\n\n  constructor(\n    readonly peerId: number,\n    private readonly out: (bytes: Uint8Array) => void,\n    private readonly binary: boolean,\n    private readonly onLocalClose: () => void,\n  ) {}\n\n  send(data: string | Uint8Array): void {\n    if (this.readyState !== 1) return;\n    this.out(typeof data === \"string\" ? enc.encode(data) : data);\n  }\n\n  close(code = 1000, reason = \"left\"): void {\n    if (this.readyState === 3) return;\n    this.closed(code, reason);\n    this.onLocalClose();\n  }\n\n  /** @internal OPEN now; `onopen` now, or one microtask later so a handler assigned right after creation still runs. */\n  open(later = false): void {\n    if (this.readyState !== 0) return;\n    this.readyState = 1;\n    if (!later) this.onopen?.({ type: \"open\" });\n    else queueMicrotask(() => this.readyState === 1 && this.onopen?.({ type: \"open\" }));\n  }\n\n  /** @internal */\n  deliver(bytes: Uint8Array): void {\n    if (this.readyState === 1) this.onmessage?.({ type: \"message\", data: this.binary ? bytes : dec.decode(bytes) });\n  }\n\n  /** @internal */\n  closed(code: number, reason: string): void {\n    if (this.readyState === 3) return;\n    this.readyState = 3;\n    this.detach();\n    this.onclose?.({ type: \"close\", code, reason, wasClean: code === 1000 || code === 1001 });\n  }\n}\n\n/**\n * Joiner: the link to the host as a socket. OPEN once `lobby.ready` resolves (at once if it already has), with\n * `onopen` one microtask later;\n * closed when the session ends, or with 1001 \"host_changed\" when a server-backed lobby migrates to a new host.\n */\nexport function joinerSocket(lobby: Lobby, o: LobbySocketOptions = {}): LobbySocket {\n  if (lobby.isHost) throw new Error(\"asWebSocket() is for joiners; the host uses lobby.onConnection()\");\n  const channel = o.channel ?? \"reliable\";\n  const s = new PeerSocket(lobby.hostPeerId, (b) => lobby.send(lobby.hostPeerId, b, { channel }), !!o.binary, () => void lobby.leave());\n  const offs = [\n    lobby.on(\"message\", (from, bytes) => {\n      if (from === lobby.hostPeerId) s.deliver(bytes);\n    }),\n    lobby.on(\"sessionEnded\", (reason) => s.closed(closeCodeFor(reason), reason)),\n    // The socket's far end is the host it opened to; after a migration that server is gone (direct lobbies end instead).\n    lobby.on(\"hostChanged\", () => s.closed(1001, \"host_changed\")),\n  ];\n  s.detach = () => offs.forEach((f) => f());\n  // Already connected (made after `await lobby.ready`): OPEN at once, so a send() right away goes out.\n  if (lobby.connectedPeers.includes(lobby.hostPeerId)) s.open(true);\n  else lobby.ready.then(() => s.open(true), () => {});\n  return s;\n}\n\n/**\n * Host: calls `handler(conn)` once per joiner, as soon as its link is ready (and right away for joiners already\n * connected). A message from a joiner the handler has not seen yet creates its connection first, so nothing is lost.\n * `conn.onclose` fires when that peer leaves (code from closeCodeFor) or the host's session ends. Returns a function\n * that stops new connections (existing ones keep working).\n */\nexport function hostConnections(lobby: Lobby, handler: (conn: LobbySocket) => void, o: LobbySocketOptions = {}): () => void {\n  if (!lobby.isHost) throw new Error(\"onConnection() is for the host; a joiner uses lobby.asWebSocket()\");\n  const channel = o.channel ?? \"reliable\";\n  const conns = new Map<number, PeerSocket>();\n  let stopped = false;\n  const ensure = (peerId: number): PeerSocket | undefined => {\n    if (peerId === lobby.localPeerId) return undefined;\n    let c = conns.get(peerId);\n    if (c || stopped) return c;\n    c = new PeerSocket(peerId, (b) => lobby.send(peerId, b, { channel }), !!o.binary, () => {});\n    const conn = c;\n    conn.detach = () => {\n      if (conns.get(peerId) === conn) conns.delete(peerId);\n    };\n    conns.set(peerId, conn);\n    conn.open();\n    handler(conn);\n    return conn;\n  };\n  const offs = [\n    lobby.on(\"peerReady\", (p: Peer) => void ensure(p.peerId)),\n    lobby.on(\"message\", (from, bytes) => ensure(from)?.deliver(bytes)),\n    lobby.on(\"peerLeft\", (p: Peer, reason) => conns.get(p.peerId)?.closed(reason === \"left\" ? 1001 : closeCodeFor(reason), reason)),\n    lobby.on(\"sessionEnded\", (reason) => {\n      for (const c of [...conns.values()]) c.closed(reason === \"left\" ? 1001 : closeCodeFor(reason), reason);\n      offs.forEach((f) => f());\n    }),\n  ];\n  for (const id of lobby.connectedPeers) ensure(id);\n  return () => {\n    stopped = true;\n  };\n}\n"]}

package/dist/testing.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Test doubles: a manual clock, an in-memory lobby server speaking the lk1 protocol (spec/signaling.md, the parts the
+ * client uses) and an in-memory peer network. Exported as `onelobby/testing`.
+ */
+import type { Clock } from "./clock.js";
+import type { ChannelName, LinkFactory, LinkOptions, PeerLink, SignalPayload, SocketFactory, SocketLike } from "./transport.js";
+/** Deterministic clock: time only moves through `advance()`. Timers fire in (time, creation) order. */
+export declare class ManualClock implements Clock {
+    private t;
+    private seq;
+    private timers;
+    now(): number;
+    setInterval(fn: () => void, ms: number): () => void;
+    setTimeout(fn: () => void, ms: number): () => void;
+    /** Advance time, firing due timers one at a time (microtasks flush between them when awaited via `run`). */
+    advance(ms: number): void;
+    /** Advance in `step` ms slices, letting promises and queued microtasks settle between slices. */
+    run(ms: number, step?: number): Promise<void>;
+}
+/** Let all pending microtasks (and chained promise continuations) run. */
+export declare function settle(rounds?: number): Promise<void>;
+/**
+ * Pairs `PeerLink`s through the signaling path like WebRTC would: the offerer's SDP string names it, the answerer
+ * resolves that name, and both open one microtask later. Messages are delivered FIFO, one microtask later.
+ */
+export declare class MemoryNetwork {
+    private offers;
+    /** Every link ever created (for assertions and fault injection). */
+    readonly links: MemoryLink[];
+    /** Set to drop all traffic in one direction pair for fault injection: key `${from}->${to}` is not tracked; use link.mute(). */
+    readonly factory: LinkFactory;
+    /** @internal */
+    register(offer: string, link: MemoryLink): void;
+    /** @internal */
+    lookup(offer: string): MemoryLink | undefined;
+    /** Kill every link whose far end is this identity-tagged factory owner (set `tag` via MemoryLink.owner). */
+    killOwner(owner: string): void;
+    /** Per-owner factory so tests can tell whose link is whose and cut one peer off. */
+    factoryFor(owner: string): LinkFactory;
+}
+export declare class MemoryLink implements PeerLink {
+    private net;
+    readonly remoteId: number;
+    isOpen: boolean;
+    owner: string;
+    onSignal: PeerLink["onSignal"];
+    onOpen: PeerLink["onOpen"];
+    onClose: PeerLink["onClose"];
+    onMessage: PeerLink["onMessage"];
+    onPath: PeerLink["onPath"];
+    /** Bytes sent per channel, for assertions. */
+    readonly sent: Record<ChannelName, number>;
+    /** While true, outgoing messages vanish (a frozen or partitioned peer). */
+    blackhole: boolean;
+    private peer;
+    private closed;
+    private id;
+    constructor(net: MemoryNetwork, opts: LinkOptions);
+    startOffer(): void;
+    handleSignal(s: SignalPayload): void;
+    /** @internal */
+    accept(answerer: MemoryLink): void;
+    private open;
+    send(channel: ChannelName, bytes: Uint8Array): void;
+    close(): void;
+    private closeFromRemote;
+}
+type Json = Record<string, unknown>;
+interface MPeer {
+    peerId: number;
+    name: string;
+    joinedAt: number;
+    sock: MemorySocket | null;
+    token: string;
+}
+interface MLobby {
+    code: string;
+    gameId: string;
+    netVersion: string;
+    name: string;
+    hostId: number;
+    epoch: number;
+    mode: string;
+    tickRate: number;
+    lateJoin: boolean;
+    phase: string;
+    meta: Record<string, string>;
+    visibility: string;
+    maxPlayers: number;
+    peers: Map<number, MPeer>;
+    next: number;
+    kicked: Set<number>;
+    reserved: Map<string, MPeer>;
+}
+/** Minimal onelobby-server (lk1) for client tests. Not a conformance target: stream A owns the real server. */
+export declare class MemoryServer {
+    readonly lobbies: Map<string, MLobby>;
+    /** Every socket ever opened (to drop one from a test). */
+    readonly sockets: MemorySocket[];
+    readonly socketFactory: SocketFactory;
+    private n;
+    iceServers: {
+        urls: string[];
+    }[];
+    /** Log of every client message, for assertions. */
+    readonly received: Json[];
+    connect(): MemorySocket;
+    /** @internal */
+    newCode(): string;
+}
+export declare class MemorySocket implements SocketLike {
+    private srv;
+    readyState: number;
+    onopen: SocketLike["onopen"];
+    onmessage: SocketLike["onmessage"];
+    onclose: SocketLike["onclose"];
+    onerror: SocketLike["onerror"];
+    private hello;
+    private lobby;
+    private peer;
+    private closed;
+    constructor(srv: MemoryServer);
+    send(data: string): void;
+    close(): void;
+    /** @internal server -> this client */
+    push(m: Json): void;
+    private err;
+    private lobbyMsg;
+    private broadcast;
+    private leaveLobby;
+    private handle;
+}
+/** Convenience: kill a socket as if the network dropped (server sees a timeout, others get peer_left). */
+export declare function dropSocket(s: SocketLike): void;
+export {};