@anweather/game-plugin-ssdk 1.5.1 → 1.6.0

package/dist-es/runtime/conformance.js

@@ -0,0 +1,90 @@
+import { isDeepStrictEqual } from "node:util";
+import { PLUGIN_PROTOCOL_VERSION } from "./version";
+function participantIds(n) {
+    return Array.from({ length: n }, (_, i) => `00000000-0000-4000-8000-${String(i + 1).padStart(12, "0")}`);
+}
+function sameMultiset(a, b) {
+    return a.length === b.length && [...a].sort().join("\u0000") === [...b].sort().join("\u0000");
+}
+export async function runConformance(service, context, options = {}) {
+    const report = { passed: [], failed: [] };
+    const check = async (name, body) => {
+        try {
+            await body();
+            report.passed.push(name);
+        }
+        catch (e) {
+            report.failed.push({ check: name, reason: e.message });
+        }
+    };
+    const expect = (cond, reason) => {
+        if (!cond)
+            throw new Error(reason);
+    };
+    const metadata = await service.GetMetadata({}, context);
+    const minPlayers = metadata.minPlayers ?? 0;
+    const maxPlayers = metadata.maxPlayers ?? 0;
+    await check("GetMetadata: id and seat counts are coherent", async () => {
+        expect(typeof metadata.id === "string" && metadata.id.length > 0, "id is empty");
+        expect(minPlayers >= 1, `minPlayers ${metadata.minPlayers} < 1`);
+        expect(maxPlayers >= minPlayers, `maxPlayers ${metadata.maxPlayers} < minPlayers ${metadata.minPlayers}`);
+    });
+    await check("Health: ok, same gameType as metadata, current protocol version", async () => {
+        const health = await service.Health({}, context);
+        expect(health.status === "ok", `status is "${health.status}"`);
+        expect(health.gameType === metadata.id, `gameType "${health.gameType}" != metadata id "${metadata.id}"`);
+        expect(health.protocolVersion === PLUGIN_PROTOCOL_VERSION, `protocolVersion ${health.protocolVersion} != ${PLUGIN_PROTOCOL_VERSION} (the platform would refuse to register this plugin)`);
+    });
+    const participants = options.participants ?? participantIds(Math.max(1, minPlayers));
+    const config = options.config ?? {};
+    await check("AssignParticipants: returns the same seats, only reordered", async () => {
+        const out = await service.AssignParticipants({ participants, config: config }, context);
+        expect(sameMultiset(out.participants ?? [], participants), `got ${JSON.stringify(out.participants)} for ${JSON.stringify(participants)}`);
+    });
+    const init = await service.InitializeGame({ participants, config: config }, context);
+    await check("InitializeGame: yields a state and a first turn among the seats", async () => {
+        expect(init.pluginState !== undefined && init.pluginState !== null, "pluginState is missing");
+        if (init.nextTurnParticipantId !== undefined) {
+            expect(participants.includes(init.nextTurnParticipantId), `nextTurnParticipantId ${init.nextTurnParticipantId} is not a participant`);
+        }
+    });
+    await check("InitializeGame: the state survives a JSON round trip unchanged", async () => {
+        const roundTripped = JSON.parse(JSON.stringify(init.pluginState));
+        expect(isDeepStrictEqual(roundTripped, init.pluginState), "pluginState changes when serialised (a Map, Set, Date, undefined or class instance inside it?)");
+    });
+    await check("GetGameStatus: a fresh game is not over", async () => {
+        const status = await service.GetGameStatus({ pluginState: init.pluginState }, context);
+        expect(status.isGameOver === false, `isGameOver is ${status.isGameOver} right after InitializeGame`);
+    });
+    await check("GetGameResult: a fresh game has no outcome", async () => {
+        const result = await service.GetGameResult({ pluginState: init.pluginState }, context);
+        expect(result.outcome === undefined, `outcome "${result.outcome}" right after InitializeGame`);
+    });
+    await check("ValidateMove: an empty payload is rejected, not thrown", async () => {
+        const out = await service.ValidateMove({ pluginState: init.pluginState, move: { participantId: participants[0], payload: {}, sequenceNumber: 1, timestamp: new Date() }, participantId: participants[0] }, context);
+        expect(typeof out.valid === "boolean", "valid is not a boolean");
+    });
+    if (metadata.hasCustomPlayerView) {
+        await check("GetPlayerView: every seat gets a view", async () => {
+            for (const p of participants) {
+                const view = await service.GetPlayerView({ pluginState: init.pluginState, participantId: p }, context);
+                expect(view.pluginState !== undefined && view.pluginState !== null, `no view for ${p}`);
+            }
+        });
+    }
+    if (metadata.hasBotStrategy) {
+        await check("SelectBotMove: the first turn holder gets a move", async () => {
+            const mover = init.nextTurnParticipantId ?? participants[0];
+            const out = await service.SelectBotMove({ pluginState: init.pluginState, participantId: mover }, context);
+            expect(out.payload !== undefined && out.payload !== null, "payload is missing");
+        });
+    }
+    return report;
+}
+export async function assertConformance(service, context, options = {}) {
+    const report = await runConformance(service, context, options);
+    if (report.failed.length > 0) {
+        throw new Error(`plugin contract violations:\n` + report.failed.map((f) => `  - ${f.check}: ${f.reason}`).join("\n"));
+    }
+    return report;
+}

