@couch-kit/runtime 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @couch-kit/runtime
 
+## 0.3.0
+
+### Minor Changes
+
+- [#164](https://github.com/faluciano/react-native-couch-kit/pull/164) [`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e) Thanks [@faluciano](https://github.com/faluciano)! - Send a projected state update as one relay frame instead of one per player
+
+  A game with a `project` function sends every player their own view, which meant
+  one WebSocket frame per player for every state change. Relays bill and
+  rate-limit per inbound frame, so a four-player table paid four messages for one
+  update and spent four of the display's 30-per-second budget.
+
+  `GameRuntimeTransport` gains an optional `sendMany(entries)`. When a transport
+  implements it, the runtime hands over the whole projected batch at once;
+  transports that do not — the LAN WebSocket path — keep receiving one `send` per
+  connection and are unaffected.
+
+  `RelayDisplayHost` implements it with a new `DATA_MULTI` envelope carrying a
+  peer-id-to-payload map, which the relay unpacks into ordinary `DATA` frames.
+  Phones need no update — nothing on the client side can tell a batched update
+  from a unicast one. If the combined frame would exceed the relay's 256KB
+  ceiling, the display falls back to individual frames rather than send something
+  the relay would drop.
+
+  Relays must be updated before displays: both bundled implementations
+  (`services/relay`, `services/relay-worker`) understand `DATA_MULTI`, and an
+  older relay answers it with `MALFORMED`. The type is host-only — a phone sending
+  it is rejected, so it cannot be used to reach another phone directly.
+
+### Patch Changes
+
+- Updated dependencies [[`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e)]:
+  - @couch-kit/core@0.10.0
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -565,20 +565,34 @@ class GameHostRuntime {
     return project ? project(this.state, playerId) : this.state;
   }
   broadcastState = () => {
-    if (!this.transport)
+    const transport = this.transport;
+    if (!transport)
       return;
     const actions = this.actionQueue;
     this.actionQueue = [];
     this.stateDirty = false;
     if (!this.config.project) {
-      this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+      transport.broadcast(createStateUpdateMessage(this.state, actions));
       return;
     }
+    const entries = [];
     for (const connectionId of this.joinedConnections) {
       const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
       if (!playerId)
         continue;
-      this.send(connectionId, createStateUpdateMessage(this.viewFor(playerId), actions));
+      entries.push({
+        connectionId,
+        message: createStateUpdateMessage(this.viewFor(playerId), actions)
+      });
+    }
+    if (entries.length === 0)
+      return;
+    if (transport.sendMany) {
+      transport.sendMany(entries);
+      return;
+    }
+    for (const { connectionId, message } of entries) {
+      this.send(connectionId, message);
     }
   };
   send(connectionId, message) {

package/dist/index.js

@@ -520,20 +520,34 @@ class GameHostRuntime {
     return project ? project(this.state, playerId) : this.state;
   }
   broadcastState = () => {
-    if (!this.transport)
+    const transport = this.transport;
+    if (!transport)
       return;
     const actions = this.actionQueue;
     this.actionQueue = [];
     this.stateDirty = false;
     if (!this.config.project) {
-      this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+      transport.broadcast(createStateUpdateMessage(this.state, actions));
       return;
     }
+    const entries = [];
     for (const connectionId of this.joinedConnections) {
       const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
       if (!playerId)
         continue;
-      this.send(connectionId, createStateUpdateMessage(this.viewFor(playerId), actions));
+      entries.push({
+        connectionId,
+        message: createStateUpdateMessage(this.viewFor(playerId), actions)
+      });
+    }
+    if (entries.length === 0)
+      return;
+    if (transport.sendMany) {
+      transport.sendMany(entries);
+      return;
+    }
+    for (const { connectionId, message } of entries) {
+      this.send(connectionId, message);
     }
   };
   send(connectionId, message) {

package/lib/runtime.d.ts

@@ -1,8 +1,24 @@
 import { type GameReducer, type HostMessage, type IAction, type IGameState } from "@couch-kit/core";
+/** One connection's share of a {@link GameRuntimeTransport.sendMany} delivery. */
+export interface AddressedMessage {
+    connectionId: string;
+    message: HostMessage;
+}
 /** Minimal message-delivery surface required by the authoritative runtime. */
 export interface GameRuntimeTransport {
     send(connectionId: string, message: HostMessage): void;
     broadcast(message: HostMessage): void;
+    /**
+     * Delivers a batch of per-connection messages, for transports that can carry
+     * them in one frame.
+     *
+     * Optional: the runtime falls back to a {@link GameRuntimeTransport.send} per
+     * entry, which is what a plain LAN WebSocket transport wants anyway. It earns
+     * its keep on the relay, where each frame the display sends is separately
+     * billed and rate-limited, so a projected state update costs one message
+     * rather than one per player.
+     */
+    sendMany?(entries: readonly AddressedMessage[]): void;
 }
 /** Configuration shared by every authoritative Couch Kit host transport. */
 export interface GameHostRuntimeConfig<S extends IGameState, A extends IAction> {

package/lib/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -56,7 +56,7 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.9.3"
+    "@couch-kit/core": "0.10.0"
   },
   "devDependencies": {
     "typescript": "^7.0.0"

package/src/runtime.ts

@@ -23,10 +23,27 @@ import {
   type JoinSessionPayload,
 } from "./session-manager.js";
 
+/** One connection's share of a {@link GameRuntimeTransport.sendMany} delivery. */
+export interface AddressedMessage {
+  connectionId: string;
+  message: HostMessage;
+}
+
 /** Minimal message-delivery surface required by the authoritative runtime. */
 export interface GameRuntimeTransport {
   send(connectionId: string, message: HostMessage): void;
   broadcast(message: HostMessage): void;
+  /**
+   * Delivers a batch of per-connection messages, for transports that can carry
+   * them in one frame.
+   *
+   * Optional: the runtime falls back to a {@link GameRuntimeTransport.send} per
+   * entry, which is what a plain LAN WebSocket transport wants anyway. It earns
+   * its keep on the relay, where each frame the display sends is separately
+   * billed and rate-limited, so a projected state update costs one message
+   * rather than one per player.
+   */
+  sendMany?(entries: readonly AddressedMessage[]): void;
 }
 
 /** Configuration shared by every authoritative Couch Kit host transport. */
@@ -404,27 +421,39 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
   }
 
   private readonly broadcastState = (): void => {
-    if (!this.transport) return;
+    const transport = this.transport;
+    if (!transport) return;
 
     const actions = this.actionQueue;
     this.actionQueue = [];
     this.stateDirty = false;
 
     if (!this.config.project) {
-      this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+      transport.broadcast(createStateUpdateMessage(this.state, actions));
       return;
     }
 
     // Projected games get one message per connection rather than a broadcast:
-    // a shared frame cannot carry different views. Costs N sends instead of 1,
-    // which is bounded by players-per-room.
+    // a shared frame cannot carry different views. Transports that can batch
+    // (see GameRuntimeTransport.sendMany) still put them on the wire as a
+    // single frame; the rest fall back to N sends, bounded by players-per-room.
+    const entries: AddressedMessage[] = [];
     for (const connectionId of this.joinedConnections) {
       const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
       if (!playerId) continue;
-      this.send(
+      entries.push({
         connectionId,
-        createStateUpdateMessage(this.viewFor(playerId), actions),
-      );
+        message: createStateUpdateMessage(this.viewFor(playerId), actions),
+      });
+    }
+    if (entries.length === 0) return;
+
+    if (transport.sendMany) {
+      transport.sendMany(entries);
+      return;
+    }
+    for (const { connectionId, message } of entries) {
+      this.send(connectionId, message);
     }
   };