@flayerlabs/gamemode-client 0.1.0

package/src/live.ts

@@ -0,0 +1,609 @@
+import type {
+  BuyFailure,
+  BuyProgress,
+  BuyResult,
+  ClientPlatform,
+  Economy,
+  EconomyState,
+  Room,
+  SendResult,
+  Snapshot,
+  Social,
+} from './index.js';
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import type { SpendAuthorisation } from '@flayerlabs/gamemode-spec/embed';
+import {
+  LIVE_PROTOCOL_VERSION,
+  isReactionId,
+  isLaunchContext,
+  type ConnectionState,
+  type LaunchContext,
+  type LiveClientFrame,
+  type MarketState,
+  type PresenceState,
+  type Reaction,
+  type WireEconomyBalance,
+  type WireMarketState,
+} from '@flayerlabs/gamemode-spec/live';
+import { Signal } from './signal.js';
+import { CachedIdentityResolver } from './identity.js';
+
+/**
+ * The page the game is embedded in, as far as the game is concerned.
+ *
+ * This is the whole wallet surface, and it is two verbs rather than a pipe. The game cannot ask
+ * for a transaction to be sent, because there is no way to say it: `buy` names an authorisation
+ * the gate already signed, and the page builds the transaction from that itself.
+ *
+ * The version this replaces forwarded `eth_sendTransaction` with parameters from the frame, which
+ * meant a game could ask for any transaction at all and have it appear in the trusted context of
+ * the page. That is fine for a game you wrote and wrong for one you did not.
+ */
+export interface Host {
+  /**
+   * Which wallet is connected to the page, or null if none is.
+   *
+   * Null is an answer, not a failure: a game can tell a player to connect. The version this
+   * replaces stayed silent instead, so the game waited out an eight-second timeout and then fell
+   * back to whatever extension the browser happened to have — which is how someone ended up signed
+   * in as one wallet while the page showed another.
+   */
+  address(signal?: AbortSignal): Promise<string | null>;
+
+  /** Ask the player to prove that wallet is theirs. Honour abort when the trusted embed closes. */
+  signIn(message: string, signal?: AbortSignal): Promise<`0x${string}`>;
+  /** Fresh, single-use admission evidence. Honour abort when the trusted embed closes. */
+  sessionEvidence?(signal?: AbortSignal): Promise<unknown>;
+  /** Spend an authorisation the gate issued. The page builds and submits the transaction. */
+  buy(
+    authorisation: Authorisation,
+    progress?: (event: HostBuyProgress) => void,
+    signal?: AbortSignal,
+  ): Promise<{ spentWei: bigint } | { failed: BuyResult }>;
+}
+
+/** The host reports only what it uniquely knows; LiveRoom owns the terminal result. */
+export type HostBuyProgress = { state: 'pending'; transactionHash?: string };
+
+/** Exactly what the gate signed. Everything is a string because bigints do not survive JSON. */
+export type Authorisation = SpendAuthorisation;
+
+export interface LiveOptions {
+  /** The gate's origin. The one place this game is allowed to talk to. */
+  gateUrl: string;
+  roundId: string;
+  host: Host;
+  /** May be supplied by the parent immediately; a new gate also sends it in its first snapshot. */
+  launch?: LaunchContext;
+  platform?: ClientPlatform;
+}
+
+/** Long enough not to hammer a gate that is restarting, short enough to feel instant. */
+const RECONNECT_MS = 1_000;
+const FIRST_SNAPSHOT_TIMEOUT_MS = 15_000;
+
+export async function joinRoom<PublicView, PlayerView, Action>(
+  options: LiveOptions,
+): Promise<Room<PublicView, PlayerView, Action>> {
+  const room = new LiveRoom<PublicView, PlayerView, Action>(options);
+  try {
+    await room.start();
+    return room;
+  } catch (error) {
+    room.dispose();
+    throw error;
+  }
+}
+
+class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, PlayerView, Action> {
+  private socket: WebSocket | null = null;
+  private token: string | null = null;
+  private me: PlayerId | null = null;
+  private latest: Snapshot<PublicView, PlayerView> | null = null;
+  /** Server time minus our time. Every countdown is drawn through this. */
+  private skew = 0;
+  private closed = false;
+  private claimSequence = 0;
+  private balanceRevision = 0;
+  private activeBuy: symbol | null = null;
+  private readonly initialSnapshot: Promise<void>;
+  private resolveInitialSnapshot!: () => void;
+  private rejectInitialSnapshot!: (error: Error) => void;
+  private readonly connectionSignal = new Signal<ConnectionState>('connecting');
+  private readonly launchSignal: Signal<LaunchContext | null>;
+  private readonly economySignal = new Signal<EconomyState>(emptyEconomy());
+  private readonly marketSignal: Signal<MarketState>;
+  private readonly presenceSignal = new Signal<PresenceState>({ connectedCount: 1 });
+  private readonly stopMarket: () => void;
+  private readonly listeners = new Set<(s: Snapshot<PublicView, PlayerView>) => void>();
+  private readonly reactionListeners = new Set<(r: Reaction) => void>();
+
+  /** Told when the connection is unhappy, so a game can say so rather than look frozen. */
+  trouble: ((what: 'connection') => void) | null = null;
+
+  readonly identity: CachedIdentityResolver;
+
+  constructor(private readonly options: LiveOptions) {
+    this.initialSnapshot = new Promise((resolve, reject) => {
+      this.resolveInitialSnapshot = resolve;
+      this.rejectInitialSnapshot = reject;
+    });
+    this.launchSignal = new Signal(options.launch ? immutableLaunch(options.launch) : null);
+    this.marketSignal = new Signal(
+      options.platform?.market?.current() ?? { status: 'unavailable', prices: [], trades: [], marketCapUsd: null },
+    );
+    this.stopMarket = options.platform?.market?.subscribe((state) => this.marketSignal.set(state)) ?? (() => {});
+    this.identity = new CachedIdentityResolver(options.platform?.identity);
+  }
+
+  async start(): Promise<void> {
+    const address = await this.options.host.address();
+    if (!address) throw new NoWallet();
+
+    const challenge = await this.post<{ nonce: string; message: string }>('/session/challenge', { address });
+    const signature = await this.options.host.signIn(challenge.message);
+    const evidence = await this.options.host.sessionEvidence?.();
+    const session = await this.post<{ token: string }>('/session', {
+      address,
+      signature,
+      nonce: challenge.nonce,
+      ...(evidence === undefined ? {} : { evidence }),
+    });
+    this.token = session.token;
+    this.me = address.toLowerCase();
+
+    await this.post(`/rounds/${this.options.roundId}/join`, {});
+    this.connect();
+
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        this.initialSnapshot,
+        new Promise<never>((_, reject) => {
+          timeout = setTimeout(
+            () => reject(new Error('the room did not send its first snapshot in time')),
+            FIRST_SNAPSHOT_TIMEOUT_MS,
+          );
+        }),
+      ]);
+      if (this.launchSignal.current() === null) {
+        throw new Error('the room did not provide launch context');
+      }
+    } catch (error) {
+      this.dispose();
+      throw error;
+    } finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+    }
+  }
+
+  private connect(): void {
+    if (this.closed) return;
+    const url = new URL(`/rounds/${this.options.roundId}/live`, this.options.gateUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    if (this.token) url.searchParams.set('token', this.token);
+
+    const socket = new WebSocket(url.toString());
+    this.socket = socket;
+
+    socket.onmessage = (event) => this.receive(String(event.data));
+    // Without this a failed upgrade is silent, and the game shows an empty room forever with
+    // nothing anywhere saying why.
+    socket.onerror = () => {
+      if (!this.closed) this.connectionSignal.set('reconnecting');
+      this.trouble?.('connection');
+    };
+    // A dropped socket is normal — a laptop lid, a tunnel, a deploy. Reconnecting silently and
+    // taking a fresh snapshot is the whole recovery story, because the gate sends whole state.
+    socket.onclose = (event) => {
+      if (this.socket === socket) this.socket = null;
+      if (this.closed) return;
+      if (event.code === 4009 || event.code === 4409) {
+        this.closed = true;
+        this.connectionSignal.set('superseded');
+        this.rejectInitialSnapshot(new Error('this room connection was superseded'));
+        return;
+      }
+      if (event.code === 4404 || event.code === 4410) {
+        this.closed = true;
+        this.connectionSignal.set('ended');
+        this.rejectInitialSnapshot(new Error('this room has ended'));
+        return;
+      }
+      this.connectionSignal.set('reconnecting');
+      setTimeout(() => this.connect(), RECONNECT_MS);
+    };
+  }
+
+  private receive(data: string): void {
+    let frame: Record<string, unknown>;
+    try {
+      const parsed: unknown = JSON.parse(data);
+      if (typeof parsed !== 'object' || parsed === null) return;
+      frame = parsed as Record<string, unknown>;
+    } catch {
+      return;
+    }
+
+    if (frame.type === 'reaction') {
+      const reaction = reactionFrom(frame.reaction);
+      if (reaction) for (const listener of this.reactionListeners) listener(reaction);
+      return;
+    }
+    if (frame.type === 'market') {
+      const market = marketFrom(frame.market);
+      if (market) this.marketSignal.set(market);
+      return;
+    }
+    if (frame.type === 'presence') {
+      const presence = presenceFrom(frame.presence);
+      if (presence) this.presenceSignal.set(presence);
+      return;
+    }
+    if (frame.type !== undefined && frame.type !== 'snapshot') return;
+
+    if (typeof frame.now === 'number') this.skew = frame.now - Date.now();
+    const economy = economyFrom(frame.economy);
+    if (economy) this.setBalance(economy);
+
+    if (this.launchSignal.current() === null && isLaunchContext(frame.launch)) {
+      this.launchSignal.set(immutableLaunch(frame.launch));
+    }
+    const presence = presenceFrom(frame.presence);
+    if (presence) this.presenceSignal.set(presence);
+    if (!('view' in frame)) return;
+
+    this.latest = { publicView: frame.view as PublicView, playerView: (frame.you ?? null) as PlayerView | null };
+    this.connectionSignal.set('connected');
+    for (const listener of this.listeners) listener(this.latest);
+    this.resolveInitialSnapshot();
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const response = await fetch(new URL(path, this.options.gateUrl), {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+      },
+      body: JSON.stringify(body),
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) throw new GateRefused(response.status, payload);
+    return payload as T;
+  }
+
+  subscribe(listener: (snapshot: Snapshot<PublicView, PlayerView>) => void): () => void {
+    this.listeners.add(listener);
+    if (this.latest) listener(this.latest);
+    return () => this.listeners.delete(listener);
+  }
+
+  readonly launch = {
+    current: () => this.requiredLaunch(),
+    subscribe: (listener: (value: LaunchContext) => void) =>
+      this.launchSignal.subscribe((value) => {
+        if (value) listener(value);
+      }),
+  };
+
+  readonly connection = {
+    current: () => this.connectionSignal.current(),
+    subscribe: (listener: (value: ConnectionState) => void) => this.connectionSignal.subscribe(listener),
+  };
+
+  readonly market = {
+    current: () => this.marketSignal.current(),
+    subscribe: (listener: (value: MarketState) => void) => this.marketSignal.subscribe(listener),
+  };
+
+  readonly presence = {
+    current: () => this.presenceSignal.current(),
+    subscribe: (listener: (value: PresenceState) => void) => this.presenceSignal.subscribe(listener),
+  };
+
+  async send(action: Action): Promise<SendResult> {
+    try {
+      await this.post(`/rounds/${this.options.roundId}/actions`, { action });
+      return { accepted: true };
+    } catch (error) {
+      if (error instanceof GateRefused) return { accepted: false, refuse: error.refuse };
+      throw error;
+    }
+  }
+
+  now(): number {
+    return Date.now() + this.skew;
+  }
+
+  readonly economy: Economy = {
+    current: () => this.economySignal.current(),
+    subscribe: (listener) => this.economySignal.subscribe(listener),
+    available: () => this.economySignal.current().availableWei,
+    buy: (maxSpendWei) => this.buy(maxSpendWei),
+  };
+
+  private async buy(maxSpendWei: bigint): Promise<BuyResult> {
+    // Set the token before the first await. Two clicks in the same turn must not both reserve the
+    // same allowance, and the losing call must not replace the lifecycle the active call renders.
+    if (this.activeBuy !== null) return { bought: false, reason: 'try-again' };
+    const attempt = Symbol('buy');
+    this.activeBuy = attempt;
+    try {
+      return await this.performBuy(maxSpendWei, attempt);
+    } finally {
+      if (this.activeBuy === attempt) this.activeBuy = null;
+    }
+  }
+
+  private async performBuy(maxSpendWei: bigint, attempt: symbol): Promise<BuyResult> {
+    if (maxSpendWei <= 0n) return this.failBuy(attempt, 'nothing-to-spend');
+    const balanceRevision = this.balanceRevision;
+    const requestId = this.nextRequestId();
+    let authorisation: Authorisation;
+    try {
+      authorisation = await this.postClaim<Authorisation>(`/rounds/${this.options.roundId}/claim`, {
+        maxSpendWei: maxSpendWei.toString(),
+        requestId,
+      });
+    } catch (error) {
+      if (error instanceof GateRefused) return this.failBuy(attempt, claimFailure(error.refuse));
+      return this.failBuy(attempt, 'try-again');
+    }
+
+    let spendWei: bigint;
+    try {
+      spendWei = BigInt(authorisation.maxSpendWei);
+    } catch {
+      return this.failBuy(attempt, 'try-again');
+    }
+    if (this.activeBuy !== attempt) return { bought: false, reason: 'try-again' };
+
+    const before = this.economySignal.current();
+    this.economySignal.set({
+      ...before,
+      ...(this.balanceRevision === balanceRevision
+        ? {
+            heldWei: before.heldWei + spendWei,
+            availableWei: before.availableWei > spendWei ? before.availableWei - spendWei : 0n,
+          }
+        : {}),
+      buy: { state: 'signing', spendWei },
+    });
+
+    let transactionHash: string | undefined;
+    let hostSettled = false;
+    // The page builds and submits. This game has no way to say what the transaction should be.
+    let result: Awaited<ReturnType<Host['buy']>>;
+    try {
+      result = await this.options.host.buy(authorisation, (progress) => {
+        if (hostSettled || this.activeBuy !== attempt) return;
+        transactionHash = progress.transactionHash;
+        const current = this.economySignal.current();
+        this.economySignal.set({
+          ...current,
+          buy: transactionHash === undefined
+            ? { state: 'pending', spendWei }
+            : { state: 'pending', spendWei, transactionHash },
+        });
+      });
+      hostSettled = true;
+    } catch {
+      hostSettled = true;
+      return this.failBuy(attempt, 'try-again');
+    }
+
+    if ('failed' in result) {
+      if (result.failed.bought) return this.failBuy(attempt, 'try-again');
+      return this.failBuy(attempt, result.failed.reason);
+    }
+    if (this.activeBuy !== attempt) return { bought: false, reason: 'try-again' };
+
+    const current = this.economySignal.current();
+    const confirmed: BuyProgress = transactionHash === undefined
+      ? { state: 'confirmed', spentWei: result.spentWei }
+      : { state: 'confirmed', spentWei: result.spentWei, transactionHash };
+    // The signed allowance remains held until the gate observes chain settlement or it expires.
+    this.economySignal.set({ ...current, buy: confirmed });
+    return { bought: true, spentWei: result.spentWei };
+  }
+
+  readonly social: Social = {
+    react: (id) => {
+      if (!isReactionId(id)) return;
+      this.sendFrame({ v: LIVE_PROTOCOL_VERSION, type: 'reaction', id });
+    },
+    onReaction: (listener) => {
+      this.reactionListeners.add(listener);
+      return () => this.reactionListeners.delete(listener);
+    },
+  };
+
+  dispose(): void {
+    this.closed = true;
+    this.activeBuy = null;
+    this.socket?.close();
+    this.connectionSignal.set('ended');
+    this.stopMarket();
+    this.listeners.clear();
+    this.reactionListeners.clear();
+    this.connectionSignal.clear();
+    this.launchSignal.clear();
+    this.economySignal.clear();
+    this.marketSignal.clear();
+    this.presenceSignal.clear();
+  }
+
+  private setBalance(balance: Omit<EconomyState, 'buy'>): void {
+    this.balanceRevision += 1;
+    this.economySignal.set({ ...balance, buy: this.economySignal.current().buy });
+  }
+
+  private failBuy(attempt: symbol, reason: BuyFailure): { bought: false; reason: BuyFailure } {
+    if (this.activeBuy === attempt) {
+      const current = this.economySignal.current();
+      this.economySignal.set({ ...current, buy: { state: 'failed', reason } });
+    }
+    return { bought: false, reason };
+  }
+
+  private nextRequestId(): string {
+    this.claimSequence += 1;
+    return `${globalThis.crypto.randomUUID()}:${this.claimSequence}`;
+  }
+
+  private requiredLaunch(): LaunchContext {
+    const launch = this.launchSignal.current();
+    if (launch === null) throw new Error('launch context is not ready');
+    return launch;
+  }
+
+  /** Claims are idempotent by request id, so a lost response can be retried exactly once. */
+  private async postClaim<T>(path: string, body: unknown): Promise<T> {
+    try {
+      return await this.post<T>(path, body);
+    } catch (error) {
+      if (error instanceof GateRefused && error.status < 500) throw error;
+      return this.post<T>(path, body);
+    }
+  }
+
+  private sendFrame(frame: LiveClientFrame): void {
+    if (this.socket?.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(frame));
+  }
+}
+
+function emptyEconomy(): EconomyState {
+  return {
+    weiPerPoint: 0n,
+    earnedWei: 0n,
+    heldWei: 0n,
+    spentWei: 0n,
+    availableWei: 0n,
+    holdExpiresAt: null,
+    buy: null,
+  };
+}
+
+function economyFrom(input: unknown): Omit<EconomyState, 'buy'> | null {
+  if (typeof input !== 'object' || input === null) return null;
+  const value = input as Partial<WireEconomyBalance>;
+  try {
+    const amounts = {
+      weiPerPoint: BigInt(value.weiPerPoint ?? '0'),
+      earnedWei: BigInt(value.earnedWei ?? '-1'),
+      heldWei: BigInt(value.heldWei ?? '-1'),
+      spentWei: BigInt(value.spentWei ?? '-1'),
+      availableWei: BigInt(value.availableWei ?? '-1'),
+    };
+    if (amounts.weiPerPoint <= 0n || Object.values(amounts).some((amount) => amount < 0n)) return null;
+
+    // A deadline is either a whole millisecond timestamp or absent. Anything else — a string, a
+    // fraction, Infinity — is a malformed frame, and a countdown drawn from one would run to a
+    // moment that never arrives.
+    const holdExpiresAt = value.holdExpiresAt;
+    if (holdExpiresAt !== null && holdExpiresAt !== undefined && !Number.isSafeInteger(holdExpiresAt)) {
+      return null;
+    }
+    return { ...amounts, holdExpiresAt: holdExpiresAt ?? null };
+  } catch {
+    return null;
+  }
+}
+
+function presenceFrom(input: unknown): PresenceState | null {
+  if (typeof input !== 'object' || input === null) return null;
+  const value = input as Partial<PresenceState>;
+  if (
+    typeof value.connectedCount !== 'number' ||
+    !Number.isSafeInteger(value.connectedCount) ||
+    value.connectedCount < 0
+  ) return null;
+  return { connectedCount: value.connectedCount };
+}
+
+function reactionFrom(input: unknown): Reaction | null {
+  if (typeof input !== 'object' || input === null) return null;
+  const value = input as { player?: unknown; id?: unknown };
+  return typeof value.player === 'string' && typeof value.id === 'string' && isReactionId(value.id)
+    ? { player: value.player, id: value.id }
+    : null;
+}
+
+export function marketFrom(input: unknown): MarketState | null {
+  if (typeof input !== 'object' || input === null) return null;
+  const value = input as Partial<WireMarketState>;
+  if (!['unavailable', 'loading', 'live', 'stale'].includes(String(value.status))) return null;
+  if (
+    !Array.isArray(value.prices) ||
+    !Array.isArray(value.trades) ||
+    value.prices.length > 1_000 ||
+    value.trades.length > 500
+  ) return null;
+
+  const prices = value.prices.filter(
+    (price) =>
+      typeof price?.at === 'number' &&
+      Number.isFinite(price.at) &&
+      typeof price.priceEth === 'number' &&
+      Number.isFinite(price.priceEth) &&
+      price.priceEth > 0,
+  );
+  const trades = value.trades.flatMap((trade) => {
+    try {
+      if (
+        typeof trade?.id !== 'string' ||
+        typeof trade.at !== 'number' ||
+        !Number.isFinite(trade.at) ||
+        (trade.player !== null && typeof trade.player !== 'string') ||
+        (trade.side !== 'buy' && trade.side !== 'sell') ||
+        (trade.priceEth !== null && (typeof trade.priceEth !== 'number' || !Number.isFinite(trade.priceEth)))
+      ) return [];
+      const spendWei = BigInt(trade.spendWei);
+      if (spendWei < 0n) return [];
+      return [{
+        id: trade.id,
+        at: trade.at,
+        player: trade.player,
+        side: trade.side,
+        spendWei,
+        priceEth: trade.priceEth,
+        ...(typeof trade.transactionHash === 'string' ? { transactionHash: trade.transactionHash } : {}),
+      }];
+    } catch {
+      return [];
+    }
+  });
+  const marketCapUsd = typeof value.marketCapUsd === 'number' && Number.isFinite(value.marketCapUsd)
+    ? value.marketCapUsd
+    : null;
+  return { status: value.status!, prices, trades, marketCapUsd };
+}
+
+export function immutableLaunch(launch: LaunchContext): LaunchContext {
+  return Object.freeze({ ...launch });
+}
+
+function claimFailure(refuse: string): BuyFailure {
+  if (refuse === 'claim.nothing_earned' || refuse === 'claim.nothing_available') return 'nothing-to-spend';
+  if (refuse === 'claim.not_open_yet' || refuse === 'claim.window_closed') return 'window-closed';
+  return 'try-again';
+}
+
+/** No wallet is connected to the page. A game should ask the player to connect one. */
+export class NoWallet extends Error {
+  constructor() {
+    super('no wallet is connected');
+    this.name = 'NoWallet';
+  }
+}
+
+/** A refusal from the gate, carrying its stable code for the client to turn into words. */
+class GateRefused extends Error {
+  readonly refuse: string;
+  constructor(readonly status: number, payload: { refuse?: string; message?: string }) {
+    super(payload.message ?? payload.refuse ?? `request failed (${status})`);
+    this.name = 'GateRefused';
+    this.refuse = payload.refuse ?? 'request.failed';
+  }
+}