package/dist-es/runtime/index.js

@@ -1,2 +1,6 @@
 export { mountSsdkHandler } from "./express";
 export { createGamePluginService } from "./defaultService";
+export { servePlugin, createPluginApp } from "./servePlugin";
+export { createRegistrationLoop } from "./registration";
+export { runConformance, assertConformance } from "./conformance";
+export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";

package/dist-es/runtime/registration.js

@@ -0,0 +1,67 @@
+export function createRegistrationLoop(options) {
+    const retryDelay = options.retryDelaySeconds ?? 5;
+    const doFetch = options.fetchImpl ?? fetch;
+    const log = options.log ?? console;
+    let timer;
+    let stopped = false;
+    async function attemptOnce() {
+        if (!options.platformUrl)
+            return retryDelay;
+        try {
+            const res = await doFetch(`${options.platformUrl}/internal/plugins/register`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    gameType: options.gameType,
+                    backendBaseUrl: options.backendBaseUrl,
+                    authToken: options.authToken,
+                }),
+            });
+            if (!res.ok) {
+                log.error(`registration rejected: ${res.status} ${await res.text()}`);
+                return retryDelay;
+            }
+            const { leaseSeconds } = (await res.json());
+            log.log(`registered with platform-server at ${options.platformUrl} (lease ${leaseSeconds}s)`);
+            return Math.max(1, leaseSeconds / 2);
+        }
+        catch (e) {
+            const cause = e.cause;
+            log.error(`registration attempt failed: ${e.message}` +
+                (cause ? ` (${cause instanceof Error ? cause.message : String(cause)})` : "") +
+                ` -- retrying in ${retryDelay}s`);
+            return retryDelay;
+        }
+    }
+    async function tick() {
+        if (stopped)
+            return;
+        const delaySeconds = await attemptOnce();
+        if (stopped)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(tick, delaySeconds * 1000);
+        timer.unref?.();
+    }
+    return {
+        start() {
+            if (!options.platformUrl)
+                return;
+            stopped = false;
+            void tick();
+        },
+        async stop() {
+            stopped = true;
+            clearTimeout(timer);
+            if (!options.platformUrl)
+                return;
+            try {
+                await doFetch(`${options.platformUrl}/internal/plugins/${options.gameType}`, { method: "DELETE" });
+            }
+            catch (e) {
+                log.error(`deregistration attempt failed: ${e.message}`);
+            }
+        },
+        attemptOnce,
+    };
+}

package/dist-es/runtime/servePlugin.js

