@roster-lock/types 1.0.0 → 1.1.0

package/dist/v1/runtime/game-launcher/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/v1/runtime/game-launcher/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/v1/runtime/game-launcher/index.ts"],"names":[],"mappings":""}

package/dist/v1/runtime/index.js

@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./download"), exports);
 __exportStar(require("./unstrusted-script"), exports);
 __exportStar(require("./piece-selection-sort"), exports);
+__exportStar(require("./game-launcher"), exports);
+__exportStar(require("./matchmaker-bridge"), exports);
 //# sourceMappingURL=index.js.map

package/dist/v1/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/runtime/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,6CAA2B;AAC3B,sDAAoC;AACpC,yDAAuC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/runtime/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,6CAA2B;AAC3B,sDAAoC;AACpC,yDAAuC;AACvC,kDAAgC;AAChC,sDAAoC"}

package/dist/v1/runtime/matchmaker-bridge/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATCHMAKER_BRIDGE_PATHS = void 0;
+exports.MATCHMAKER_BRIDGE_PATHS = {
+    installGameLauncherPlugin: "installGameLauncherPlugin",
+    getInstalledGameLauncherPlugins: "getInstalledGameLauncherPlugins",
+    getIdentity: "getIdentity",
+    requestSelection: "requestSelection",
+    updateGameLauncherSettings: "updateGameLauncherSettings",
+    initiateRelay: "initiateRelay",
+    ready: "ready",
+};
+//# sourceMappingURL=index.js.map

package/dist/v1/runtime/matchmaker-bridge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/v1/runtime/matchmaker-bridge/index.ts"],"names":[],"mappings":";;;AA6Ea,QAAA,uBAAuB,GAAG;IACrC,yBAAyB,EAAE,2BAA2B;IACtD,+BAA+B,EAAE,iCAAiC;IAClE,WAAW,EAAE,aAAa;IAC1B,gBAAgB,EAAE,kBAAkB;IACpC,0BAA0B,EAAE,4BAA4B;IACxD,aAAa,EAAE,eAAe;IAC9B,KAAK,EAAE,OAAO;CACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roster-lock/types",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Types for roster lock",
   "repository": {
     "type": "git",
@@ -19,6 +19,9 @@
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2"
   },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
   "scripts": {
     "build": "rimraf ./dist && tsc"
   }

package/src/v1/lock/roster.ts

@@ -3,6 +3,10 @@ import { PieceId, Sha256 } from "../shared";
 
 type URLType = string;
 type DownloadableSource = string;
