@anweather/game-plugin-ssdk 1.5.0 → 1.6.0

package/dist-types/runtime/conformance.d.ts

@@ -0,0 +1,17 @@
+import type { GamePluginService } from "../src/server/GamePluginService";
+export interface ConformanceOptions {
+    /** Participant ids to seat. Defaults to metadata.minPlayers generated ids. */
+    participants?: string[];
+    /** InitializeGame config. Defaults to {}. */
+    config?: unknown;
+}
+export interface ConformanceReport {
+    passed: string[];
+    failed: {
+        check: string;
+        reason: string;
+    }[];
+}
+export declare function runConformance<Context>(service: GamePluginService<Context>, context: Context, options?: ConformanceOptions): Promise<ConformanceReport>;
+/** runConformance, throwing one error naming every failed check. */
+export declare function assertConformance<Context>(service: GamePluginService<Context>, context: Context, options?: ConformanceOptions): Promise<ConformanceReport>;

package/dist-types/runtime/index.d.ts

@@ -1,3 +1,10 @@
 export { mountSsdkHandler } from "./express";
 export { createGamePluginService } from "./defaultService";
 export type { RequiredGamePluginService, OptionalGamePluginService } from "./defaultService";
+export { servePlugin, createPluginApp } from "./servePlugin";
+export type { ServePluginOptions, PluginServiceDefinition, PluginApp, RunningPlugin } from "./servePlugin";
+export { createRegistrationLoop } from "./registration";
+export type { RegistrationOptions, RegistrationLoop } from "./registration";
+export { runConformance, assertConformance } from "./conformance";
+export type { ConformanceOptions, ConformanceReport } from "./conformance";
+export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";

package/dist-types/runtime/registration.d.ts

@@ -0,0 +1,25 @@
+export interface RegistrationOptions {
+    gameType: string;
+    /** The platform's base URL, e.g. http://platform:8080. Absent means
+     * "never register" -- the backend runs standalone (local tests, the
+     * Jackson-bridge test). */
+    platformUrl: string | undefined;
+    /** How the platform reaches this backend, e.g. http://chess-remote:8091. */
+    backendBaseUrl: string;
+    /** The shared secret the platform will send back as X-Plugin-Auth. */
+    authToken: string | undefined;
+    /** Seconds between attempts while registration keeps failing. */
+    retryDelaySeconds?: number;
+    fetchImpl?: typeof fetch;
+    log?: Pick<Console, "log" | "error">;
+}
+export interface RegistrationLoop {
+    /** Start registering (returns immediately; the first attempt is async). */
+    start(): void;
+    /** Stop renewing and tell the platform this backend is going away. */
+    stop(): Promise<void>;
+    /** One attempt, resolving to the delay in seconds before the next one.
+     * Exposed for tests; start() drives this on a timer. */
+    attemptOnce(): Promise<number>;
+}
+export declare function createRegistrationLoop(options: RegistrationOptions): RegistrationLoop;

package/dist-types/runtime/servePlugin.d.ts