@@ -0,0 +1,75 @@
+import express from "express";
+import { getGamePluginServiceHandler } from "../src/server/GamePluginService";
+import { createGamePluginService } from "./defaultService";
+import { mountSsdkHandler } from "./express";
+import { createRegistrationLoop } from "./registration";
+import { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";
+const permissiveValidation = () => undefined;
+export function createPluginApp(options) {
+    const env = options.env ?? process.env;
+    const port = Number(env.PORT ?? options.defaultPort ?? 0);
+    const authToken = env.PLUGIN_AUTH_TOKEN || undefined;
+    const platformUrl = env.PLATFORM_URL || undefined;
+    const backendBaseUrl = env.PLUGIN_BACKEND_BASE_URL || `http://localhost:${port}`;
+    const log = options.log ?? console;
+    const service = createGamePluginService({
+        Health: async () => ({
+            status: "ok",
+            gameType: options.gameType,
+            protocolVersion: PLUGIN_PROTOCOL_VERSION,
+            runtimeVersion: runtimeVersion(),
+        }),
+        ...options.service,
+    });
+    const handler = getGamePluginServiceHandler(service, options.validationCustomizer ?? permissiveValidation);
+    const app = express();
+    app.use(express.raw({ type: "*/*", limit: options.bodyLimit ?? "16mb" }));
+    app.use((req, res, next) => {
+        if (req.path === "/v1/health" || req.path.startsWith("/assets/") || req.path === "/assets")
+            return next();
+        if (!authToken)
+            return next();
+        if (req.header("X-Plugin-Auth") === `Bearer ${authToken}`)
+            return next();
+        res.status(401).json({ __type: "Unauthorized", message: "missing or invalid X-Plugin-Auth" });
+    });
+    if (options.staticDir)
+        app.use("/assets", express.static(options.staticDir));
+    options.configure?.(app);
+    const makeContext = options.makeContext ?? (() => ({}));
+    app.all("/v1/*", mountSsdkHandler(handler, makeContext));
+    const registration = createRegistrationLoop({
+        gameType: options.gameType,
+        platformUrl,
+        backendBaseUrl,
+        authToken,
+        retryDelaySeconds: options.retryDelaySeconds,
+        fetchImpl: options.fetchImpl,
+        log,
+    });
+    return { app, registration, port, authToken, platformUrl, backendBaseUrl };
+}
+export async function servePlugin(options) {
+    const built = createPluginApp(options);
+    const log = options.log ?? console;
+    const server = await new Promise((resolve, reject) => {
+        const s = built.app.listen(built.port, () => resolve(s));
+        s.once("error", reject);
+    });
+    const boundPort = server.address().port;
+    log.log(`${options.gameType} plugin backend listening on :${boundPort}`);
+    built.registration.start();
+    let closing;
+    const close = () => (closing ??= (async () => {
+        await built.registration.stop();
+        await new Promise((resolve) => server.close(() => resolve()));
+    })());
+    if (options.handleSignals ?? true) {
+        const onSignal = () => {
+            close().finally(() => process.exit(0));
+        };
+        process.once("SIGTERM", onSignal);
+        process.once("SIGINT", onSignal);
+    }
+    return { ...built, server, port: boundPort, close };
+}

package/dist-es/runtime/version.js

@@ -0,0 +1,10 @@
+export const PLUGIN_PROTOCOL_VERSION = 1;
+export function runtimeVersion() {
+    try {
+        const pkg = require("../../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist-es/src/models/models_0.js

@@ -618,6 +618,10 @@ export var HealthOutput;
                         ]);
                         break;
                     }
+                    case "runtimeVersion": {
+                        memberValidators["runtimeVersion"] = new __NoOpValidator();
+                        break;
+                    }
                 }
             }
             return memberValidators[member];
@@ -626,6 +630,7 @@ export var HealthOutput;
             ...getMemberValidator("status").validate(obj.status, `${path}/status`),
             ...getMemberValidator("gameType").validate(obj.gameType, `${path}/gameType`),
             ...getMemberValidator("protocolVersion").validate(obj.protocolVersion, `${path}/protocolVersion`),
+            ...getMemberValidator("runtimeVersion").validate(obj.runtimeVersion, `${path}/runtimeVersion`),
         ];
     };
 })(HealthOutput || (HealthOutput = {}));

package/dist-es/src/protocols/Aws_restJson1.js

@@ -706,6 +706,7 @@ export const serializeHealthResponse = async (input, ctx) => {
     body = JSON.stringify(take(input, {
         'gameType': [],
         'protocolVersion': [],
+        'runtimeVersion': [],
         'status': [],
     }));
     if (body && Object.keys(headers).map((str) => str.toLowerCase()).indexOf('content-length') === -1) {