@antha/multiplayer-server 0.0.8 → 0.1.1

package/README.md

@@ -1 +1,55 @@
 # @antha/multiplayer-server
+
+This package provides the server that [Antha](https://www.npmjs.com/package/@antha/engine) multiplayer clients use for room discovery and WebRTC signaling. It is only used for listing and connecting to rooms. Actual game state transfer is expected to be p2p.
+
+## Install
+
+```sh
+npm i @antha/multiplayer-server
+```
+
+## API
+
+<!-- example-link: src/readme-examples/starting-server.example.ts -->
+
+```TypeScript
+import {AnyOrigin} from '@rest-vir/api';
+import {startMultiplayerServer} from '@antha/multiplayer-server';
+
+await startMultiplayerServer({
+    backendOrigin: 'http://localhost:9348',
+    games: {
+        default: AnyOrigin,
+    },
+    host: 'localhost',
+    lockPort: true,
+    port: 9348,
+});
+```
+
+## CLI
+
+The `start-mp-server` command accepts a required path to a JavaScript, TypeScript, JSON, YAML, or TOML configuration file. The configuration uses the same options as `startMultiplayerServer`.
+
+Create a configuration file:
+
+<!-- example-link: src/readme-examples/multiplayer-server-config.example.ts -->
+
+```TypeScript
+export default {
+    games: {
+        byId: {
+            'example-game-id': 'https://electrovir.github.io',
+        },
+    },
+    host: '127.0.0.1',
+    lockPort: true,
+    port: 9348,
+};
+```
+
+Start the server with the configuration file path:
+
+```sh
+npx start-mp-server ./multiplayer-server.config.mjs
+```

package/dist/cli/bin.script.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const packageDirPath: string;

package/dist/cli/bin.script.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { assertWrap } from '@augment-vir/assert';
+import { readPackageJson } from '@augment-vir/node';
+import { parseArgs } from 'cli-vir';
+import { resolve } from 'node:path';
+import { runMultiplayerServerCli } from './cli.js';
+export const packageDirPath = resolve(import.meta.dirname, '..', '..');
+const binName = assertWrap.isTruthy(Object.keys(assertWrap.isObject((await readPackageJson(packageDirPath)).bin, 'Bin definition is not an object.'))[0], 'Failed to find bin name.');
+const args = parseArgs(process.argv, {
+    configPath: {
+        position: 0,
+        required: true,
+        description: 'Path to a config file (can be JS, TS, JSON, YAML, or TOML) with contents matching startMultiplayerServerOptionsShape.',
+    },
+}, {
+    binName,
+    importMeta: import.meta,
+});
+await runMultiplayerServerCli(args.configPath);

package/dist/cli/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Load a config file and start the multiplayer server from its options.
+ *
+ * @category Internal
+ */
+export declare function runMultiplayerServerCli(configFilePath: string): Promise<void>;

package/dist/cli/cli.js

@@ -0,0 +1,14 @@
+import { loadConfig } from 'config-vir';
+import { startMultiplayerServer, startMultiplayerServerOptionsShape } from '../start-server.js';
+/**
+ * Load a config file and start the multiplayer server from its options.
+ *
+ * @category Internal
+ */
+export async function runMultiplayerServerCli(configFilePath) {
+    const config = await loadConfig({
+        configPath: configFilePath,
+        configShape: startMultiplayerServerOptionsShape,
+    });
+    await startMultiplayerServer(config);
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export * from './implemented-multiplayer-api.js';
+export * from './cli/cli.js';
+export * from './multiplayer-api-implementation.js';
 export * from './start-server.js';

package/dist/index.js

@@ -1,2 +1,3 @@
-export * from './implemented-multiplayer-api.js';
+export * from './cli/cli.js';
+export * from './multiplayer-api-implementation.js';
 export * from './start-server.js';

package/dist/multiplayer-api-implementation.d.ts

@@ -0,0 +1,103 @@
+import { type MultiplayerRoomHandler } from '@antha/multiplayer-core';
+import { type ServerLogger } from '@rest-vir/host';
+/**
+ * Shape definition for {@link MultiplayerServerOptions}.
+ *
+ * @category Internal
+ */
+export declare const multiplayerServerOptionsShape: import("object-shape-tester").Shape<{
+    /**
+     * The Multiplayer server's logger.
+     *
+     * For help setting this, see any of the following from `@rest-vir/host`:
+     *
+     * - `silentServerLogger`
+     * - `defaultServerLogger`
+     * - `createServerLogger`
+     */
+    logger: import("object-shape-tester").Shape<import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUndefined | import("@sinclair/typebox").TNull | import("@sinclair/typebox").TObject<{
+        error: import("@sinclair/typebox").TUnsafe<(error: Error) => void>;
+        info: import("@sinclair/typebox").TUnsafe<(...args: ReadonlyArray<unknown>) => void>;
+    }>)[]>>>;
+    backendOrigin: import("object-shape-tester").Shape<import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUndefined | import("@sinclair/typebox").TNull | import("@sinclair/typebox").TString)[]>>>;
+    games: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TObject<{
+        byId: import("@sinclair/typebox").TUnsafe<Record<string, string | RegExp | import("@rest-vir/api").OriginCheckCallback | {
+            anyOriginWithCredentials?: undefined;
+            anyOrigin: true;
+        } | {
+            anyOrigin?: undefined;
+            anyOriginWithCredentials: true;
+        }>>;
+        default: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TUndefined, import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TString | import("@sinclair/typebox").TUnsafe<RegExp> | import("@sinclair/typebox").TUnsafe<import("@rest-vir/api").OriginCheckCallback> | import("@sinclair/typebox").TObject<{
+            anyOrigin: import("@sinclair/typebox").TUnsafe<true>;
+            anyOriginWithCredentials: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUndefined>;
+        }> | import("@sinclair/typebox").TObject<{
+            anyOrigin: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUndefined>;
+            anyOriginWithCredentials: import("@sinclair/typebox").TUnsafe<true>;
+        }>)[]>]>>;
+    }> | import("@sinclair/typebox").TObject<{
+        byId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TUndefined, import("@sinclair/typebox").TUnsafe<Record<string, string | RegExp | import("@rest-vir/api").OriginCheckCallback | {
+            anyOriginWithCredentials?: undefined;
+            anyOrigin: true;
+        } | {
+            anyOrigin?: undefined;
+            anyOriginWithCredentials: true;
+        }>>]>>;
+        default: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TString | import("@sinclair/typebox").TUnsafe<RegExp> | import("@sinclair/typebox").TUnsafe<import("@rest-vir/api").OriginCheckCallback> | import("@sinclair/typebox").TObject<{
+            anyOrigin: import("@sinclair/typebox").TUnsafe<true>;
+            anyOriginWithCredentials: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUndefined>;
+        }> | import("@sinclair/typebox").TObject<{
+            anyOrigin: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUndefined>;
+            anyOriginWithCredentials: import("@sinclair/typebox").TUnsafe<true>;
+        }>)[]>;
+    }>)[]>>;
+}>;
+/**
+ * Multiplayer server options.
+ *
+ * @category Internal
+ */
+export type MultiplayerServerOptions = typeof multiplayerServerOptionsShape.runtimeType;
+/**
+ * Internal state for the multiplayer server.
+ *
+ * @category Internal
+ */
+export type MultiplayerServerState = {
+    roomHandler: MultiplayerRoomHandler;
+    logger: ServerLogger;
+};
+/**
+ * The default logger for {@link ImplementedMultiplayerApi}.
+ *
+ * @category Internal
+ */
+export declare const defaultMultiplayerApiLogger: ServerLogger;
+/**
+ * Per-request host context derived from the multiplayer API request.
+ *
+ * @category Internal
+ */
+export type MultiplayerHostContext = {
+    /** Game id associated with the request or WebSocket connection. */
+    gameId: string;
+};
+/**
+ * The implemented API returned from {@link implementMultiplayerApi}.
+ *
+ * @category Internal
+ */
+export type ImplementedMultiplayerApi = ReturnType<typeof implementMultiplayerApi>['api'];
+/**
+ * Implements the multiplayer API.
+ *
+ * @category Internal
+ */
+export declare function implementMultiplayerApi(options: MultiplayerServerOptions): {
+    serverState: MultiplayerServerState;
+    api: Readonly<import("@rest-vir/host").ApiImplementation<{
+        apiName: string;
+        endpoints: Readonly<Record<"/" | "/health" | "/rooms", Readonly<import("@rest-vir/api").EndpointDefinition>>>;
+        webSockets: Readonly<Record<"/connect", Readonly<import("@rest-vir/api").WebSocketDefinition>>>;
+    }, MultiplayerHostContext>>;
+};

