@diffenderfer-games/hub 2.0.0-next.4 → 2.0.0-next.6

package/src/core/turns/hub-turns.ts

@@ -0,0 +1,140 @@
+/**
+ * `hub.turns`: online, turn-based games the hub runs from the game's own
+ * rules module (`game.turns`), played over minutes or days. Make one
+ * (inviting friends, with a link, or with open seats anyone may take),
+ * join one, open one the player sits in, and list them. Players see "an
+ * online game", never "a turn game".
+ *
+ * ```ts
+ * const opened = hub.saved.opened;
+ * const game = opened?.kind === 'turns' ? await hub.turns.open(opened.id)
+ *   : hub.turns.link !== null ? await hub.turns.join(hub.turns.link)
+ *   : null;
+ * game?.on('move', ({ view, events }) => animate(events, view));
+ * ```
+ */
+import type { CreateTurnGame, OpenTurnGame, TurnDeadline } from '@diffenderfer-games/hub-contract';
+import { toStoredJson, type GamePayload } from '../game-data';
+import { isBrowserPage } from '../page';
+import type { SavedEntry } from '../saved/saved-types';
+import { TurnGame, type TurnGameHost } from './turn-game';
+
+/** The query parameter an invite link carries (`/<slug>/?hub_turn_link=<key>`); the client strips it. */
+export const TURN_LINK_PARAM = 'hub_turn_link';
+
+/** Where the answer is kept for the page. */
+const PAGE_FLAG = '__HUB_TURN_LINK__';
+
+/** How to make a game. */
+export interface TurnCreateOptions {
+  readonly mode?: string;
+  /** The game's own setup choices (at most 2 KB of JSON). */
+  readonly options?: GamePayload;
+  /** Friends to invite (their seats are held). */
+  readonly invite?: readonly number[];
+  /** Make a link others can take a seat with (`game.link`). */
+  readonly link?: boolean;
+  /** List the open seats in Play online for anyone to take. */
+  readonly public?: boolean;
+  /** Seats in all (within `game.turns.players`). */
+  readonly seats?: number;
+  /** Let the computer fill seats nobody took (default true, when the game has bots). */
+  readonly bots?: boolean;
+  /** How long a turn may wait before the others may let the computer play it (default none). */
+  readonly deadline?: TurnDeadline;
+  /** Start by itself once every seat is taken (the creator needn't come back). */
+  readonly autoStart?: boolean;
+}
+
+/** What `hub.turns` needs from its client. */
+export interface TurnsHost extends TurnGameHost {
+  readonly slug: string | null;
+  create(body: CreateTurnGame): ReturnType<TurnGameHost['get']>;
+  join(id: string): ReturnType<TurnGameHost['get']>;
+  joinByLink(key: string): ReturnType<TurnGameHost['get']>;
+  listOpen(game: string | null): Promise<OpenTurnGame[]>;
+  list(): Promise<SavedEntry[]>;
+}
+
+/** Read and strip `hub_turn_link`, once per page. */
+function linkOnPage(): string | null {
+  if (!isBrowserPage()) {
+    return null;
+  }
+  if (Reflect.has(window, PAGE_FLAG)) {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: a window field another bundle may have set
+    const recorded: unknown = Reflect.get(window, PAGE_FLAG);
+    return typeof recorded === 'string' ? recorded : null;
+  }
+  let key: string | null = null;
+  try {
+    const url = new URL(location.href);
+    key = url.searchParams.get(TURN_LINK_PARAM);
+    if (key !== null) {
+      url.searchParams.delete(TURN_LINK_PARAM);
+      history.replaceState(history.state, '', `${url.pathname}${url.search}${url.hash}`);
+    }
+  } catch {
+    // A sandboxed page keeps the parameter; the answer is still recorded.
+  }
+  Reflect.set(window, PAGE_FLAG, key);
+  return key;
+}
+
+/** Whether `idOrKey` is a game id (`sg_…`) rather than a link key. */
+function isGameId(idOrKey: string): boolean {
+  return idOrKey.startsWith('sg_');
+}
+
+/** `hub.turns`. */
+export class HubTurns {
+  private readonly host: TurnsHost;
+
+  constructor(host: TurnsHost) {
+    this.host = host;
+  }
+
+  /** The invite link key this page was opened with (`?hub_turn_link=`), taken out of the address bar; `null` when none. Synchronous. */
+  get link(): string | null {
+    return linkOnPage();
+  }
+
+  /** Make a game in this page's game (its lobby): the player takes the first seat. */
+  async create<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(options: TurnCreateOptions = {}): Promise<TurnGame<View, Move, Event>> {
+    const slug = this.host.slug ?? '';
+    const body: CreateTurnGame = {
+      game: slug,
+      ...(options.mode === undefined ? {} : { mode: options.mode }),
+      ...(options.options === undefined ? {} : { options: toStoredJson(options.options) }),
+      ...(options.invite === undefined ? {} : { invite: [...options.invite] }),
+      ...(options.link === undefined ? {} : { link: options.link }),
+      ...(options.public === undefined ? {} : { public: options.public }),
+      ...(options.seats === undefined ? {} : { seats: options.seats }),
+      ...(options.bots === undefined ? {} : { bots: options.bots }),
+      ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
+      ...(options.autoStart === undefined ? {} : { autoStart: options.autoStart }),
+    };
+    return new TurnGame<View, Move, Event>(this.host, await this.host.create(body));
+  }
+
+  /** Take a seat: by the game's id (an invite, an open seat) or by an invite link's key. */
+  async join<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(idOrLinkKey: string): Promise<TurnGame<View, Move, Event>> {
+    const joined = isGameId(idOrLinkKey) ? await this.host.join(idOrLinkKey) : await this.host.joinByLink(idOrLinkKey);
+    return new TurnGame<View, Move, Event>(this.host, joined);
+  }
+
+  /** Open a game the player sits in (from `hub.saved.opened`, the Continue list, an invite). */
+  async open<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(id: string): Promise<TurnGame<View, Move, Event>> {
+    return new TurnGame<View, Move, Event>(this.host, await this.host.get(id));
+  }
+
+  /** This game's online games the player sits in (the same rows as `hub.saved.list({ kinds: ['turns'] })`). */
+  list(): Promise<SavedEntry[]> {
+    return this.host.list();
+  }
+
+  /** Open-seat games of this game anyone may join (none across a block). */
+  openLobbies(): Promise<OpenTurnGame[]> {
+    return this.host.listOpen(this.host.slug);
+  }
+}

