@couch-kit/display 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @couch-kit/display
 
+## 0.7.0
+
+### Minor Changes
+
+- [#210](https://github.com/faluciano/react-native-couch-kit/pull/210) [`0810bd2`](https://github.com/faluciano/react-native-couch-kit/commit/0810bd28a55fca11eb780c9ba19e3c8e17d4086d) Thanks [@faluciano](https://github.com/faluciano)! - **New features:** `RelayDisplayHost` takes its room back after a dropped relay connection. It used to lose the room on any drop.
+
+  When the display's network blinks, it moves to the new `reconnecting` status. It reconnects with backoff and claims the room with the resume token the relay issued at creation. Phones stay connected throughout and the room code does not change. On success it:
+
+  - disconnects phones that left while it was away
+  - connects phones that arrived, whose held JOINs follow
+  - re-sends the current state to everyone
+
+  The room ends, as before, if:
+
+  - the relay's 30-second grace period runs out
+  - the relay no longer has the room
+  - the relay closed the display on purpose
+  - the relay predates resumption
+
+  Set `resume: false` to end the room on any drop. `stop()` now closes with code 1000, so the relay ends the room at once rather than holding it.
+
+  **Migration:** `RelayDisplayStatus` gains `"reconnecting"`. An exhaustive `switch` over it needs a new case.
+
+### Patch Changes
+
+- Updated dependencies [[`0810bd2`](https://github.com/faluciano/react-native-couch-kit/commit/0810bd28a55fca11eb780c9ba19e3c8e17d4086d), [`0810bd2`](https://github.com/faluciano/react-native-couch-kit/commit/0810bd28a55fca11eb780c9ba19e3c8e17d4086d)]:
+  - @couch-kit/client@0.16.0
+  - @couch-kit/runtime@0.6.0
+
+## 0.6.0
+
+### Minor Changes
+
+- [#208](https://github.com/faluciano/react-native-couch-kit/pull/208) [`99598d6`](https://github.com/faluciano/react-native-couch-kit/commit/99598d6796b0bd3042aa9f3fbd3bf44ee891b890) Thanks [@faluciano](https://github.com/faluciano)! - `RelayDisplayHost` gains `subscribeActions(listener)`, the runtime's complete action stream: the display's own dispatches, players' actions, and join/leave lifecycle actions. State updates are no longer sent through the relay while no phone has joined the game.
+
+### Patch Changes
+
+- Updated dependencies [[`f4b57e3`](https://github.com/faluciano/react-native-couch-kit/commit/f4b57e3fba385d18396781d22a413a1d8afcb909), [`99598d6`](https://github.com/faluciano/react-native-couch-kit/commit/99598d6796b0bd3042aa9f3fbd3bf44ee891b890), [`99598d6`](https://github.com/faluciano/react-native-couch-kit/commit/99598d6796b0bd3042aa9f3fbd3bf44ee891b890)]:
+  - @couch-kit/client@0.15.1
+  - @couch-kit/core@0.10.1
+  - @couch-kit/runtime@0.5.0
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -69,7 +69,8 @@ plus the relay coordinates:
 | `reducer`   | The shared game reducer                        |
 | `initialState` | The shared initial state                    |
 
-| `onStatusChange` | Called when the relay connection changes: `connecting` → `open` → `closed` |
+| `onStatusChange` | Called when the relay connection changes: `connecting` → `open`, then `reconnecting` ↔ `open` across drops, and `closed` at the end |
+| `resume`    | Take the room back after a dropped connection (default `true`). `false` ends the room on any drop |
 | `onError`   | Receives runtime and relay errors; relay errors are `RelayError` with a `code` |
 | `stateThrottleMs` | Minimum interval between state broadcasts. Defaults to 50ms here (not the LAN default of 33ms) so a continuously updating game stays inside the relay's per-connection rate limit |
 
@@ -79,23 +80,40 @@ Instance members:
 - `subscribe(listener)` — subscribe to state changes; returns an unsubscribe fn.
 - `dispatch(action)` — dispatch a trusted host-side action.
 - `status` — `connecting` until the relay confirms the room, then `open`;
-  `closed` once the relay connection is gone.
+  `reconnecting` while taking the room back after a drop; `closed` once the
+  room is gone.
+- `subscribeActions(listener)` — every action the runtime reduces, from any
+  source; pass the host to `useActionRecorder({ source })` to record sessions.
 - `stop()` — tear down the runtime and close the relay socket.
 
 ### When the relay connection drops
 
-A relay room lives exactly as long as its display's socket. If that socket
-closes — the tab loses its network, the relay restarts — the relay closes every
-phone in the room, and the display host:
+When the room is created the relay hands the display a resume token. If the
+display's socket then dies without closing — the tab's network blinks — the
+relay keeps the room for 30 seconds, phones stay connected, and what they send
+is held for the display. Meanwhile the display host:
 
-- marks every player `connected: false` in the game state,
-- moves to `status: "closed"` and calls `onStatusChange("closed")`,
-- reports the loss through `onError`.
+- moves to `status: "reconnecting"`, keeping every player as they were,
+- reconnects with backoff and claims the room with its token,
+- on success, disconnects phones that left while it was away, connects phones
+  that arrived (their held JOINs follow), re-sends the current state to
+  everyone, and returns to `open`. The room code does not change.
 
-It does not reconnect: a new connection is a new room with a new code. The game
-state stays readable, so the display can show what happened rather than a board
-that silently stopped updating. Phones see `disconnectReason: "HOST_LEFT"`,
-which `describeRelayError` turns into a message for the join screen.
+The room ends instead — the display marks every player `connected: false`,
+moves to `status: "closed"`, and reports the loss through `onError` — when:
+
+- the 30 seconds run out, or the relay no longer has the room (it restarted);
+- the relay closed the display on purpose (a rate-limit breach);
+- `resume: false` is set, or the relay predates resumption and issued no token.
+
+The game state stays readable after `closed`, so the display can show what
+happened rather than a board that silently stopped updating. Phones see
+`disconnectReason: "HOST_LEFT"`, which `describeRelayError` turns into a
+message for the join screen.
+
+A page reload is not a drop: the browser closes the socket on purpose and the
+game state is gone with the page, so the relay ends the room at once. So does
+`stop()`.
 
 The host maps relay `PEER_JOINED` / `DATA` / `PEER_LEFT` to the runtime's
 `handleConnection` / `handleMessage` / `handleDisconnect`, and implements the

package/dist/index.js

@@ -5,10 +5,15 @@ import {
   DEFAULT_MAX_MESSAGE_BYTES
 } from "@couch-kit/runtime";
 import {
+  RELAY_CLOSE_HOST_REPLACED,
+  RELAY_HOST_RESUME_GRACE_MS,
+  RelayErrorCodes,
   RelayMessageTypes,
   relayRoomUrl
 } from "@couch-kit/client";
 var DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
+var RECONNECT_BASE_DELAY_MS = 250;
+var RECONNECT_MAX_DELAY_MS = 4000;
 
 class RelayError extends Error {
   code;
@@ -21,42 +26,39 @@ class RelayError extends Error {
 
 class RelayDisplayHost {
   runtime;
+  url;
   ws;
   assignedRoomId;
   onRoomCode;
   onStatusChange;
+  resumeEnabled;
   peers = new Set;
   currentStatus = "connecting";
   socketOpen = false;
   stopped = false;
+  resumeToken = null;
+  awaySince = null;
+  reconnectAttempts = 0;
+  reconnectTimer = null;
   constructor(options) {
-    const { url, roomId, onRoomCode, onStatusChange, ...runtimeConfig } = options;
+    const {
+      url,
+      roomId,
+      onRoomCode,
+      onStatusChange,
+      resume,
+      ...runtimeConfig
+    } = options;
+    this.url = url;
     this.assignedRoomId = roomId ?? null;
     this.onRoomCode = onRoomCode;
     this.onStatusChange = onStatusChange;
+    this.resumeEnabled = resume ?? true;
     this.runtime = new GameHostRuntime({
       ...runtimeConfig,
       stateThrottleMs: runtimeConfig.stateThrottleMs ?? DEFAULT_RELAY_STATE_THROTTLE_MS
     });
-    this.ws = new WebSocket(relayRoomUrl(url, roomId));
-    this.ws.onopen = () => {
-      this.socketOpen = true;
-      this.ws.send(JSON.stringify({
-        type: RelayMessageTypes.CREATE_ROOM,
-        roomId: this.assignedRoomId ?? undefined
-      }));
-    };
-    this.ws.onmessage = (event) => {
-      let msg;
-      try {
-        msg = JSON.parse(event.data);
-      } catch {
-        return;
-      }
-      this.handleRelayMessage(msg);
-    };
-    this.ws.onerror = (event) => this.runtime.handleError(event instanceof Error ? event : new Error("Relay socket error"));
-    this.ws.onclose = (event) => this.handleSocketClose(event);
+    this.connect();
     const transport = {
       send: (connectionId, message) => this.sendEnvelope(message, connectionId),
       broadcast: (message) => this.sendEnvelope(message),
@@ -72,16 +74,54 @@ class RelayDisplayHost {
   }
   getState = () => this.runtime.getState();
   subscribe = (listener) => this.runtime.subscribe(listener);
+  subscribeActions = (listener) => this.runtime.subscribeActions(listener);
   dispatch = (action) => this.runtime.dispatch(action);
   stop() {
     this.stopped = true;
     this.socketOpen = false;
+    this.clearReconnectTimer();
     this.peers.clear();
     this.runtime.setTransport(null);
     this.runtime.stop();
-    this.ws.close();
+    this.ws.close(1000, "Display stopped");
     this.setStatus("closed");
   }
+  connect() {
+    const resumeToken = this.resumeToken;
+    const ws = new WebSocket(relayRoomUrl(this.url, this.assignedRoomId ?? undefined));
+    this.ws = ws;
+    ws.onopen = () => {
+      if (ws !== this.ws)
+        return;
+      this.socketOpen = true;
+      ws.send(JSON.stringify({
+        type: RelayMessageTypes.CREATE_ROOM,
+        roomId: this.assignedRoomId ?? undefined,
+        resumeToken: resumeToken ?? undefined
+      }));
+    };
+    ws.onmessage = (event) => {
+      if (ws !== this.ws)
+        return;
+      let msg;
+      try {
+        msg = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      this.handleRelayMessage(msg);
+    };
+    ws.onerror = (event) => {
+      if (ws !== this.ws || this.currentStatus === "reconnecting")
+        return;
+      this.runtime.handleError(event instanceof Error ? event : new Error("Relay socket error"));
+    };
+    ws.onclose = (event) => {
+      if (ws !== this.ws)
+        return;
+      this.handleSocketClose(event);
+    };
+  }
   setStatus(status) {
     if (this.currentStatus === status)
       return;
@@ -92,12 +132,76 @@ class RelayDisplayHost {
     this.socketOpen = false;
     if (this.stopped)
       return;
+    if (this.canResume(event)) {
+      this.awaySince ??= Date.now();
+      this.setStatus("reconnecting");
+      this.scheduleReconnect();
+      return;
+    }
+    this.endRoom(`Relay connection closed (code ${event?.code ?? "unknown"})` + (event?.reason ? `: ${event.reason}` : ""));
+  }
+  canResume(event) {
+    if (!this.resumeEnabled || this.resumeToken === null)
+      return false;
+    const code = event?.code;
+    if (code === 1008 || code === RELAY_CLOSE_HOST_REPLACED)
+      return false;
+    return this.awaySince === null || this.timeLeftToResume() > 0;
+  }
+  timeLeftToResume() {
+    if (this.awaySince === null)
+      return RELAY_HOST_RESUME_GRACE_MS;
+    return this.awaySince + RELAY_HOST_RESUME_GRACE_MS - Date.now();
+  }
+  scheduleReconnect() {
+    const remaining = this.timeLeftToResume();
+    if (remaining <= 0) {
+      this.endRoom("Could not reach the relay before the room expired");
+      return;
+    }
+    const delay = Math.min(RECONNECT_BASE_DELAY_MS * 2 ** this.reconnectAttempts, RECONNECT_MAX_DELAY_MS, remaining);
+    this.reconnectAttempts++;
+    this.clearReconnectTimer();
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (!this.stopped)
+        this.connect();
+    }, delay);
+  }
+  clearReconnectTimer() {
+    if (this.reconnectTimer !== null)
+      clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+  endRoom(reason) {
+    this.clearReconnectTimer();
+    this.resumeToken = null;
+    this.awaySince = null;
     for (const peerId of this.peers) {
       this.runtime.handleDisconnect(peerId);
     }
     this.peers.clear();
     this.setStatus("closed");
-    this.runtime.handleError(new Error(`Relay connection closed (code ${event?.code ?? "unknown"})` + (event?.reason ? `: ${event.reason}` : "")));
+    this.runtime.handleError(new Error(reason));
+  }
+  handleResumed(peers) {
+    const present = new Set(peers);
+    for (const peerId of Array.from(this.peers)) {
+      if (present.has(peerId))
+        continue;
+      this.peers.delete(peerId);
+      this.runtime.handleDisconnect(peerId);
+    }
+    for (const peerId of present) {
+      if (this.peers.has(peerId))
+        continue;
+      this.peers.add(peerId);
+      this.runtime.handleConnection(peerId);
+    }
+    this.awaySince = null;
+    this.reconnectAttempts = 0;
+    this.setStatus("open");
+    this.runtime.resendState();
   }
   sendMultiEnvelope(entries) {
     if (!this.socketOpen)
@@ -159,10 +263,20 @@ class RelayDisplayHost {
       }
       case RelayMessageTypes.ROOM_CREATED:
         this.assignedRoomId = msg.roomId;
+        this.resumeToken = msg.resumeToken ?? null;
         this.setStatus("open");
         this.onRoomCode?.(msg.roomId);
         break;
+      case RelayMessageTypes.ROOM_RESUMED:
+        this.handleResumed(msg.peers);
+        break;
       case RelayMessageTypes.ERROR:
+        if (this.currentStatus === "reconnecting" && msg.code === RelayErrorCodes.ROOM_NOT_FOUND) {
+          this.socketOpen = false;
+          this.ws.close(1000, "Room expired");
+          this.endRoom("The room expired before the display reconnected");
+          break;
+        }
         this.runtime.handleError(new RelayError(msg.code, msg.message));
         break;
     }

package/lib/relay-display-host.d.ts

@@ -1,15 +1,15 @@
-import { type GameHostRuntimeConfig } from "@couch-kit/runtime";
+import { type GameHostRuntimeConfig, type RuntimeActionListener } from "@couch-kit/runtime";
 import type { IGameState, IAction } from "@couch-kit/core";
 import { type RelayErrorCode } from "@couch-kit/client";
 /**
  * Default minimum interval (ms) between state broadcasts through a relay.
  *
- * Slower than the LAN default on purpose: a relay rate-limits every connection
- * (30 messages/second on the reference relays) and answers a breach by closing
- * the socket — which, for the display, ends the room. 20 broadcasts/second
- * leaves headroom for the unicast traffic the display also sends (WELCOME,
- * PONG, errors), so a game that updates continuously cannot talk itself out of
- * its own room.
+ * Slower than the LAN default on purpose: every frame the display sends is
+ * billed by the relay and counted against the display's rate limit, whose
+ * breach closes the socket — and, for the display, ends the room. 20
+ * broadcasts/second is smooth for a party game and leaves the display's budget
+ * (1200 messages/second on the reference relays) to the unicast replies it
+ * also sends: WELCOME, PONG, errors.
  */
 export declare const DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
 /**
@@ -17,11 +17,14 @@ export declare const DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
  *
  * - `connecting` — socket opening, or open but the room not yet confirmed.
  * - `open` — the room exists and phones can join.
+ * - `reconnecting` — the connection dropped and the display is taking its
+ *   room back. Phones stay connected to the relay meanwhile, and what they
+ *   send is delivered once the room resumes.
  * - `closed` — the relay connection is gone, and the room with it. Terminal:
  *   the game state is still readable, but a new {@link RelayDisplayHost} (and a
  *   new room code) is needed for phones to rejoin.
  */
-export type RelayDisplayStatus = "connecting" | "open" | "closed";
+export type RelayDisplayStatus = "connecting" | "open" | "reconnecting" | "closed";
 /** An error reported by the relay, carrying its machine-readable code. */
 export declare class RelayError extends Error {
     readonly code: RelayErrorCode;
@@ -60,6 +63,13 @@ export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction
      * rather than a board that will never update again.
      */
     onStatusChange?: (status: RelayDisplayStatus) => void;
+    /**
+     * Whether to take the room back after the relay connection drops. Default
+     * `true`: a display whose network blinks reconnects within the relay's grace
+     * period (30 seconds on the reference relays) and keeps its room code and
+     * its phones. Set `false` to have any drop end the room, as before.
+     */
+    resume?: boolean;
 }
 /**
  * Browser **display host** for the cross-network relay transport.
@@ -80,17 +90,26 @@ export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction
  */
 export declare class RelayDisplayHost<S extends IGameState, A extends IAction> {
     private readonly runtime;
-    private readonly ws;
+    private readonly url;
+    /** The current relay socket; replaced on each reconnect. */
+    private ws;
     /** Null until the relay confirms the room, when the code is relay-assigned. */
     private assignedRoomId;
     private readonly onRoomCode?;
     private readonly onStatusChange?;
+    private readonly resumeEnabled;
     /** Connected phone connection ids (relay peer ids). */
     private readonly peers;
     private currentStatus;
     /** Whether frames can be written; a socket still connecting throws on send. */
     private socketOpen;
     private stopped;
+    /** The room's resume credential, from `ROOM_CREATED`. */
+    private resumeToken;
+    /** When the connection dropped, while reconnecting. */
+    private awaySince;
+    private reconnectAttempts;
+    private reconnectTimer;
     constructor(options: RelayDisplayHostOptions<S, A>);
     /**
      * The room code phones join with, or `null` before the relay has assigned
@@ -104,17 +123,54 @@ export declare class RelayDisplayHost<S extends IGameState, A extends IAction> {
     getState: () => S;
     /** Subscribe to state changes (for `useSyncExternalStore` or manual render). */
     subscribe: (listener: () => void) => (() => void);
+    /**
+     * Subscribe to every action the runtime reduces — the display's own
+     * dispatches, players' actions, and join/leave lifecycle actions. A
+     * `RelayDisplayHost` can be passed straight to `useActionRecorder({ source })`.
+     */
+    subscribeActions: (listener: RuntimeActionListener<S, A>) => (() => void);
     /** Dispatch a trusted host-display action. */
     dispatch: (action: A) => void;
     /** Tear down the runtime and relay socket. */
     stop(): void;
+    /**
+     * Opens a relay socket and either creates the room or, once the relay has
+     * issued a resume token, takes it back.
+     *
+     * Every handler checks that its socket is still the current one: a socket
+     * replaced by a reconnect may still deliver a late close or message, and
+     * acting on it would tear down the connection that replaced it.
+     */
+    private connect;
     private setStatus;
     /**
-     * The relay connection ended. The relay drops the room with its host, so
-     * every phone is gone too: mark them disconnected so the state on screen
-     * says so, and report the loss unless this was our own {@link stop}.
+     * The relay connection ended. If the room can still be taken back, try;
+     * otherwise the room is gone.
      */
     private handleSocketClose;
+    /**
+     * Whether a drop is worth reconnecting after: the room exists and has a
+     * token, and the relay did not end it on purpose. A policy close (rate
+     * limited) ends the room on the relay's side, and a replaced host means
+     * another connection holds the token now.
+     */
+    private canResume;
+    /** How long until the relay gives up on this display. */
+    private timeLeftToResume;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    /**
+     * The room is gone, and every phone with it: mark them disconnected so the
+     * state on screen says so, and report the loss.
+     */
+    private endRoom;
+    /**
+     * The room is ours again. Phones that left while the display was away are
+     * disconnected, phones that arrived are connected (their JOINs follow as
+     * ordinary DATA), and everyone gets the current state: updates sent while
+     * the socket was down never left this machine.
+     */
+    private handleResumed;
     /**
      * Sends per-connection messages as one `DATA_MULTI` frame, which the relay
      * unpacks into an ordinary `DATA` frame per phone.

package/lib/relay-display-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay-display-host.d.ts","sourceRoot":"","sources":["../src/relay-display-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAe,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElE,0EAA0E;AAC1E,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,YAAY,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAIhD;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CACtC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO,CACjB,SAAQ,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAuC;IACvE,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAoC;IACzD,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,EAiDjD;IAED;;;;OAIG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,yEAAyE;IACzE,IAAI,MAAM,IAAI,kBAAkB,CAE/B;IAED,wCAAwC;IACxC,QAAQ,QAAO,CAAC,CAA4B;IAE5C,gFAAgF;IAChF,SAAS,aAAc,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CACb;IAEnC,8CAA8C;IAC9C,QAAQ,WAAY,CAAC,KAAG,IAAI,CAAkC;IAE9D,8CAA8C;IAC9C,IAAI,IAAI,IAAI,CAQX;IAED,OAAO,CAAC,SAAS;IAMjB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,kBAAkB;CA4C3B"}
+{"version":3,"file":"relay-display-host.d.ts","sourceRoot":"","sources":["../src/relay-display-host.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/display",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -51,9 +51,9 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/client": "0.15.0",
-    "@couch-kit/core": "0.10.0",
-    "@couch-kit/runtime": "0.4.0"
+    "@couch-kit/client": "0.16.0",
+    "@couch-kit/core": "0.10.1",
+    "@couch-kit/runtime": "0.6.0"
   },
   "devDependencies": {
     "typescript": "^7.0.0"

package/src/relay-display-host.ts

@@ -5,9 +5,13 @@ import {
   type AddressedMessage,
   type GameHostRuntimeConfig,
   type GameRuntimeTransport,
+  type RuntimeActionListener,
 } from "@couch-kit/runtime";
 import type { IGameState, IAction, HostMessage } from "@couch-kit/core";
 import {
+  RELAY_CLOSE_HOST_REPLACED,
+  RELAY_HOST_RESUME_GRACE_MS,
+  RelayErrorCodes,
   RelayMessageTypes,
   relayRoomUrl,
   type RelayErrorCode,
@@ -17,12 +21,12 @@ import {
 /**
  * Default minimum interval (ms) between state broadcasts through a relay.
  *
- * Slower than the LAN default on purpose: a relay rate-limits every connection
- * (30 messages/second on the reference relays) and answers a breach by closing
- * the socket — which, for the display, ends the room. 20 broadcasts/second
- * leaves headroom for the unicast traffic the display also sends (WELCOME,
- * PONG, errors), so a game that updates continuously cannot talk itself out of
- * its own room.
+ * Slower than the LAN default on purpose: every frame the display sends is
+ * billed by the relay and counted against the display's rate limit, whose
+ * breach closes the socket — and, for the display, ends the room. 20
+ * broadcasts/second is smooth for a party game and leaves the display's budget
+ * (1200 messages/second on the reference relays) to the unicast replies it
+ * also sends: WELCOME, PONG, errors.
  */
 export const DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
 
@@ -31,11 +35,20 @@ export const DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
  *
  * - `connecting` — socket opening, or open but the room not yet confirmed.
  * - `open` — the room exists and phones can join.
+ * - `reconnecting` — the connection dropped and the display is taking its
+ *   room back. Phones stay connected to the relay meanwhile, and what they
+ *   send is delivered once the room resumes.
  * - `closed` — the relay connection is gone, and the room with it. Terminal:
  *   the game state is still readable, but a new {@link RelayDisplayHost} (and a
  *   new room code) is needed for phones to rejoin.
  */
-export type RelayDisplayStatus = "connecting" | "open" | "closed";
+export type RelayDisplayStatus =
+  "connecting" | "open" | "reconnecting" | "closed";
+
+/** First delay before a reconnect attempt, doubled per failure. */
+const RECONNECT_BASE_DELAY_MS = 250;
+/** Longest wait between reconnect attempts. */
+const RECONNECT_MAX_DELAY_MS = 4_000;
 
 /** An error reported by the relay, carrying its machine-readable code. */
 export class RelayError extends Error {
@@ -84,6 +97,13 @@ export interface RelayDisplayHostOptions<
    * rather than a board that will never update again.
    */
   onStatusChange?: (status: RelayDisplayStatus) => void;
+  /**
+   * Whether to take the room back after the relay connection drops. Default
+   * `true`: a display whose network blinks reconnects within the relay's grace
+   * period (30 seconds on the reference relays) and keeps its room code and
+   * its phones. Set `false` to have any drop end the room, as before.
+   */
+  resume?: boolean;
 }
 
 /**
@@ -105,60 +125,47 @@ export interface RelayDisplayHostOptions<
  */
 export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   private readonly runtime: GameHostRuntime<S, A>;
-  private readonly ws: WebSocket;
+  private readonly url: string;
+  /** The current relay socket; replaced on each reconnect. */
+  private ws!: WebSocket;
   /** Null until the relay confirms the room, when the code is relay-assigned. */
   private assignedRoomId: string | null;
   private readonly onRoomCode?: (roomCode: string) => void;
   private readonly onStatusChange?: (status: RelayDisplayStatus) => void;
+  private readonly resumeEnabled: boolean;
   /** Connected phone connection ids (relay peer ids). */
   private readonly peers = new Set<string>();
   private currentStatus: RelayDisplayStatus = "connecting";
   /** Whether frames can be written; a socket still connecting throws on send. */
   private socketOpen = false;
   private stopped = false;
+  /** The room's resume credential, from `ROOM_CREATED`. */
+  private resumeToken: string | null = null;
+  /** When the connection dropped, while reconnecting. */
+  private awaySince: number | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(options: RelayDisplayHostOptions<S, A>) {
-    const { url, roomId, onRoomCode, onStatusChange, ...runtimeConfig } =
-      options;
+    const {
+      url,
+      roomId,
+      onRoomCode,
+      onStatusChange,
+      resume,
+      ...runtimeConfig
+    } = options;
+    this.url = url;
     this.assignedRoomId = roomId ?? null;
     this.onRoomCode = onRoomCode;
     this.onStatusChange = onStatusChange;
+    this.resumeEnabled = resume ?? true;
     this.runtime = new GameHostRuntime<S, A>({
       ...runtimeConfig,
       stateThrottleMs:
         runtimeConfig.stateThrottleMs ?? DEFAULT_RELAY_STATE_THROTTLE_MS,
     });
-    this.ws = new WebSocket(relayRoomUrl(url, roomId));
-
-    this.ws.onopen = () => {
-      this.socketOpen = true;
-      // No roomId asks the relay to allocate one. Sending the field as
-      // undefined omits it from the JSON, which is what the relay reads as
-      // "you pick".
-      this.ws.send(
-        JSON.stringify({
-          type: RelayMessageTypes.CREATE_ROOM,
-          roomId: this.assignedRoomId ?? undefined,
-        }),
-      );
-    };
-
-    this.ws.onmessage = (event: MessageEvent) => {
-      let msg: RelayServerMessage;
-      try {
-        msg = JSON.parse(event.data as string) as RelayServerMessage;
-      } catch {
-        return;
-      }
-      this.handleRelayMessage(msg);
-    };
-
-    this.ws.onerror = (event) =>
-      this.runtime.handleError(
-        event instanceof Error ? event : new Error("Relay socket error"),
-      );
-
-    this.ws.onclose = (event: CloseEvent) => this.handleSocketClose(event);
+    this.connect();
 
     const transport: GameRuntimeTransport = {
       send: (connectionId, message) => this.sendEnvelope(message, connectionId),
@@ -189,6 +196,14 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   subscribe = (listener: () => void): (() => void) =>
     this.runtime.subscribe(listener);
 
+  /**
+   * Subscribe to every action the runtime reduces — the display's own
+   * dispatches, players' actions, and join/leave lifecycle actions. A
+   * `RelayDisplayHost` can be passed straight to `useActionRecorder({ source })`.
+   */
+  subscribeActions = (listener: RuntimeActionListener<S, A>): (() => void) =>
+    this.runtime.subscribeActions(listener);
+
   /** Dispatch a trusted host-display action. */
   dispatch = (action: A): void => this.runtime.dispatch(action);
 
@@ -196,13 +211,72 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   stop(): void {
     this.stopped = true;
     this.socketOpen = false;
+    this.clearReconnectTimer();
     this.peers.clear();
     this.runtime.setTransport(null);
     this.runtime.stop();
-    this.ws.close();
+    // A deliberate close: the relay ends the room now rather than holding it
+    // for a resume that will never come.
+    this.ws.close(1000, "Display stopped");
     this.setStatus("closed");
   }
 
+  /**
+   * Opens a relay socket and either creates the room or, once the relay has
+   * issued a resume token, takes it back.
+   *
+   * Every handler checks that its socket is still the current one: a socket
+   * replaced by a reconnect may still deliver a late close or message, and
+   * acting on it would tear down the connection that replaced it.
+   */
+  private connect(): void {
+    const resumeToken = this.resumeToken;
+    const ws = new WebSocket(
+      relayRoomUrl(this.url, this.assignedRoomId ?? undefined),
+    );
+    this.ws = ws;
+
+    ws.onopen = () => {
+      if (ws !== this.ws) return;
+      this.socketOpen = true;
+      // No roomId asks the relay to allocate one. Sending the field as
+      // undefined omits it from the JSON, which is what the relay reads as
+      // "you pick".
+      ws.send(
+        JSON.stringify({
+          type: RelayMessageTypes.CREATE_ROOM,
+          roomId: this.assignedRoomId ?? undefined,
+          resumeToken: resumeToken ?? undefined,
+        }),
+      );
+    };
+
+    ws.onmessage = (event: MessageEvent) => {
+      if (ws !== this.ws) return;
+      let msg: RelayServerMessage;
+      try {
+        msg = JSON.parse(event.data as string) as RelayServerMessage;
+      } catch {
+        return;
+      }
+      this.handleRelayMessage(msg);
+    };
+
+    ws.onerror = (event) => {
+      // A failed reconnect attempt is expected while the network is down; its
+      // close event decides what happens next.
+      if (ws !== this.ws || this.currentStatus === "reconnecting") return;
+      this.runtime.handleError(
+        event instanceof Error ? event : new Error("Relay socket error"),
+      );
+    };
+
+    ws.onclose = (event: CloseEvent) => {
+      if (ws !== this.ws) return;
+      this.handleSocketClose(event);
+    };
+  }
+
   private setStatus(status: RelayDisplayStatus): void {
     if (this.currentStatus === status) return;
     this.currentStatus = status;
@@ -210,25 +284,107 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   }
 
   /**
-   * The relay connection ended. The relay drops the room with its host, so
-   * every phone is gone too: mark them disconnected so the state on screen
-   * says so, and report the loss unless this was our own {@link stop}.
+   * The relay connection ended. If the room can still be taken back, try;
+   * otherwise the room is gone.
    */
   private handleSocketClose(event: CloseEvent): void {
     this.socketOpen = false;
     if (this.stopped) return;
 
+    if (this.canResume(event)) {
+      this.awaySince ??= Date.now();
+      this.setStatus("reconnecting");
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.endRoom(
+      `Relay connection closed (code ${event?.code ?? "unknown"})` +
+        (event?.reason ? `: ${event.reason}` : ""),
+    );
+  }
+
+  /**
+   * Whether a drop is worth reconnecting after: the room exists and has a
+   * token, and the relay did not end it on purpose. A policy close (rate
+   * limited) ends the room on the relay's side, and a replaced host means
+   * another connection holds the token now.
+   */
+  private canResume(event: CloseEvent): boolean {
+    if (!this.resumeEnabled || this.resumeToken === null) return false;
+    const code = event?.code;
+    if (code === 1008 || code === RELAY_CLOSE_HOST_REPLACED) return false;
+    return this.awaySince === null || this.timeLeftToResume() > 0;
+  }
+
+  /** How long until the relay gives up on this display. */
+  private timeLeftToResume(): number {
+    if (this.awaySince === null) return RELAY_HOST_RESUME_GRACE_MS;
+    return this.awaySince + RELAY_HOST_RESUME_GRACE_MS - Date.now();
+  }
+
+  private scheduleReconnect(): void {
+    const remaining = this.timeLeftToResume();
+    if (remaining <= 0) {
+      this.endRoom("Could not reach the relay before the room expired");
+      return;
+    }
+    const delay = Math.min(
+      RECONNECT_BASE_DELAY_MS * 2 ** this.reconnectAttempts,
+      RECONNECT_MAX_DELAY_MS,
+      remaining,
+    );
+    this.reconnectAttempts++;
+    this.clearReconnectTimer();
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (!this.stopped) this.connect();
+    }, delay);
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer !== null) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+
+  /**
+   * The room is gone, and every phone with it: mark them disconnected so the
+   * state on screen says so, and report the loss.
+   */
+  private endRoom(reason: string): void {
+    this.clearReconnectTimer();
+    this.resumeToken = null;
+    this.awaySince = null;
     for (const peerId of this.peers) {
       this.runtime.handleDisconnect(peerId);
     }
     this.peers.clear();
     this.setStatus("closed");
-    this.runtime.handleError(
-      new Error(
-        `Relay connection closed (code ${event?.code ?? "unknown"})` +
-          (event?.reason ? `: ${event.reason}` : ""),
-      ),
-    );
+    this.runtime.handleError(new Error(reason));
+  }
+
+  /**
+   * The room is ours again. Phones that left while the display was away are
+   * disconnected, phones that arrived are connected (their JOINs follow as
+   * ordinary DATA), and everyone gets the current state: updates sent while
+   * the socket was down never left this machine.
+   */
+  private handleResumed(peers: readonly string[]): void {
+    const present = new Set(peers);
+    for (const peerId of Array.from(this.peers)) {
+      if (present.has(peerId)) continue;
+      this.peers.delete(peerId);
+      this.runtime.handleDisconnect(peerId);
+    }
+    for (const peerId of present) {
+      if (this.peers.has(peerId)) continue;
+      this.peers.add(peerId);
+      this.runtime.handleConnection(peerId);
+    }
+    this.awaySince = null;
+    this.reconnectAttempts = 0;
+    this.setStatus("open");
+    this.runtime.resendState();
   }
 
   /**
@@ -325,10 +481,25 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
         // Carries the code when the relay chose it, and confirms the code when
         // the caller supplied one.
         this.assignedRoomId = msg.roomId;
+        this.resumeToken = msg.resumeToken ?? null;
         this.setStatus("open");
         this.onRoomCode?.(msg.roomId);
         break;
+      case RelayMessageTypes.ROOM_RESUMED:
+        this.handleResumed(msg.peers);
+        break;
       case RelayMessageTypes.ERROR:
+        // The relay no longer has the room (or the token): it expired, or
+        // the relay restarted. Nothing left to reconnect to.
+        if (
+          this.currentStatus === "reconnecting" &&
+          msg.code === RelayErrorCodes.ROOM_NOT_FOUND
+        ) {
+          this.socketOpen = false;
+          this.ws.close(1000, "Room expired");
+          this.endRoom("The room expired before the display reconnected");
+          break;
+        }
         this.runtime.handleError(new RelayError(msg.code, msg.message));
         break;
       // ROOM_JOINED is an acknowledgement; no action needed.