@anweather/game-plugin-ssdk 1.16.0 → 1.17.0

package/dist-es/runtime/auth.js

@@ -0,0 +1,5 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+const digest = (s) => createHash("sha256").update(s, "utf8").digest();
+export function bearerMatches(header, token) {
+    return timingSafeEqual(digest(header ?? ""), digest(`Bearer ${token}`));
+}

package/dist-es/runtime/conformance.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { PLUGIN_PROTOCOL_VERSION } from "./version";
+import { runLiveConformance } from "./live/conformance";
 function participantIds(n) {
     return Array.from({ length: n }, (_, i) => `00000000-0000-4000-8000-${String(i + 1).padStart(12, "0")}`);
 }
@@ -79,6 +80,11 @@ export async function runConformance(service, context, options = {}) {
             expect(out.payload !== undefined && out.payload !== null, "payload is missing");
         });
     }
+    if (options.live) {
+        const live = await runLiveConformance(options.live, { gameType: metadata.id, ...options.liveOptions });
+        report.passed.push(...live.passed);
+        report.failed.push(...live.failed);
+    }
     return report;
 }
 export async function assertConformance(service, context, options = {}) {

package/dist-es/runtime/index.js

@@ -5,3 +5,8 @@ export { createRegistrationLoop } from "./registration";
 export { runConformance, assertConformance } from "./conformance";
 export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";
 export { createBlobClient, casUpdate, blobOwner, BlobStoreError, isVersionConflict } from "./blobClient";
+export { attachLive } from "./live/server";
+export { createLiveHarness } from "./live/harness";
+export { loadRoomCheckpoint } from "./live/checkpoint";
+export { runLiveConformance, assertLiveConformance } from "./live/conformance";
+export { LIVE_PROTOCOL_VERSION, LIVE_PATH, LinkCloseCode, MAX_LINK_FRAME_BYTES } from "./live/protocol";

package/dist-es/runtime/live/checkpoint.js

@@ -0,0 +1,28 @@
+import { isVersionConflict } from "../blobClient";
+export async function loadRoomCheckpoint(client, owner, key, opts = {}) {
+    const blob = await client.get(owner, key);
+    let value = blob.version === 0 ? undefined : blob.value;
+    let version = blob.version;
+    return {
+        get value() {
+            return value;
+        },
+        get version() {
+            return version;
+        },
+        async save(next) {
+            try {
+                const written = await client.put(owner, key, next, version);
+                version = written.version;
+                value = next;
+                return true;
+            }
+            catch (e) {
+                if (!isVersionConflict(e))
+                    throw e;
+                opts.room?.close("another room took over this scope");
+                return false;
+            }
+        },
+    };
+}

package/dist-es/runtime/live/conformance.js

@@ -0,0 +1,210 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { LIVE_PATH, LIVE_PROTOCOL_VERSION, LinkCloseCode, encodeFrame } from "./protocol";
+import { attachLive } from "./server";
+function connect(url, headers, onSend = () => undefined) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url, { headers });
+        const frames = [];
+        const listeners = new Set();
+        let open = false;
+        const closed = new Promise((r) => ws.once("close", (code) => { open = false; r(code); }));
+        ws.on("message", (data) => {
+            try {
+                frames.push(JSON.parse(data.toString()));
+            }
+            catch {
+                frames.push(data.toString());
+            }
+            for (const l of listeners)
+                l();
+        });
+        ws.once("unexpected-response", (_req, res) => {
+            resolve({ status: res.statusCode ?? 0 });
+            ws.terminate();
+        });
+        ws.once("error", (e) => { if (!open)
+            reject(e); });
+        ws.once("open", () => {
+            open = true;
+            resolve({
+                ws,
+                frames,
+                closed,
+                isOpen: () => open,
+                send: (frame) => {
+                    onSend();
+                    ws.send(typeof frame === "string" ? frame : encodeFrame(frame));
+                },
+                waitFor: (pred, ms) => new Promise((ok, fail) => {
+                    const check = () => {
+                        if (frames.some(pred)) {
+                            listeners.delete(check);
+                            clearTimeout(timer);
+                            ok();
+                        }
+                    };
+                    const timer = setTimeout(() => {
+                        listeners.delete(check);
+                        fail(new Error(`nothing matching within ${ms} ms; got ${JSON.stringify(frames).slice(0, 200)}`));
+                    }, ms);
+                    listeners.add(check);
+                    check();
+                }),
+            });
+        });
+    });
+}
+export async function runLiveConformance(live, options = {}) {
+    const report = { passed: [], failed: [] };
+    const gameType = options.gameType ?? "conformance";
+    const scope = options.scope ?? `game:${randomUUID()}`;
+    const timeout = options.timeoutMs ?? 5_000;
+    const token = randomUUID();
+    const errors = [];
+    const quiet = { log: () => undefined, error: () => undefined };
+    const server = createServer((_req, res) => res.writeHead(404).end());
+    await new Promise((r) => server.listen(0, r));
+    const liveServer = attachLive(server, {
+        gameType,
+        authToken: token,
+        log: quiet,
+        live: {
+            ...live,
+            shutdownTimeoutMs: Math.min(live.shutdownTimeoutMs ?? timeout, timeout),
+            onError: (e, where) => {
+                errors.push(`${where.handler} threw: ${e?.message ?? String(e)}`);
+                live.onError?.(e, where);
+            },
+        },
+    });
+    const url = `ws://127.0.0.1:${server.address().port}${LIVE_PATH}`;
+    const headers = (auth, scopeKey = scope) => ({
+        ...(auth === undefined ? {} : { "X-Plugin-Auth": auth }),
+        "X-Live-Scope": scopeKey,
+        "X-Live-Epoch": randomUUID(),
+        "X-Game-Type": gameType,
+        "X-Live-Protocol": String(LIVE_PROTOCOL_VERSION),
+    });
+    const check = async (name, body) => {
+        errors.length = 0;
+        try {
+            await body();
+            if (errors.length > 0)
+                throw new Error(errors.join("; "));
+            report.passed.push(name);
+        }
+        catch (e) {
+            report.failed.push({ check: name, reason: e.message });
+        }
+    };
+    const expect = (cond, reason) => {
+        if (!cond)
+            throw new Error(reason);
+    };
+    let sent = 0;
+    const settle = async () => {
+        const deadline = Date.now() + timeout;
+        while (liveServer.framesReceived() < sent) {
+            if (Date.now() > deadline)
+                throw new Error(`the plugin read ${liveServer.framesReceived()} of ${sent} frames within ${timeout} ms`);
+            await new Promise((r) => setTimeout(r, 5));
+        }
+        await Promise.race([
+            liveServer.settled(),
+            new Promise((_, fail) => setTimeout(() => fail(new Error(`room did not settle within ${timeout} ms`)), timeout)),
+        ]);
+    };
+    const links = [];
+    try {
+        await check("live: a bad or missing X-Plugin-Auth is refused with 401", async () => {
+            const bad = await connect(url, headers("Bearer not-the-token"));
+            expect("status" in bad && bad.status === 401, `a bad token got ${JSON.stringify("status" in bad ? bad.status : "an open link")}`);
+            const none = await connect(url, headers(undefined));
+            expect("status" in none && none.status === 401, `no token got ${JSON.stringify("status" in none ? none.status : "an open link")}`);
+        });
+        let link;
+        await check("live: the room answers ready", async () => {
+            const opened = await connect(url, headers(`Bearer ${token}`), () => void sent++);
+            expect(!("status" in opened), `the upgrade was refused with ${"status" in opened ? opened.status : ""}`);
+            link = opened;
+            links.push(link);
+            await link.waitFor((f) => f?.t === "ready", timeout);
+        });
+        if (!link)
+            return report;
+        const l = link;
+        await check("live: unknown and malformed frames are ignored", async () => {
+            l.send({ t: "from-a-future-version", x: 1 });
+            l.send("not json at all");
+            l.send({ t: "join" });
+            l.send({ t: "sig", conn: "never-joined", participantId: "x", d: {} });
+            await settle();
+            l.send(join("probe"));
+            l.send({ t: "leave", conn: "probe", reason: "closed" });
+            await settle();
+            expect(l.isOpen(), "the link was closed");
+            expect(liveServer.room(scope) !== undefined, "the room is gone");
+        });
+        await check("live: survives a join/leave storm", async () => {
+            const n = options.stormSize ?? 100;
+            for (let i = 0; i < n; i++) {
+                l.send(join(`s${i}`, i % 7 === 0 ? "SPECTATOR" : "PARTICIPANT"));
+                if (i % 3 === 0)
+                    l.send({ t: "sig", conn: `s${i}`, participantId: `p-s${i}`, d: options.signal ?? {} });
+                if (i % 5 === 0)
+                    l.send({ t: "presence", conn: `s${i}`, state: "AWAY" });
+                if (i >= 2)
+                    l.send({ t: "leave", conn: `s${i - 2}`, reason: i % 2 ? "closed" : "timeout" });
+            }
+            l.send({ t: "leave", conn: `s${n - 2}`, reason: "closed" });
+            l.send({ t: "leave", conn: `s${n - 1}`, reason: "closed" });
+            l.send({ t: "game", gameId: scope.slice(scope.indexOf(":") + 1), revision: 1 });
+            await settle();
+            expect(l.isOpen(), "the link was closed");
+            const room = liveServer.room(scope);
+            expect(room !== undefined, "the room is gone");
+            expect(room.conns().length === 0, `${room.conns().length} connections still in the room after every one left`);
+        });
+        await check("live: a second link for the same scope is the same room", async () => {
+            const second = await connect(url, headers(`Bearer ${token}`), () => void sent++);
+            expect(!("status" in second), "the second link was refused");
+            links.push(second);
+            await second.waitFor((f) => f?.t === "ready", timeout);
+            expect(liveServer.rooms().length === 1, `${liveServer.rooms().length} rooms for one scope`);
+        });
+        await check("live: shutdown closes every link with 1012", async () => {
+            await liveServer.close();
+            const codes = await Promise.all(links.map((x) => x.closed));
+            expect(codes.every((c) => c === LinkCloseCode.RESTART), `closed with ${codes.join(", ")}`);
+        });
+    }
+    finally {
+        await liveServer.close();
+        for (const x of links)
+            x.ws.terminate();
+        await new Promise((r) => server.close(() => r()));
+    }
+    return report;
+}
+function join(conn, role = "PARTICIPANT") {
+    return {
+        t: "join",
+        conn,
+        participantId: `p-${conn}`,
+        playerId: `u-${conn}`,
+        displayName: conn,
+        role,
+        gameId: "conformance",
+        hidden: false,
+        state: "ACTIVE",
+    };
+}
+export async function assertLiveConformance(live, options = {}) {
+    const report = await runLiveConformance(live, options);
+    if (report.failed.length > 0) {
+        throw new Error(`live room contract violations:\n` + report.failed.map((f) => `  - ${f.check}: ${f.reason}`).join("\n"));
+    }
+    return report;
+}

