@couch-kit/client 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @couch-kit/client
 
+## 0.14.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.
+
+- [#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)! - Back the time-sync ping off to 30s once the clock estimate settles
+
+  `useGameClient`'s clock sync pinged every 5 seconds for the life of the
+  connection. It now starts there and doubles to a 30-second ceiling
+  (`MAX_SYNC_INTERVAL`), resetting to the fast interval whenever a new socket is
+  established, including after a reconnect.
+
+  The first few pings are what converge the offset; the clock difference they
+  measure does not drift on a human timescale, so the fast interval stops earning
+  its cost within about a minute. On a relay transport it is not free: each ping
+  is a message in and a `PONG` back out, and pings are the only traffic an idle
+  table generates at all. A four-player lobby went from 5,760 relay messages an
+  hour to under 1,000 while sitting untouched.
+
+  `rtt` and `getServerTime()` are unchanged in accuracy — both are updated by the
+  same `PONG` handling as before, just less often once settled. Games needing the
+  old cadence can dispatch their own pings; the constants
+  (`DEFAULT_SYNC_INTERVAL`, `MAX_SYNC_INTERVAL`, `SYNC_BACKOFF_FACTOR`) are
+  exported from `@couch-kit/core`.
+
+### Patch Changes
+
+- Updated dependencies [[`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e)]:
+  - @couch-kit/core@0.10.0
+
+## 0.13.0
+
+### Minor Changes
+
+- [#158](https://github.com/faluciano/react-native-couch-kit/pull/158) [`509ea7c`](https://github.com/faluciano/react-native-couch-kit/commit/509ea7c02aa6f2e56ebf01e781d6de74f0ded021) Thanks [@faluciano](https://github.com/faluciano)! - Let the relay assign room codes
+
+  `RelayDisplayHost`'s `roomId` is now optional. Omit it and the relay mints an
+  unused six-character code, reported through the new `onRoomCode` callback and
+  the `roomCode` getter.
+
+  A display could never check its own code for collisions — only the relay knows
+  which codes are live — so a self-chosen code could land on a game already in
+  progress, and did so only after it was on screen. Minted codes are drawn from
+  the CSPRNG over a 32-character alphabet without `O`/`0` or `I`/`1`, giving about
+  1.07 billion codes.
+
+  Existing callers that pass `roomId` keep their current behaviour, including
+  `ROOM_EXISTS` when the code is taken. New callers should expect the code to
+  arrive one round trip after connecting rather than being known up front:
+
+  ```ts
+  const [roomCode, setRoomCode] = useState<string | null>(null);
+  new RelayDisplayHost({ url, onRoomCode: setRoomCode, reducer, initialState });
+  ```
+
+  Relays need a matching update to mint: both bundled implementations
+  (`services/relay`, `services/relay-worker`) support it. A display that omits
+  `roomId` against an older relay gets `MALFORMED`.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/index.js

@@ -15,6 +15,8 @@ import {
   MessageTypes,
   generateId,
   DEFAULT_SYNC_INTERVAL,
+  MAX_SYNC_INTERVAL,
+  SYNC_BACKOFF_FACTOR,
   MAX_PENDING_PINGS
 } from "@couch-kit/core";
 
@@ -53,6 +55,9 @@ function calculateTimeSync(clientSendTime, clientReceiveTime, serverTime) {
   const offset = expectedServerTime - clientReceiveTime;
   return { offset, rtt };
 }
+function nextSyncInterval(current) {
+  return Math.min(current * SYNC_BACKOFF_FACTOR, MAX_SYNC_INTERVAL);
+}
 function useServerTime(socket) {
   const [timeSync, setTimeSync] = useState({
     offset: 0,
@@ -74,6 +79,8 @@ function useServerTime(socket) {
   useEffect(() => {
     if (!socket || socket.readyState !== TransportReadyState.OPEN)
       return;
+    let delay = DEFAULT_SYNC_INTERVAL;
+    let timer = null;
     const sync = () => {
       if (pings.current.size >= MAX_PENDING_PINGS) {
         const oldest = pings.current.keys().next().value;
@@ -87,10 +94,14 @@ function useServerTime(socket) {
         type: MessageTypes.PING,
         payload: { id, timestamp }
       }));
+      delay = nextSyncInterval(delay);
+      timer = setTimeout(sync, delay);
     };
     sync();
-    const interval = setInterval(sync, DEFAULT_SYNC_INTERVAL);
-    return () => clearInterval(interval);
+    return () => {
+      if (timer !== null)
+        clearTimeout(timer);
+    };
   }, [socket]);
   return { getServerTime, rtt: timeSync.rtt, handlePong };
 }
@@ -330,6 +341,7 @@ var RelayMessageTypes = {
   PEER_JOINED: "PEER_JOINED",
   PEER_LEFT: "PEER_LEFT",
   DATA: "DATA",
+  DATA_MULTI: "DATA_MULTI",
   ERROR: "ERROR"
 };
 var RelayErrorCodes = {
@@ -345,9 +357,10 @@ var RelayErrorCodes = {
 function relayRoomUrl(url, roomId) {
   const trimmed = url.replace(/\/+$/, "");
   const [base, query] = trimmed.split("?", 2);
-  const path = `${base}/r/${encodeURIComponent(roomId)}`;
+  const path = roomId === undefined ? `${base}${RELAY_MINT_PATH}` : `${base}/r/${encodeURIComponent(roomId)}`;
   return query ? `${path}?${query}` : path;
 }
+var RELAY_MINT_PATH = "/new";
 // src/relay-transport.ts
 var POLICY_CLOSE_CODE = 1008;
 
@@ -637,6 +650,7 @@ export {
   resolveSessionSecret,
   relayRoomUrl,
   normalizeRoomCode,
+  nextSyncInterval,
   interpretHostMessage,
   describeRelayError,
   createWebSocketTransport,
@@ -647,5 +661,6 @@ export {
   SESSION_SECRET_KEY,
   RelayMessageTypes,
   RelayErrorCodes,
-  RelayClientTransport
+  RelayClientTransport,
+  RELAY_MINT_PATH
 };

package/lib/relay-protocol.d.ts

@@ -27,6 +27,8 @@ export declare const RelayMessageTypes: {
     readonly PEER_LEFT: "PEER_LEFT";
     /** Bidirectional: carries an opaque Couch Kit JSON message as `data`. */
     readonly DATA: "DATA";
+    /** Display → relay: one frame carrying a different payload per phone. */
+    readonly DATA_MULTI: "DATA_MULTI";
     /** Relay → client: a protocol/room error. */
     readonly ERROR: "ERROR";
 };
@@ -97,6 +99,22 @@ export interface DataMessage {
     to?: string;
     data: string;
 }
+/**
+ * Display → relay: one envelope carrying a different payload per phone.
+ *
+ * `payloads` maps a phone's `peerId` to the already-serialized Couch Kit
+ * message for that phone. The relay unpacks it into ordinary
+ * {@link DataMessage} frames, so phones never see this type — it exists purely
+ * so a projected game costs one inbound relay message per state change instead
+ * of one per player. Peer ids the room does not know are skipped.
+ *
+ * Host-only: the relay rejects it from a phone.
+ */
+export interface DataMultiMessage {
+    type: typeof RelayMessageTypes.DATA_MULTI;
+    roomId: string;
+    payloads: Record<string, string>;
+}
 /** Relay → client: a protocol/room error. */
 export interface RelayErrorMessage {
     type: typeof RelayMessageTypes.ERROR;
@@ -104,7 +122,7 @@ export interface RelayErrorMessage {
     message: string;
 }
 /** Any message a client may send to the relay. */
-export type RelayClientMessage = CreateRoomMessage | JoinRoomMessage | DataMessage;
+export type RelayClientMessage = CreateRoomMessage | JoinRoomMessage | DataMessage | DataMultiMessage;
 /** Any message the relay may send to a client. */
 export type RelayServerMessage = RoomCreatedMessage | RoomJoinedMessage | PeerJoinedMessage | PeerLeftMessage | DataMessage | RelayErrorMessage;
 /** Every relay wire message. */
@@ -119,8 +137,19 @@ export type RelayMessage = RelayClientMessage | RelayServerMessage;
  * that keep every room in one process (the Bun reference server) ignore the
  * path, so this is safe to send to either.
  *
+ * Passing no room code addresses {@link RELAY_MINT_PATH} instead, asking the
+ * relay to allocate one; the code comes back in `ROOM_CREATED`.
+ *
  * @param url - Base relay URL, e.g. `wss://relay.example.com`.
- * @param roomId - Room code to address.
+ * @param roomId - Room code to address, or omitted to have one minted.
+ */
+export declare function relayRoomUrl(url: string, roomId?: string): string;
+/**
+ * Path that asks the relay to allocate a room code.
+ *
+ * Reserved, so it can never be mistaken for a room code. Single-process relays
+ * ignore the path and mint from the `CREATE_ROOM` message alone; sharded relays
+ * need it, because they must choose the shard before any frame arrives.
  */
-export declare function relayRoomUrl(url: string, roomId: string): string;
+export declare const RELAY_MINT_PATH = "/new";
 //# sourceMappingURL=relay-protocol.d.ts.map

package/lib/relay-protocol.d.ts.map

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

package/lib/time-sync.d.ts

@@ -15,6 +15,19 @@ export declare function calculateTimeSync(clientSendTime: number, clientReceiveT
     offset: number;
     rtt: number;
 };
+/**
+ * The interval to wait before the next PING, given the one just used.
+ *
+ * Grows geometrically to {@link MAX_SYNC_INTERVAL}: the first pings after
+ * connecting are what converge the offset, and re-measuring it every few
+ * seconds forever buys nothing — the clock difference does not move, while on a
+ * relay transport each ping is a billed message in both directions and the only
+ * traffic an idle table generates at all.
+ *
+ * @param current - Interval (ms) used for the ping just sent.
+ * @returns The next interval, capped at {@link MAX_SYNC_INTERVAL}.
+ */
+export declare function nextSyncInterval(current: number): number;
 /**
  * React hook that synchronizes the client clock with the host server.
  *

package/lib/time-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-sync.d.ts","sourceRoot":"","sources":["../src/time-sync.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAOxE;;;;;;;;;;;GAWG;AAEH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM;;;EAQnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;;;0BAgB9C;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;EAgDtE"}
+{"version":3,"file":"time-sync.d.ts","sourceRoot":"","sources":["../src/time-sync.ts"],"names":[],"mappings":"AASA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAOxE;;;;;;;;;;;GAWG;AAEH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM;;;EAQnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;;;0BAgB9C;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;EA8DtE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -49,7 +49,7 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.9.3"
+    "@couch-kit/core": "0.10.0"
   },
   "devDependencies": {
     "react": "^19.0.0",

package/src/relay-protocol.ts

@@ -28,6 +28,8 @@ export const RelayMessageTypes = {
   PEER_LEFT: "PEER_LEFT",
   /** Bidirectional: carries an opaque Couch Kit JSON message as `data`. */
   DATA: "DATA",
+  /** Display → relay: one frame carrying a different payload per phone. */
+  DATA_MULTI: "DATA_MULTI",
   /** Relay → client: a protocol/room error. */
   ERROR: "ERROR",
 } as const;
@@ -109,6 +111,23 @@ export interface DataMessage {
   data: string;
 }
 
+/**
+ * Display → relay: one envelope carrying a different payload per phone.
+ *
+ * `payloads` maps a phone's `peerId` to the already-serialized Couch Kit
+ * message for that phone. The relay unpacks it into ordinary
+ * {@link DataMessage} frames, so phones never see this type — it exists purely
+ * so a projected game costs one inbound relay message per state change instead
+ * of one per player. Peer ids the room does not know are skipped.
+ *
+ * Host-only: the relay rejects it from a phone.
+ */
+export interface DataMultiMessage {
+  type: typeof RelayMessageTypes.DATA_MULTI;
+  roomId: string;
+  payloads: Record<string, string>;
+}
+
 /** Relay → client: a protocol/room error. */
 export interface RelayErrorMessage {
   type: typeof RelayMessageTypes.ERROR;
@@ -118,9 +137,7 @@ export interface RelayErrorMessage {
 
 /** Any message a client may send to the relay. */
 export type RelayClientMessage =
-  | CreateRoomMessage
-  | JoinRoomMessage
-  | DataMessage;
+  CreateRoomMessage | JoinRoomMessage | DataMessage | DataMultiMessage;
 
 /** Any message the relay may send to a client. */
 export type RelayServerMessage =
@@ -144,12 +161,27 @@ export type RelayMessage = RelayClientMessage | RelayServerMessage;
  * that keep every room in one process (the Bun reference server) ignore the
  * path, so this is safe to send to either.
  *
+ * Passing no room code addresses {@link RELAY_MINT_PATH} instead, asking the
+ * relay to allocate one; the code comes back in `ROOM_CREATED`.
+ *
  * @param url - Base relay URL, e.g. `wss://relay.example.com`.
- * @param roomId - Room code to address.
+ * @param roomId - Room code to address, or omitted to have one minted.
  */
-export function relayRoomUrl(url: string, roomId: string): string {
+export function relayRoomUrl(url: string, roomId?: string): string {
   const trimmed = url.replace(/\/+$/, "");
   const [base, query] = trimmed.split("?", 2);
-  const path = `${base}/r/${encodeURIComponent(roomId)}`;
+  const path =
+    roomId === undefined
+      ? `${base}${RELAY_MINT_PATH}`
+      : `${base}/r/${encodeURIComponent(roomId)}`;
   return query ? `${path}?${query}` : path;
 }
+
+/**
+ * Path that asks the relay to allocate a room code.
+ *
+ * Reserved, so it can never be mistaken for a room code. Single-process relays
+ * ignore the path and mint from the `CREATE_ROOM` message alone; sharded relays
+ * need it, because they must choose the shard before any frame arrives.
+ */
+export const RELAY_MINT_PATH = "/new";

package/src/time-sync.ts

@@ -3,6 +3,8 @@ import {
   MessageTypes,
   generateId,
   DEFAULT_SYNC_INTERVAL,
+  MAX_SYNC_INTERVAL,
+  SYNC_BACKOFF_FACTOR,
   MAX_PENDING_PINGS,
 } from "@couch-kit/core";
 import { TransportReadyState, type ClientTransport } from "./transport";
@@ -38,6 +40,22 @@ export function calculateTimeSync(
   return { offset, rtt };
 }
 
+/**
+ * The interval to wait before the next PING, given the one just used.
+ *
+ * Grows geometrically to {@link MAX_SYNC_INTERVAL}: the first pings after
+ * connecting are what converge the offset, and re-measuring it every few
+ * seconds forever buys nothing — the clock difference does not move, while on a
+ * relay transport each ping is a billed message in both directions and the only
+ * traffic an idle table generates at all.
+ *
+ * @param current - Interval (ms) used for the ping just sent.
+ * @returns The next interval, capped at {@link MAX_SYNC_INTERVAL}.
+ */
+export function nextSyncInterval(current: number): number {
+  return Math.min(current * SYNC_BACKOFF_FACTOR, MAX_SYNC_INTERVAL);
+}
+
 /**
  * React hook that synchronizes the client clock with the host server.
  *
@@ -85,9 +103,19 @@ export function useServerTime(socket: ClientTransport | null) {
   );
 
   // Periodic Sync
+  //
+  // The interval backs off from DEFAULT_SYNC_INTERVAL to MAX_SYNC_INTERVAL
+  // rather than staying fast forever: the first few pings are what converge the
+  // offset, and after that we are re-measuring a clock difference that does not
+  // move. A self-rescheduling timeout is used instead of setInterval because
+  // the delay changes between ticks. Backoff state lives inside the effect, so
+  // a new socket — including a reconnect — starts fast again.
   useEffect(() => {
     if (!socket || socket.readyState !== TransportReadyState.OPEN) return;
 
+    let delay = DEFAULT_SYNC_INTERVAL;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
     const sync = () => {
       // Prevent unbounded growth if PONGs are lost
       if (pings.current.size >= MAX_PENDING_PINGS) {
@@ -105,13 +133,17 @@ export function useServerTime(socket: ClientTransport | null) {
           payload: { id, timestamp },
         }),
       );
+
+      delay = nextSyncInterval(delay);
+      timer = setTimeout(sync, delay);
     };
 
     // Initial sync
     sync();
 
-    const interval = setInterval(sync, DEFAULT_SYNC_INTERVAL);
-    return () => clearInterval(interval);
+    return () => {
+      if (timer !== null) clearTimeout(timer);
+    };
   }, [socket]);
 
   return { getServerTime, rtt: timeSync.rtt, handlePong };