package/dist/{implemented-multiplayer-api.js → multiplayer-api-implementation.js}

@@ -1,8 +1,62 @@
 import { createMultiplayerRoomHandler, multiplayerApi, multiplayerConnectWebSocket, multiplayerHealthEndpoint, multiplayerRoomsEndpoint, multiplayerRootEndpoint, } from '@antha/multiplayer-core';
 import { check } from '@augment-vir/assert';
 import { callAsynchronously, ensureArray } from '@augment-vir/common';
-import { AnyOrigin, checkOriginRequirement, HttpMethod, HttpStatus, } from '@rest-vir/api';
+import { AnyOrigin, checkOriginRequirement, HttpMethod, HttpStatus, originRequirementShape, } from '@rest-vir/api';
 import { createApiImplementor, defaultServerLogger, implementApi, silentServerLogger, } from '@rest-vir/host';
+import { defineShape, nullableShape, optionalShape, recordShape, unionShape, } from 'object-shape-tester';
+/**
+ * Shape definition for {@link MultiplayerServerOptions}.
+ *
+ * @category Internal
+ */
+export const multiplayerServerOptionsShape = defineShape({
+    /**
+     * The Multiplayer server's logger.
+     *
+     * For help setting this, see any of the following from `@rest-vir/host`:
+     *
+     * - `silentServerLogger`
+     * - `defaultServerLogger`
+     * - `createServerLogger`
+     */
+    logger: nullableShape({
+        /** Log an error reported by the multiplayer server. */
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        error: (error) => { },
+        /** Log an informational message from the multiplayer server. */
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        info: (...args) => { },
+    }),
+    backendOrigin: nullableShape(''),
+    games: unionShape({
+        /**
+         * Allow specific games by id. If a game id is not matched, the below `default`
+         * requirement is checked. If no game id is matched and there is no specified `default`
+         * requirement, the request is blocked.
+         *
+         * If a game id's origin requirement is `undefined`, it is not considered a match.
+         */
+        byId: recordShape({
+            keys: '',
+            values: originRequirementShape,
+        }),
+        /**
+         * The default requirement for all unmatched game ids. If this is omitted or
+         * `undefined`, all unmatched game ids are blocked.
+         */
+        default: optionalShape(originRequirementShape, {
+            alsoUndefined: true,
+        }),
+    }, {
+        byId: optionalShape(recordShape({
+            keys: '',
+            values: originRequirementShape,
+        }), {
+            alsoUndefined: true,
+        }),
+        default: originRequirementShape,
+    }),
+});
 /**
  * The default logger for {@link ImplementedMultiplayerApi}.
  *
@@ -59,7 +113,14 @@ export function implementMultiplayerApi(options) {
                     },
                 };
             }
-            else if (!(await checkOriginRequirement(extractOrigin(requestHeaders), originRequirement))) {
+            else if (await checkOriginRequirement(extractOrigin(requestHeaders), originRequirement)) {
+                return {
+                    context: {
+                        gameId,
+                    },
+                };
+            }
+            else {
                 serverState.logger.error(new TypeError(`Origin check failed for game: '${gameId}'`));
                 return {
                     reject: {
@@ -67,11 +128,6 @@ export function implementMultiplayerApi(options) {
                     },
                 };
             }
-            return {
-                context: {
-                    gameId,
-                },
-            };
         },
         endpoints: [
             implementor.implementEndpoint(multiplayerRootEndpoint, {

package/dist/start-server.d.ts

@@ -1,17 +1,66 @@
-import { type SetRequired } from '@augment-vir/common';
-import { type RunApiUserOptions } from '@rest-vir/host';
-import { type MultiplayerServerOptions } from './implemented-multiplayer-api.js';
+/**
+ * Shape definition for {@link StartMultiplayerServerOptions}.
+ *
+ * @category Internal
+ */
+export declare const startMultiplayerServerOptionsShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    logger?: {
+        error: (error: Error) => void;
+        info: (...args: ReadonlyArray<unknown>) => void;
+    } | null | undefined;
+    backendOrigin?: string | null | undefined;
+    games: {
+        default?: string | RegExp | import("@rest-vir/api").OriginCheckCallback | {
+            anyOriginWithCredentials?: undefined;
+            anyOrigin: true;
+        } | {
+            anyOrigin?: undefined;
+            anyOriginWithCredentials: true;
+        } | undefined;
+        byId: Record<string, string | RegExp | import("@rest-vir/api").OriginCheckCallback | {
+            anyOriginWithCredentials?: undefined;
+            anyOrigin: true;
+        } | {
+            anyOrigin?: undefined;
+            anyOriginWithCredentials: true;
+        }>;
+    } | {
+        byId?: Record<string, string | RegExp | import("@rest-vir/api").OriginCheckCallback | {
+            anyOriginWithCredentials?: undefined;
+            anyOrigin: true;
+        } | {
+            anyOrigin?: undefined;
+            anyOriginWithCredentials: true;
+        }> | undefined;
+        default: string | RegExp | import("@rest-vir/api").OriginCheckCallback | {
+            anyOriginWithCredentials?: undefined;
+            anyOrigin: true;
+        } | {
+            anyOrigin?: undefined;
+            anyOriginWithCredentials: true;
+        };
+    };
+} & {
+    host?: string | undefined;
+    lockPort?: boolean | undefined;
+    debug?: boolean | undefined;
+    port: number | undefined;
+}>>>;
+/**
+ * Args for {@link startMultiplayerServer}.
+ *
+ * @category Internal
+ */
+export type StartMultiplayerServerOptions = typeof startMultiplayerServerOptionsShape.runtimeType;
 /**
  * Starts the multiplayer server.
  *
  * @category Main
  */
