@magicworks/client-party-game 0.1.0-rc.0

package/README.md

@@ -0,0 +1,91 @@
+# @magicworks/client-party-game
+
+Host TV client and wire protocol for the multiplayer party games (Name the Artist, Name the Song). The ROXi app uses `PartyGameClient` to open a room, run rounds and get scores from `@magicworks/service-party-game`. The protocol module is the one definition of events, payloads, limits and scoring, shared by the server and the app.
+
+## Tech Stack
+
+- **socket.io-client (bring your own)**: the client takes socket.io-client's `io` as an option instead of bundling it. Version 2.x (what the app ships) and 4.x both work.
+
+## Features
+
+- Opens, reopens and re-attaches to rooms, remembering the last room code so *Play again* within 20 minutes keeps the same phones
+- Reaches a room in its own region: codes say which region holds them (`PARTY_REGIONS`), and with `regionUrls` the client connects for a code to that region's servers. Only opening a new room goes to the global, latency-routed `url`
+- Routes by room: every connection made for a room carries its code in the `c` query parameter, which the load balancer uses to reach the server holding the room. A connection made before a room exists reconnects with the code once it has one, during the lobby, where the reconnect costs nothing
+- Retries on another server when one is draining for a deploy (`host:create` refused with `reason: 'draining'`)
+- Holds host calls while a reconnect re-attaches, so nothing reaches the server from a socket it doesn't know the room of
+- Measures the clock offset to the server NTP-style (fastest of 5 pings, every 60s), for starting rounds at an agreed moment
+- Follows its room between servers: when a draining server asks (`room:move`), the client takes the room to a server still taking parties and opens it there under a new code. The phones follow on their own, and host calls made meanwhile wait and are sent to the new server. It also follows `movedTo` when it asks for a room by an old code
+- Reports a session change (`onSession`) whenever the room's code changes: it moved, or its server went and a reconnect was given a new room. The lobby should show the new code
+- `restart()` on a server past its drain deadline opens a fresh room elsewhere; the phones have to scan the new code
+
+## Reference
+
+| Type | Function | Arguments | Returns | Description |
+|------|----------|-----------|---------|-------------|
+| Session | host | gameType: PartyGameType, genre: string, genreName: string \| null, fresh?: boolean | Promise\<PartyHostSession\> | Open a room, or reopen the last one; `fresh` walks away from it |
+| Session | getSession | - | PartyHostSession \| null | The current room |
+| Session | getPlayers | - | PartyPlayer[] | Last roster pushed by the server |
+| Session | isConnected | - | boolean | Whether the socket is up |
+| Session | close | - | void | Leave the room and drop the socket |
+| Game | start | totalRounds?: number | Promise\<PartyPlayer[]\> | Close the lobby; unready players are dropped |
+| Game | readyForGame | - | void | This TV is ready for the countdown |
+| Game | waitForCountdown | - | Promise\<void\> | Resolves when the server starts the countdown |
+| Game | startRound | config: PartyRoundConfig | Promise\<void\> | Options and answer for a round whose video is preloaded |
+| Game | waitForRoundGo | round: number | Promise\<PartyRoundGo\> | When the round starts, on the server's clock |
+| Game | endRound | - | Promise\<PartyRoundResults \| null\> | Score the round |
+| Game | endGame | - | Promise\<PartyPlayer[]\> | Final standings |
+| Game | restart | - | Promise\<PartyPlayer[]\> | Same players, scores back to zero (a fresh, empty room if the server won't play again) |
+| Game | getTotalRounds | - | number | Rounds in this game |
+| Clock | syncClock | - | Promise\<void\> | Measure the offset to the server again |
+| Clock | serverNow | - | number | Now, on the server's clock |
+| Clock | toServerTime / toLocalTime | time: number | number | Convert between this device's clock and the server's |
+| Listener | onPlayers / onAllAnswered / onRoundGo / onSession | listener | () => void | Subscribe; returns an unsubscribe |
+| Util | speedtest | bytes: number | { url, bytes } \| null | The CDN file of at least `bytes` random bytes for the lobby's bandwidth test, and its real size; null until there is a session |
+| Protocol | scoreForAnswer | secondsLeft: number, totalRoundTime: number, modifier: number | number | Points for a right answer |
+| Protocol | normaliseCode | code: unknown | string \| null | A typed code tidied up, or null if it can't be one |
+| Protocol | codePrefixOf | code: string | string | The server prefix a code routes by |
+
+The protocol module also exports `Feature`, `HostRefusal` and `RoomSnapshot`, the event names (`HostEvent`, `PlayerEvent`, `GameEvent`, `TimeEvent`, `HostMessage`, `PlayerMessage`, `GameMessage`), the limits (`MAX_PLAYERS`, `MAX_NAME_LENGTH`, `TOTAL_ROUNDS`, `REOPEN_WINDOW_MS`, `ROUND_LEAD_MS`, `GAME_READY_TIMEOUT_MS`, `CODE_ALPHABET`, `CODE_LENGTH`, `CODE_PREFIX_LENGTH`, `ROUTING_QUERY_KEY`), and request/ack/message types for every event.
+
+## Usage
+
+```ts
+import io from 'socket.io-client'; // the app's 2.x
+import { PartyGameClient } from '@magicworks/client-party-game';
+
+const client = new PartyGameClient({
+  url: 'https://party-ws.prod.cat.roxi.tv',
+  regionUrls: {
+    'us-east-1': 'https://party-ws.prod-us-east-1.cat.roxi.tv',
+    'eu-west-1': 'https://party-ws.prod-eu-west-1.cat.roxi.tv',
+  },
+  io,
+  hostId: deviceBarcodeId, // the same TV across app restarts
+});
+
+const session = await client.host('nametheartist', 'pop', 'Pop');
+showQrCode(session.joinUrl);
+client.onPlayers(players => renderLobby(players));
+
+await client.start(15);
+client.readyForGame();
+await client.waitForCountdown();
+
+await client.startRound({ round: 1, options, correctIndex: 2, durationMs: 20000, modifier: 1, notBefore });
+const { startAt } = await client.waitForRoundGo(1);
+schedulePlay(client.toLocalTime(startAt));
+const results = await client.endRound();
+```
+
+## Configuration
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| url | string | Yes | The party servers' global, latency-routed URL (`party-ws.<stage>.cat.roxi.tv`), not the phone page's: where a new room opens |
+| regionUrls | Record\<string, string\> | No | Each region's own URL. A room is reached at its code's region (`PARTY_REGIONS`), so a TV that latency routing sends to another region still finds its room. Without it, everything goes to `url` |
+| io | PartySocketFactory | Yes | socket.io-client's `io`, either major version |
+| hostId | string | No | Identifies this TV across its connections; one per process by default |
+| roomMemory | RoomMemory | No | Where the last room code is kept; in memory by default |
+| logger | PartyLogger | No | `debug` and `warn`; `console` by default |
+| ackTimeoutMs | number | No | How long to wait for any answer from the server (8000) |
+| clockSyncIntervalMs | number | No | How often the clock offset is measured again (60000) |

package/dist/client.d.ts

@@ -0,0 +1,210 @@
+import { type PartyGameType, type PartyHostSession, type PartyPlayer, type PartyRoundConfig, type PartyRoundGo, type PartyRoundResults } from './protocol';
+import type { PartySocketFactory } from './socket';
+/**
+ * Where the last room this app hosted is remembered, past one client being
+ * closed and the next one made.
+ *
+ * A second game is nearly always the same people in the same room, so the
+ * lobby offers this code back to the server: if the room is still recent
+ * enough the server reopens it - same code, same names, scores cleared - and
+ * everyone readies up on the phone they already have open instead of scanning
+ * again. The server owns that "recent enough", so this is kept indefinitely
+ * and a stale code simply gets a new room back.
+ */
+export interface RoomMemory {
+    get(): string | null;
+    set(code: string): void;
+}
+export interface PartyLogger {
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+export interface PartyGameClientOptions {
+    /**
+     * The party servers' global name, e.g. `https://party-ws.prod.cat.roxi.tv`:
+     * latency-routed, so a new room opens in the nearest region.
+     */
+    url: string;
+    /**
+     * Each region's own name, e.g. `{ 'eu-west-1': 'https://party-ws.prod-eu-west-1.cat.roxi.tv' }`.
+     * A room is reached at its code's region (see PARTY_REGIONS) wherever the
+     * global name would send this TV now. Without it, everything goes to `url`.
+     */
+    regionUrls?: Record<string, string>;
+    /** socket.io-client's `io`: see `PartySocketFactory`. */
+    io: PartySocketFactory;
+    /**
+     * Which TV this is. The server will not hand a room to another TV while its
+     * host is connected, and a connection closed on the way into the next lobby
+     * can still look connected to the server for a moment - so the room is
+     * claimed by this, not by the connection. One per app run by default.
+     */
+    hostId?: string;
+    /** In memory, for as long as this module is loaded, by default. */
+    roomMemory?: RoomMemory;
+    logger?: PartyLogger;
+    /** How long to wait on the server's answer to anything. */
+    ackTimeoutMs?: number;
+    /** How often the clock offset to the server is measured again. */
+    clockSyncIntervalMs?: number;
+}
+type PlayersListener = (players: PartyPlayer[]) => void;
+type AllAnsweredListener = (round: number) => void;
+type RoundGoListener = (go: PartyRoundGo) => void;
+type SessionListener = (session: PartyHostSession) => void;
+/**
+ * Host side of the party games protocol. The TV owns the video and therefore
+ * owns round timing: it tells the server when a round starts and when it ends,
+ * and the server answers with who scored what.
+ *
+ * One instance is meant to be shared by the lobby screen and the game itself,
+ * so navigating from the lobby into the first round keeps the same room and
+ * the same players.
+ *
+ * Rooms live in the memory of one server of several, and the load balancer
+ * finds it by the room code: every connection made for a room carries its
+ * code (ROUTING_QUERY_KEY). A connection made before there is a room goes to
+ * any server, so once that server has opened one the client connects again
+ * with its code - in the lobby, where a moment's reconnect costs nothing,
+ * rather than leaving the game on a route the load balancer can take away.
+ */
+export declare class PartyGameClient {
+    private readonly url;
+    private readonly regionUrls;
+    private readonly io;
+    private readonly hostId;
+    private readonly roomMemory;
+    private readonly logger;
+    private readonly ackTimeoutMs;
+    private readonly clockSyncIntervalMs;
+    private socket;
+    /** The room code the current socket was routed by, if any. */
+    private routedCode;
+    /**
+     * Whether the current connection is attached to the session's room. Host
+     * calls wait for it: sent while a reconnect is still re-attaching, they
+     * would reach the server from a socket it does not know the room of.
+     */
+    private attached;
+    private attachedWaiters;
+    private session;
+    /** Where the session's room is now, when a server has said it moved. */
+    private redirectCode;
+    /** What the last lobby was opened for, to open another like it. */
+    private lastHost;
+    private players;
+    private playersListeners;
+    private allAnsweredListeners;
+    private sessionListeners;
+    /** Start times the server has given rounds of the current game. */
+    private roundGos;
+    private roundGoListeners;
+    /** Whether the server has started the current game's countdown. */
+    private countdownStarted;
+    private countdownListeners;
+    /** Server clock minus this TV's clock, in ms. */
+    private clockOffset;
+    private clockSyncTimer;
+    constructor(options: PartyGameClientOptions);
+    getSession(): PartyHostSession | null;
+    getPlayers(): PartyPlayer[];
+    isConnected(): boolean;
+    /**
+     * A download of at least `bytes` random bytes for the TV to time in the
+     * lobby, and its real size, which the bandwidth has to be worked out from.
+     * It is a file on the CDN the phone page is on - the origin of the
+     * session's join URL - so null until there is a session.
+     */
+    speedtest(bytes: number): {
+        url: string;
+        bytes: number;
+    } | null;
+    /** The socket for `code`'s room (or for no room), connecting a new one if need be. */
+    private socketFor;
+    private currentSocket;
+    private setAttached;
+    private whenAttached;
+    /** Where `code`'s room is: its region's servers, or for no room, the nearest. */
+    private urlFor;
+    /** A socket routed by `code`, to `url` (by default, where `code`'s room is). */
+    private connectTo;
+    private openSocket;
+    /**
+     * Back on the room we were already hosting, so a dropped connection
+     * mid-party does not lose the players or their scores. If the room is gone
+     * - its server is - the server opens a new one, and the session follows.
+     */
+    private reattach;
+    /** Takes on a session the server has handed back, rerouting by its code if need be. */
+    private adopt;
+    private send;
+    private emit;
+    private moveRoom;
+    /**
+     * Measures the offset from this TV's clock to the server's, NTP style: a few
+     * round trips, trusting the quickest - the one whose reply spent the least
+     * time in flight, and so says most exactly what the server's clock read.
+     */
+    syncClock(): Promise<void>;
+    /** The time now on the server's clock. */
+    serverNow(): number;
+    /** A time by this TV's `Date.now()`, as the server's clock would read it. */
+    toServerTime(localTime: number): number;
+    /** A time on the server's clock, as this TV's `Date.now()` would read it. */
+    toLocalTime(serverTime: number): number;
+    /**
+     * Opens a room and returns the code / join URL to put in the QR code.
+     * Passing the code of a room we hosted recently reopens that one instead,
+     * which is what a second game does: same phones, same names, and a
+     * `reused` session so the lobby can tell people to tap Ready.
+     *
+     * `fresh` is the way out of that: a brand new room, and the one we were
+     * holding is closed behind us so its phones are not left waiting on it.
+     */
+    host(gameType: PartyGameType, genre: string, genreName: string | null, fresh?: boolean): Promise<PartyHostSession>;
+    /**
+     * Closes the lobby - no more players can join after this. The round count is
+     * chosen in the lobby, so it is locked in here.
+     */
+    start(totalRounds?: number): Promise<PartyPlayer[]>;
+    /** How many rounds this party is playing; the default until a game starts. */
+    getTotalRounds(): number;
+    /**
+     * This TV has the game on screen and its player set up: the countdown to
+     * round 1 can start as far as it is concerned. It starts on the TV and the
+     * phones at once, when they have all said so - see waitForCountdown.
+     */
+    readyForGame(): void;
+    /** Resolves when the server starts the countdown to round 1 of this game. */
+    waitForCountdown(): Promise<void>;
+    /**
+     * Tells the server the host's video for the round is preloaded, with the
+     * options for the phones; the correct index stays between us and the server.
+     * The round starts at the time `waitForRoundGo` resolves with.
+     */
+    startRound(config: PartyRoundConfig): Promise<void>;
+    /** When the server has said a round starts: at once if it already has. */
+    waitForRoundGo(round: number): Promise<PartyRoundGo>;
+    /** Scores the round. Players who did not answer are scored as wrong. */
+    endRound(): Promise<PartyRoundResults | null>;
+    endGame(): Promise<PartyPlayer[]>;
+    /**
+     * Same players, scores back to zero, room back to the lobby. A server past
+     * its drain deadline plays no more games, and closes the room instead: the
+     * lobby then opens fresh on another server, with a code to scan.
+     */
+    restart(): Promise<PartyPlayer[]>;
+    onPlayers(listener: PlayersListener): () => boolean;
+    onAllAnswered(listener: AllAnsweredListener): () => boolean;
+    onRoundGo(listener: RoundGoListener): () => boolean;
+    /**
+     * The room changed under us: its server went away and a reconnect was
+     * handed a new one. The lobby shows the new code; a game in progress has
+     * lost its players.
+     */
+    onSession(listener: SessionListener): () => boolean;
+    /** Leaves the room entirely - the next `host()` opens a fresh one. */
+    close(): void;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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