@anweather/game-plugin-ssdk 1.5.1 → 1.6.1

package/dist-cjs/runtime/conformance.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runConformance = runConformance;
+exports.assertConformance = assertConformance;
+const node_util_1 = require("node:util");
+const version_1 = require("./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");
+}
+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 === version_1.PLUGIN_PROTOCOL_VERSION, `protocolVersion ${health.protocolVersion} != ${version_1.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((0, node_util_1.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;
+}
+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-cjs/runtime/index.js

@@ -1,7 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGamePluginService = exports.mountSsdkHandler = void 0;
+exports.runtimeVersion = exports.PLUGIN_PROTOCOL_VERSION = exports.assertConformance = exports.runConformance = exports.createRegistrationLoop = exports.createPluginApp = exports.servePlugin = exports.createGamePluginService = exports.mountSsdkHandler = void 0;
 var express_1 = require("./express");
 Object.defineProperty(exports, "mountSsdkHandler", { enumerable: true, get: function () { return express_1.mountSsdkHandler; } });
 var defaultService_1 = require("./defaultService");
 Object.defineProperty(exports, "createGamePluginService", { enumerable: true, get: function () { return defaultService_1.createGamePluginService; } });
+var servePlugin_1 = require("./servePlugin");
+Object.defineProperty(exports, "servePlugin", { enumerable: true, get: function () { return servePlugin_1.servePlugin; } });
+Object.defineProperty(exports, "createPluginApp", { enumerable: true, get: function () { return servePlugin_1.createPluginApp; } });
+var registration_1 = require("./registration");
+Object.defineProperty(exports, "createRegistrationLoop", { enumerable: true, get: function () { return registration_1.createRegistrationLoop; } });
+var conformance_1 = require("./conformance");
+Object.defineProperty(exports, "runConformance", { enumerable: true, get: function () { return conformance_1.runConformance; } });
+Object.defineProperty(exports, "assertConformance", { enumerable: true, get: function () { return conformance_1.assertConformance; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "PLUGIN_PROTOCOL_VERSION", { enumerable: true, get: function () { return version_1.PLUGIN_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "runtimeVersion", { enumerable: true, get: function () { return version_1.runtimeVersion; } });

package/dist-cjs/runtime/registration.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRegistrationLoop = createRegistrationLoop;
+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-cjs/runtime/servePlugin.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginApp = createPluginApp;
+exports.servePlugin = servePlugin;
+const tslib_1 = require("tslib");
+const express_1 = tslib_1.__importDefault(require("express"));
+const GamePluginService_1 = require("../src/server/GamePluginService");
+const defaultService_1 = require("./defaultService");
+const express_2 = require("./express");
+const registration_1 = require("./registration");
+const version_1 = require("./version");
+const permissiveValidation = () => undefined;
+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 = (0, defaultService_1.createGamePluginService)({
+        Health: async () => ({
+            status: "ok",
+            gameType: options.gameType,
+            protocolVersion: version_1.PLUGIN_PROTOCOL_VERSION,
+            runtimeVersion: (0, version_1.runtimeVersion)(),
+        }),
+        ...options.service,
+    });
+    const handler = (0, GamePluginService_1.getGamePluginServiceHandler)(service, options.validationCustomizer ?? permissiveValidation);
+    const app = (0, express_1.default)();
+    app.use(express_1.default.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_1.default.static(options.staticDir));
+    options.configure?.(app);
+    const makeContext = options.makeContext ?? (() => ({}));
+    app.all("/v1/*", (0, express_2.mountSsdkHandler)(handler, makeContext));
+    const registration = (0, registration_1.createRegistrationLoop)({
+        gameType: options.gameType,
+        platformUrl,
+        backendBaseUrl,
+        authToken,
+        retryDelaySeconds: options.retryDelaySeconds,
+        fetchImpl: options.fetchImpl,
+        log,
+    });
+    return { app, registration, port, authToken, platformUrl, backendBaseUrl };
+}
+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-cjs/runtime/version.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_PROTOCOL_VERSION = void 0;
+exports.runtimeVersion = runtimeVersion;
+exports.PLUGIN_PROTOCOL_VERSION = 1;
+function runtimeVersion() {
+    try {
+        const pkg = require("../../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

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

@@ -623,6 +623,10 @@ var HealthOutput;
                         ]);
                         break;
                     }
+                    case "runtimeVersion": {
+                        memberValidators["runtimeVersion"] = new server_common_1.NoOpValidator();
+                        break;
+                    }
                 }
             }
             return memberValidators[member];
@@ -631,6 +635,7 @@ 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 || (exports.HealthOutput = HealthOutput = {}));

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

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