@flayerlabs/gamemode-gate 0.1.0

package/src/room.ts

@@ -0,0 +1,297 @@
+import type { Pool } from 'pg';
+import { Round } from '@flayerlabs/gamemode-spec/round';
+import type { Award, Command, Decision, GameModule, PlayerId, Refusal, RoundWindow } from '@flayerlabs/gamemode-spec';
+import type { LaunchContext } from '@flayerlabs/gamemode-spec/live';
+import { isRefusal } from '@flayerlabs/gamemode-spec';
+import { inTransaction, toBigInt } from './store.js';
+
+/**
+ * Everything except a wake.
+ *
+ * Wakes belong to {@link Room.tick}. Passing one to {@link Room.apply} would fire the same deadline
+ * twice — `send` runs due wakes on the way to the command — collapsing whatever phase sat between
+ * them. Excluding it from the type is better than checking for it: the mistake stops compiling.
+ */
+type PlayerCommand<Action> = Exclude<Command<Action>, { kind: 'wake' }>;
+
+/**
+ * A round, made durable.
+ *
+ * One command at a time, and each one commits in a single transaction: the command itself, the
+ * resulting state, and every point it awarded. Nothing can be half-applied, so a process that dies
+ * mid-command leaves a round that either took it or did not.
+ *
+ * Rebuilding is a snapshot read, not a replay. The command log exists to answer "why does this
+ * state look like this" during an incident, which is a different job from reconstructing it.
+ */
+export class Room<Config, State, Event, Action, PublicView, PlayerView> {
+  /**
+   * HTTP actions and the server ticker can arrive together. Keep the one-writer promise true
+   * inside a process by running both through the same serial tail.
+   */
+  private pending: Promise<void> = Promise.resolve();
+
+  private constructor(
+    private readonly pool: Pool,
+    private readonly game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+    readonly id: string,
+    private round: Round<Config, State, Event, Action, PublicView, PlayerView>,
+    readonly window: RoundWindow,
+    readonly launch: LaunchContext,
+    readonly weiPerPoint: bigint,
+    private seq: number,
+  ) {}
+
+  static async create<Config, State, Event, Action, PublicView, PlayerView>(
+    pool: Pool,
+    game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+    round: {
+      id: string;
+      config: Config;
+      seed: number;
+      window: RoundWindow;
+      weiPerPoint: bigint;
+      walletCapWei: bigint;
+      poolId: string;
+      booksCloseAt?: number;
+      launch?: {
+        coinAddress?: string | null;
+        name?: string;
+        symbol?: string;
+        imageUrl?: string | null;
+      };
+    },
+  ): Promise<Room<Config, State, Event, Action, PublicView, PlayerView>> {
+    const booksCloseAt = round.booksCloseAt ?? round.window.closesAt;
+    if (!Number.isSafeInteger(booksCloseAt) || booksCloseAt < round.window.closesAt) {
+      throw new RangeError('booksCloseAt must be a safe timestamp at or after closesAt');
+    }
+    const launch = Object.freeze({
+      roundId: round.id,
+      poolId: round.poolId,
+      coinAddress: round.launch?.coinAddress ?? null,
+      name: round.launch?.name ?? '',
+      symbol: round.launch?.symbol ?? '',
+      imageUrl: round.launch?.imageUrl ?? null,
+      opensAt: round.window.opensAt,
+      closesAt: round.window.closesAt,
+      booksCloseAt,
+    });
+    const started = Round.start(game, round.config, round.seed, round.window);
+    await pool.query(
+      `insert into rounds (
+         id, wei_per_point, wallet_cap_wei, pool_id, opens_at, closes_at, books_close_at,
+         coin_address, coin_name, coin_symbol, coin_image_url, state, seq
+       ) values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, 0)`,
+      [
+        round.id,
+        round.weiPerPoint.toString(),
+        round.walletCapWei.toString(),
+        round.poolId,
+        round.window.opensAt,
+        round.window.closesAt,
+        booksCloseAt,
+        launch.coinAddress,
+        launch.name,
+        launch.symbol,
+        launch.imageUrl,
+        serialise(game.id, started.snapshot()),
+      ],
+    );
+    return new Room(pool, game, round.id, started, round.window, launch, round.weiPerPoint, 0);
+  }
+
+  /** Pick up a round that already exists. Returns null if there is no such round. */
+  static async load<Config, State, Event, Action, PublicView, PlayerView>(
+    pool: Pool,
+    game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+    id: string,
+  ): Promise<Room<Config, State, Event, Action, PublicView, PlayerView> | null> {
+    const result = await pool.query<{
+      state: State;
+      seq: number;
+      pool_id: string;
+      opens_at: string;
+      closes_at: string;
+      books_close_at: string;
+      coin_address: string | null;
+      coin_name: string;
+      coin_symbol: string;
+      coin_image_url: string | null;
+      wei_per_point: string;
+    }>(
+      `select state, seq, pool_id, opens_at, closes_at, books_close_at, wei_per_point,
+              coin_address, coin_name, coin_symbol, coin_image_url
+       from rounds where id = $1`,
+      [id],
+    );
+    const row = result.rows[0];
+    if (!row) return null;
+
+    const window = { opensAt: Number(row.opens_at), closesAt: Number(row.closes_at) };
+    const launch = Object.freeze({
+      roundId: id,
+      poolId: row.pool_id,
+      coinAddress: row.coin_address,
+      name: row.coin_name,
+      symbol: row.coin_symbol,
+      imageUrl: row.coin_image_url,
+      ...window,
+      booksCloseAt: Number(row.books_close_at),
+    });
+    return new Room(
+      pool,
+      game,
+      id,
+      Round.resume(game, row.state, window),
+      window,
+      launch,
+      toBigInt(row.wei_per_point),
+      row.seq,
+    );
+  }
+
+  /**
+   * Apply one command and commit everything it caused.
+   *
+   * A refusal is not persisted. It changed nothing, and writing a row for every rejected action
+   * would let anyone with a keyboard grow the database.
+   */
+  async apply(command: PlayerCommand<Action>): Promise<Decision<Event> | Refusal> {
+    return this.serially(() => this.applyNow(command));
+  }
+
+  private async applyNow(command: PlayerCommand<Action>): Promise<Decision<Event> | Refusal> {
+    const awards: Award[] = [];
+    const round = this.working((award) => awards.push(award));
+
+    // Catch up first, and keep whatever that produced even if the command itself is refused. A
+    // reveal that fired on the way to a rejected action really happened: discarding it would
+    // silently un-reveal the round and delay everyone's points until something else arrived.
+    const caughtUp = round.advanceTo(command.at) > 0;
+
+    const result = round.send(command);
+    const refused = isRefusal(result);
+    if (refused && !caughtUp) return result;
+
+    const seq = this.seq + 1;
+    await this.commit(seq, refused ? { kind: 'wake', at: command.at } : command, round.snapshot(), awards);
+    this.round = round;
+    this.seq = seq;
+    return result;
+  }
+
+  /**
+   * A round over a COPY of the committed state.
+   *
+   * `evolve` is supposed to be pure, and a copy is what makes that a rule rather than a hope: a
+   * game that mutates its state in place would otherwise corrupt the live round even when the
+   * transaction that was meant to save it failed.
+   */
+  private working(onAward: (award: Award) => void): Round<Config, State, Event, Action, PublicView, PlayerView> {
+    return Round.resume(this.game, structuredClone(this.round.snapshot()), this.window, onAward);
+  }
+
+  /**
+   * Write one step: the command, the state it produced, and the points it awarded.
+   *
+   * The update is conditional on the sequence we read, so a second writer for the same round —
+   * another process, or a second Room in this one — loses instead of silently overwriting. There
+   * is meant to be one writer per round; this is what makes a broken assumption loud.
+   */
+  private async commit(seq: number, command: Command<Action>, state: State, awards: Award[]): Promise<void> {
+    await inTransaction(this.pool, async (tx) => {
+      const updated = await tx.query(
+        `update rounds set state = $2, seq = $3 where id = $1 and seq = $4`,
+        [this.id, serialise(this.game.id, state), seq, seq - 1],
+      );
+      if (updated.rowCount !== 1) {
+        throw new Error(`${this.id}: round moved on while this command was being applied`);
+      }
+      await tx.query(`insert into commands (round_id, seq, command) values ($1, $2, $3)`, [
+        this.id,
+        seq,
+        JSON.stringify(command),
+      ]);
+      for (const award of awards) {
+        // Same transaction as the state that earned them. Points credited without the state that
+        // justifies them, or the reverse, is a ledger nobody can reconcile.
+        await tx.query(
+          `insert into balances (round_id, player, points) values ($1, $2, $3)
+           on conflict (round_id, player) do update set points = balances.points + excluded.points`,
+          [this.id, award.player, Math.floor(award.points)],
+        );
+      }
+    });
+  }
+
+  /**
+   * Catch the round up to `now`, firing every wake it has missed.
+   *
+   * This lets the round advance itself rather than sending it a wake command. Sending one would
+   * fire the same deadline twice — `send` runs due wakes before applying anything — which skips
+   * whatever phase sat between them and reveals a quiz answer early.
+   */
+  async tick(now: number): Promise<void> {
+    return this.serially(() => this.tickNow(now));
+  }
+
+  private async tickNow(now: number): Promise<void> {
+    const awards: Award[] = [];
+    const round = this.working((award) => awards.push(award));
+    if (round.advanceTo(now) === 0) return;
+
+    const seq = this.seq + 1;
+    await this.commit(seq, { kind: 'wake', at: now }, round.snapshot(), awards);
+    this.round = round;
+    this.seq = seq;
+  }
+
+  private serially<T>(work: () => Promise<T>): Promise<T> {
+    const result = this.pending.then(work, work);
+    this.pending = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  nextWakeAt(): number | null {
+    return this.game.nextWakeAt(this.round.snapshot());
+  }
+
+  publicView(): PublicView {
+    return this.round.publicView();
+  }
+
+  playerView(player: PlayerId): PlayerView {
+    return this.round.playerView(player);
+  }
+
+  /** The cursor a reconnecting client resumes from. */
+  sequence(): number {
+    return this.seq;
+  }
+
+}
+
+/**
+ * Game state has to survive a round trip through JSON, and one thing silently does not: `bigint`
+ * makes `JSON.stringify` throw. It is an easy mistake — a game holding wei or a large counter — and
+ * the default message says only "Do not know how to serialize a BigInt", naming neither the game
+ * nor the field. Saying which game, and what to do instead, turns a confusing crash into an
+ * instruction.
+ */
+function serialise(gameId: string, state: unknown): string {
+  try {
+    return JSON.stringify(state);
+  } catch (error) {
+    if (error instanceof TypeError && /BigInt/i.test(error.message)) {
+      throw new TypeError(
+        `${gameId}: game state contains a bigint, which cannot be stored. Keep bigints out of state — ` +
+          'points are plain numbers and the platform owns anything measured in wei.',
+      );
+    }
+    throw error;
+  }
+}