package/dist-es/runtime/live/harness.js

@@ -0,0 +1,141 @@
+import { LinkCloseCode, decodePluginFrame, encodeFrame, parseScope, } from "./protocol";
+import { RoomHost } from "./rooms";
+export function createLiveHarness(live, opts = {}) {
+    const host = new RoomHost({ gameType: opts.gameType ?? "harness", live, log: opts.log });
+    let epochs = 0;
+    const openLink = (scopeText, linkOpts = {}) => {
+        const scope = parseScope(scopeText);
+        if (!scope)
+            throw new Error(`not a scope: ${scopeText} (want game:{id} or space:{id})`);
+        const clients = new Map();
+        let nextConn = 0;
+        let ready = false;
+        let closedByPlugin;
+        let closed = false;
+        const frames = [];
+        const handle = host.attach({ scope, epoch: linkOpts.epoch ?? `epoch-${++epochs}` }, {
+            write: (text, done) => {
+                const decoded = decodePluginFrame(text);
+                if (!decoded.ok)
+                    throw new Error(`the runtime wrote a frame the platform cannot read: ${text}`);
+                const frame = decoded.frame;
+                frames.push(frame);
+                if (frame.t === "ready")
+                    ready = true;
+                else if (frame.t === "send") {
+                    const targets = frame.to === "all" ? [...clients.values()] : frame.to.map((c) => clients.get(c)).filter((c) => !!c);
+                    for (const c of targets) {
+                        if (!c.open)
+                            continue;
+                        const message = { from: "host", d: JSON.parse(JSON.stringify(frame.d)) };
+                        if (frame.k !== undefined)
+                            message.k = frame.k;
+                        c.received.push(message);
+                    }
+                }
+                else if (frame.t === "kick") {
+                    const c = clients.get(frame.conn);
+                    if (c?.open) {
+                        c.open = false;
+                        c.kicked = { code: frame.code ?? 4403, reason: frame.reason };
+                        clients.delete(c.conn);
+                        queueMicrotask(() => deliver({ t: "leave", conn: c.conn, reason: "kicked" }));
+                    }
+                }
+                queueMicrotask(done);
+            },
+            close: (code, reason) => {
+                if (closed)
+                    return;
+                closed = true;
+                closedByPlugin = { code, reason };
+                for (const c of clients.values())
+                    c.open = false;
+                queueMicrotask(() => handle.closed(code));
+            },
+        });
+        const deliver = (frame) => {
+            if (closed)
+                return;
+            handle.receive(encodeFrame(frame));
+        };
+        return {
+            scope: scope.key,
+            get ready() {
+                return ready;
+            },
+            get closedByPlugin() {
+                return closedByPlugin;
+            },
+            frames,
+            join(spec) {
+                if (closed)
+                    throw new Error("link is closed");
+                const conn = spec.conn ?? `c${++nextConn}`;
+                const state = { conn, participantId: spec.participantId, received: [], kicked: undefined, open: true };
+                clients.set(conn, state);
+                deliver({
+                    t: "join",
+                    conn,
+                    participantId: spec.participantId,
+                    playerId: spec.playerId ?? `player-${spec.participantId}`,
+                    displayName: spec.displayName ?? spec.participantId,
+                    role: spec.role ?? "PARTICIPANT",
+                    gameId: spec.gameId ?? (scope.kind === "game" ? scope.id : `game-of-${spec.participantId}`),
+                    hidden: spec.hidden ?? false,
+                    state: spec.state ?? "ACTIVE",
+                });
+                return {
+                    conn,
+                    participantId: spec.participantId,
+                    get received() {
+                        return state.received;
+                    },
+                    get kicked() {
+                        return state.kicked;
+                    },
+                    get open() {
+                        return state.open;
+                    },
+                    signal(d) {
+                        if (!state.open)
+                            return;
+                        deliver({ t: "sig", conn, participantId: spec.participantId, d });
+                    },
+                    presence(s) {
+                        if (state.open)
+                            deliver({ t: "presence", conn, state: s });
+                    },
+                    leave(reason = "closed") {
+                        if (!state.open)
+                            return;
+                        state.open = false;
+                        clients.delete(conn);
+                        deliver({ t: "leave", conn, reason });
+                    },
+                };
+            },
+            game: (gameId, revision) => deliver({ t: "game", gameId, revision }),
+            members: (members) => deliver({ t: "members", members }),
+            raw: (text) => {
+                if (!closed)
+                    handle.receive(text);
+            },
+            close: (code = LinkCloseCode.NORMAL) => {
+                if (closed)
+                    return;
+                closed = true;
+                for (const c of clients.values())
+                    c.open = false;
+                handle.closed(code);
+            },
+        };
+    };
+    return {
+        openLink,
+        settled: () => host.settled(),
+        room: (scope) => host.room(scope),
+        rooms: () => host.list(),
+        shutdown: () => host.shutdown(),
+    };
+}

