@anweather/game-plugin-ssdk 1.16.0 → 1.18.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/blobClient.d.ts

@@ -1,10 +1,25 @@
-/** `save:{id}`, `player:{id}` or `world:{uuid}` -- see the model's doc. */
-export type BlobOwnerKey = `save:${string}` | `player:${string}` | `world:${string}`;
+/** `save:{id}`, `player:{id}`, `world:{uuid}` or `space:{spaceId}` -- see
+ * the model's doc. A `space:` owner can only be written once the Space
+ * exists (and is this game type's); check current membership first, see
+ * spaceClient.ts. */
+export type BlobOwnerKey = `save:${string}` | `player:${string}` | `world:${string}` | `space:${string}`;
 export declare const blobOwner: {
     save: (saveFileId: string) => BlobOwnerKey;
     player: (participantId: string) => BlobOwnerKey;
     world: (worldId: string) => BlobOwnerKey;
+    space: (spaceId: string) => BlobOwnerKey;
 };
+/** One owner holding blobs, as ListBlobOwners reports it. */
+export interface BlobOwnerSummary {
+    ownerKey: string;
+    blobCount: number;
+    totalBytes: number;
+}
+export interface BlobOwnerPage {
+    owners: BlobOwnerSummary[];
+    /** Pass as `after` for the next page; absent on the last one. */
+    nextToken?: string;
+}
 export interface BlobClientOptions {
     /** The platform's base URL, e.g. http://platform:8080. */
     platformUrl: string;
@@ -70,8 +85,18 @@ export interface BlobClient {
         totalBytes: number;
         quotaBytes: number;
     }>;
+    /** Owners of this game type holding blobs, by key prefix ("world:",
+     * "space", or "" for all), sorted by key, one page (default 500, at
+     * most 1000) at a time. See allBlobOwners for every page. */
+    listOwners(prefix?: string, page?: {
+        after?: string;
+        limit?: number;
+    }): Promise<BlobOwnerPage>;
 }
 export declare function createBlobClient(options: BlobClientOptions): BlobClient;
+/** Every owner with this prefix, following nextToken page by page -- e.g.
+ * a backfill's `for await (const o of allBlobOwners(blobs, "world:"))`. */
+export declare function allBlobOwners(client: BlobClient, prefix?: string, pageSize?: number): AsyncGenerator<BlobOwnerSummary>;
 /** Read `key`, apply `change` to its value (undefined when absent), and
  * write the result conditional on the version read -- re-reading and
  * re-applying on a VersionConflict, up to `maxAttempts` times. `change`

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

@@ -8,5 +8,18 @@ export type { RegistrationOptions, RegistrationLoop } from "./registration";
 export { runConformance, assertConformance } from "./conformance";
 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 { createBlobClient, casUpdate, blobOwner, allBlobOwners, BlobStoreError, isVersionConflict } from "./blobClient";
+export type { BlobClient, BlobClientOptions, BlobOwnerKey, Blob, BlobItem, BlobInfo, BlobWrite, BlobErrorType, BlobOwnerSummary, BlobOwnerPage, } 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";
+export { createSpaceClient, createMembershipGuard, isAlreadyASpace, SpaceApiError, NotASpaceMemberError, FakeSpaceClient, MAX_MEMBERSHIP_AGE_MS, } from "./spaceClient";
+export type { SpaceClient, SpaceClientOptions, PluginSpace, PluginSpaceMember, SpaceImport, SpaceImportMember, SpaceImportResult, SpaceErrorType, SpaceCounts, SpaceRole, SpaceMemberStatus, MembershipGuard, MembershipGuardOptions, } from "./spaceClient";

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 {};