@anweather/game-plugin-ssdk 1.16.0 → 1.17.0

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

@@ -0,0 +1,575 @@
+import { LinkCloseCode, MAX_KICK_REASON, MAX_LINK_FRAME_BYTES, byteLength, decodePlatformFrame, encodeFrame, isKickCode, } from "./protocol";
+import { Outbox } from "./outbox";
+const DEFAULT_REATTACH_GRACE_MS = 60_000;
+const DEFAULT_MAX_PENDING = 4096;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
+const DEFAULT_STALL_WARNING_MS = 10_000;
+const TIMED_OUT = Symbol("timed out");
+async function within(p, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            p,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(TIMED_OUT), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+class Link {
+    serial;
+    info;
+    transport;
+    outbox;
+    conns = new Map();
+    ready = false;
+    detached = false;
+    constructor(serial, info, transport, outbox) {
+        this.serial = serial;
+        this.info = info;
+        this.transport = transport;
+        this.outbox = new Outbox(transport, outbox);
+    }
+    write(frame, key) {
+        this.outbox.push(encodeFrame(frame), { key, droppable: frame.t === "send" });
+    }
+}
+class ConnImpl {
+    link;
+    wire;
+    participantId;
+    playerId;
+    displayName;
+    role;
+    gameId;
+    hidden;
+    room;
+    open = true;
+    presence;
+    constructor(link, wire, participantId, playerId, displayName, role, gameId, hidden, presence, room) {
+        this.link = link;
+        this.wire = wire;
+        this.participantId = participantId;
+        this.playerId = playerId;
+        this.displayName = displayName;
+        this.role = role;
+        this.gameId = gameId;
+        this.hidden = hidden;
+        this.room = room;
+        this.presence = presence;
+    }
+    get epoch() {
+        return this.link.info.epoch;
+    }
+    get id() {
+        return `${this.link.serial}.${this.wire}`;
+    }
+    send(data, opts) {
+        this.room.send(this, data, opts);
+    }
+    kick(opts) {
+        this.room.kick(this, opts);
+    }
+}
+class RoomImpl {
+    scope;
+    gameType;
+    host;
+    live;
+    links = new Set();
+    order = [];
+    handlers = {};
+    latestMembers;
+    queue = [];
+    processing = false;
+    loaded = false;
+    disposing;
+    timers = new Set();
+    graceTimer;
+    idleWaiters = [];
+    loading;
+    closed = false;
+    constructor(scope, gameType, host, live) {
+        this.scope = scope;
+        this.gameType = gameType;
+        this.host = host;
+        this.live = live;
+    }
+    load(previous) {
+        this.loading = this.runLoad(previous);
+        return this.loading;
+    }
+    async runLoad(previous) {
+        if (previous) {
+            const waited = await within(previous.catch(() => undefined), this.closeTimeout());
+            if (waited === TIMED_OUT) {
+                this.host.reportError(new Error(`previous room still closing after ${this.closeTimeout()} ms; loading anyway`), this.scope.key, "onRoom");
+            }
+        }
+        try {
+            this.handlers = (await this.live.onRoom(this)) ?? {};
+        }
+        catch (e) {
+            this.host.reportError(e, this.scope.key, "onRoom");
+            void this.dispose("error", LinkCloseCode.INTERNAL_ERROR, "room setup failed", { runOnClose: false, drainFirst: false });
+            return;
+        }
+        this.loaded = true;
+        if (this.closed)
+            return;
+        for (const link of this.links)
+            this.markReady(link);
+        void this.drain();
+    }
+    linkWithEpoch(epoch) {
+        for (const l of this.links)
+            if (l.info.epoch === epoch)
+                return l;
+        return undefined;
+    }
+    markReady(link) {
+        if (link.ready || link.detached)
+            return;
+        link.ready = true;
+        link.write({ t: "ready" });
+    }
+    attach(link) {
+        if (this.graceTimer) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = undefined;
+        }
+        this.links.add(link);
+        if (this.loaded)
+            this.markReady(link);
+    }
+    supersede(old) {
+        if (old.detached)
+            return;
+        old.transport.close(LinkCloseCode.SUPERSEDED, "superseded by a newer link");
+        this.detach(old, LinkCloseCode.SUPERSEDED);
+    }
+    detach(link, code) {
+        if (link.detached)
+            return;
+        link.detached = true;
+        link.outbox.close();
+        this.enqueue("onLeave", async () => {
+            for (const conn of [...link.conns.values()])
+                await this.removeConn(conn, "link");
+        });
+        this.links.delete(link);
+        if (this.links.size > 0 || this.closed)
+            return;
+        if (code === LinkCloseCode.NORMAL)
+            this.dispose("idle");
+        else if (code === LinkCloseCode.GONE)
+            this.dispose("ended");
+        else {
+            const grace = this.live.reattachGraceMs ?? DEFAULT_REATTACH_GRACE_MS;
+            this.graceTimer = setTimeout(() => {
+                this.graceTimer = undefined;
+                if (this.links.size === 0)
+                    this.dispose("lost");
+            }, grace);
+            this.graceTimer.unref?.();
+        }
+    }
+    dispose(reason, code = LinkCloseCode.NORMAL, closeReason = reason, opts = {}) {
+        if (this.disposing)
+            return this.disposing;
+        this.closed = true;
+        for (const t of this.timers)
+            clearTimeout(t);
+        this.timers.clear();
+        if (this.graceTimer)
+            clearTimeout(this.graceTimer);
+        const drainFirst = (opts.drainFirst ?? true) && this.loaded;
+        if (!drainFirst)
+            this.queue.length = 0;
+        if (reason === "error")
+            this.closeLinks(code, closeReason);
+        const limit = this.closeTimeout();
+        this.disposing = (async () => {
+            const settled = await within((async () => {
+                if (this.loading)
+                    await this.loading;
+                await this.whenIdle();
+            })(), limit);
+            if (settled === TIMED_OUT) {
+                this.host.reportError(new Error(`a handler was still running ${limit} ms after the room began closing (${reason}); onClose skipped`), this.scope.key, "onClose");
+            }
+            else if ((opts.runOnClose ?? true) && this.loaded) {
+                const closed = await within(this.call("onClose", () => this.handlers.onClose?.(reason)), limit);
+                if (closed === TIMED_OUT) {
+                    this.host.reportError(new Error(`onClose(${reason}) did not finish within ${limit} ms`), this.scope.key, "onClose");
+                }
+            }
+            this.closeLinks(code, closeReason);
+        })();
+        this.host.forget(this, this.disposing);
+        return this.disposing;
+    }
+    closeLinks(code, reason) {
+        for (const link of this.links) {
+            link.detached = true;
+            link.outbox.close();
+            link.transport.close(code, reason);
+        }
+        this.links.clear();
+    }
+    closeTimeout() {
+        return this.live.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    }
+    enqueue(name, run) {
+        if (this.closed)
+            return;
+        this.queue.push({ name, run });
+        const max = this.live.maxPendingEvents ?? DEFAULT_MAX_PENDING;
+        if (this.queue.length > max) {
+            this.host.reportError(new Error(`room fell ${max} events behind`), this.scope.key, name);
+            void this.dispose("error", LinkCloseCode.INTERNAL_ERROR, "room overloaded", { drainFirst: false });
+            return;
+        }
+        if (this.loaded)
+            void this.drain();
+    }
+    async drain() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        try {
+            while (this.queue.length > 0) {
+                const event = this.queue.shift();
+                await this.call(event.name, event.run);
+            }
+        }
+        finally {
+            this.processing = false;
+            for (const w of this.idleWaiters.splice(0))
+                w();
+        }
+    }
+    whenIdle() {
+        if (this.isIdle())
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.push(resolve)).then(() => this.whenIdle());
+    }
+    isIdle() {
+        return !this.processing && this.queue.length === 0;
+    }
+    isSettled() {
+        return this.closed || (this.loaded && this.isIdle());
+    }
+    async call(handler, fn) {
+        const stallMs = this.live.stallWarningMs ?? DEFAULT_STALL_WARNING_MS;
+        const started = Date.now();
+        const watchdog = stallMs > 0
+            ? setTimeout(() => {
+                this.host.reportError(new Error(`${handler} has been running for ${Date.now() - started} ms; the room's queue is stalled behind it`), this.scope.key, handler);
+            }, stallMs)
+            : undefined;
+        watchdog?.unref?.();
+        try {
+            await fn();
+        }
+        catch (e) {
+            this.host.reportError(e, this.scope.key, handler);
+        }
+        finally {
+            if (watchdog)
+                clearTimeout(watchdog);
+        }
+    }
+    onFrame(link, frame) {
+        switch (frame.t) {
+            case "join":
+                this.enqueue("onJoin", async () => {
+                    if (link.detached)
+                        return;
+                    const prior = link.conns.get(frame.conn);
+                    if (prior)
+                        await this.removeConn(prior, "rejoined");
+                    const conn = new ConnImpl(link, frame.conn, frame.participantId, frame.playerId, frame.displayName, frame.role, frame.gameId, frame.hidden, frame.state, this);
+                    link.conns.set(frame.conn, conn);
+                    this.order.push(conn);
+                    await this.handlers.onJoin?.(conn);
+                });
+                return;
+            case "leave":
+                this.enqueue("onLeave", async () => {
+                    const conn = link.conns.get(frame.conn);
+                    if (conn)
+                        await this.removeConn(conn, frame.reason);
+                });
+                return;
+            case "sig":
+                this.enqueue("onMessage", async () => {
+                    const conn = link.conns.get(frame.conn);
+                    if (conn)
+                        await this.handlers.onMessage?.(conn, frame.d);
+                });
+                return;
+            case "presence":
+                this.enqueue("onPresence", async () => {
+                    const conn = link.conns.get(frame.conn);
+                    if (!conn || conn.presence === frame.state)
+                        return;
+                    conn.presence = frame.state;
+                    await this.handlers.onPresence?.(conn, frame.state);
+                });
+                return;
+            case "game":
+                this.enqueue("onGame", () => this.handlers.onGame?.(frame.gameId, frame.revision));
+                return;
+            case "members":
+                this.enqueue("onMembers", async () => {
+                    this.latestMembers = frame.members;
+                    await this.handlers.onMembers?.(frame.members);
+                });
+                return;
+        }
+    }
+    async removeConn(conn, reason) {
+        if (!conn.open)
+            return;
+        conn.open = false;
+        conn.link.conns.delete(conn.wire);
+        const i = this.order.indexOf(conn);
+        if (i >= 0)
+            this.order.splice(i, 1);
+        await this.handlers.onLeave?.(conn, reason);
+    }
+    conns() {
+        return [...this.order];
+    }
+    participants() {
+        const ids = new Set();
+        for (const c of this.order)
+            if (c.role === "PARTICIPANT")
+                ids.add(c.participantId);
+        return [...ids];
+    }
+    connsOf(participantId) {
+        return this.order.filter((c) => c.participantId === participantId);
+    }
+    members() {
+        return this.latestMembers;
+    }
+    broadcast(data, opts = {}) {
+        if (this.closed)
+            return;
+        const except = new Set(opts.except === undefined ? [] : Array.isArray(opts.except) ? opts.except : [opts.except]);
+        const everyone = except.size === 0 && !opts.participantsOnly;
+        for (const link of this.links) {
+            if (everyone) {
+                this.write(link, "all", data, opts.k);
+            }
+            else {
+                const to = [...link.conns.values()].filter((c) => !except.has(c) && (!opts.participantsOnly || c.role === "PARTICIPANT"));
+                if (to.length > 0)
+                    this.write(link, to.map((c) => c.wire), data, opts.k);
+            }
+        }
+    }
+    send(to, data, opts = {}) {
+        if (this.closed)
+            return;
+        const list = (Array.isArray(to) ? to : [to]);
+        const byLink = new Map();
+        for (const c of list) {
+            if (!(c instanceof ConnImpl) || !c.open || c.link.detached || !this.links.has(c.link))
+                continue;
+            const wires = byLink.get(c.link) ?? [];
+            wires.push(c.wire);
+            byLink.set(c.link, wires);
+        }
+        for (const [link, wires] of byLink)
+            this.write(link, wires, data, opts.k);
+    }
+    sendToParticipant(participantId, data, opts) {
+        this.send(this.connsOf(participantId), data, opts);
+    }
+    kick(conn, opts) {
+        if (this.closed || !(conn instanceof ConnImpl) || !conn.open || conn.link.detached)
+            return;
+        const code = opts?.code;
+        if (!isKickCode(code))
+            throw new RangeError(`kick code ${code}: use 4403 or 4900-4999`);
+        this.assertReady(conn.link);
+        const reason = opts.reason === undefined ? undefined : opts.reason.slice(0, MAX_KICK_REASON);
+        conn.link.write({ t: "kick", conn: conn.wire, code, reason });
+    }
+    setTimeout(fn, ms) {
+        return this.timer(fn, ms, false);
+    }
+    setInterval(fn, ms) {
+        return this.timer(fn, ms, true);
+    }
+    close(reason = "room closed") {
+        void this.dispose("closed", LinkCloseCode.NORMAL, reason);
+    }
+    post(fn) {
+        this.enqueue("post", fn);
+    }
+    timer(fn, ms, repeat) {
+        if (this.closed)
+            return { cancel: () => undefined };
+        let pending = false;
+        const fire = () => {
+            if (!repeat)
+                return this.enqueue("setTimeout", fn);
+            if (pending || this.closed)
+                return;
+            pending = true;
+            this.enqueue("setInterval", async () => {
+                pending = false;
+                await fn();
+            });
+        };
+        const handle = repeat
+            ? setInterval(fire, ms)
+            : setTimeout(() => {
+                this.timers.delete(handle);
+                fire();
+            }, ms);
+        this.timers.add(handle);
+        return {
+            cancel: () => {
+                clearTimeout(handle);
+                clearInterval(handle);
+                this.timers.delete(handle);
+            },
+        };
+    }
+    assertReady(link) {
+        if (!link.ready)
+            throw new Error("room is not ready: send from a handler, not from onRoom");
+    }
+    write(link, to, data, k) {
+        if (link.detached)
+            return;
+        if (data === undefined)
+            throw new TypeError("cannot send undefined");
+        this.assertReady(link);
+        const frame = k === undefined ? { t: "send", to, d: data } : { t: "send", to, k, d: data };
+        const text = encodeFrame(frame);
+        if (byteLength(text) > MAX_LINK_FRAME_BYTES) {
+            throw new RangeError(`send frame is ${byteLength(text)} bytes; the room link carries at most ${MAX_LINK_FRAME_BYTES}`);
+        }
+        link.outbox.push(text, { key: k === undefined ? undefined : `${k}\u0000${Array.isArray(to) ? to.join(",") : to}`, droppable: true });
+    }
+    outboxStats() {
+        return [...this.links].map((l) => ({ ...l.outbox.stats }));
+    }
+}
+export class RoomHost {
+    options;
+    rooms = new Map();
+    disposing = new Map();
+    serial = 0;
+    shuttingDown = false;
+    log;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? console;
+    }
+    get gameType() {
+        return this.options.gameType;
+    }
+    attach(info, transport) {
+        const link = new Link(++this.serial, info, transport, this.options.live.outbox);
+        if (this.shuttingDown) {
+            transport.close(LinkCloseCode.RESTART, "plugin shutting down");
+            return { receive: () => undefined, closed: () => undefined };
+        }
+        let room = this.rooms.get(info.scope.key);
+        if (!room) {
+            room = new RoomImpl(info.scope, this.options.gameType, this, this.options.live);
+            this.rooms.set(info.scope.key, room);
+            room.attach(link);
+            void room.load(this.disposing.get(info.scope.key));
+        }
+        else {
+            const stale = room.linkWithEpoch(info.epoch);
+            room.attach(link);
+            if (stale)
+                room.supersede(stale);
+        }
+        const owner = room;
+        return {
+            receive: (text) => {
+                if (link.detached)
+                    return;
+                const decoded = decodePlatformFrame(text);
+                if (decoded.ok)
+                    owner.onFrame(link, decoded.frame);
+                else if (!decoded.unknown)
+                    this.log.error(`live ${info.scope.key}: dropped a malformed frame (${decoded.error})`);
+            },
+            closed: (code) => owner.detach(link, code),
+        };
+    }
+    list() {
+        return [...this.rooms.values()];
+    }
+    room(scopeKey) {
+        return this.rooms.get(scopeKey);
+    }
+    outboxStats(scopeKey) {
+        return this.rooms.get(scopeKey)?.outboxStats() ?? [];
+    }
+    async settled() {
+        for (let i = 0; i < 10_000; i++) {
+            await Promise.all([...this.disposing.values()]);
+            if (this.disposing.size === 0 && [...this.rooms.values()].every((r) => r.isSettled()))
+                return;
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        throw new Error("live rooms did not settle (an onRoom or handler that never resolves?)");
+    }
+    async shutdown() {
+        this.shuttingDown = true;
+        const timeout = this.options.live.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+        const all = [...this.rooms.values()].map((r) => r.dispose("shutdown", LinkCloseCode.RESTART, "plugin restarting"));
+        let timer;
+        await Promise.race([
+            Promise.all([...all, ...this.disposing.values()]),
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    this.log.error(`live: rooms still checkpointing after ${timeout} ms; closing anyway`);
+                    resolve();
+                }, timeout);
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+    }
+    forget(room, done) {
+        if (this.rooms.get(room.scope.key) === room)
+            this.rooms.delete(room.scope.key);
+        const tracked = done.finally(() => {
+            if (this.disposing.get(room.scope.key) === tracked)
+                this.disposing.delete(room.scope.key);
+        });
+        this.disposing.set(room.scope.key, tracked);
+    }
+    reportError(error, scope, handler) {
+        try {
+            if (this.options.live.onError)
+                this.options.live.onError(error, { scope, handler });
+            else
+                this.log.error(`live ${scope}: ${handler} threw`, error);
+        }
+        catch (e) {
+            try {
+                console.error(`live ${scope}: onError threw while reporting ${handler}`, e);
+            }
+            catch {
+            }
+        }
+    }
+}

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

