onelobby 0.5.0 → 0.7.0

package/dist/lobby.js

@@ -4,6 +4,7 @@ import { Reassembler, splitChunks } from "./chunking.js";
 import { Emitter } from "./emitter.js";
 import { Lockstep } from "./lockstep.js";
 import { claimWinsWrapped, pickNewHost } from "./migration.js";
+import { Pause } from "./pause.js";
 import { OneLobbyError } from "./signaling.js";
 import { Voice } from "./voice.js";
 import { hostConnections, joinerSocket } from "./socket.js";
@@ -11,6 +12,8 @@ import { hostConnections, joinerSocket } from "./socket.js";
 export const MIN_PEER_TIMEOUT_MS = 6000;
 /** Host: how long a kicked / disconnected peer's link stays open for the hub's notice to reach it first. */
 export const KICK_LINGER_MS = 3000;
+/** How long an offer held during a possible migration stays answerable. */
+const HELD_OFFER_MS = 20_000;
 /** The name shown for a peer that chose none: "Player N", N = its seat (peer id, join order). */
 export function seatName(p) {
     const n = typeof p.name === "string" ? p.name.trim() : "";
@@ -31,31 +34,62 @@ export class Lobby extends Emitter {
     tickRate;
     lockstep;
     chat;
+    /** The shared co-op pause (docs/recipes/pause.md). */
+    pause;
     voice;
     localPeerId;
     hostPeerId;
     phase;
     meta;
+    /** The lobby's name as the server keeps it (host()'s `name`, sanitised); "" if the server sends none. */
+    name;
     resumeToken;
     /** Last measured round trip to the host in ms (joiners), or 0. */
     rtt = 0;
     /**
-     * Direct-IP host only (onelobby/direct): the code friends paste to join, e.g. "6B01-RGFE-P2B" (docs/direct-ip.md
+     * Direct-IP host only (onelobby/direct): the code friends paste to join, e.g. "6B01-RGFE-P2B" (docs/design/direct-ip.md
      * s.2a). Show it with joinCodeKind. Empty when the machine has no IPv4 address, and on joiners.
      */
     joinCode = "";
-    /** "internet": the router forwarded the port and the code carries its public address; "same_network": the LAN address. */
+    /**
+     * "nostr": a version 1 code that works through public Nostr relays (spec/nostr-signaling.md; the default for a direct
+     * host). "internet": the router forwarded the port and the code carries its public address; "same_network": the LAN
+     * address. "none": no code.
+     */
     joinCodeKind = "none";
+    /**
+     * Direct-IP host only: the IP code (address and port, version 0), with `directCodeKind` "internet" or "same_network".
+     * Equal to `joinCode` when Nostr is off; otherwise the code to hand out for LAN play or when the router port is open.
+     */
+    directCode = "";
+    directCodeKind = "none";
     /** Direct-IP host only: this machine's addresses with the port, for an "Advanced" fold-out. */
     directAddresses = [];
     /** Direct-IP host only: how the router port-open went ("UPnP", "no UPnP gateway answered; ...", "off"). */
     portMapping = "";
+    /** Direct-IP host only: the one startup line (bound port, join code, port mapping); see `formatHostLog` in onelobby/direct. */
+    directHostLog = "";
+    /** Browser host only (`kit.hostNostr`): true while the host tab is hidden (see the `hostHiddenChanged` event). */
+    hostHidden = false;
+    /** @internal kit.hostNostr: the tab's visibility changed. */
+    setHostHidden(hidden) {
+        if (this.hostHidden === hidden)
+            return;
+        this.hostHidden = hidden;
+        this.emit("hostHiddenChanged", hidden);
+    }
+    /** @internal onelobby/direct: fires `joinCodeChanged` with the current code. */
+    notifyJoinCodeChanged() {
+        this.emit("joinCodeChanged", this.joinCode, this.joinCodeKind);
+    }
     signaling;
     cfg;
     roster = new Map();
     links = new Map();
     /** ICE from a peer that has no link yet: its candidates can overtake its offer (node-datachannel). */
     earlyIce = new Map();
+    /** Offers from roster members that arrived while the host link was open (see offerVerdict), by sender. */
+    heldOffers = new Map();
     connected = new Set(); // host: peers that said hi
     hiSentTo = new Set();
     epoch = 0;
@@ -77,6 +111,8 @@ export class Lobby extends Emitter {
     lastHeard = new Map();
     /** Host: links of kicked / disconnected peers, kept open briefly (removePeer `linger`). */
     lingering = new Set();
+    /** Host: joiners that joined but are not ready yet, with the cancel of their readyTimeoutMs timer (peerFailed). */
+    notReady = new Map();
     /** Host: per-peer fixed window for rateLimit. */
     rate = new Map();
     /**
@@ -107,6 +143,7 @@ export class Lobby extends Emitter {
         this.hostPeerId = st.hostId;
         this.phase = st.phase;
         this.meta = { ...st.meta };
+        this.name = st.name ?? "";
         this.resumeToken = st.resumeToken;
         for (const p of st.peers)
             this.roster.set(p.peerId, seatName(p));
@@ -131,6 +168,11 @@ export class Lobby extends Emitter {
         this.lockstep = new Lockstep(this.hub, { hashEveryTicks: cfg.hashEveryTicks });
         this.chat = new Chat(this.hub, cfg.wall, (id) => this.voice.isMutedPeer(id));
         this.voice = new Voice(this.hub, cfg.voice);
+        this.pause = new Pause(this.hub, {
+            phase: () => this.phase,
+            hold: (held) => this.lockstep.hold(held),
+            hasPeer: (id) => this.roster.has(id),
+        });
         this.lockstep.on("started", () => this.setPhase("in_game"));
         this.lockstep.on("error", (e) => this.reportError(e));
         this.signaling.onMessage = (m) => this.onSignaling(m);
@@ -162,14 +204,9 @@ export class Lobby extends Emitter {
     get connectedPeers() {
         return this.connectedPeerIds();
     }
-    /**
-     * Joiner: the link to the host as a WebSocket-shaped object (text by default), so WebSocket client code runs
-     * unchanged. It opens when `ready` resolves and closes when the session ends (`host_left` gives code 1001).
-     */
     asWebSocket(opts) {
         return joinerSocket(this, opts);
     }
-    /** Host: `handler(conn)` once per joiner (a WebSocket-shaped connection), the server-side mirror of asWebSocket(). */
     onConnection(handler, opts) {
         return hostConnections(this, handler, opts);
     }
@@ -204,6 +241,17 @@ export class Lobby extends Emitter {
         if (this.mode === "lockstep")
             this.lockstep.hostStart();
     }
+    /**
+     * Changes your display name mid-session. The hub sanitises it (as at hello, at most 24 characters) and every member,
+     * you included, gets `peerRenamed`. Names need not be unique. At most one rename per second; a refusal
+     * (`bad_request` for an empty name, `rate_limited`) arrives on the kit's `error` event. Throws `unsupported` when
+     * the hub is too old to rename.
+     */
+    async rename(name) {
+        if (!(this.cfg.features ?? []).includes("set_name"))
+            throw new OneLobbyError("unsupported", "this lobby's hub cannot rename players (update it)");
+        this.signaling.send({ t: "set_name", name: String(name ?? "") });
+    }
     async setMeta(meta) {
         if (!this.isHost)
             throw new Error("only the host can set metadata");
@@ -368,7 +416,11 @@ export class Lobby extends Emitter {
         }, budget);
     }
     giveUpConnecting() {
-        const err = new OneLobbyError("ice_failed", `could not open a connection to the host${this.relayRetry ? " (direct or relayed)" : ""}`);
+        // what the host link saw (states, signals, timings), so a test log of a failed connect says where it stalled
+        const hostLink = this.links.get(this.hostPeerId);
+        const diagnostics = hostLink ? hostLink.diagnostics?.() : (this.lastHostLinkEnd ?? "no offer from the host ever arrived");
+        // the trace holds ICE candidates (local addresses): keep it in data, out of the message a game may show
+        const err = new OneLobbyError("ice_failed", `could not open a connection to the host${this.relayRetry ? " (direct or relayed)" : ""}`, diagnostics ? { diagnostics } : undefined);
         this.failReady(err);
         this.reportError(err);
         if (this.ended)
@@ -377,6 +429,8 @@ export class Lobby extends Emitter {
         this.teardown("ice_failed");
     }
     // ---- links -----------------------------------------------------------------------------------------------------
+    /** @internal A direct host's hub learns where each joiner's link comes from (Nostr kick bans the address too). */
+    linkAddressSink = null;
     makeLink(peerId, relayOnly = this.cfg.relayOnly) {
         const old = this.links.get(peerId);
         if (old) {
@@ -391,6 +445,7 @@ export class Lobby extends Emitter {
         link.onClose = (reason) => this.onLinkClosed(peerId, link, reason);
         link.onMessage = (ch, bytes) => this.onData(peerId, ch, bytes);
         link.onPath = (path) => this.signaling.send({ t: "path", path });
+        link.onRemoteAddress = (ip) => this.linkAddressSink?.(peerId, ip);
         return link;
     }
     /** Host side: offer to a joiner. */
@@ -420,9 +475,13 @@ export class Lobby extends Emitter {
         this.emit("peerReady", this.roster.get(link.remoteId) ?? { peerId: link.remoteId, name: "" });
         this.flush(link.remoteId);
     }
+    /** Why and how the joiner's last link to the host ended (shown when the join gives up). */
+    lastHostLinkEnd = null;
     onLinkClosed(peerId, link, _reason) {
         if (this.links.get(peerId) !== link)
             return; // replaced
+        if (!this.isHost && peerId === this.hostPeerId)
+            this.lastHostLinkEnd = `link ended (${_reason}): ${link.diagnostics?.() ?? ""}`;
         this.links.delete(peerId);
         this.hiSentTo.delete(link);
         if (this.ended)
@@ -454,6 +513,10 @@ export class Lobby extends Emitter {
         }
         if (!d)
             return;
+        // The topology is a star: a joiner hears only its host. Anything else over some other link (a peer that offered to
+        // us, or a member that dialled us) is not host traffic and must not reach raw / lockstep / pause / chat handling.
+        if (!this.isHost && from !== this.hostPeerId && d.msg.type !== "host_claim")
+            return;
         if (!reassembled)
             this.lastHeard.set(from, this.cfg.clock.now());
         const { msg, route } = d;
@@ -505,6 +568,11 @@ export class Lobby extends Emitter {
             case "chat_reject":
                 this.chat.handle(from, route, msg);
                 break;
+            case "pause_request":
+            case "pause_state":
+            case "pause_refuse":
+                this.pause.handle(from, msg);
+                break;
             case "voice":
                 if (channel === "voice")
                     this.voice.handle(from, route, msg); // a voice frame on another channel is ignored
@@ -525,6 +593,8 @@ export class Lobby extends Emitter {
     }
     onHi(from, lastTick) {
         this.connected.add(from);
+        this.notReady.get(from)?.();
+        this.notReady.delete(from);
         this.sendTo(from, {
             type: "welcome_dc",
             // the tick the snapshot will carry (the game's applied tick), so welcome_dc.tick == snapshot.tick even when
@@ -535,6 +605,7 @@ export class Lobby extends Emitter {
             hostId: this.localPeerId,
         }, 0);
         this.chat.sendHistory(from);
+        this.pause.sendState(from);
         if (this.mode === "lockstep")
             this.lockstep.onPeerHi(from, lastTick);
         this.emit("peerReady", this.roster.get(from) ?? { peerId: from, name: "" });
@@ -583,6 +654,12 @@ export class Lobby extends Emitter {
             return;
         this.hostPeerId = hostId;
         this.emit("hostChanged", hostId);
+        const held = this.heldOffers.get(hostId);
+        if (held) {
+            this.heldOffers.delete(hostId);
+            if (this.cfg.clock.now() - held.at <= HELD_OFFER_MS)
+                void this.acceptOffer(hostId, held.payload);
+        }
     }
     /** The host is gone (link closed, no frames for 3 s, or the server said so): run the s.9 rule. */
     handleHostLost(reason) {
@@ -610,6 +687,16 @@ export class Lobby extends Emitter {
         if (candidate === this.localPeerId)
             this.becomeHost();
         // else: wait for the candidate's host_claim (or the server's host_changed); it offers to us and we answer with hi
+        this.replayHeldOffers();
+    }
+    /** Offers that came from roster members while the host link was still open: now the host is lost, answer them. */
+    replayHeldOffers() {
+        const now = this.cfg.clock.now();
+        for (const [from, held] of [...this.heldOffers]) {
+            this.heldOffers.delete(from);
+            if (now - held.at <= HELD_OFFER_MS && this.roster.has(from))
+                void this.acceptOffer(from, held.payload);
+        }
     }
     becomeHost() {
         this.epoch = (this.epoch + 1) & 0xffff;
@@ -619,6 +706,7 @@ export class Lobby extends Emitter {
         this.hiSentTo.clear();
         this.lastHeard.clear(); // joiners spoke to the old host; their clocks start when they say hi to us
         this.lockstep.becomeHost();
+        this.pause.onBecameHost();
         this.emit("hostChanged", this.localPeerId);
         if (this.serverUp)
             this.signaling.send({ t: "host_changed", hostId: this.localPeerId, epoch: this.epoch });
@@ -628,6 +716,8 @@ export class Lobby extends Emitter {
         }
     }
     onHostClaim(from, epoch, hostId) {
+        if (hostId !== from)
+            return; // a claim is a peer claiming itself; nobody claims for someone else
         const mine = { epoch: this.epoch, hostId: this.hostPeerId };
         const theirs = { epoch, hostId };
         if (hostId === this.hostPeerId && epoch === this.epoch && !this.isHost) {
@@ -667,8 +757,10 @@ export class Lobby extends Emitter {
                 const peer = seatName(m.peer);
                 this.roster.set(peer.peerId, peer);
                 this.emit("peerJoined", peer);
-                if (this.isHost)
+                if (this.isHost) {
+                    this.watchReady(peer.peerId);
                     this.offerTo(peer.peerId);
+                }
                 break;
             }
             case "peer_left":
@@ -702,11 +794,19 @@ export class Lobby extends Emitter {
             case "lobby": {
                 const st = m;
                 this.meta = { ...st.meta };
+                if (st.name)
+                    this.name = st.name;
                 if (st.resumeToken && st.resumeToken !== this.resumeToken) {
                     this.resumeToken = st.resumeToken;
                     this.seatSink?.(this.resumeToken);
                 }
+                const before = this.roster;
                 this.roster = new Map(st.peers.map((p) => [p.peerId, seatName(p)]));
+                for (const [id, p] of this.roster) {
+                    const old = before.get(id);
+                    if (old && old.name !== p.name)
+                        this.emit("peerRenamed", p, old.name);
+                }
                 if (st.hostId !== this.hostPeerId && !this.isHost)
                     this.setHost(st.hostId);
                 this.setPhase(st.phase);
@@ -745,20 +845,21 @@ export class Lobby extends Emitter {
         if (s.ice)
             payload.ice = s.ice;
         if (s.sdp?.type === "offer") {
-            // We are the answerer; an offer always comes from the (new) host.
-            link = this.makeLink(from);
-            const early = this.earlyIce.get(from) ?? [];
-            this.earlyIce.delete(from);
-            // the link holds candidates until the offer is set, so hand them over right behind it
-            const done = link.handleSignal(payload);
-            for (const e of early)
-                void link.handleSignal(e);
-            await done;
+            // We are the answerer. An offer comes from the (new) host, so a peer may dial us only as that rule allows.
+            const verdict = this.offerVerdict(from);
+            if (verdict === "hold") {
+                if (this.heldOffers.size < 64 || this.heldOffers.has(from))
+                    this.heldOffers.set(from, { payload, at: this.cfg.clock.now() });
+            }
+            else if (verdict === "accept")
+                await this.acceptOffer(from, payload);
             return;
         }
         if (!link) {
             if (!payload.ice || this.ended || !this.roster.has(from))
                 return;
+            if (this.cfg.direct && from !== this.hostPeerId)
+                return;
             const q = this.earlyIce.get(from) ?? [];
             if (q.length < 64)
                 q.push(payload);
@@ -767,6 +868,35 @@ export class Lobby extends Emitter {
         }
         await link.handleSignal(payload);
     }
+    /**
+     * Whether an SDP offer from `from` may be answered. The host (or a joiner's host) always may. Direct lobbies have no
+     * migration, so nobody else. In a server lobby a roster member may dial us when we are the host (a claim race decides
+     * who wins) or when our own link to the host is gone (the migration window); while that link is open the offer is
+     * held, to be answered if the host turns out to be lost a moment later.
+     */
+    offerVerdict(from) {
+        if (this.ended || from === this.localPeerId)
+            return "drop";
+        if (!this.isHost && from === this.hostPeerId)
+            return "accept";
+        if (this.cfg.direct || !this.roster.has(from))
+            return "drop";
+        if (this.isHost)
+            return "accept";
+        if (!this.isReady)
+            return "drop"; // still joining: only the host's own offer is expected
+        return this.links.get(this.hostPeerId)?.isOpen ? "hold" : "accept";
+    }
+    async acceptOffer(from, payload) {
+        const link = this.makeLink(from);
+        const early = this.earlyIce.get(from) ?? [];
+        this.earlyIce.delete(from);
+        // the link holds candidates until the offer is set, so hand them over right behind it
+        const done = link.handleSignal(payload);
+        for (const e of early)
+            void link.handleSignal(e);
+        await done;
+    }
     /**
      * `linger` (host kick / disconnect): stop using the peer's link at once but leave it open until that peer closes it
      * or KICK_LINGER_MS pass. The hub tells the peer over its WebSocket; closing the data link first would make it look
@@ -781,6 +911,13 @@ export class Lobby extends Emitter {
         if (peer)
             this.roster.delete(peerId);
         this.earlyIce.delete(peerId);
+        const cancelWatch = this.notReady.get(peerId);
+        if (cancelWatch) {
+            cancelWatch();
+            this.notReady.delete(peerId);
+            if (peer && reason !== "kicked" && reason !== "disconnected")
+                this.emit("peerFailed", peer, reason);
+        }
         const link = this.links.get(peerId);
         if (link && peerId !== this.hostPeerId) {
             link.onMessage = null;
@@ -810,6 +947,7 @@ export class Lobby extends Emitter {
         this.lockstep.onPeerLeft(peerId);
         this.chat.onPeerLeft(peerId);
         this.voice.onPeerLeft(peerId);
+        this.pause.onPeerLeft(peerId);
         if (peer)
             this.emit("peerLeft", peer, reason, close);
         if (peerId === this.hostPeerId && !this.isHost) {
@@ -827,6 +965,8 @@ export class Lobby extends Emitter {
         if (this.phase === p)
             return;
         this.phase = p;
+        if (p === "lobby")
+            this.pause.onLobbyPhase();
         if (p === "in_game" && !this.lockstep.started)
             this.lockstep.markStarted();
         this.emit("phase", p);
@@ -882,11 +1022,29 @@ export class Lobby extends Emitter {
             return;
         this.sendTo(this.hostPeerId, { type: "ping", n: ++this.pingN, t: this.cfg.clock.now() >>> 0 }, 0, "fast");
     }
+    /** Host: report a joiner that is not ready `readyTimeoutMs` after joining as peerFailed("timeout"), once. */
+    watchReady(peerId) {
+        const ms = this.cfg.readyTimeoutMs ?? 0;
+        let cancel = () => { };
+        if (ms > 0) {
+            cancel = this.cfg.clock.setTimeout(() => {
+                if (!this.notReady.delete(peerId))
+                    return;
+                const peer = this.roster.get(peerId);
+                if (peer)
+                    this.emit("peerFailed", peer, "timeout");
+            }, ms);
+        }
+        this.notReady.set(peerId, cancel);
+    }
     teardown(reason, close) {
         if (this.ended)
             return;
         this.ended = true;
         this.cancelReadyTimer?.();
+        for (const cancel of this.notReady.values())
+            cancel();
+        this.notReady.clear();
         if (!this.isReady) {
             const code = reason === "ice_failed" || reason === "kicked" ? reason : "closed";
             this.failReady(new OneLobbyError(code, `the lobby ended before connecting (${reason})`));
@@ -902,6 +1060,7 @@ export class Lobby extends Emitter {
         }
         this.links.clear();
         this.earlyIce.clear();
+        this.heldOffers.clear();
         this.lingering.clear();
         this.signaling.onClose = null;
         this.signaling.onMessage = null;