@anweather/game-plugin-ssdk 1.16.0 → 1.17.0

package/dist-types/runtime/live/server.d.ts

@@ -0,0 +1,36 @@
+import type { Server } from "node:http";
+import { type LiveOptions, type Room } from "./rooms";
+import type { OutboxStats } from "./outbox";
+export interface AttachLiveOptions {
+    gameType: string;
+    /** The X-Plugin-Auth bearer token; absent accepts every caller (local
+     * dev), exactly like the RPC routes. */
+    authToken?: string;
+    live: LiveOptions;
+    /** Protocol ping interval; the link closes after `linkTimeoutMs` with no
+     * frame, ping or pong from the platform. Defaults 20 s and 45 s (design
+     * §7.4). */
+    pingIntervalMs?: number;
+    linkTimeoutMs?: number;
+    log?: Pick<Console, "log" | "error">;
+}
+export interface LiveServer {
+    /** Rooms currently hosted. */
+    rooms(): Room[];
+    room(scopeKey: string): Room | undefined;
+    outboxStats(scopeKey: string): OutboxStats[];
+    /** Number of open room links. */
+    links(): number;
+    /** Text frames read off every link so far, handed to their rooms. Lets a
+     * test know the socket has delivered what it sent before it waits for
+     * the rooms to settle. */
+    framesReceived(): number;
+    /** Resolves once every room has loaded and drained its queue (tests). */
+    settled(): Promise<void>;
+    /** Checkpoint every room (onClose "shutdown"), close links with 1012, and
+     * stop accepting upgrades. */
+    close(): Promise<void>;
+}
+/** Serve room links on `server`'s /v1/live. servePlugin calls this when
+ * given `live`; a plugin with its own http.Server can call it directly. */
+export declare function attachLive(server: Server, options: AttachLiveOptions): LiveServer;

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

@@ -4,6 +4,8 @@ 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";
+import { type LiveServer } from "./live/server";
+import type { LiveOptions } from "./live/rooms";
 /** 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>;
@@ -41,6 +43,10 @@ export interface ServePluginOptions<Context = Record<string, never>> {
     retryDelaySeconds?: number;
     log?: Pick<Console, "log" | "error">;
     fetchImpl?: typeof fetch;
+    /** Host live rooms (Hosted mode, plugin-protocol/live/PROTOCOL.md): the
+     * platform opens one room link per active channel to /v1/live on this
+     * same server, behind the same X-Plugin-Auth token. Absent: no /v1/live. */
+    live?: LiveOptions;
 }
 export interface PluginApp {
     app: Express;
@@ -52,6 +58,8 @@ export interface PluginApp {
 }
 export interface RunningPlugin extends PluginApp {
     server: Server;
+    /** Present when `live` was given. */
+    live?: LiveServer;
     /** The port actually bound (differs from the configured one only for 0). */
     port: number;
     /** Stop renewing, deregister, close the listener. */

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.16.0",
+    "version": "1.17.0",
     "scripts": {
         "build": "concurrently 'npm:build:cjs' 'npm:build:es' 'npm:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",
@@ -60,7 +60,8 @@
         "@smithy/util-defaults-mode-browser": "^4.0.20",
         "@smithy/util-defaults-mode-node": "^4.0.20",
         "@smithy/util-endpoints": "^3.0.6",
-        "@smithy/util-utf8": "^4.0.0"
+        "@smithy/util-utf8": "^4.0.0",
+        "ws": "^8.18.0"
     },
     "devDependencies": {
         "@tsconfig/node18": "18.2.4",
@@ -71,7 +72,9 @@
         "rimraf": "^3.0.0",
         "typescript": "~5.8.3",
         "@types/node": "^18.19.69",
-        "tsx": "^4.19.2"
+        "tsx": "^4.19.2",
+        "@types/ws": "^8.5.12",
+        "ajv": "^8.17.1"
     },
     "engines": {
         "node": ">=18.0.0"