@@ -0,0 +1,102 @@
+import { WebSocketServer } from "ws";
+import { LIVE_PATH, LIVE_PROTOCOL_VERSION, MAX_LINK_FRAME_BYTES, checkHandshake } from "./protocol";
+import { RoomHost } from "./rooms";
+const STATUS_TEXT = { 400: "Bad Request", 401: "Unauthorized", 404: "Not Found", 503: "Service Unavailable" };
+function refuse(socket, status, message) {
+    const body = `${message}\n`;
+    socket.end(`HTTP/1.1 ${status} ${STATUS_TEXT[status] ?? "Error"}\r\n` +
+        `Connection: close\r\n` +
+        `Content-Type: text/plain; charset=utf-8\r\n` +
+        `Content-Length: ${Buffer.byteLength(body)}\r\n` +
+        `X-Live-Protocol: ${LIVE_PROTOCOL_VERSION}\r\n\r\n` +
+        body);
+}
+export function attachLive(server, options) {
+    const log = options.log ?? console;
+    const host = new RoomHost({ gameType: options.gameType, live: options.live, log });
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_LINK_FRAME_BYTES });
+    const sockets = new Set();
+    const pingEvery = options.pingIntervalMs ?? 20_000;
+    const timeout = options.linkTimeoutMs ?? 45_000;
+    let closing = false;
+    let received = 0;
+    const onUpgrade = (req, socket, head) => {
+        const path = (req.url ?? "").split("?")[0];
+        if (path !== LIVE_PATH) {
+            if (server.listenerCount("upgrade") === 1)
+                refuse(socket, 404, "no such upgrade route");
+            return;
+        }
+        if (closing)
+            return refuse(socket, 503, "plugin shutting down");
+        const check = checkHandshake(req.headers, { gameType: options.gameType, authToken: options.authToken });
+        if (!check.ok)
+            return refuse(socket, check.status, check.message);
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            sockets.add(ws);
+            const handle = host.attach({ scope: check.scope, epoch: check.epoch }, {
+                write: (text, done) => {
+                    if (ws.readyState !== ws.OPEN)
+                        return done();
+                    ws.send(text, () => done());
+                },
+                close: (code, reason) => ws.close(code, reason.slice(0, 120)),
+            });
+            let lastHeard = Date.now();
+            const heard = () => {
+                lastHeard = Date.now();
+            };
+            let lastPing = Date.now();
+            const heartbeat = setInterval(() => {
+                const now = Date.now();
+                if (now - lastHeard > timeout) {
+                    log.error(`live ${check.scope.key}: link silent for ${timeout} ms, dropping it`);
+                    ws.terminate();
+                    return;
+                }
+                if (now - lastPing >= pingEvery && ws.readyState === ws.OPEN) {
+                    lastPing = now;
+                    ws.ping();
+                }
+            }, Math.max(1, Math.min(pingEvery, Math.floor(timeout / 3))));
+            heartbeat.unref?.();
+            ws.on("message", (data, isBinary) => {
+                heard();
+                received++;
+                if (isBinary)
+                    return;
+                handle.receive(data.toString());
+            });
+            ws.on("ping", heard);
+            ws.on("pong", heard);
+            ws.on("error", (e) => log.error(`live ${check.scope.key}: link error`, e));
+            ws.on("close", (code) => {
+                clearInterval(heartbeat);
+                sockets.delete(ws);
+                handle.closed(code);
+            });
+        });
+    };
+    server.on("upgrade", onUpgrade);
+    return {
+        rooms: () => host.list(),
+        room: (key) => host.room(key),
+        outboxStats: (key) => host.outboxStats(key),
+        links: () => sockets.size,
+        framesReceived: () => received,
+        settled: () => host.settled(),
+        close: async () => {
+            if (closing)
+                return;
+            closing = true;
+            await host.shutdown();
+            const deadline = Date.now() + 1_000;
+            while (sockets.size > 0 && Date.now() < deadline)
+                await new Promise((r) => setTimeout(r, 10));
+            for (const ws of sockets)
+                ws.terminate();
+            server.off("upgrade", onUpgrade);
+            wss.close();
+        },
+    };
+}