@flayerlabs/gamemode-gate 0.1.0

package/dist/room.d.ts

@@ -0,0 +1,98 @@
+import type { Pool } from 'pg';
+import type { Command, Decision, GameModule, PlayerId, Refusal, RoundWindow } from '@flayerlabs/gamemode-spec';
+import type { LaunchContext } from '@flayerlabs/gamemode-spec/live';
+/**
+ * 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 declare class Room<Config, State, Event, Action, PublicView, PlayerView> {
+    private readonly pool;
+    private readonly game;
+    readonly id: string;
+    private round;
+    readonly window: RoundWindow;
+    readonly launch: LaunchContext;
+    readonly weiPerPoint: bigint;
+    private seq;
+    /**
+     * 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;
+    private constructor();
+    static 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>>;
+    /** Pick up a round that already exists. Returns null if there is no such round. */
+    static 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>;
+    /**
+     * 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.
+     */
+    apply(command: PlayerCommand<Action>): Promise<Decision<Event> | Refusal>;
+    private applyNow;
+    /**
+     * 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;
+    /**
+     * 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 commit;
+    /**
+     * 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.
+     */
+    tick(now: number): Promise<void>;
+    private tickNow;
+    private serially;
+    nextWakeAt(): number | null;
+    publicView(): PublicView;
+    playerView(player: PlayerId): PlayerView;
+    /** The cursor a reconnecting client resumes from. */
+    sequence(): number;
+}
+export {};
+//# sourceMappingURL=room.d.ts.map

package/dist/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../src/room.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B,OAAO,KAAK,EAAS,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACtH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAIpE;;;;;;GAMG;AACH,KAAK,aAAa,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,qBAAa,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;IAQlE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,OAAO,CAAC,KAAK;IACb,QAAQ,CAAC,MAAM,EAAE,WAAW;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,OAAO,CAAC,GAAG;IAdb;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAoC;IAEnD,OAAO;WAWM,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EACtE,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,EACtE,KAAK,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,WAAW,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE;YACP,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SAC1B,CAAC;KACH,GACA,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAwCtE,mFAAmF;WACtE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EACpE,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,EACtE,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC;IA6C7E;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC;YAIjE,QAAQ;IAoBtB;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IAIf;;;;;;OAMG;YACW,MAAM;IA0BpB;;;;;;OAMG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIxB,OAAO;IAWrB,OAAO,CAAC,QAAQ;IAShB,UAAU,IAAI,MAAM,GAAG,IAAI;IAI3B,UAAU,IAAI,UAAU;IAIxB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU;IAIxC,qDAAqD;IACrD,QAAQ,IAAI,MAAM;CAInB"}

package/dist/room.js