package/src/core/turns/turn-game.ts

@@ -0,0 +1,388 @@
+/**
+ * One online game, as a seated player's page holds it (`hub.turns.open`,
+ * `create`, `join`). The hub runs the game's rules: the page only ever has
+ * its own `view` and sends moves.
+ *
+ * Live changes arrive as the social runtime's `hub:turn` window events
+ * (from `/_ws`): `on('move')` for each move (with its events as this seat may
+ * see them, to animate), `on('turn')` whenever whose move it is or the seats
+ * change, `on('ended')` at the end, `on('chat')` for chat lines. Moves made
+ * while the page was away are replayed from `history` when it comes back
+ * (and, without the runtime, every so often while the page is visible).
+ */
+import type { Json, TurnChatLine, TurnGameView, TurnSeat, TurnSummary } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../errors';
+import { toGameData, type GamePayload } from '../game-data';
+import { isBrowserPage } from '../page';
+import { isJson, parseJsonText } from '../storage/json-guards';
+import { readField } from '../../realtime/cross-bundle';
+
+/** The window event the social runtime fires for each `ev:turn`. */
+export const TURN_EVENT = 'hub:turn';
+
+/** The runtime's live connection (re)opened: anything sent while it was down is fetched again. */
+export const TURN_RESYNC_EVENT = 'hub:turn-resync';
+
+/** The window event the social runtime fires for each `ev:turn.chat`. */
+export const TURN_CHAT_EVENT = 'hub:turn-chat';
+
+/** How often a page without the live runtime looks for moves, ms. */
+export const TURN_POLL_MS = 20_000;
+
+/** A game's end: the winning seats, and optionally places and scores by seat. */
+export type TurnOutcome = NonNullable<TurnGameView['outcome']>;
+
+/** One move as this seat saw it. */
+export interface TurnMoveEvent<View, Ev> {
+  readonly seq: number;
+  readonly seat: number;
+  /** The view after the move (for a replayed move, the view now). */
+  readonly view: View;
+  readonly events: readonly Ev[];
+}
+
+/** What a game's listeners hear. */
+export interface TurnGameEvents<View, Ev> {
+  move: TurnMoveEvent<View, Ev>;
+  turn: TurnSummary;
+  ended: { readonly outcome: TurnOutcome | null; readonly view: View };
+  chat: TurnChatLine;
+}
+
+/** What a game needs from its client: the REST calls, by name. */
+export interface TurnGameHost {
+  get(id: string): Promise<TurnGameView>;
+  start(id: string): Promise<TurnGameView>;
+  move(id: string, seq: number, move: Json): Promise<{ game: TurnGameView; events: Json[] }>;
+  history(id: string, since: number): Promise<{ seq: number; seat: number; events: Json[] }[]>;
+  leave(id: string): Promise<void>;
+  nudge(id: string): Promise<void>;
+  setNotify(id: string, mode: 'on' | 'off'): Promise<void>;
+  rematch(id: string): Promise<TurnGameView>;
+  invite(id: string, userIds: readonly number[]): Promise<TurnGameView>;
+  share(id: string, share: { readonly link?: boolean; readonly public?: boolean }): Promise<TurnGameView>;
+  autoPlay(id: string): Promise<TurnGameView>;
+  chat(id: string, send: { readonly text?: string; readonly quick?: string }): Promise<TurnChatLine>;
+  /** The page has a game open (saves of a run are off while it does). */
+  opened(game: object): void;
+  closed(game: object): void;
+  /** Whether the live runtime is on the page (else the game polls). */
+  isLive(): boolean;
+}
+
+type Listener<Payload> = (payload: Payload) => void;
+
+/** One online game. `View`, `Move` and `Ev` (its events) are the game's own JSON types from its rules. */
+export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload, Ev = GamePayload> {
+  readonly id: string;
+  private state: TurnGameView;
+  private readonly host: TurnGameHost;
+  private readonly listeners: { [K in keyof TurnGameEvents<View, Ev>]: Set<Listener<TurnGameEvents<View, Ev>[K]>> } = {
+    move: new Set(), turn: new Set(), ended: new Set(), chat: new Set(),
+  };
+  private readonly stopListening: (() => void)[] = [];
+  private isClosed = false;
+  private catchingUp: Promise<void> | null = null;
+  /** The move count this page's own move in flight will make (its live echo is not another player's move). */
+  private ownSeq: number | null = null;
+
+  constructor(host: TurnGameHost, initial: TurnGameView) {
+    this.host = host;
+    this.id = initial.id;
+    this.state = initial;
+    host.opened(this);
+    this.listen();
+  }
+
+  /** Whose move it is, the seats and the deadline. */
+  get summary(): TurnSummary {
+    return this.state.summary;
+  }
+
+  /** This seat's view, from the game's rules (`null` before the game starts). */
+  get view(): View {
+    return toGameData<View>(this.state.view);
+  }
+
+  /** This player's seat, or `null` (they left). */
+  get mySeat(): number | null {
+    return this.state.mySeat;
+  }
+
+  /** The end, once the game is over. */
+  get outcome(): TurnOutcome | null {
+    return this.state.outcome;
+  }
+
+  /** The last chat lines, oldest first. */
+  get chat(): readonly TurnChatLine[] {
+    return this.state.chat;
+  }
+
+  /** `on`: friends may type (moderated); `quick`: quick-chat and emotes only; `off`. */
+  get chatMode(): TurnGameView['chatMode'] {
+    return this.state.chatMode;
+  }
+
+  /** The link others can take a seat with (the creator's, while seats are open), else `null`. */
+  get link(): string | null {
+    return this.state.link === null ? null : new URL(this.state.link, location.origin).href;
+  }
+
+  /** Creator: start the game (empty seats go to the computer when the game allows). */
+  async start(): Promise<void> {
+    this.update(await this.host.start(this.id));
+  }
+
+  /**
+   * Make a move. Rejects with a `HubError`: 403 `not_your_turn`, 409
+   * `stale` (the game moved on: the view is refreshed first), 422 `illegal`
+   * with the rules' own code in `rule`.
+   */
+  async move(move: Move): Promise<{ seq: number; view: View; events: Ev[] }> {
+    this.ownSeq = this.state.summary.seq + 1;
+    try {
+      const answer = await this.host.move(this.id, this.state.summary.seq, toPayload(move));
+      this.update(answer.game);
+      return { seq: answer.game.summary.seq, view: this.view, events: answer.events.map((event) => toGameData<Ev>(event)) };
+    } catch (failure) {
+      if (failure instanceof HubError && failure.code === 'stale') {
+        await this.refresh();
+      }
+      throw failure;
+    } finally {
+      this.ownSeq = null;
+    }
+  }
+
+  /** The moves after `sinceSeq`, with their events as this seat may see them ("what happened while you were away"). */
+  async history(sinceSeq: number): Promise<{ seq: number; seat: number; events: Ev[] }[]> {
+    const moves = await this.host.history(this.id, sinceSeq);
+    return moves.map((move) => ({ seq: move.seq, seat: move.seat, events: move.events.map((event) => toGameData<Ev>(event)) }));
+  }
+
+  /** Leave: the computer plays the seat (or, without bots, the others win). The player can't come back. */
+  async leave(): Promise<void> {
+    await this.host.leave(this.id);
+    this.close();
+  }
+
+  /** Remind whoever must move (once a day). */
+  nudge(): Promise<void> {
+    return this.host.nudge(this.id);
+  }
+
+  /** This game's "your turn" alerts. */
+  setNotify(mode: 'on' | 'off'): Promise<void> {
+    return this.host.setNotify(this.id, mode);
+  }
+
+  /** A finished game: a new one with the same friends (they get an invite). */
+  async rematch(): Promise<TurnGame<View, Move, Ev>> {
+    return new TurnGame<View, Move, Ev>(this.host, await this.host.rematch(this.id));
+  }
+
+  /** Creator, before the start: add an invite link (`link: true`, then read `link`) or list the open seats for anyone (`public`). */
+  async share(share: { readonly link?: boolean; readonly public?: boolean }): Promise<void> {
+    this.update(await this.host.share(this.id, share));
+  }
+
+  /** Invite friends to free seats (before the start). */
+  async invite(userIds: readonly number[]): Promise<void> {
+    this.update(await this.host.invite(this.id, userIds));
+  }
+
+  /** The turn's deadline passed (or its player is suspended): let the computer play it. */
+  async letComputerPlay(): Promise<void> {
+    this.update(await this.host.autoPlay(this.id));
+  }
+
+  /** Say something: `{ text }` between friends (moderated), `{ quick }` (a quick-chat phrase id) with anyone. */
+  say(send: { readonly text?: string; readonly quick?: string }): Promise<TurnChatLine> {
+    return this.host.chat(this.id, send);
+  }
+
+  /** Fetch the game again, and replay moves missed since the last one this page saw. */
+  async refresh(): Promise<void> {
+    const before = this.state.summary.seq;
+    const fresh = await this.host.get(this.id);
+    if (fresh.summary.seq > before) {
+      const missed = await this.host.history(this.id, before);
+      this.update(fresh);
+      for (const move of missed) {
+        this.emit('move', { seq: move.seq, seat: move.seat, view: this.view, events: move.events.map((event) => toGameData<Ev>(event)) });
+      }
+    } else {
+      this.update(fresh);
+    }
+  }
+
+  /** Hear moves, turn changes, the end and chat; returns a function that stops listening. */
+  on<K extends keyof TurnGameEvents<View, Ev>>(eventName: K, listener: Listener<TurnGameEvents<View, Ev>[K]>): () => void {
+    const set: Set<Listener<TurnGameEvents<View, Ev>[K]>> = this.listeners[eventName];
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+    };
+  }
+
+  /** Stop live updates for this page (the game itself goes on). */
+  close(): void {
+    if (this.isClosed) {
+      return;
+    }
+    this.isClosed = true;
+    for (const stop of this.stopListening) {
+      stop();
+    }
+    this.host.closed(this);
+  }
+
+  /** Take a fresh answer from the hub; fire `turn` and `ended` when they changed. */
+  private update(next: TurnGameView): void {
+    const previous = this.state;
+    this.state = next;
+    const isChanged = previous.summary.seq !== next.summary.seq || previous.summary.phase !== next.summary.phase || !sameSeats(previous.summary, next.summary)
+      || previous.chatMode !== next.chatMode || previous.link !== next.link;
+    if (isChanged) {
+      this.emit('turn', next.summary);
+    }
+    if (previous.summary.phase !== 'ended' && next.summary.phase === 'ended') {
+      this.emit('ended', { outcome: next.outcome, view: this.view });
+    }
+  }
+
+  private emit<K extends keyof TurnGameEvents<View, Ev>>(eventName: K, payload: TurnGameEvents<View, Ev>[K]): void {
+    const set: Set<Listener<TurnGameEvents<View, Ev>[K]>> = this.listeners[eventName];
+    for (const listener of set) {
+      listener(payload);
+    }
+  }
+
+  /** A live `hub:turn` for this game: a move (or a missed run of them), or another change. */
+  private onLive(detail: object): void {
+    const seq = readField(detail, 'seq');
+    const view = readField(detail, 'view');
+    const summary = readField(detail, 'summary');
+    if (typeof seq !== 'number' || !isSummary(summary) || view === undefined) {
+      return;
+    }
+    if (seq > this.state.summary.seq + 1) {
+      void this.catchUp();
+      return;
+    }
+    const seat = readField(detail, 'seat');
+    const events = readField(detail, 'events');
+    const outcome = readField(detail, 'outcome');
+    const isMove = typeof seat === 'number' && seq === this.state.summary.seq + 1 && seq !== this.ownSeq;
+    if (summary.phase !== this.state.summary.phase || !sameSeating(this.state.summary, summary)) {
+      // Who sits where changed (a join, the start, a leave): the chat mode and link may have too, and the live event doesn't carry them.
+      void this.catchUp();
+    }
+    this.update({ ...this.state, summary, view: toPayloadJson(view), outcome: isOutcome(outcome) ? outcome : this.state.outcome });
+    if (isMove) {
+      this.emit('move', { seq, seat, view: this.view, events: Array.isArray(events) ? events.map((event) => toGameData<Ev>(toPayloadJson(event))) : [] });
+    }
+  }
+
+  /** Replay what was missed (one catch-up at a time). */
+  private catchUp(): Promise<void> {
+    this.catchingUp ??= this.refresh().catch(() => undefined).finally(() => {
+      this.catchingUp = null;
+    });
+    return this.catchingUp;
+  }
+
+  private listen(): void {
+    if (!isBrowserPage()) {
+      return;
+    }
+    const onTurn = (event: Event): void => {
+      if (!(event instanceof CustomEvent) || readField(event.detail, 'id') !== this.id) {
+        return;
+      }
+      // eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail, read field by field
+      const detail: unknown = event.detail;
+      if (typeof detail === 'object' && detail !== null) {
+        this.onLive(detail);
+      }
+    };
+    const onChat = (event: Event): void => {
+      if (event instanceof CustomEvent && readField(event.detail, 'id') === this.id) {
+        const line = readField(event.detail, 'line');
+        if (isChatLine(line)) {
+          this.state = { ...this.state, chat: [...this.state.chat, line].slice(-50) };
+          this.emit('chat', line);
+        }
+      }
+    };
+    const onVisible = (): void => {
+      if (document.visibilityState === 'visible') {
+        void this.catchUp();
+      }
+    };
+    const onResync = (): void => { void this.catchUp(); };
+    window.addEventListener(TURN_EVENT, onTurn);
+    window.addEventListener(TURN_CHAT_EVENT, onChat);
+    window.addEventListener(TURN_RESYNC_EVENT, onResync);
+    document.addEventListener('visibilitychange', onVisible);
+    const poll = setInterval(() => {
+      if (!this.host.isLive() && document.visibilityState === 'visible') {
+        void this.catchUp();
+      }
+    }, TURN_POLL_MS);
+    this.stopListening.push(
+      () => { window.removeEventListener(TURN_EVENT, onTurn); },
+      () => { window.removeEventListener(TURN_CHAT_EVENT, onChat); },
+      () => { window.removeEventListener(TURN_RESYNC_EVENT, onResync); },
+      () => { document.removeEventListener('visibilitychange', onVisible); },
+      () => { clearInterval(poll); },
+    );
+  }
+}
+
+/** Every seat matches its counterpart by `same`. */
+function eachSeat(a: TurnSummary, b: TurnSummary, same: (seat: TurnSeat, other: TurnSeat) => boolean): boolean {
+  return a.seats.length === b.seats.length && a.seats.every((seat, index) => {
+    const other = b.seats[index];
+    return other !== undefined && same(seat, other);
+  });
+}
+
+/** The same players in the same seats with the same statuses (who sits where). */
+function sameSeating(a: TurnSummary, b: TurnSummary): boolean {
+  return eachSeat(a, b, (seat, other) => seat.status === other.status && seat.userId === other.userId);
+}
+
+/** The same seating, and the same looks (a player's new avatar is a change: `turn` fires). */
+function sameSeats(a: TurnSummary, b: TurnSummary): boolean {
+  return sameSeating(a, b) && eachSeat(a, b, (seat, other) => seat.look === other.look);
+}
+
+/** A game's move as the JSON the hub takes. */
+function toPayload(move: GamePayload): Json {
+  return toPayloadJson(move);
+}
+
+/** Any JSON-safe value as `Json` (a JSON round trip). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a game's own move, or a value from another bundle's event
+function toPayloadJson(value: unknown): Json {
+  const parsed = parseJsonText(JSON.stringify(value ?? null));
+  return isJson(parsed) ? parsed : null;
+}
+
+/** Shape checks for a live event's parts (it comes from another bundle). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail
+function isSummary(value: unknown): value is TurnSummary {
+  return typeof readField(value, 'phase') === 'string' && Array.isArray(readField(value, 'seats')) && Array.isArray(readField(value, 'toAct'));
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail
+function isOutcome(value: unknown): value is TurnOutcome | null {
+  return value === null || Array.isArray(readField(value, 'winners'));
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail
+function isChatLine(value: unknown): value is TurnChatLine {
+  return typeof readField(value, 'text') === 'string' && typeof readField(value, 'from') === 'number';
+}

package/src/core/version/client-version.gen.ts

@@ -1,3 +1,3 @@
-// Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
+// Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client`.
 /** This client's package version, sent as `x-hub-client` on REST calls and `client` in `hello`. */
-export const HUB_CLIENT_VERSION = '2.0.0-next.4';
+export const HUB_CLIENT_VERSION = '2.0.0-next.6';