-export declare function startMultiplayerServer(options: Readonly<MultiplayerServerOptions & SetRequired<Pick<RunApiUserOptions, 'host' | 'lockPort' | 'port'>, 'port'> & {
-    debug?: boolean | undefined;
-}>): Promise<{
-    serverState: import("./implemented-multiplayer-api.js").MultiplayerServerState;
-    port: number;
+export declare function startMultiplayerServer(options: Readonly<StartMultiplayerServerOptions>): Promise<{
+    serverState: import("./multiplayer-api-implementation.js").MultiplayerServerState;
     host: string;
+    port: number;
     server: import("fastify").FastifyInstance;
     kill: (this: void) => import("@augment-vir/common").MaybePromise<void>;
 }>;

package/dist/start-server.js

@@ -1,7 +1,25 @@
 import { defaultMultiplayerApiOrigin } from '@antha/multiplayer-core';
 import { omitObjectKeys } from '@augment-vir/common';
 import { startApiServer } from '@rest-vir/host';
-import { implementMultiplayerApi, } from './implemented-multiplayer-api.js';
+import { defineShape, intersectShape, optionalShape, unionShape } from 'object-shape-tester';
+import { implementMultiplayerApi, multiplayerServerOptionsShape, } from './multiplayer-api-implementation.js';
+/**
+ * Shape definition for {@link StartMultiplayerServerOptions}.
+ *
+ * @category Internal
+ */
+export const startMultiplayerServerOptionsShape = defineShape(intersectShape(multiplayerServerOptionsShape, {
+    host: optionalShape('', {
+        alsoUndefined: true,
+    }),
+    lockPort: optionalShape(false, {
+        alsoUndefined: true,
+    }),
+    port: unionShape(0, undefined),
+    debug: optionalShape(false, {
+        alsoUndefined: true,
+    }),
+}));
 /**
  * Starts the multiplayer server.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/multiplayer-server",
-    "version": "0.0.8",
+    "version": "0.1.1",
     "description": "An multiplayer server that can be used with the Antha multiplayer mod.",
     "keywords": [
         "vir",
@@ -27,6 +27,9 @@
     "main": "dist/index.js",
     "module": "dist/index.js",
     "types": "dist/index.d.ts",
+    "bin": {
+        "start-mp-server": "dist/cli/bin.script.js"
+    },
     "scripts": {
         "compile": "virmator compile",
         "docs": "virmator docs",
@@ -35,26 +38,30 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@antha/multiplayer-p2p-lock-step": "^0.0.8",
-        "@augment-vir/assert": "^31.73.1",
-        "@augment-vir/common": "^31.73.1",
-        "@rest-vir/api": "^2.2.0",
-        "@rest-vir/host": "^2.2.0",
-        "date-vir": "^8.5.0",
-        "object-shape-tester": "^6.14.0",
-        "type-fest": "^5.7.0"
+        "@antha/multiplayer-core": "^0.1.1",
+        "@antha/multiplayer-p2p-lock-step": "^0.1.1",
+        "@augment-vir/assert": "^32.2.2",
+        "@augment-vir/common": "^32.2.2",
+        "@augment-vir/node": "^32.2.2",
+        "@rest-vir/api": "^2.3.1",
+        "@rest-vir/host": "^2.3.1",
+        "cli-vir": "^1.0.5",
+        "config-vir": "^1.0.1",
+        "date-vir": "^9.0.0",
+        "object-shape-tester": "^6.14.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.73.1",
-        "@types/node": "^25.9.3",
-        "@web/dev-server-esbuild": "^1.0.5",
-        "@web/test-runner": "^0.20.2",
-        "@web/test-runner-playwright": "^0.11.1",
-        "c8": "^11.0.0",
-        "istanbul-smart-text-reporter": "^1.1.5"
+        "@augment-vir/test": "^32.2.2",
+        "@types/node": "^26.2.0",
+        "@web/dev-server-esbuild": "^2.0.0",
+        "@web/test-runner": "^1.0.0",
+        "@web/test-runner-playwright": "^1.0.0",
+        "c8": "^12.0.0",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "tsx": "^4.23.11"
     },
     "peerDependencies": {
-        "@antha/engine": "^0.0.8"
+        "@antha/engine": "^0.1.1"
     },
     "engines": {
         "node": ">=22"

package/dist/implemented-multiplayer-api.d.ts

@@ -1,84 +0,0 @@
-import { type MultiplayerRoomHandler } from '@antha/multiplayer-core';
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { type OriginRequirement } from '@rest-vir/api';
-import { type ServerLogger } from '@rest-vir/host';
-import { type RequireAtLeastOne } from 'type-fest';
-/**
- * Multiplayer server options.
- *
- * @category Internal
- */
-export type MultiplayerServerOptions = PartialWithUndefined<{
-    /**
-     * The Multiplayer server's logger.
-     *
-     * For help setting this, see any of the following from `@rest-vir/host`:
-     *
-     * - `silentServerLogger`
-     * - `defaultServerLogger`
-     * - `createServerLogger`
-     */
-    logger: ServerLogger;
-    backendOrigin: string;
-}> & {
-    games: RequireAtLeastOne<{
-        /**
-         * Allow specific games by id. If a game id is not matched, the below `default` requirement
-         * is checked. If no game id is matched and there is no specified `default` requirement, the
-         * request is blocked.
-         *
-         * If a game id's origin requirement is `undefined`, it is not considered a match.
-         */
-        byId: {
-            [GameId in string]: OriginRequirement;
-        };
-        /**
-         * The default requirement for all unmatched game ids. If this is omitted or `undefined`,
-         * all unmatched game ids are blocked.
-         */
-        default: OriginRequirement;
-    }>;
-};
-/**
- * Internal state for the multiplayer server.
- *
- * @category Internal
- */
-export type MultiplayerServerState = {
-    roomHandler: MultiplayerRoomHandler;
-    logger: ServerLogger;
-};
-/**
- * The default logger for {@link ImplementedMultiplayerApi}.
- *
- * @category Internal
- */
-export declare const defaultMultiplayerApiLogger: ServerLogger;
-/**
- * Per-request host context derived from the multiplayer API request.
- *
- * @category Internal
- */
-export type MultiplayerHostContext = {
-    /** Game id associated with the request or WebSocket connection. */
-    gameId: string;
-};
-/**
- * The implemented API returned from {@link implementMultiplayerApi}.
- *
- * @category Internal
- */
-export type ImplementedMultiplayerApi = ReturnType<typeof implementMultiplayerApi>['api'];
-/**
- * Implements the multiplayer API.
- *
- * @category Internal
- */
-export declare function implementMultiplayerApi(options: MultiplayerServerOptions): {
-    serverState: MultiplayerServerState;
-    api: Readonly<import("@rest-vir/host").ApiImplementation<{
-        apiName: string;
-        endpoints: Readonly<Record<"/" | "/health" | "/rooms", Readonly<import("@rest-vir/api").EndpointDefinition>>>;
-        webSockets: Readonly<Record<"/connect", Readonly<import("@rest-vir/api").WebSocketDefinition>>>;
-    }, MultiplayerHostContext>>;
-};