@@ -0,0 +1,215 @@
+import { Round } from '@flayerlabs/gamemode-spec/round';
+import { isRefusal } from '@flayerlabs/gamemode-spec';
+import { inTransaction, toBigInt } from './store.js';
+/**
+ * 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 {
+    pool;
+    game;
+    id;
+    round;
+    window;
+    launch;
+    weiPerPoint;
+    seq;
+    /**
+     * 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.
+     */
+    pending = Promise.resolve();
+    constructor(pool, game, id, round, window, launch, weiPerPoint, seq) {
+        this.pool = pool;
+        this.game = game;
+        this.id = id;
+        this.round = round;
+        this.window = window;
+        this.launch = launch;
+        this.weiPerPoint = weiPerPoint;
+        this.seq = seq;
+    }
+    static async create(pool, game, round) {
+        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(pool, game, id) {
+        const result = await pool.query(`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) {
+        return this.serially(() => this.applyNow(command));
+    }
+    async applyNow(command) {
+        const awards = [];
+        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.
+     */
+    working(onAward) {
+        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.
+     */
+    async commit(seq, command, state, awards) {
+        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) {
+        return this.serially(() => this.tickNow(now));
+    }
+    async tickNow(now) {
+        const awards = [];
+        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;
+    }
+    serially(work) {
+        const result = this.pending.then(work, work);
+        this.pending = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    nextWakeAt() {
+        return this.game.nextWakeAt(this.round.snapshot());
+    }
+    publicView() {
+        return this.round.publicView();
+    }
+    playerView(player) {
+        return this.round.playerView(player);
+    }
+    /** The cursor a reconnecting client resumes from. */
+    sequence() {
+        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, state) {
+    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;
+    }
+}
+//# sourceMappingURL=room.js.map

package/dist/room.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,92 @@
+import { type FastifyInstance } from 'fastify';
+import type { Pool } from 'pg';
+import type { Command, GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
+import { Room } from './room.js';
+import { Claims } from './claims.js';
+import { Sessions } from './sessions.js';
+import type { Discovery, Launch, PoolKey } from './chain/discover.js';
+import type { Settlement } from './settlement.js';
+/**
+ * The gate's door.
+ *
+ * Deliberately small. Everything interesting already lives behind it — the room decides, the
+ * ledger and signer authorise — so this file is transport and nothing else. Any rule that appears
+ * here is a rule in the wrong place.
+ *
+ * Views are sent whole rather than as deltas. Whole snapshots stop being sensible somewhere in the
+ * low thousands of players in one room; deltas are the fix, and adding them before there is a room
+ * that size would be guessing at the shape of a problem nobody has.
+ */
+interface GateBaseOptions<Config, State, Event, Action, PublicView, PlayerView> {
+    pool: Pool;
+    game: GameModule<Config, State, Event, Action, PublicView, PlayerView>;
+    sessions: Sessions;
+    claims: Claims;
+    /** How many points a dollar buys. The only economic number anyone sets by hand. */
+    pointsPerDollar: number;
+    usdPerEth: number;
+    /** Verifies from the chain that a coin really is a game launch. */
+    discovery?: Discovery;
+    /** Keeps the ledger's view of spending level with the chain's. */
+    settlement?: Settlement;
+    /** How long charts and final spend reconciliation remain live after gameplay closes. */
+    settlementTailMs?: number;
+    /** Origins allowed to call this gate: the game's own, and nothing else. */
+    allowedOrigins: string[];
+    /**
+     * Decide whether a caller may open a session or spend a request, or refuse them.
+     *
+     * One optional seam rather than a bot layer, because the pieces of a bot layer are not
+     * game-neutral and this library is self-hosted. A human-verification vendor needs keys only the
+     * operator has; a request budget needs a cadence only the game knows — a quiz taking one answer
+     * every ten seconds and a shooter taking thirty a second cannot share a number; and a false
+     * refusal on a claim costs a player a purchase inside a window that will not come back.
+     *
+     * So the policy belongs to whoever runs the gate. What belongs here is the place to put it, and
+     * the guarantee it is consulted before a session is issued and before allowance is committed.
+     *
+     * Omitted, everything is admitted, which is what a laptop and a test want.
+     */
+    admit?: Admit;
+    /** The only cosmetic reaction IDs this game may broadcast. Omitted disables reactions. */
+    reactionIds?: readonly string[];
+}
+/** Resolve one immutable rules config after the launch has been verified. */
+export type VerifiedLaunch = Readonly<Omit<Launch, 'poolKey'>> & {
+    readonly poolKey: Readonly<PoolKey>;
+};
+export type ConfigForLaunch<Config> = (launch: VerifiedLaunch) => Promise<Config>;
+export type GateOptions<Config, State, Event, Action, PublicView, PlayerView> = GateBaseOptions<Config, State, Event, Action, PublicView, PlayerView> & {
+    /** A static serialisable config, or a factory resolved once after each launch is verified. */
+    config: Config | ConfigForLaunch<Config>;
+};
+/** Where an admission check is being made. Enough to tell a sign-in from a spend. */
+export interface AdmissionRequest {
+    /** `session` on sign-in, `action` on gameplay, `claim` when allowance is about to be committed. */
+    at: 'session' | 'action' | 'claim';
+    /** Null at `session`, because nobody has proved who they are yet. */
+    player: PlayerId | null;
+    roundId: string | null;
+    /** Straight from the socket, so a limiter can key on it. Absent behind some proxies. */
+    ip: string | null;
+    /** Opaque and operator-defined: a captcha solution, a device token, whatever was sent. */
+    evidence: unknown;
+}
+/**
+ * Allow, or refuse with a reason a player can be shown.
+ *
+ * The reason reaches the player, so write it for them: "too many tries, wait a minute", not a rule
+ * name or a score.
+ */
+export type Admission = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type Admit = (request: AdmissionRequest) => Admission | Promise<Admission>;
+export declare const DEFAULT_SETTLEMENT_TAIL_MS: number;
+export declare function createGate<Config, State, Event, Action, PublicView, PlayerView>(options: GateOptions<Config, State, Event, Action, PublicView, PlayerView>): FastifyInstance;
+export { Room, Claims, Sessions };
+export type { Command };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

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