@anweather/game-plugin-ssdk 1.16.0 → 1.17.0

package/dist-types/runtime/auth.d.ts

@@ -0,0 +1,3 @@
+/** True when `header` is exactly `Bearer <token>`. Hashing both sides first
+ * gives timingSafeEqual equal-length inputs without leaking the length. */
+export declare function bearerMatches(header: string | undefined, token: string): boolean;

package/dist-types/runtime/conformance.d.ts

@@ -1,9 +1,15 @@
 import type { GamePluginService } from "../src/server/GamePluginService";
+import { type LiveConformanceOptions } from "./live/conformance";
+import type { LiveOptions } from "./live/rooms";
 export interface ConformanceOptions {
     /** Participant ids to seat. Defaults to metadata.minPlayers generated ids. */
     participants?: string[];
     /** InitializeGame config. Defaults to {}. */
     config?: unknown;
+    /** The plugin's servePlugin `live` option: adds the room checks (a real
+     * /v1/live on a throwaway port; see live/conformance.ts). */
+    live?: LiveOptions;
+    liveOptions?: LiveConformanceOptions;
 }
 export interface ConformanceReport {
     passed: string[];

package/dist-types/runtime/index.d.ts

@@ -10,3 +10,14 @@ export type { ConformanceOptions, ConformanceReport } from "./conformance";
 export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";
 export { createBlobClient, casUpdate, blobOwner, BlobStoreError, isVersionConflict } from "./blobClient";
 export type { BlobClient, BlobClientOptions, BlobOwnerKey, Blob, BlobItem, BlobInfo, BlobWrite, BlobErrorType, } from "./blobClient";
+export { attachLive } from "./live/server";
+export type { AttachLiveOptions, LiveServer } from "./live/server";
+export type { LiveOptions, Room, RoomHandlers, Conn, RoomCloseReason, RoomTimer, SendOptions, BroadcastOptions, KickOptions, } from "./live/rooms";
+export { createLiveHarness } from "./live/harness";
+export { loadRoomCheckpoint } from "./live/checkpoint";
+export type { RoomCheckpoint } from "./live/checkpoint";
+export type { LiveHarness, FakeLink, FakeClient, JoinSpec, HarnessMessage } from "./live/harness";
+export { runLiveConformance, assertLiveConformance } from "./live/conformance";
+export type { LiveConformanceOptions, LiveConformanceReport } from "./live/conformance";
+export { LIVE_PROTOCOL_VERSION, LIVE_PATH, LinkCloseCode, MAX_LINK_FRAME_BYTES } from "./live/protocol";
+export type { RoomScope, SpaceMember, PresenceState, Role } from "./live/protocol";

package/dist-types/runtime/live/checkpoint.d.ts

@@ -0,0 +1,15 @@
+import { type BlobClient, type BlobOwnerKey } from "../blobClient";
+import type { Room } from "./rooms";
+export interface RoomCheckpoint<T> {
+    /** What onRoom loaded (or the last successful save); undefined if none. */
+    readonly value: T | undefined;
+    /** The blob version this room owns; 0 before the first write. */
+    readonly version: number;
+    /** Write `value` if nobody else has written since this room's last read
+     * or write. False on a conflict: another room took over the scope (and,
+     * when a room was given, this one is closed). Other errors throw. */
+    save(value: T): Promise<boolean>;
+}
+export declare function loadRoomCheckpoint<T>(client: BlobClient, owner: BlobOwnerKey, key: string, opts?: {
+    room?: Room;
+}): Promise<RoomCheckpoint<T>>;

package/dist-types/runtime/live/conformance.d.ts

@@ -0,0 +1,24 @@
+import type { LiveOptions } from "./rooms";
+export interface LiveConformanceOptions {
+    /** The game type to claim on the link. Default "conformance". */
+    gameType?: string;
+    /** Scope to open. Default a fresh "game:{uuid}". */
+    scope?: string;
+    /** The payload of every Signal the storm sends. Default {}: a room must
+     * treat client data as untrusted and must not throw on it. */
+    signal?: unknown;
+    /** Connections in the join/leave storm. Default 100. */
+    stormSize?: number;
+    /** How long to wait for `ready` and for the room to settle. Default 5 s. */
+    timeoutMs?: number;
+}
+export interface LiveConformanceReport {
+    passed: string[];
+    failed: {
+        check: string;
+        reason: string;
+    }[];
+}
+export declare function runLiveConformance(live: LiveOptions, options?: LiveConformanceOptions): Promise<LiveConformanceReport>;
+/** runLiveConformance, throwing one error naming every failed check. */
+export declare function assertLiveConformance(live: LiveOptions, options?: LiveConformanceOptions): Promise<LiveConformanceReport>;

package/dist-types/runtime/live/harness.d.ts

@@ -0,0 +1,71 @@
+import { type PresenceState, type Role, type SpaceMember } from "./protocol";
+import { type LiveOptions, type Room } from "./rooms";
+export interface HarnessMessage {
+    /** Always "host": the only sender a Hosted client hears from. */
+    from: "host";
+    k?: string;
+    d: unknown;
+}
+export interface FakeClient {
+    readonly conn: string;
+    readonly participantId: string;
+    /** Signals the room sent this connection, oldest first. */
+    readonly received: HarnessMessage[];
+    /** Set once the room kicked this connection. */
+    readonly kicked: {
+        code: number;
+        reason?: string;
+    } | undefined;
+    readonly open: boolean;
+    signal(d: unknown): void;
+    presence(state: PresenceState): void;
+    leave(reason?: string): void;
+}
+export interface JoinSpec {
+    participantId: string;
+    playerId?: string;
+    displayName?: string;
+    role?: Role;
+    gameId?: string;
+    hidden?: boolean;
+    state?: PresenceState;
+    /** Defaults to a fresh "c1", "c2"... per link. */
+    conn?: string;
+}
+export interface FakeLink {
+    readonly scope: string;
+    /** True once the room answered `ready`. */
+    readonly ready: boolean;
+    /** Set once the plugin closed the link. */
+    readonly closedByPlugin: {
+        code: number;
+        reason: string;
+    } | undefined;
+    /** Every plugin frame on this link, decoded, oldest first. */
+    readonly frames: unknown[];
+    join(spec: JoinSpec): FakeClient;
+    game(gameId: string, revision: number): void;
+    members(members: SpaceMember[]): void;
+    /** Push any text frame, well-formed or not (conformance, fuzzing). */
+    raw(text: string): void;
+    /** The platform closes the link: 1000 idle, 4410 the game ended, 1012 a
+     * platform restart... */
+    close(code?: number): void;
+}
+export interface LiveHarness {
+    /** Open a room link for `scope` ("game:{id}" or "space:{id}"). A second
+     * link for a scope already open is the deploy-overlap case. */
+    openLink(scope: string, opts?: {
+        epoch?: string;
+    }): FakeLink;
+    /** Resolves once every room has loaded and handled everything sent so far. */
+    settled(): Promise<void>;
+    room(scope: string): Room | undefined;
+    rooms(): Room[];
+    /** Plugin shutdown: onClose("shutdown") everywhere, links closed with 1012. */
+    shutdown(): Promise<void>;
+}
+export declare function createLiveHarness(live: LiveOptions, opts?: {
+    gameType?: string;
+    log?: Pick<Console, "log" | "error">;
+}): LiveHarness;

package/dist-types/runtime/live/outbox.d.ts

@@ -0,0 +1,39 @@
+export interface LinkWriter {
+    /** Hand `text` to the socket; call `done` once it has been flushed (or
+     * failed: the link is going away and its close handles the rest). */
+    write(text: string, done: () => void): void;
+}
+export interface OutboxOptions {
+    /** Bytes in flight (written, not yet flushed) before frames queue here. */
+    highWaterBytes?: number;
+    /** Queued frames before the oldest droppable one is discarded. */
+    maxQueuedFrames?: number;
+}
+export interface OutboxStats {
+    /** Frames waiting here right now. */
+    queued: number;
+    /** Frames replaced by a newer one with the same key. */
+    coalesced: number;
+    /** Frames discarded because the queue was full. */
+    dropped: number;
+}
+export declare const DEFAULT_HIGH_WATER_BYTES: number;
+export declare const DEFAULT_MAX_QUEUED_FRAMES = 1024;
+export declare class Outbox {
+    private readonly writer;
+    private readonly highWater;
+    private readonly maxQueued;
+    private readonly queue;
+    private inflight;
+    private pumping;
+    private closed;
+    readonly stats: OutboxStats;
+    constructor(writer: LinkWriter, options?: OutboxOptions);
+    push(text: string, opts: {
+        key?: string;
+        droppable: boolean;
+    }): void;
+    /** Stop writing; whatever is queued is abandoned with the link. */
+    close(): void;
+    private pump;
+}

package/dist-types/runtime/live/protocol.d.ts

@@ -0,0 +1,169 @@
+/** The X-Live-Protocol value this runtime speaks. */
+export declare const LIVE_PROTOCOL_VERSION = 1;
+/** The upgrade path, beside the RPC operations under /v1. */
+export declare const LIVE_PATH = "/v1/live";
+export declare const LIVE_HEADERS: {
+    readonly auth: "x-plugin-auth";
+    readonly scope: "x-live-scope";
+    readonly epoch: "x-live-epoch";
+    readonly gameType: "x-game-type";
+    readonly protocol: "x-live-protocol";
+};
+/** The biggest frame either side may put on the link. A client Signal is at
+ * most 16 KiB (the Hosted client ceiling, design §10.1), so a platform frame
+ * carrying one fits with room for the envelope; a plugin `send` over this is
+ * refused by the runtime before it is written. */
+export declare const MAX_LINK_FRAME_BYTES: number;
+/** Close codes on the room link (PROTOCOL.md §6). */
+export declare const LinkCloseCode: {
+    /** Platform: the channel has been idle for its grace; the room is done.
+     *  Plugin: `room.close()`, the room is discarded (the platform reopens a
+     *  fresh link if clients remain). */
+    readonly NORMAL: 1000;
+    /** Platform: going away without a restart planned. */
+    readonly GOING_AWAY: 1001;
+    /** Malformed handshake follow-up or repeated protocol abuse. */
+    readonly POLICY: 1008;
+    /** A frame over MAX_LINK_FRAME_BYTES. */
+    readonly TOO_BIG: 1009;
+    /** The plugin's room failed (setup threw, or it fell too far behind). */
+    readonly INTERNAL_ERROR: 1011;
+    /** Either side is restarting; the platform reopens with backoff. */
+    readonly RESTART: 1012;
+    /** Platform: the link fell behind its inbound bound (design §10.3). */
+    readonly TOO_SLOW: 4008;
+    /** Plugin: a newer link with the same X-Live-Epoch replaced this one
+     *  (PROTOCOL.md §5.4). The platform has already moved to the new link. */
+    readonly SUPERSEDED: 4409;
+    /** Platform: the scope ended (its Game completed or was abandoned). */
+    readonly GONE: 4410;
+};
+export type Role = "PARTICIPANT" | "SPECTATOR";
+export type PresenceState = "ACTIVE" | "AWAY";
+/** One entry of a Space's membership, the same shape as config.space.members. */
+export interface SpaceMember {
+    playerId: string;
+    displayName: string;
+    role: string;
+    status: string;
+}
+export type RoomScope = {
+    kind: "game";
+    id: string;
+    key: string;
+} | {
+    kind: "space";
+    id: string;
+    key: string;
+};
+export interface JoinFrame {
+    t: "join";
+    conn: string;
+    participantId: string;
+    playerId: string;
+    displayName: string;
+    role: Role;
+    gameId: string;
+    hidden: boolean;
+    state: PresenceState;
+}
+export interface LeaveFrame {
+    t: "leave";
+    conn: string;
+    reason: string;
+}
+export interface SigFrame {
+    t: "sig";
+    conn: string;
+    participantId: string;
+    d: unknown;
+}
+export interface PresenceFrame {
+    t: "presence";
+    conn: string;
+    state: PresenceState;
+}
+export interface GameFrame {
+    t: "game";
+    gameId: string;
+    revision: number;
+}
+export interface MembersFrame {
+    t: "members";
+    members: SpaceMember[];
+}
+export type PlatformFrame = JoinFrame | LeaveFrame | SigFrame | PresenceFrame | GameFrame | MembersFrame;
+export interface SendFrame {
+    t: "send";
+    to: "all" | string[];
+    k?: string;
+    d: unknown;
+}
+export interface KickFrame {
+    t: "kick";
+    conn: string;
+    code: number;
+    reason?: string;
+}
+export interface ReadyFrame {
+    t: "ready";
+}
+export type PluginFrame = SendFrame | KickFrame | ReadyFrame;
+export type Decoded<F> = {
+    ok: true;
+    frame: F;
+}
+/** Well-formed JSON object with a `t` this version doesn't know: ignore. */
+ | {
+    ok: false;
+    unknown: true;
+    t: string;
+}
+/** Not a JSON object, or a known frame missing/mistyping a field: drop. */
+ | {
+    ok: false;
+    unknown: false;
+    error: string;
+};
+/** A platform -> plugin frame, as the runtime reads it off the link. */
+export declare function decodePlatformFrame(text: string): Decoded<PlatformFrame>;
+/** A plugin -> platform frame, as the platform (or the loopback harness)
+ * reads it. The runtime never needs this itself; it is here so the harness
+ * and the tests decode exactly what the platform will. */
+export declare function decodePluginFrame(text: string): Decoded<PluginFrame>;
+/** A WebSocket close reason is at most 123 bytes; 120 characters of the
+ * plugin's own leaves room for nothing to be cut mid-character in practice. */
+export declare const MAX_KICK_REASON = 120;
+/** 4403 keeps the client out (terminal, design §6.3); 4900-4999 are the
+ * plugin's own, and the client reconnects after them like any other
+ * non-terminal close. Nothing else: a plugin must not be able to fake the
+ * platform's own meanings (4401 auth, 4409 superseded, 4410 game over...). */
+export declare function isKickCode(v: unknown): v is number;
+/** Encode either direction. `undefined` fields are dropped by JSON itself. */
+export declare function encodeFrame(frame: PluginFrame | PlatformFrame): string;
+export declare function byteLength(text: string): number;
+/** "game:{gameId}" or "space:{spaceId}"; anything else is null. */
+export declare function parseScope(header: string | undefined): RoomScope | null;
+export interface HandshakeExpectations {
+    gameType: string;
+    /** Absent: no token configured (local dev), every caller is accepted --
+     * the same rule as the RPC routes. */
+    authToken?: string;
+}
+export type HandshakeResult = {
+    ok: true;
+    scope: RoomScope;
+    epoch: string;
+    protocol: number;
+} | {
+    ok: false;
+    status: 400 | 401 | 404;
+    message: string;
+};
+type Headers = Record<string, string | string[] | undefined>;
+/** Check an upgrade request's headers (lower-cased, as node gives them).
+ * The order is the order a platform engineer would want the errors in:
+ * auth first, so nothing about the plugin leaks to an unauthenticated
+ * caller. */
+export declare function checkHandshake(headers: Headers, expect: HandshakeExpectations): HandshakeResult;
+export {};

package/dist-types/runtime/live/rooms.d.ts

@@ -0,0 +1,302 @@
+import { type PlatformFrame, type PluginFrame, type PresenceState, type Role, type RoomScope, type SpaceMember } from "./protocol";
+import { Outbox, type LinkWriter, type OutboxOptions, type OutboxStats } from "./outbox";
+type Awaitable<T> = T | Promise<T>;
+/** Why a room was discarded, as RoomHandlers.onClose hears it. */
+export type RoomCloseReason = 
+/** The platform closed the last link with 1000: no client for its idle grace. */
+"idle"
+/** The platform closed with 4410: the Game behind the scope is over. */
+ | "ended"
+/** This process is stopping (SIGTERM or RunningPlugin.close()). The
+ * checkpoint hook: clients are still connected and will get a fresh room
+ * from the next container (design §8.4). */
+ | "shutdown"
+/** Every link dropped without a planned close, and none came back within
+ * reattachGraceMs. */
+ | "lost"
+/** The room called room.close() itself. */
+ | "closed"
+/** onRoom threw, or the room fell maxPendingEvents behind. */
+ | "error";
+export interface Conn {
+    /** Unique within the room (the platform's conn id, namespaced by link). */
+    readonly id: string;
+    readonly participantId: string;
+    readonly playerId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    /** The participant's own Game; in a Space room each player has their own. */
+    readonly gameId: string;
+    /** The X-Live-Epoch of the link that carries this connection: the
+     * platform channel's incarnation. A new epoch means the platform
+     * restarted and every client is resyncing. */
+    readonly epoch: string;
+    /** The player appears offline (design §3.2): a room must not reveal them
+     * to the other members. Fixed for the connection's life: a player who
+     * toggles "Appear offline" reconnects, and the new conn carries the new
+     * value. */
+    readonly hidden: boolean;
+    readonly presence: PresenceState;
+    /** False once the connection has left. Sends to it are then dropped. */
+    readonly open: boolean;
+    send(data: unknown, opts?: SendOptions): void;
+    kick(opts: KickOptions): void;
+}
+export interface SendOptions {
+    /** Coalescing key: under backpressure a newer frame with the same key
+     * replaces an undelivered older one, here and on the platform. */
+    k?: string;
+}
+export interface BroadcastOptions extends SendOptions {
+    /** Connections to leave out (typically the sender of what is echoed). */
+    except?: Conn | readonly Conn[];
+    /** Leave spectators out. */
+    participantsOnly?: boolean;
+}
+export interface KickOptions {
+    /** Required, so "may this client come back" is always an explicit
+     * choice: 4403 keeps it out (terminal); 4900-4999 are the plugin's own
+     * and the client reconnects after them. */
+    code: number;
+    reason?: string;
+}
+export interface RoomTimer {
+    cancel(): void;
+}
+export interface Room {
+    readonly scope: RoomScope;
+    readonly gameType: string;
+    /** True once the room has been discarded; every call becomes a no-op. */
+    readonly closed: boolean;
+    /** Open connections, in join order. */
+    conns(): readonly Conn[];
+    /** Participant ids with at least one open connection (spectators excluded). */
+    participants(): string[];
+    connsOf(participantId: string): readonly Conn[];
+    /** The latest `members` frame (Space scope only), else undefined. */
+    members(): readonly SpaceMember[] | undefined;
+    broadcast(data: unknown, opts?: BroadcastOptions): void;
+    send(to: Conn | readonly Conn[], data: unknown, opts?: SendOptions): void;
+    /** Every open connection of one participant (several tabs are allowed). */
+    sendToParticipant(participantId: string, data: unknown, opts?: SendOptions): void;
+    kick(conn: Conn, opts: KickOptions): void;
+    /** Runs `fn` through the room's queue after `ms`; cancelled with the room. */
+    setTimeout(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    /** Runs `fn` through the queue every `ms`. A tick is skipped while the
+     * previous one is still queued or running, so a slow room never builds a
+     * backlog of ticks. */
+    setInterval(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    /** Runs `fn` through the room's queue as soon as it is free: the way to act
+     * on the room from outside a handler (a blob read finishing, a message
+     * from elsewhere in the process) without racing its handlers. Dropped if
+     * the room has closed. */
+    post(fn: () => Awaitable<void>): void;
+    /** Discard this room: onClose("closed"), then its links close with 1000.
+     * The platform reopens a link while clients remain, and that gets a fresh
+     * room -- so this is "restart from durable state", not "end the game"
+     * (only a Move ends a Game). */
+    close(reason?: string): void;
+}
+export interface RoomHandlers {
+    onJoin?(conn: Conn): Awaitable<void>;
+    /** `reason` is the platform's (closed, kicked, timeout, removed...), or
+     * the runtime's own: "link" when the link that carried the connection
+     * closed or was superseded, "rejoined" when the platform sent a second
+     * `join` for a conn id it had already joined (the old Conn leaves, the new
+     * one joins). Not debounced: apply a grace with room.setTimeout if a party
+     * should survive a blip. */
+    onLeave?(conn: Conn, reason: string): Awaitable<void>;
+    /** A client's Signal. `data` is untrusted: the sender is `conn`, anything
+     * inside `data` is a claim (design §7.2). In a Space room, a signal from a
+     * member removed a moment ago can still be queued ahead of their `leave`;
+     * check room.members() before letting it change shared state. */
+    onMessage?(conn: Conn, data: unknown): Awaitable<void>;
+    onPresence?(conn: Conn, state: PresenceState): Awaitable<void>;
+    /** A Move was committed on a Game in this scope. */
+    onGame?(gameId: string, revision: number): Awaitable<void>;
+    /** Space membership changed. Removed members' connections leave right after. */
+    onMembers?(members: readonly SpaceMember[]): Awaitable<void>;
+    /** The room is being discarded; the last chance to write a checkpoint. */
+    onClose?(reason: RoomCloseReason): Awaitable<void>;
+}
+export interface LiveOptions {
+    /** Called once per room, when the first link for its scope arrives. Load
+     * state here (from blobs); the runtime answers `ready` when it resolves and
+     * holds every event until then. Per-room state lives in this closure. */
+    onRoom(room: Room): Awaitable<RoomHandlers | void>;
+    /** How long a room whose links all dropped unexpectedly (a platform
+     * restart, a network cut) is kept for a new link to the same scope.
+     * Default 60 s. */
+    reattachGraceMs?: number;
+    /** Events queued behind a slow room before it is failed with 1011 (the
+     * platform then opens a fresh one). Default 4096. */
+    maxPendingEvents?: number;
+    /** How long a discarded room gets to finish the handler in flight, drain
+     * and run onClose, whatever the reason (shutdown included); also how long
+     * a successor room for the same scope waits for that before loading
+     * anyway. A handler that never resolves can delay a scope by this much,
+     * never brick it. Default 5 s. */
+    shutdownTimeoutMs?: number;
+    /** A handler still running after this long is reported through onError
+     * (once per call) as a stall. It is not cancelled: JS can't. Default 10 s;
+     * 0 turns the watchdog off. */
+    stallWarningMs?: number;
+    /** Plugin -> platform backpressure, per link. */
+    outbox?: OutboxOptions;
+    /** A handler threw or stalled. Default: log it. The room carries on. An
+     * onError that throws is itself caught and logged. */
+    onError?(error: unknown, where: {
+        scope: string;
+        handler: string;
+    }): void;
+}
+export interface LinkInfo {
+    scope: RoomScope;
+    epoch: string;
+}
+/** The socket side of a link, supplied by server.ts or the harness. */
+export interface LinkTransport extends LinkWriter {
+    close(code: number, reason: string): void;
+}
+/** What the transport calls back into. */
+export interface LinkHandle {
+    receive(text: string): void;
+    /** The socket closed (either side). Idempotent. */
+    closed(code: number): void;
+}
+export interface RoomHostOptions {
+    gameType: string;
+    live: LiveOptions;
+    log?: Pick<Console, "log" | "error">;
+}
+declare class Link {
+    readonly serial: number;
+    readonly info: LinkInfo;
+    readonly transport: LinkTransport;
+    readonly outbox: Outbox;
+    readonly conns: Map<string, ConnImpl>;
+    ready: boolean;
+    detached: boolean;
+    constructor(serial: number, info: LinkInfo, transport: LinkTransport, outbox: OutboxOptions | undefined);
+    write(frame: PluginFrame, key?: string): void;
+}
+declare class ConnImpl implements Conn {
+    readonly link: Link;
+    readonly wire: string;
+    readonly participantId: string;
+    readonly playerId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly gameId: string;
+    readonly hidden: boolean;
+    private readonly room;
+    open: boolean;
+    presence: PresenceState;
+    constructor(link: Link, wire: string, participantId: string, playerId: string, displayName: string, role: Role, gameId: string, hidden: boolean, presence: PresenceState, room: RoomImpl);
+    get epoch(): string;
+    get id(): string;
+    send(data: unknown, opts?: SendOptions): void;
+    kick(opts: KickOptions): void;
+}
+declare class RoomImpl implements Room {
+    readonly scope: RoomScope;
+    readonly gameType: string;
+    private readonly host;
+    private readonly live;
+    readonly links: Set<Link>;
+    private readonly order;
+    private handlers;
+    private latestMembers;
+    private readonly queue;
+    private processing;
+    private loaded;
+    private disposing;
+    private readonly timers;
+    private graceTimer;
+    private idleWaiters;
+    private loading;
+    closed: boolean;
+    constructor(scope: RoomScope, gameType: string, host: RoomHost, live: LiveOptions);
+    load(previous: Promise<void> | undefined): Promise<void>;
+    private runLoad;
+    linkWithEpoch(epoch: string): Link | undefined;
+    markReady(link: Link): void;
+    attach(link: Link): void;
+    /** A newer link with the same epoch replaced `old` (PROTOCOL.md §5.4): the
+     * platform has abandoned it, so close it now and let its conns leave. */
+    supersede(old: Link): void;
+    /** A link's socket went away. Its connections leave through the queue. */
+    detach(link: Link, code: number): void;
+    /** Discard the room: stop timers, let pending events finish (unless
+     * failing), run onClose, close any remaining links. Idempotent.
+     *
+     * Everything after the timers stop is bounded by closeTimeout(): a
+     * handler or onClose that never resolves delays the links' close by that
+     * much, never forever. A failing room ("error") closes its links first,
+     * at once, so the platform can open a fresh room while this one winds
+     * down. */
+    dispose(reason: RoomCloseReason, code?: number, closeReason?: string, opts?: {
+        runOnClose?: boolean;
+        drainFirst?: boolean;
+    }): Promise<void>;
+    private closeLinks;
+    closeTimeout(): number;
+    enqueue(name: string, run: () => Awaitable<void>): void;
+    private drain;
+    /** Resolves when nothing is queued or running. */
+    whenIdle(): Promise<void>;
+    isIdle(): boolean;
+    /** Loaded (or discarded) with nothing queued or running: for the harness. */
+    isSettled(): boolean;
+    private call;
+    onFrame(link: Link, frame: PlatformFrame): void;
+    private removeConn;
+    conns(): readonly Conn[];
+    participants(): string[];
+    connsOf(participantId: string): readonly Conn[];
+    members(): readonly SpaceMember[] | undefined;
+    broadcast(data: unknown, opts?: BroadcastOptions): void;
+    send(to: Conn | readonly Conn[], data: unknown, opts?: SendOptions): void;
+    sendToParticipant(participantId: string, data: unknown, opts?: SendOptions): void;
+    kick(conn: Conn, opts: KickOptions): void;
+    setTimeout(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    setInterval(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    close(reason?: string): void;
+    post(fn: () => Awaitable<void>): void;
+    private timer;
+    private assertReady;
+    private write;
+    outboxStats(): OutboxStats[];
+}
+/** Every room this process hosts. One per servePlugin({live}). */
+export declare class RoomHost {
+    private readonly options;
+    private readonly rooms;
+    /** Rooms being discarded, by scope, so a successor waits for onClose. */
+    private readonly disposing;
+    private serial;
+    private shuttingDown;
+    private readonly log;
+    constructor(options: RoomHostOptions);
+    get gameType(): string;
+    /** A new link. Returns the callbacks its socket drives. */
+    attach(info: LinkInfo, transport: LinkTransport): LinkHandle;
+    /** Rooms currently hosted (not ones being discarded). */
+    list(): Room[];
+    room(scopeKey: string): Room | undefined;
+    /** Every room's outbox counters, for metrics and tests. */
+    outboxStats(scopeKey: string): OutboxStats[];
+    /** Resolves once every room has loaded and has nothing queued or
+     * running, and every discarded room has finished its onClose. For tests:
+     * real code never needs to wait for a room. */
+    settled(): Promise<void>;
+    /** SIGTERM: every room checkpoints (onClose "shutdown", bounded), then its
+     * links close with 1012 so the platform reopens them on the next task. */
+    shutdown(): Promise<void>;
+    /** @internal A room is being discarded: a new link for its scope gets a
+     * fresh room, which waits for `done` before loading. */
+    forget(room: RoomImpl, done: Promise<void>): void;
+    /** @internal */
+    reportError(error: unknown, scope: string, handler: string): void;
+}
+export {};