+// A "data:image/<type>;base64,<data>" URI, embedded directly in the lock file rather
+// than fetched - unlike downloadSources, selection UIs need this available offline/at
+// select-time, before any piece content has been downloaded.
+type ImageDataURI = string;
 
 export type RosterLockPiece = {
   id: PieceId,
@@ -15,7 +19,7 @@ export type RosterLockPiece = {
     name: string,
     author: string,
     url: URLType,
-    image?: URLType,
+    image?: ImageDataURI,
   }
   downloadSources: Array<DownloadableSource>,
   pathVariables: Record<string, string>,

package/src/v1/lock/selection/index.ts

@@ -8,7 +8,7 @@ import { SelectionUnselectableConfig } from "./selection-types/unselectable";
 
 export * from "./meta";
 
-export {
+export type {
   SelectionPreselectedConfig,
   SelectionGameControlledConfig,
   SelectionNormalConfig,
@@ -16,7 +16,7 @@ export {
   UserSelectionValidation,
 };
 
-export { UntrustedScriptRef };
+export type { UntrustedScriptRef };
 
 export type RosterLockSelectionConfig = {
   piece: Record<PieceType, (

package/src/v1/relay/index.ts

@@ -2,7 +2,11 @@
 // Room Creation
 export type RoomConfig = {
   matchmakerId: string;
-  coordinatorId: string;
+  // `false` is an explicit, deliberate "this room has no game coordinator"
+  // choice (e.g. a fully-internal connection mode) - kept required rather
+  // than optional so a matchmaker can't omit it by accident and have that
+  // silently treated as an opt-out.
+  coordinatorId: string | false;
   roomId: string;
   rosterConfigHash: string;
   machines: RoomMachine[];

package/src/v1/runtime/game-launcher/index.ts

@@ -0,0 +1,228 @@
+
+import { RosterLockV1Config } from "../../lock";
+import { RosterLockV1SyncDLResult } from "../../request";
+import { RoomMachine } from "../../relay";
+import { Sha256 } from "../../shared";
+import type { AnySchema, JSONSchemaType } from "ajv";
+
+export type ConnectionMode = "direct-tcp" | "room" | "internal";
+
+// Mirrors NodeJS.Platform/NodeJS.Architecture (node_modules/@types/node's
+// process.d.ts) rather than importing them - this package deliberately
+// carries no @types/node dependency since it's also consumed by browser
+// code (see package.json's empty "types" compiler option). A caller with
+// @types/node can still pass process.platform/process.arch straight
+// through unchanged.
+export type PlatformName = (
+  "aix" | "android" | "darwin" | "freebsd" | "haiku" | "linux" |
+  "openbsd" | "sunos" | "win32" | "cygwin" | "netbsd"
+);
+export type ArchName = (
+  "arm" | "arm64" | "ia32" | "loong64" | "mips" | "mipsel" |
+  "ppc64" | "riscv64" | "s390x" | "x64"
+);
+
+// What a caller resolves a multi-platform binaryLocation bundle against -
+// see docs/v2/binary-location.md.
+export type PlatformTarget = {
+  platform: PlatformName,
+  arch: ArchName,
+};
+
+// The two variants shared as-is between ConnectionSetup and ConnectionConfig
+// below - neither needs anything resolved before a plugin can use it.
+type RoomOrInternalConnection = (
+  // The room's actual connection work happens entirely on the game side -
+  // `version` just tells it which of its own supported approaches to use
+  // (see GameLauncherPlugin.supportedRoomVersions), `url` is where it does
+  // that work. No separate protocol field: whatever `version` names already
+  // implies its protocol.
+  | { type: "room", version: string, url: string }
+  // The game has its own online connection story - roster-lock hands it a
+  // selection and gets out of the way.
+  | { type: "internal" }
+);
+
+// What a matchmaker/caller hands to match-agent's start-game route - a
+// direct-tcp room's host address isn't knowable upfront by whoever builds
+// this (it may be behind NAT, or simply not yet bound its listen socket), so
+// both variants instead carry the address of a small rendezvous coordinator
+// (see plugins/game-launcher/shared/direct-ip-coordinator and
+// docs/v2/ikemen-go/game-coordinator.md) rather than a resolved address.
+// match-agent's GameLauncher.startGame is what turns this into a
+// ConnectionConfig below before a plugin ever sees it - no plugin talks to a
+// coordinator itself.
+export type ConnectionSetup = (
+  | { type: "direct-tcp", party: "host", port: number, coordinator: { host: string, port: number } }
+  | { type: "direct-tcp", party: "client", port: number, coordinator: { host: string, port: number } }
+  | RoomOrInternalConnection
+);
+
+// What a GameLauncherPlugin's startGame actually receives - direct-tcp is
+// already resolved by this point (see ConnectionSetup above), so a plugin
+// only ever deals with an address to dial, never a coordinator of its own.
+export type ConnectionConfig = (
+  | { type: "direct-tcp", party: "host", port: number }
+  // hostIp is what a coordinator (or whatever else resolved this) reported
+  // - the same value startGame would otherwise have had to go discover
+  // itself.
+  | { type: "direct-tcp", party: "client", port: number, hostIp: string }
+  | RoomOrInternalConnection
+);
+
+export type GameProcessHandle = {
+  // Fires when the process this plugin is directly watching exits - not
+  // necessarily the same as "the game is over". Some games are started via
+  // an intermediary (a platform launcher, a wrapper script) that spawns the
+  // real game and exits 0 once it's handed off; for those, onExit only means
+  // the hand-off succeeded, not that play has ended - the plugin may have no
+  // handle to the actual game process at all. A plugin watching the real
+  // game process directly (e.g. spawning the engine binary itself, like
+  // ikemen-go does) can report both meaningfully; one that can't should say
+  // so in its publicInfo rather than let callers assume more than it can
+  // promise.
+  exited: false | { code: number },
+  onExit: (cb: (code: number | null) => void) => void,
+  onCrash: (cb: (error: Error) => void) => void,
+  // Best-effort - may not actually be able to stop the game if it's already
+  // handed off to a process this plugin no longer has a handle to.
+  stop: () => Promise<void>,
+};
+
+export type StartGameArgs<T> = {
+  // Handed to the game coordinator on the relay room's success webhook -
+  // lets a plugin correlate itself back to that room if it ever needs to.
+  relayRoomId: string,
+  currentMachine: {
+    machineId: string,
+    publicKey: string,
+    // A temp file - written with restrictive/owner-only permissions before
+    // startGame is invoked, deleted once the returned GameProcessHandle
+    // reports exit/crash - containing this machine's private key, for
+    // plugins that need to sign messages to identify the user to a game
+    // coordinator. Most games (Ikemen included) have no identity concept in
+    // their own netcode and never touch this.
+    //
+    // Handled as a file the framework manages (see
+    // @roster-lock/plugin-runtime's GameLauncher) rather than handing plugins
+    // the raw key directly, so a plugin is safe by default even if it does
+    // something careless with it - e.g. forwarding it into the spawned
+    // process's argv/env would otherwise leak to other users via `ps`/`/proc`
+    // on a shared machine (see docs/v2/test-environments.md's Internet Cafe
+    // / Arcade targets). A plugin that does need to hand the game itself an
+    // identity can still pass this same file path through unchanged.
+    privateKeyFile: string,
+  },
+  allMachines: Array<RoomMachine>,
+  selectionResult: RosterLockV1SyncDLResult,
+  rosterConfig: RosterLockV1Config,
+  // Lets a plugin without direct filesystem access to the downloaded pieces
+  // (selectionResult.downloadResults[...].folder assumes it's running on the
+  // same machine as match-agent) pull file contents over HTTP instead.
+  matchAgent: { port: number, authCode: string },
+  // Room-shared settings every participant agreed to at room-creation time
+  // (e.g. team mode, round time). Validated against gameConfigSchema.
+  gameConfig: T,
+};
+
+export type GameLauncherPlugin<T> = {
+  name: string,
+  publicInfo: {
+    title: string,
+    description: string,
+  },
+  // Which ConnectionConfig["type"] values this plugin actually knows how to
+  // consume in startGame - not just "would make sense for", since a mode
+  // like "room" typically depends on unbuilt bridge infrastructure. Only
+  // declare a mode once startGame genuinely handles it.
+  supportedConnectionModes: Array<ConnectionMode>,
+  // Which ConnectionConfig["room"]["version"] values this plugin supports.
+  // Only meaningful if "room" is in supportedConnectionModes.
+  supportedRoomVersions?: Array<string>,
+  // Identifies which RosterLockEngineConfig["pieceDefinitions"] shape this
+  // plugin was built against - a hash of that shape alone (not engine.name,
+  // engine.version, or engine.officialSelections, which are roster-author
+  // choices, not part of what the plugin structurally needs). Before a room
+  // can be created, this is compared against the same hash computed over the
+  // roster config's own engine.pieceDefinitions ("Engine Sha" in
+  // docs/v2/ikemen-go/general-plan.md) - a mismatch means the plugin's
+  // assumptions about piece layout (e.g. ikemen-go's defName path variable)
+  // don't hold for that roster.
+  engineSha: Sha256,
+  // JSON Schema for StartGameArgs["gameConfig"]. Set even when empty ({}).
+  gameConfigSchema: JSONSchemaType<T>,
+  // JSON Schema for this plugin's other per-machine settings (e.g. a
+  // preferred direct-tcp port). Excludes binaryLocation, which every Game
+  // Runner has by definition - see the functions below. Set even when empty.
+  localConfigSchema: AnySchema,
+  // Every platform/arch this plugin knows how to run on at all, independent
+  // of whether any particular binaryLocation currently has a binary for one
+  // of them - see docs/v2/binary-location.md. Lets a browsing/install UI
+  // warn "not supported on macOS" before the user has configured a
+  // binaryLocation to check against.
+  supportedPlatforms: Array<PlatformTarget>,
+
+  // binaryLocation is resolved locally (e.g. from match-agent's own config)
+  // and is what "disabled until configured" is about - every function below
+  // needs it pointed at something real to do anything useful. As of
+  // docs/v2/binary-location.md it's the root of a multi-platform bundle, not
+  // a path to one executable - each function below that needs a concrete
+  // binary resolves `target` against it itself; the layout convention for
+  // doing that is the plugin's own to define.
+  //
+  // `target` is required everywhere a concrete binary has to be resolved,
+  // rather than any function defaulting to "the current host" implicitly -
+  // see docs/v2/binary-location.md's "Platform targeting per function" for
+  // why (getSupportedVersion is the one exception, since it's a
+  // platform-agnostic upstream-metadata query).
+  getLocalVersion: (binaryLocation: string, target: PlatformTarget) => Promise<{ title: string, id: string }>,
+  // Knowing binaryLocation can help (e.g. picking a release channel), but
+  // this is expected to mostly be a network call, not a local read. No
+  // target - the answer ("what's the latest upstream version") doesn't vary
+  // by platform.
+  getSupportedVersion: (binaryLocation: string) => Promise<{ title: string, id: string }>,
+  // Optional - a plugin without one just means no in-app update; the user
+  // downloads a new version and re-points binaryLocation at it themselves.
+  // `target` is a floor, not a ceiling: the call guarantees at least that
+  // platform/arch gets updated, but a plugin may update other slots too as
+  // a side effect (e.g. one upstream artifact that already bundles every
+  // platform). Callers never loop over supportedPlatforms to force full
+  // coverage themselves - whether the bundle ends up complete for every
+  // platform after one call is entirely the plugin's own choice.
+  updateBinary?: (binaryLocation: string, target: PlatformTarget) => Promise<void>,
+  // Checks whether binaryLocation actually has a usable binary for `target`
+  // - "does the binary this host would run actually exist at the resolved
+  // path" (and on POSIX, is it executable) - so a caller can surface a
+  // plugin-authored reason (e.g. "no linux-x64 build in this folder")
+  // instead of a raw ENOENT/spawn error from startGame. Takes the same
+  // target startGame will actually receive, since that's the call it's
+  // answering for.
+  validateBinaryLocation: (
+    binaryLocation: string, target: PlatformTarget
+  ) => Promise<{ valid: true } | { valid: false, message: string }>,
+
+  startGame: (
+    binaryLocation: string, target: PlatformTarget, connectionConfig: ConnectionConfig, args: StartGameArgs<T>
+  ) => Promise<GameProcessHandle>,
+};
+
+// GameLauncherPlugin<T> is for *implementing* a plugin, where T (the plugin's
+// own gameConfig shape) is known and worth enforcing at both
+// gameConfigSchema and startGame. A caller that's just routing to *some*
+// installed plugin by name (match-agent, plugin-runtime's GameLauncher) never
+// knows T - it received the plugin dynamically, and gameConfig is exactly
+// what gameConfigSchema exists to describe/validate at runtime instead.
+//
+// GameLauncherPlugin<any> alone doesn't work for that: T=any is right for the
+// startGame/StartGameArgs positions (the usual erasure for storing/calling
+// a value whose real generic argument varies per plugin instance - see
+// PluginTypeMap["untrusted-script"]'s UntrustedScript<any> for the same
+// pattern elsewhere), but it also leaks into gameConfigSchema, turning it
+// into JSONSchemaType<any> - not the same thing as "some JSON Schema", and
+// not what a caller that never touches T actually wants. localConfigSchema
+// (AnySchema, no generic) is already the right shape for "opaque schema a
+// caller passes through" - gameConfigSchema needs that same shape once T
+// isn't known, hence the override below rather than just GameLauncherPlugin<any>.
+export type AnyGameLauncherPlugin = Omit<GameLauncherPlugin<any>, "gameConfigSchema"> & {
+  gameConfigSchema: AnySchema,
+};

package/src/v1/runtime/index.ts

@@ -2,3 +2,5 @@
 export * from "./download";
 export * from "./unstrusted-script";
 export * from "./piece-selection-sort";
+export * from "./game-launcher";
+export * from "./matchmaker-bridge";

package/src/v1/runtime/matchmaker-bridge/index.ts

@@ -0,0 +1,86 @@
+import { RosterLockV1Config } from "../../lock";
+import { UserSelection } from "../../request";
+
+// The wire protocol between a matchmaker UI (loaded in an <iframe>, e.g.
+// examples/services/match-makers/titled-room/client) and its host shell (e.g.
+// core/match-agent/client), carried over a postMessage-backed MessageBridge
+// (@roster-lock/utils). All six calls are iframe -> host; the host never
+// initiates. MessageBridge itself is untyped (see its own docs) - these
+// types exist purely so both sides' thin bridge wrapper modules agree on
+// shape, not because MessageBridge enforces it.
+//
+// Deliberately excludes any raw-signing/private-key primitive - titled-room
+// (the first matchmaker built against this protocol) uses JWT/bearer auth,
+// not signatures, so nothing needs one yet. A future signature-auth
+// matchmaker would need a new request added here, not a workaround.
+
+// installGameLauncherPlugin(pluginName) - host installs the plugin package and
+// opens a lightbox that also lets the user finish local config
+// (binaryLocation) before resolving.
+export type InstallGameLauncherPluginRequest = { pluginName: string };
+export type InstallGameLauncherPluginResponse = {};
+
+// getInstalledGameLauncherPlugins() - what game-launcher plugins this machine
+// already has installed, so a matchmaker's room UI can tell a user "you
+// don't have this one yet" without ever touching match-agent itself.
+// gameConfigSchema is included so a matchmaker can render the room-shared
+// settings a game launcher needs (e.g. ikemen-go's teamMode/roundTime/rounds)
+// as a real form (e.g. via rjsf) instead of asking the user for raw JSON -
+// it's already public (GameLauncherPlugin.gameConfigSchema, exposed by match-
+// agent's own /v1/game-launcher/available route), just not previously carried
+// across this bridge. Left as `unknown` here rather than ajv's AnySchema,
+// matching how match-agent-client's own GameLauncherSettingsForm already treats
+// localConfigSchema at this same kind of boundary - a consumer narrows it
+// (e.g. an RJSFSchema type guard) at render time instead.
+export type GetInstalledGameLauncherPluginsResponse = Array<{ id: string, version: string, gameConfigSchema: unknown }>;
+
+// getIdentity() - never includes the private key, only what's safe for a
+// matchmaker to see. playerCount reflects the host's own local player-slot
+// count (Join Settings), not anything the guest can set.
+export type GetIdentityResponse = { publicKey: string, machineId: string, playerCount: number };
+
+// requestSelection(rosterLockConfig, numPlayers) - host opens the Selection
+// lightbox for exactly `numPlayers` local player slots and resolves with the
+// built selection once confirmed. Unlike the other calls, the selection
+// *content* does cross back to the guest here - it isn't secret, only the
+// private key is.
+export type RequestSelectionRequest = { rosterLockConfig: RosterLockV1Config, numPlayers: number };
+export type RequestSelectionResponse = Record<number, UserSelection>;
+
+// updateGameLauncherSettings(pluginName, gameConfig) - room-shared settings a
+// game launcher needs before it can start (e.g. ikemen-go's teamMode). The
+// host holds onto this and folds it into the eventual
+// /v1/game-launcher/:pluginName/start call it makes later, since the host
+// (not the guest) is the one that ends up calling that route.
+export type UpdateGameLauncherSettingsRequest = { pluginName: string, gameConfig: unknown };
+export type UpdateGameLauncherSettingsResponse = {};
+
+// initiateRelay(...) - fire-and-forget event, not a request: the guest is
+// about to be torn down (host navigates away from the iframe entirely), so
+// there's nothing useful to await. Host merges this with whatever it already
+// has from requestSelection/updateGameLauncherSettings and navigates to
+// wherever it runs its own download/start-game flow.
+export type InitiateRelayEvent = {
+  relay: { url: string, roomId: string },
+  rosterConfig: RosterLockV1Config,
+  gameLauncherPlugin: string,
+  isHost: boolean,
+  // A direct-tcp game launcher's rendezvous coordinator (see
+  // plugins/game-launcher/shared/direct-ip-coordinator and
+  // docs/v2/ikemen-go/game-coordinator.md) - null for game launchers that
+  // don't use one (a matchmaker resolves this the same way it resolves
+  // `relay`, e.g. titled-room's /room/start response).
+  coordinator: { host: string, port: number } | null,
+};
+
+// Bridge message/event path names, so both sides reference the same literal
+// strings instead of hand-typing them.
+export const MATCHMAKER_BRIDGE_PATHS = {
+  installGameLauncherPlugin: "installGameLauncherPlugin",
+  getInstalledGameLauncherPlugins: "getInstalledGameLauncherPlugins",
+  getIdentity: "getIdentity",
+  requestSelection: "requestSelection",
+  updateGameLauncherSettings: "updateGameLauncherSettings",
+  initiateRelay: "initiateRelay",
+  ready: "ready",
+} as const;