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

package/dist/client.js

@@ -0,0 +1,659 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PartyGameClient = void 0;
+const protocol_1 = require("./protocol");
+const defaultAckTimeoutMs = 8000;
+const defaultClockSyncIntervalMs = 60 * 1000;
+const clockSyncSamples = 5;
+/** Servers that can be on their way out at once, during a deploy. */
+const maxDrainingRetries = 3;
+/** Hops a room can have made between servers since we last knew its code. */
+const maxRedirects = 3;
+/** What this client can do beyond the first protocol: see Feature. */
+const features = [protocol_1.Feature.Move];
+const processHostId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+let rememberedCode = null;
+const moduleRoomMemory = {
+    get: () => rememberedCode,
+    set: code => {
+        rememberedCode = code;
+    },
+};
+function withTimeout(promise, ms, what) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`party server did not answer ${what} in ${ms}ms`)), ms);
+        promise.then(value => {
+            clearTimeout(timer);
+            resolve(value);
+        }, error => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+function routesAlike(a, b) {
+    return (a ? (0, protocol_1.codePrefixOf)(a) : null) === (b ? (0, protocol_1.codePrefixOf)(b) : null);
+}
+/**
+ * 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.
+ */
+class PartyGameClient {
+    url;
+    regionUrls;
+    io;
+    hostId;
+    roomMemory;
+    logger;
+    ackTimeoutMs;
+    clockSyncIntervalMs;
+    socket = null;
+    /** The room code the current socket was routed by, if any. */
+    routedCode = null;
+    /**
+     * 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.
+     */
+    attached = true;
+    attachedWaiters = [];
+    session = null;
+    /** Where the session's room is now, when a server has said it moved. */
+    redirectCode = null;
+    /** What the last lobby was opened for, to open another like it. */
+    lastHost = null;
+    players = [];
+    playersListeners = new Set();
+    allAnsweredListeners = new Set();
+    sessionListeners = new Set();
+    /** Start times the server has given rounds of the current game. */
+    roundGos = new Map();
+    roundGoListeners = new Set();
+    /** Whether the server has started the current game's countdown. */
+    countdownStarted = false;
+    countdownListeners = new Set();
+    /** Server clock minus this TV's clock, in ms. */
+    clockOffset = 0;
+    clockSyncTimer = null;
+    constructor(options) {
+        this.url = options.url.replace(/\/+$/, '');
+        /* No Object.entries or fromEntries: older TV browsers lack them, and the
+           app has no polyfill. */
+        const regionUrls = options.regionUrls || {};
+        this.regionUrls = {};
+        for (const region of Object.keys(regionUrls)) {
+            this.regionUrls[region] = regionUrls[region].replace(/\/+$/, '');
+        }
+        this.io = options.io;
+        this.hostId = options.hostId || processHostId;
+        this.roomMemory = options.roomMemory || moduleRoomMemory;
+        this.logger = options.logger || console;
+        this.ackTimeoutMs = options.ackTimeoutMs ?? defaultAckTimeoutMs;
+        this.clockSyncIntervalMs =
+            options.clockSyncIntervalMs ?? defaultClockSyncIntervalMs;
+    }
+    getSession() {
+        return this.session;
+    }
+    getPlayers() {
+        return this.players;
+    }
+    isConnected() {
+        return this.socket ? this.socket.connected : false;
+    }
+    /**
+     * 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) {
+        if (!this.session) {
+            return null;
+        }
+        const origin = new URL(this.session.joinUrl).origin;
+        const size = protocol_1.SPEEDTEST_SIZES.find(candidate => candidate >= bytes) ??
+            protocol_1.SPEEDTEST_SIZES[protocol_1.SPEEDTEST_SIZES.length - 1];
+        return { url: `${origin}${(0, protocol_1.speedtestPath)(size)}`, bytes: size };
+    }
+    /* ---------------------------------------------------------- connection */
+    /** The socket for `code`'s room (or for no room), connecting a new one if need be. */
+    socketFor(code, { fresh = false } = {}) {
+        if (this.socket && !fresh && routesAlike(this.routedCode, code)) {
+            return this.socket;
+        }
+        if (this.socket) {
+            this.logger.debug('PartyGames', 'reconnecting to route by', code);
+            this.socket.close();
+        }
+        this.routedCode = code;
+        this.socket = this.openSocket(code);
+        return this.socket;
+    }
+    currentSocket() {
+        return this.socket || this.socketFor(this.session?.code || null);
+    }
+    setAttached(attached) {
+        this.attached = attached;
+        if (attached) {
+            const waiters = this.attachedWaiters;
+            this.attachedWaiters = [];
+            for (const waiter of waiters) {
+                waiter();
+            }
+        }
+    }
+    whenAttached(what) {
+        if (this.attached) {
+            return Promise.resolve();
+        }
+        return withTimeout(new Promise(resolve => this.attachedWaiters.push(resolve)), this.ackTimeoutMs, `${what} (reconnecting)`);
+    }
+    /** Where `code`'s room is: its region's servers, or for no room, the nearest. */
+    urlFor(code) {
+        return code
+            ? (0, protocol_1.socketUrlForCode)(code, {
+                socketUrl: this.url,
+                regionSocketUrls: this.regionUrls,
+            })
+            : this.url;
+    }
+    /** A socket routed by `code`, to `url` (by default, where `code`'s room is). */
+    connectTo(code, url = this.urlFor(code)) {
+        return this.io(url, {
+            transports: ['websocket'],
+            jsonp: false,
+            query: code ? { [protocol_1.ROUTING_QUERY_KEY]: code } : {},
+            forceNew: true,
+            reconnection: true,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 5000,
+            timeout: this.ackTimeoutMs,
+        });
+    }
+    openSocket(code) {
+        this.setAttached(false);
+        const socket = this.connectTo(code);
+        socket.on('connect', () => {
+            if (socket !== this.socket) {
+                return;
+            }
+            this.logger.debug('PartyGames', 'connected to', this.url);
+            this.syncClock();
+            this.reattach(socket);
+        });
+        socket.on('disconnect', () => {
+            if (socket !== this.socket) {
+                return;
+            }
+            this.logger.debug('PartyGames', 'disconnected');
+            this.setAttached(false);
+        });
+        socket.on('connect_error', (error) => {
+            this.logger.warn('PartyGames', 'connect error', error?.message);
+        });
+        socket.on(protocol_1.HostMessage.Players, (payload) => {
+            this.players = payload?.players || [];
+            for (const listener of this.playersListeners) {
+                listener(this.players);
+            }
+        });
+        socket.on(protocol_1.HostMessage.AllAnswered, (payload) => {
+            for (const listener of this.allAnsweredListeners) {
+                listener(payload.round);
+            }
+        });
+        socket.on(protocol_1.GameMessage.Countdown, () => {
+            this.countdownStarted = true;
+            for (const listener of [...this.countdownListeners]) {
+                listener();
+            }
+        });
+        socket.on(protocol_1.HostMessage.Move, (message) => {
+            if (socket === this.socket && message?.token) {
+                this.moveRoom(socket, message.token);
+            }
+        });
+        socket.on(protocol_1.HostMessage.RoundGo, (go) => {
+            if (go) {
+                this.roundGos.set(go.round, go);
+                for (const listener of this.roundGoListeners) {
+                    listener(go);
+                }
+            }
+        });
+        if (!this.clockSyncTimer) {
+            /* clocks drift, and so does the route to the server */
+            this.clockSyncTimer = setInterval(() => this.syncClock(), this.clockSyncIntervalMs);
+        }
+        return socket;
+    }
+    /**
+     * 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.
+     */
+    reattach(socket) {
+        const session = this.session;
+        if (!session) {
+            this.setAttached(true);
+            return;
+        }
+        this.send(socket, protocol_1.HostEvent.Create, {
+            code: this.redirectCode || session.code,
+            hostId: this.hostId,
+            features,
+        })
+            .then(response => {
+            if (response?.ok) {
+                // A re-attach is not a reopen, so it says `reused: false`; the
+                // lobby still is the one it was.
+                const same = response.code === this.session?.code;
+                this.adopt({
+                    ...response,
+                    reused: same ? Boolean(this.session?.reused) : response.reused,
+                });
+            }
+            else if (response?.reason === protocol_1.HostRefusal.Moved && response.movedTo) {
+                /* it left that server while we were away: follow it */
+                this.redirectCode = response.movedTo;
+                this.socketFor(response.movedTo);
+            }
+            else if (response?.reason === protocol_1.HostRefusal.Draining) {
+                /* the room is gone and its server opens no new ones: another will,
+                   over a new connection the load balancer can send elsewhere */
+                this.socketFor(null, { fresh: true });
+            }
+            else {
+                this.logger.warn('PartyGames', 'failed to re-attach', response);
+            }
+        })
+            .catch(error => this.logger.warn('PartyGames', 'failed to re-attach', error))
+            .finally(() => {
+            if (socket === this.socket) {
+                this.setAttached(true);
+            }
+        });
+    }
+    /** Takes on a session the server has handed back, rerouting by its code if need be. */
+    adopt(response) {
+        const previous = this.session;
+        this.redirectCode = null;
+        this.session = {
+            code: response.code,
+            joinUrl: response.joinUrl,
+            reused: response.reused,
+            maxPlayers: response.maxPlayers,
+            totalRounds: response.totalRounds,
+            status: response.status,
+            players: response.players || [],
+        };
+        this.players = this.session.players;
+        this.roomMemory.set(response.code);
+        if (previous && previous.code !== response.code) {
+            this.logger.warn('PartyGames', 'room', previous.code, 'is gone, now', response.code);
+            for (const listener of this.sessionListeners) {
+                listener(this.session);
+            }
+        }
+        if (!routesAlike(this.routedCode, response.code)) {
+            this.socketFor(response.code);
+        }
+        else {
+            /* same server: from now on this socket stands for the room */
+            this.routedCode = response.code;
+        }
+    }
+    send(socket, event, payload = {}) {
+        return withTimeout(new Promise(resolve => socket.emit(event, payload, resolve)), this.ackTimeoutMs, event);
+    }
+    /**
+     * A host call: once the connection is attached to the room. A call that
+     * crossed the room's move to another server is sent again from there.
+     */
+    async emit(event, payload = {}) {
+        for (let attempt = 0;; ++attempt) {
+            const socket = this.currentSocket();
+            await this.whenAttached(event);
+            const response = await this.send(this.socket || socket, event, payload);
+            const reason = response?.reason;
+            if (reason !== protocol_1.HostRefusal.Moving || attempt >= maxRedirects) {
+                return response;
+            }
+            /* the room:move that came before this answer has us reconnecting */
+            await this.whenAttached(event);
+        }
+    }
+    /**
+     * Takes the room to another server, which the one it is on asked for: it
+     * is on its way out, and no game is being played. The room is adopted over
+     * a connection with no room in its query - so the load balancer hands it
+     * to a server still taking parties - the old server is told where it went,
+     * for the phones, and the client then connects for the new code as usual.
+     * Host calls wait meanwhile. If it cannot be done the room stays where it
+     * was, and the server asks again later.
+     */
+    async moveRoom(oldSocket, token) {
+        this.setAttached(false);
+        // The handover is between the servers of one region, whose tables hold
+        // it, so it goes to the room's region rather than the nearest.
+        const regionUrl = this.urlFor(this.session?.code || null);
+        let adopted = null;
+        for (let attempt = 0; attempt <= maxDrainingRetries && !adopted; ++attempt) {
+            const socket = this.connectTo(null, regionUrl);
+            try {
+                await withTimeout(new Promise(resolve => socket.on('connect', () => resolve())), this.ackTimeoutMs, 'connecting to move the room');
+                const response = await this.send(socket, protocol_1.HostEvent.Adopt, {
+                    token,
+                    hostId: this.hostId,
+                    features,
+                });
+                if (response?.ok) {
+                    adopted = response;
+                }
+                else if (response?.reason !== protocol_1.HostRefusal.Draining) {
+                    this.logger.warn('PartyGames', 'could not move the room', response);
+                    break;
+                }
+            }
+            catch (error) {
+                this.logger.warn('PartyGames', 'could not move the room', error);
+            }
+            finally {
+                socket.close();
+            }
+        }
+        if (oldSocket !== this.socket) {
+            return;
+        }
+        if (!adopted) {
+            this.setAttached(true);
+            return;
+        }
+        this.logger.debug('PartyGames', 'room moved to', adopted.code);
+        await this.send(oldSocket, protocol_1.HostEvent.Moved, { code: adopted.code }).catch(error => this.logger.warn('PartyGames', 'could not say where the room went', error));
+        if (oldSocket === this.socket) {
+            this.adopt(adopted);
+        }
+    }
+    /* --------------------------------------------------------------- clock */
+    /**
+     * 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.
+     */
+    async syncClock() {
+        let best = null;
+        for (let sample = 0; sample < clockSyncSamples; ++sample) {
+            try {
+                const sentAt = Date.now();
+                const response = await this.send(this.currentSocket(), protocol_1.TimeEvent.Ping);
+                const receivedAt = Date.now();
+                const rtt = receivedAt - sentAt;
+                if (typeof response?.now === 'number' && (!best || rtt < best.rtt)) {
+                    best = { rtt, offset: response.now + rtt / 2 - receivedAt };
+                }
+            }
+            catch {
+                break;
+            }
+        }
+        if (best) {
+            this.clockOffset = best.offset;
+            this.logger.debug('PartyGames', 'clock offset', Math.round(best.offset), 'ms, rtt', best.rtt, 'ms');
+        }
+    }
+    /** The time now on the server's clock. */
+    serverNow() {
+        return Date.now() + this.clockOffset;
+    }
+    /** A time by this TV's `Date.now()`, as the server's clock would read it. */
+    toServerTime(localTime) {
+        return localTime + this.clockOffset;
+    }
+    /** A time on the server's clock, as this TV's `Date.now()` would read it. */
+    toLocalTime(serverTime) {
+        return serverTime - this.clockOffset;
+    }
+    /* ---------------------------------------------------------------- game */
+    /**
+     * 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.
+     */
+    async host(gameType, genre, genreName, fresh = false) {
+        this.lastHost = { gameType, genre, genreName };
+        const known = this.session?.code || this.roomMemory.get();
+        const code = fresh ? undefined : known || undefined;
+        const request = {
+            code,
+            features,
+            /* Opening a lobby, not re-attaching: the room comes back cleared. */
+            reopen: !fresh,
+            hostId: this.hostId,
+            gameType,
+            genre,
+            /* for the phones, which only show it */
+            genreName,
+            totalRounds: protocol_1.TOTAL_ROUNDS,
+        };
+        /* A fresh room is opened over the connection we have, so the server
+           holding the old one closes it; any other ask goes where its room is. */
+        if (!fresh) {
+            this.socketFor(code || null);
+        }
+        for (let attempt = 0;; ++attempt) {
+            if (!fresh && attempt > 0) {
+                /* wherever the room is by now */
+                request.code = this.redirectCode || this.session?.code || request.code;
+            }
+            const response = await this.emit(protocol_1.HostEvent.Create, request);
+            if (response?.ok) {
+                this.adopt(response);
+                await this.whenAttached('the room');
+                return this.session;
+            }
+            if (response?.reason === protocol_1.HostRefusal.Moved &&
+                response.movedTo &&
+                attempt < maxRedirects) {
+                /* opened again on another server since we last knew it */
+                this.redirectCode = response.movedTo;
+                this.socketFor(response.movedTo);
+                continue;
+            }
+            if (response?.reason === protocol_1.HostRefusal.Draining &&
+                attempt < maxDrainingRetries) {
+                /* asked a server on its way out: any other server will do */
+                this.logger.debug('PartyGames', 'server draining, asking another');
+                if (fresh) {
+                    /* walking away from the old room, so not re-attaching to it */
+                    this.session = null;
+                }
+                // A new connection even if this one had no room either: over the
+                // same socket the same draining server would answer again.
+                this.socketFor(null, { fresh: true });
+                continue;
+            }
+            throw new Error(response?.error || 'failed to open a party game room');
+        }
+    }
+    /**
+     * Closes the lobby - no more players can join after this. The round count is
+     * chosen in the lobby, so it is locked in here.
+     */
+    async start(totalRounds = protocol_1.TOTAL_ROUNDS) {
+        const response = await this.emit(protocol_1.HostEvent.Start, {
+            totalRounds,
+        });
+        if (!response?.ok) {
+            throw new Error(response?.error || 'failed to start the game');
+        }
+        this.players = response.players || [];
+        if (this.session) {
+            this.session = {
+                ...this.session,
+                totalRounds: response.totalRounds || totalRounds,
+            };
+        }
+        /* round numbers start again at 1 */
+        this.roundGos.clear();
+        this.countdownStarted = false;
+        return this.players;
+    }
+    /** How many rounds this party is playing; the default until a game starts. */
+    getTotalRounds() {
+        return this.session?.totalRounds || protocol_1.TOTAL_ROUNDS;
+    }
+    /**
+     * 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() {
+        this.emit(protocol_1.GameEvent.Ready).catch(error => this.logger.warn('PartyGames', 'failed to report ready for the game', error));
+    }
+    /** Resolves when the server starts the countdown to round 1 of this game. */
+    waitForCountdown() {
+        if (this.countdownStarted) {
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            const listener = () => {
+                this.countdownListeners.delete(listener);
+                resolve();
+            };
+            this.countdownListeners.add(listener);
+        });
+    }
+    /**
+     * 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.
+     */
+    async startRound(config) {
+        await this.emit(protocol_1.HostEvent.RoundStart, config);
+    }
+    /** When the server has said a round starts: at once if it already has. */
+    waitForRoundGo(round) {
+        const known = this.roundGos.get(round);
+        if (known) {
+            return Promise.resolve(known);
+        }
+        return new Promise(resolve => {
+            const unsubscribe = this.onRoundGo(go => {
+                if (go.round === round) {
+                    unsubscribe();
+                    resolve(go);
+                }
+            });
+        });
+    }
+    /** Scores the round. Players who did not answer are scored as wrong. */
+    async endRound() {
+        const response = await this.emit(protocol_1.HostEvent.RoundEnd);
+        if (!response?.ok) {
+            return null;
+        }
+        this.players = response.players || [];
+        return response;
+    }
+    async endGame() {
+        const response = await this.emit(protocol_1.HostEvent.GameEnd);
+        if (!response?.ok) {
+            return this.players;
+        }
+        this.players = response.standings || [];
+        return this.players;
+    }
+    /**
+     * 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.
+     */
+    async restart() {
+        const response = await this.emit(protocol_1.HostEvent.Restart);
+        if (response?.reason ===
+            protocol_1.HostRefusal.Draining &&
+            this.lastHost) {
+            const { gameType, genre, genreName } = this.lastHost;
+            this.session = null;
+            this.socketFor(null, { fresh: true });
+            return (await this.host(gameType, genre, genreName, true)).players;
+        }
+        if (response?.ok) {
+            this.players = response.players || [];
+            if (this.session) {
+                this.session = {
+                    ...this.session,
+                    status: 'lobby',
+                    players: this.players,
+                };
+            }
+        }
+        return this.players;
+    }
+    /* ----------------------------------------------------------- listeners */
+    onPlayers(listener) {
+        this.playersListeners.add(listener);
+        return () => this.playersListeners.delete(listener);
+    }
+    onAllAnswered(listener) {
+        this.allAnsweredListeners.add(listener);
+        return () => this.allAnsweredListeners.delete(listener);
+    }
+    onRoundGo(listener) {
+        this.roundGoListeners.add(listener);
+        return () => this.roundGoListeners.delete(listener);
+    }
+    /**
+     * 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) {
+        this.sessionListeners.add(listener);
+        return () => this.sessionListeners.delete(listener);
+    }
+    /** Leaves the room entirely - the next `host()` opens a fresh one. */
+    close() {
+        this.playersListeners.clear();
+        this.allAnsweredListeners.clear();
+        this.roundGoListeners.clear();
+        this.sessionListeners.clear();
+        this.roundGos.clear();
+        this.countdownListeners.clear();
+        this.countdownStarted = false;
+        if (this.clockSyncTimer) {
+            clearInterval(this.clockSyncTimer);
+            this.clockSyncTimer = null;
+        }
+        this.session = null;
+        this.redirectCode = null;
+        this.players = [];
+        if (this.socket) {
+            const socket = this.socket;
+            this.socket = null;
+            this.routedCode = null;
+            socket.close();
+        }
+        this.setAttached(true);
+    }
+}
+exports.PartyGameClient = PartyGameClient;
+//# sourceMappingURL=client.js.map