package/dist-es/runtime/live/outbox.js

@@ -0,0 +1,68 @@
+export const DEFAULT_HIGH_WATER_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_QUEUED_FRAMES = 1024;
+export class Outbox {
+    writer;
+    highWater;
+    maxQueued;
+    queue = [];
+    inflight = 0;
+    pumping = false;
+    closed = false;
+    stats = { queued: 0, coalesced: 0, dropped: 0 };
+    constructor(writer, options = {}) {
+        this.writer = writer;
+        this.highWater = options.highWaterBytes ?? DEFAULT_HIGH_WATER_BYTES;
+        this.maxQueued = options.maxQueuedFrames ?? DEFAULT_MAX_QUEUED_FRAMES;
+    }
+    push(text, opts) {
+        if (this.closed)
+            return;
+        const entry = { text, bytes: Buffer.byteLength(text, "utf8"), key: opts.key, droppable: opts.droppable };
+        if (entry.key !== undefined) {
+            const i = this.queue.findIndex((e) => e.key === entry.key);
+            if (i >= 0) {
+                this.queue.splice(i, 1);
+                this.stats.coalesced++;
+            }
+        }
+        this.queue.push(entry);
+        if (this.queue.length > this.maxQueued) {
+            const victim = this.queue.findIndex((e) => e.droppable);
+            if (victim >= 0) {
+                this.queue.splice(victim, 1);
+                this.stats.dropped++;
+            }
+        }
+        this.pump();
+    }
+    close() {
+        this.closed = true;
+        this.queue.length = 0;
+        this.stats.queued = 0;
+    }
+    pump() {
+        if (this.pumping)
+            return;
+        this.pumping = true;
+        try {
+            while (!this.closed && this.queue.length > 0 && this.inflight < this.highWater) {
+                const entry = this.queue.shift();
+                this.inflight += entry.bytes;
+                let finished = false;
+                this.writer.write(entry.text, () => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    this.inflight -= entry.bytes;
+                    this.pump();
+                });
+            }
+        }
+        finally {
+            this.pumping = false;
+            this.stats.queued = this.queue.length;
+        }
+        if (!this.closed && this.queue.length > 0 && this.inflight < this.highWater)
+            this.pump();
+    }
+}