@@ -0,0 +1,65 @@
+import { type Express, type Request } from "express";
+import type { Server } from "node:http";
+import type { ValidationCustomizer } from "@aws-smithy/server-common";
+import type { GamePluginService, GamePluginServiceOperations } from "../src/server/GamePluginService";
+import type { OptionalGamePluginService, RequiredGamePluginService } from "./defaultService";
+import { type RegistrationLoop } from "./registration";
+/** What a plugin supplies: every operation createGamePluginService requires,
+ * except Health, which servePlugin answers itself unless overridden. */
+export type PluginServiceDefinition<Context> = Omit<RequiredGamePluginService<Context>, "Health"> & Partial<Pick<GamePluginService<Context>, "Health">> & OptionalGamePluginService<Context>;
+export interface ServePluginOptions<Context = Record<string, never>> {
+    /** The wire GameType id, as GetMetadata reports it. */
+    gameType: string;
+    service: PluginServiceDefinition<Context>;
+    /** Port to listen on when the environment sets no PORT. 0 picks a free one. */
+    defaultPort?: number;
+    /** Directory served, unauthenticated, under /assets -- the plugin's own
+     * frontend bundle. Absent means no /assets route. */
+    staticDir?: string;
+    /** express.raw body limit. Every RPC carries the whole pluginState, and
+     * the platform's own ceiling is the games row (16 MB), so that is the
+     * default rather than Express's 100 KB. */
+    bodyLimit?: string;
+    /** Where PORT, PLUGIN_AUTH_TOKEN, PLATFORM_URL and
+     * PLUGIN_BACKEND_BASE_URL are read from. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** Per-request context handed to every operation. Defaults to {}. */
+    makeContext?: (req: Request) => Context;
+    /** Smithy input validation policy. The default is permissive: the rules
+     * engine's own validateMove is the real gate for move-shape
+     * correctness, and a strict customizer would 400 a Document-typed
+     * payload the engine would have rejected with a readable reason. */
+    validationCustomizer?: ValidationCustomizer<GamePluginServiceOperations>;
+    /** Extra routes or middleware, mounted before the /v1 catch-all and
+     * after the auth gate. */
+    configure?: (app: Express) => void;
+    /** Install SIGTERM/SIGINT handlers that deregister and exit. Defaults
+     * to true; tests pass false. */
+    handleSignals?: boolean;
+    /** Seconds between registration attempts while the platform is
+     * unreachable. */
+    retryDelaySeconds?: number;
+    log?: Pick<Console, "log" | "error">;
+    fetchImpl?: typeof fetch;
+}
+export interface PluginApp {
+    app: Express;
+    registration: RegistrationLoop;
+    port: number;
+    authToken: string | undefined;
+    platformUrl: string | undefined;
+    backendBaseUrl: string;
+}
+export interface RunningPlugin extends PluginApp {
+    server: Server;
+    /** The port actually bound (differs from the configured one only for 0). */
+    port: number;
+    /** Stop renewing, deregister, close the listener. */
+    close(): Promise<void>;
+}
+/** Build the app without listening -- what servePlugin does first, exposed
+ * for tests and for a plugin that wants to hand the app to its own server. */
+export declare function createPluginApp<Context = Record<string, never>>(options: ServePluginOptions<Context>): PluginApp;
+/** Listen, register with the platform, and keep the registration alive
+ * until close() or SIGTERM. Resolves once the port is bound. */
+export declare function servePlugin<Context = Record<string, never>>(options: ServePluginOptions<Context>): Promise<RunningPlugin>;

package/dist-types/runtime/version.d.ts

@@ -0,0 +1,9 @@
+export declare const PLUGIN_PROTOCOL_VERSION = 1;
+/** The version of this npm package as installed -- what servePlugin()
+ * reports as Health.runtimeVersion so the platform can see which SDK
+ * release a running plugin was built against. Read from the package's own
+ * package.json at runtime (which is why it is not a compile-time constant:
+ * the publish workflow stamps the version after the build). "unknown" only
+ * when the package layout is not the published one, e.g. a bundler that
+ * inlined this module. */
+export declare function runtimeVersion(): string;

package/dist-types/src/models/models_0.d.ts

@@ -281,6 +281,17 @@ export interface HealthOutput {
     status: string | undefined;
     gameType: string | undefined;
     protocolVersion: number | undefined;
+    /**
+     * The version of the plugin runtime library this backend was built
+     * with (the Kotlin plugin-protocol-kotlin-runtime artifact or the
+     * @anweather/game-plugin-ssdk npm package -- both publish on one
+     * shared semver, see plugin-protocol/CLAUDE.md). Informational:
+     * the platform records it at registration so a plugin on a stale
+     * runtime is visible without shelling into its container. Absent
+     * from a backend built before this field existed.
+     * @public
+     */
+    runtimeVersion?: string | undefined;
 }
 export declare namespace HealthOutput {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@anweather/game-plugin-ssdk",
     "description": "Generated GamePlugin RPC types/server (plugin-protocol/model/game-plugin.smithy) plus a hand-written Express bridge and default-handler wrapper (./runtime) -- see plugin-protocol/CLAUDE.md's \"Publishing for cross-repo plugins\".",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "scripts": {
         "build": "concurrently 'npm:build:cjs' 'npm:build:es' 'npm:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",
@@ -9,7 +9,8 @@
         "build:types": "tsc -p tsconfig.types.json",
         "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
         "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo || exit 0",
-        "prepack": "npm run clean && npm run build"
+        "prepack": "npm run clean && npm run build",
+        "test": "tsx --test test/*.test.ts"
     },
     "main": "./dist-cjs/src/index.js",
     "types": "./dist-types/src/index.d.ts",
@@ -69,7 +70,8 @@
         "express": "^4.21.2",
         "rimraf": "^3.0.0",
         "typescript": "~5.8.3",
-        "@types/node": "^18.19.69"
+        "@types/node": "^18.19.69",
+        "tsx": "^4.19.2"
     },
     "engines": {
         "node": ">=18.0.0"