@antha/multiplayer-core 0.0.1

package/dist/room-handler-server/mock-room-handler-server-api-client.d.ts

@@ -0,0 +1,47 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type MultiplayerClientRooms } from '../multiplayer-api/multiplayer-api.js';
+/**
+ * Creates a mock multiplayer API client that can be used without running a backend server. The
+ * returned API client mocks all HTTP endpoints and WebSocket connections.
+ *
+ * - If a client connects to a room that doesn't exist, the room is created and the client becomes the
+ *   host.
+ * - If a client connects to a room that already exists, the offer is forwarded to the host and the
+ *   host's answer is relayed back to the connecting client.
+ *
+ * This is useful for demos, testing, and development scenarios where you want the multiplayer code
+ * path to work without a real backend.
+ *
+ * Use the returned mock API client with lower-level multiplayer controllers.
+ *
+ * @category Main
+ * @example
+ *
+ * ```ts
+ * import {createNewRoom, createMockRoomHandlerServerApiClient} from '@antha/multiplayer-core';
+ * import {P2pLockStepMultiplayerController} from '@antha/multiplayer-p2p-lock-step';
+ *
+ * const mockApiClient = createMockRoomHandlerServerApiClient();
+ * const p2pLockStep = new P2pLockStepMultiplayerController({
+ *     gameId: 'my-game',
+ *     frameDuration: {milliseconds: 16},
+ * });
+ * await p2pLockStep.initMultiplayer({
+ *     backendOrigin: mockApiClient.baseUrl,
+ *     multiplayerApiClient: mockApiClient,
+ * });
+ * await p2pLockStep.joinOrCreateRoom(
+ *     createNewRoom({
+ *         roomName: 'My Room',
+ *     }),
+ * );
+ * ```
+ */
+export declare function createMockRoomHandlerServerApiClient(options?: Readonly<PartialWithUndefined<{
+    /** Mock rooms to return from the `/rooms` endpoint. */
+    rooms: Readonly<MultiplayerClientRooms>;
+}>>): import("@rest-vir/api").RestVirClient<{
+    apiName: string;
+    endpoints: Readonly<Record<"/" | "/health" | "/rooms", Readonly<import("@rest-vir/api").EndpointDefinition>>>;
+    webSockets: Readonly<Record<"/connect", Readonly<import("@rest-vir/api").WebSocketDefinition>>>;
+}>;

package/dist/room-handler-server/mock-room-handler-server-api-client.js

@@ -0,0 +1,107 @@
+import { createMockHost, HttpMethod, HttpStatus } from '@rest-vir/api';
+import { multiplayerApi, multiplayerConnectWebSocket, multiplayerHealthEndpoint, multiplayerRoomsEndpoint, multiplayerRootEndpoint, } from '../multiplayer-api/multiplayer-api.js';
+import { createMultiplayerRoomHandler } from './multiplayer-room-handler.js';
+/**
+ * Creates a mock multiplayer API client that can be used without running a backend server. The
+ * returned API client mocks all HTTP endpoints and WebSocket connections.
+ *
+ * - If a client connects to a room that doesn't exist, the room is created and the client becomes the
+ *   host.
+ * - If a client connects to a room that already exists, the offer is forwarded to the host and the
+ *   host's answer is relayed back to the connecting client.
+ *
+ * This is useful for demos, testing, and development scenarios where you want the multiplayer code
+ * path to work without a real backend.
+ *
+ * Use the returned mock API client with lower-level multiplayer controllers.
+ *
+ * @category Main
+ * @example
+ *
+ * ```ts
+ * import {createNewRoom, createMockRoomHandlerServerApiClient} from '@antha/multiplayer-core';
+ * import {P2pLockStepMultiplayerController} from '@antha/multiplayer-p2p-lock-step';
+ *
+ * const mockApiClient = createMockRoomHandlerServerApiClient();
+ * const p2pLockStep = new P2pLockStepMultiplayerController({
+ *     gameId: 'my-game',
+ *     frameDuration: {milliseconds: 16},
+ * });
+ * await p2pLockStep.initMultiplayer({
+ *     backendOrigin: mockApiClient.baseUrl,
+ *     multiplayerApiClient: mockApiClient,
+ * });
+ * await p2pLockStep.joinOrCreateRoom(
+ *     createNewRoom({
+ *         roomName: 'My Room',
+ *     }),
+ * );
+ * ```
+ */
+export function createMockRoomHandlerServerApiClient(options) {
+    const defaultGameId = 'mock';
+    const roomHandler = createMultiplayerRoomHandler({
+        disablePeriodicCleanup: true,
+    });
+    /** Seed any initially provided rooms into the fetching cache. */
+    if (options?.rooms) {
+        Object.assign(roomHandler.state.roomsForFetching, {
+            [defaultGameId]: {
+                ...options.rooms,
+            },
+        });
+    }
+    return createMockHost(multiplayerApi, {
+        endpoints: {
+            [multiplayerRootEndpoint.path]: {
+                [HttpMethod.Get]() {
+                    return {
+                        [HttpStatus.Ok]: {
+                            responseData: 'ok',
+                        },
+                    };
+                },
+            },
+            [multiplayerHealthEndpoint.path]: {
+                [HttpMethod.Get]() {
+                    return {
+                        [HttpStatus.Ok]: {
+                            responseData: 'ok',
+                        },
+                    };
+                },
+            },
+            [multiplayerRoomsEndpoint.path]: {
+                [HttpMethod.Get]() {
+                    return {
+                        [HttpStatus.Ok]: {
+                            responseData: roomHandler.getRoomsForFetching(defaultGameId),
+                        },
+                    };
+                },
+            },
+        },
+        webSockets: {
+            [multiplayerConnectWebSocket.path]: {
+                message({ message, webSocket }) {
+                    roomHandler.enqueueMessage({
+                        gameId: defaultGameId,
+                        message,
+                        transport: {
+                            send(hostMessage) {
+                                webSocket.send(hostMessage);
+                            },
+                            get readyState() {
+                                return webSocket.readyState;
+                            },
+                        },
+                    });
+                    roomHandler.processQueue();
+                },
+                close() {
+                    roomHandler.updateRoomsForFetching(defaultGameId);
+                },
+            },
+        },
+    });
+}

package/dist/room-handler-server/multiplayer-room-handler.d.ts

@@ -0,0 +1,121 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { CommonWebSocketState } from '@rest-vir/api';
+import { type MultiplayerClientRoom, type MultiplayerClientRooms, type MultiplayerConnectClientMessage, type MultiplayerConnectHostMessage } from '../multiplayer-api/multiplayer-api.js';
+import { type ClientId, type RoomId } from '../multiplayer-id.js';
+/**
+ * A transport-agnostic client handle that the room handler uses to send messages and check
+ * connection state. Both real server WebSockets and mock WebSockets implement this.
+ *
+ * @category Internal
+ */
+export type MultiplayerTransportClient = {
+    /** Send a signaling message to the connected transport client. */
+    send: (message: MultiplayerConnectHostMessage) => void;
+    /** Current WebSocket-compatible connection state. */
+    readyState: CommonWebSocketState;
+};
+/**
+ * An individual multiplayer client tracked by the room handler.
+ *
+ * @category Internal
+ */
+export type RoomHandlerClient = {
+    clientId: ClientId;
+    clientSecret: string;
+    transport: MultiplayerTransportClient;
+};
+/**
+ * A multiplayer room managed by the room handler.
+ *
+ * @category Internal
+ */
+export type RoomHandlerRoom = {
+    clientsAwaitingAnswer: Record<ClientId, RoomHandlerClient>;
+    hostClient: RoomHandlerClient;
+    clientCount: number;
+    roomPassword: string;
+    lastHostPingTimestamp: number;
+} & Pick<MultiplayerClientRoom, 'roomName' | 'roomId'>;
+/**
+ * A collection of rooms grouped by game id.
+ *
+ * @category Internal
+ */
+export type RoomHandlerRooms = {
+    [GameId in string]: Record<RoomId, RoomHandlerRoom>;
+};
+/**
+ * Logger interface for the room handler.
+ *
+ * @category Internal
+ */
+export type RoomHandlerLogger = {
+    /** Log informational room handler messages. */
+    info: (...args: ReadonlyArray<unknown>) => void;
+    /** Log room handler errors. */
+    error: (error: Error) => void;
+};
+/**
+ * The internal state for the multiplayer room handler.
+ *
+ * @category Internal
+ */
+export type MultiplayerRoomHandlerState = {
+    rooms: RoomHandlerRooms;
+    messageQueue: {
+        gameId: string;
+        transport: MultiplayerTransportClient;
+        message: MultiplayerConnectClientMessage;
+    }[];
+    isProcessingQueue: boolean;
+    updateRoomsIntervalId: ReturnType<typeof setInterval> | undefined;
+    /**
+     * Precomputed client-friendly room listing, updated on an interval for real servers or on
+     * demand for mocks.
+     */
+    roomsForFetching: {
+        [GameId in string]: MultiplayerClientRooms;
+    };
+    logger: RoomHandlerLogger;
+};
+/**
+ * Options for creating a {@link MultiplayerRoomHandler}.
+ *
+ * @category Internal
+ */
+export type MultiplayerRoomHandlerOptions = PartialWithUndefined<{
+    logger: RoomHandlerLogger;
+    /**
+     * When true, disables the periodic interval that cleans up stale rooms and updates
+     * `roomsForFetching`. This is useful for mock/frontend environments where the interval is
+     * unnecessary.
+     */
+    disablePeriodicCleanup: boolean;
+}>;
+/**
+ * Creates a transport-agnostic multiplayer room handler. This contains the core room management and
+ * message routing logic shared between the real server and mock/frontend implementations.
+ *
+ * @category Internal
+ */
+export declare function createMultiplayerRoomHandler(options?: Readonly<MultiplayerRoomHandlerOptions>): {
+    state: MultiplayerRoomHandlerState;
+    /** Enqueue a message without immediately processing the queue. */
+    enqueueMessage(params: {
+        gameId: string;
+        transport: MultiplayerTransportClient;
+        message: MultiplayerConnectClientMessage;
+    }): void;
+    /** Process all queued messages. Safe to call multiple times; re-entrant calls are no-ops. */
+    processQueue(): void;
+    /** Get the client-friendly room listing for a game. */
+    getRoomsForFetching(gameId: string): MultiplayerClientRooms;
+    /** Force an immediate update of the rooms-for-fetching cache for a game. */
+    updateRoomsForFetching(gameId: string): void;
+};
+/**
+ * The return type of {@link createMultiplayerRoomHandler}.
+ *
+ * @category Internal
+ */
+export type MultiplayerRoomHandler = ReturnType<typeof createMultiplayerRoomHandler>;

package/dist/room-handler-server/multiplayer-room-handler.js

@@ -0,0 +1,216 @@
+import { getOrSet, mapObjectValues, omitObjectKeys, stringify, } from '@augment-vir/common';
+import { CommonWebSocketState } from '@rest-vir/api';
+import { convertDuration } from 'date-vir';
+import { createMultiplayerId } from '../multiplayer-id.js';
+import { MultiplayerWebSocketMessageType } from '../webrtc/web-rtc-communication.js';
+const silentLogger = {
+    info() { },
+    error() { },
+};
+/**
+ * Creates a transport-agnostic multiplayer room handler. This contains the core room management and
+ * message routing logic shared between the real server and mock/frontend implementations.
+ *
+ * @category Internal
+ */
+export function createMultiplayerRoomHandler(options) {
+    const state = {
+        rooms: {},
+        messageQueue: [],
+        isProcessingQueue: false,
+        updateRoomsIntervalId: undefined,
+        roomsForFetching: {},
+        logger: options?.logger || silentLogger,
+    };
+    return {
+        state,
+        /** Enqueue a message without immediately processing the queue. */
+        enqueueMessage(params) {
+            state.messageQueue.push(params);
+        },
+        /** Process all queued messages. Safe to call multiple times; re-entrant calls are no-ops. */
+        processQueue() {
+            processQueue(state, options?.disablePeriodicCleanup || false);
+        },
+        /** Get the client-friendly room listing for a game. */
+        getRoomsForFetching(gameId) {
+            return state.roomsForFetching[gameId] || {};
+        },
+        /** Force an immediate update of the rooms-for-fetching cache for a game. */
+        updateRoomsForFetching(gameId) {
+            updateRoomsForFetching(gameId, state);
+        },
+    };
+}
+const updateRoomsForFetchingIntervalDuration = convertDuration({
+    seconds: 5,
+}, {
+    milliseconds: true,
+});
+function updateRoomsForFetchingOnInterval(state) {
+    if (state.updateRoomsIntervalId) {
+        return;
+    }
+    state.updateRoomsIntervalId = setInterval(() => {
+        Object.keys(state.rooms).forEach((gameId) => updateRoomsForFetching(gameId, state));
+        if (!Object.keys(state.rooms).length) {
+            clearInterval(state.updateRoomsIntervalId);
+            state.updateRoomsIntervalId = undefined;
+        }
+    }, updateRoomsForFetchingIntervalDuration.milliseconds);
+}
+function updateRoomsForFetching(gameId, state) {
+    const gameRooms = state.rooms[gameId];
+    if (!gameRooms) {
+        return;
+    }
+    Object.values(gameRooms).forEach((room) => {
+        if (
+        /** Delete a room if its host is no longer active. */
+        room.hostClient.transport.readyState !== CommonWebSocketState.Open ||
+            /** Delete a room if the host reports no active room clients. */
+            room.clientCount <= 0 ||
+            /** Delete a room if it has had no updates from the host for two cycles. */
+            room.lastHostPingTimestamp <=
+                Date.now() - updateRoomsForFetchingIntervalDuration.milliseconds * 2) {
+            delete gameRooms[room.roomId];
+        }
+    });
+    if (!Object.keys(gameRooms).length) {
+        delete state.rooms[gameId];
+        delete state.roomsForFetching[gameId];
+        return;
+    }
+    state.roomsForFetching[gameId] = mapObjectValues(gameRooms, (roomId, room) => {
+        return {
+            clientCount: room.clientCount,
+            hasRoomPassword: !!room.roomPassword,
+            roomId,
+            roomName: room.roomName,
+        };
+    });
+}
+function processQueueItem(state, { message, transport, gameId, }) {
+    const room = state.rooms[gameId]?.[message.roomId]?.hostClient.transport.readyState ===
+        CommonWebSocketState.Open
+        ? state.rooms[gameId][message.roomId]
+        : undefined;
+    const currentClient = {
+        clientId: message.clientId,
+        transport,
+        clientSecret: 'clientSecret' in message ? message.clientSecret : '',
+    };
+    if (message.type === MultiplayerWebSocketMessageType.Offer) {
+        if (room) {
+            /** The client is connecting to an existing room with a valid host. */
+            if (room.roomPassword && message.roomPassword !== room.roomPassword) {
+                transport.send({
+                    messageId: message.messageId,
+                    type: MultiplayerWebSocketMessageType.Error,
+                    errorMessage: 'Invalid password.',
+                });
+            }
+            else {
+                state.logger.info(`Sending offer to host ${room.hostClient.clientId} in room ${room.roomName} (${room.roomId})`);
+                room.clientsAwaitingAnswer[currentClient.clientId] = currentClient;
+                room.hostClient.transport.send(omitObjectKeys(message, [
+                    'clientSecret',
+                    'roomPassword',
+                ]));
+                transport.send({
+                    messageId: message.messageId,
+                    type: MultiplayerWebSocketMessageType.OfferResult,
+                    hostClientId: room.hostClient.clientId,
+                });
+            }
+        }
+        else {
+            /**
+             * The client is either creating a new room or joining a room that just died (so create
+             * a new one).
+             */
+            const newRoom = {
+                clientsAwaitingAnswer: {},
+                hostClient: currentClient,
+                roomName: message.roomName,
+                roomId: message.roomId,
+                roomPassword: message.roomPassword,
+                clientCount: 1,
+                lastHostPingTimestamp: Date.now(),
+            };
+            state.logger.info(`Creating new room '${newRoom.roomName}' with id '${newRoom.roomId}' and host '${currentClient.clientId}'`);
+            getOrSet(state.rooms, gameId, () => {
+                return {};
+            })[newRoom.roomId] = newRoom;
+            updateRoomsForFetching(gameId, state);
+            transport.send({
+                messageId: message.messageId,
+                type: MultiplayerWebSocketMessageType.OfferResult,
+                hostClientId: newRoom.hostClient.clientId,
+            });
+        }
+    }
+    else if (message.type === MultiplayerWebSocketMessageType.Answer) {
+        /** The host client is sending an answer to one of its clients. */
+        state.logger.info(`Received answer from ${message.clientId}`);
+        const client = room?.clientsAwaitingAnswer[message.clientId];
+        if (client && client.transport.readyState === CommonWebSocketState.Open) {
+            /**
+             * Now that we're sending an answer to this client, we can remove it from the list of
+             * clients that are waiting for answers.
+             */
+            delete room.clientsAwaitingAnswer[message.clientId];
+            state.logger.info(`Sending answer to host ${message.clientId} in room ${room.roomName} (${room.roomId}).`);
+            state.logger.info(`Sending answer to ${client.clientId}`);
+            client.transport.send(message);
+        }
+        else {
+            const errorMessage = `No client found waiting for an answer by id ${message.clientId}`;
+            state.logger.error(new Error(errorMessage));
+            transport.send({
+                messageId: message.messageId,
+                type: MultiplayerWebSocketMessageType.Error,
+                errorMessage,
+            });
+            return;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    }
+    else if (message.type === MultiplayerWebSocketMessageType.HostPing) {
+        if (room && room.hostClient.clientSecret === message.clientSecret) {
+            room.clientCount = message.clientCount;
+            room.roomName = message.roomName;
+            room.roomPassword = message.roomPassword;
+            room.lastHostPingTimestamp = Date.now();
+            updateRoomsForFetching(gameId, state);
+        }
+        else {
+            transport.send({
+                messageId: message.messageId,
+                type: MultiplayerWebSocketMessageType.Error,
+                errorMessage: 'Invalid room to ping.',
+            });
+        }
+    }
+    else {
+        transport.send({
+            messageId: createMultiplayerId.socketMessage(),
+            type: MultiplayerWebSocketMessageType.Error,
+            errorMessage: `Invalid message: ${stringify(message)}`,
+        });
+    }
+}
+function processQueue(state, disablePeriodicCleanup) {
+    if (state.isProcessingQueue) {
+        return;
+    }
+    state.isProcessingQueue = true;
+    if (!disablePeriodicCleanup) {
+        updateRoomsForFetchingOnInterval(state);
+    }
+    let nextItem;
+    while ((nextItem = state.messageQueue.shift())) {
+        processQueueItem(state, nextItem);
+    }
+    state.isProcessingQueue = false;
+}

package/dist/webrtc/web-rtc-communication.d.ts

@@ -0,0 +1,64 @@
+/**
+ * All possible message types sent to and from the game-vir multiplayer server. These are used to
+ * establish WebRTC connections.
+ *
+ * @category Internal
+ */
+export declare enum MultiplayerWebSocketMessageType {
+    /**
+     * Sent to the multiplayer server from a client when they want to connect. The offer is then
+     * forwarded to the host client.
+     *
+     * If a host has not been set yet, then this client becomes the host.
+     */
+    Offer = "offer",
+    /**
+     * Sent to the multiplayer server from a host client (in response to an offer), then forwarded
+     * to the client.
+     *
+     * If the offer was rejected, this will contain significantly less data.
+     */
+    Answer = "answer",
+    /**
+     * Sent from the multiplayer server to a client WebSocket after their offer has been processed
+     * to instruct the client on what kind of client they are (member or host).
+     */
+    OfferResult = "offer-result",
+    /**
+     * A message sent to the multiplayer server from the host client to keep the room info up to
+     * date. This will be sent repeatedly on an interval.
+     */
+    HostPing = "host-ping",
+    /** An error message. */
+    Error = "error"
+}
+/**
+ * Shape definition for {@link WebrtcAnswer}.
+ *
+ * @category Internal
+ */
+export declare const webrtcAnswerShape: import("object-shape-tester").Shape<{
+    type: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<MultiplayerWebSocketMessageType.Answer>>;
+    sdp: string;
+}>;
+/**
+ * WebRTC handshake answer data.
+ *
+ * @category Internal
+ */
+export type WebrtcAnswer = typeof webrtcAnswerShape.runtimeType;
+/**
+ * Shape definition for {@link WebrtcOffer}.
+ *
+ * @category Internal
+ */
+export declare const webrtcOfferShape: import("object-shape-tester").Shape<{
+    type: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<MultiplayerWebSocketMessageType.Offer>>;
+    sdp: string;
+}>;
+/**
+ * WebRTC handshake offer data.
+ *
+ * @category Internal
+ */
+export type WebrtcOffer = typeof webrtcOfferShape.runtimeType;

package/dist/webrtc/web-rtc-communication.js

@@ -0,0 +1,54 @@
+import { defineShape, exactShape } from 'object-shape-tester';
+/**
+ * All possible message types sent to and from the game-vir multiplayer server. These are used to
+ * establish WebRTC connections.
+ *
+ * @category Internal
+ */
+export var MultiplayerWebSocketMessageType;
+(function (MultiplayerWebSocketMessageType) {
+    /**
+     * Sent to the multiplayer server from a client when they want to connect. The offer is then
+     * forwarded to the host client.
+     *
+     * If a host has not been set yet, then this client becomes the host.
+     */
+    MultiplayerWebSocketMessageType["Offer"] = "offer";
+    /**
+     * Sent to the multiplayer server from a host client (in response to an offer), then forwarded
+     * to the client.
+     *
+     * If the offer was rejected, this will contain significantly less data.
+     */
+    MultiplayerWebSocketMessageType["Answer"] = "answer";
+    /**
+     * Sent from the multiplayer server to a client WebSocket after their offer has been processed
+     * to instruct the client on what kind of client they are (member or host).
+     */
+    MultiplayerWebSocketMessageType["OfferResult"] = "offer-result";
+    /**
+     * A message sent to the multiplayer server from the host client to keep the room info up to
+     * date. This will be sent repeatedly on an interval.
+     */
+    MultiplayerWebSocketMessageType["HostPing"] = "host-ping";
+    /** An error message. */
+    MultiplayerWebSocketMessageType["Error"] = "error";
+})(MultiplayerWebSocketMessageType || (MultiplayerWebSocketMessageType = {}));
+/**
+ * Shape definition for {@link WebrtcAnswer}.
+ *
+ * @category Internal
+ */
+export const webrtcAnswerShape = defineShape({
+    type: exactShape(MultiplayerWebSocketMessageType.Answer),
+    sdp: '',
+});
+/**
+ * Shape definition for {@link WebrtcOffer}.
+ *
+ * @category Internal
+ */
+export const webrtcOfferShape = defineShape({
+    type: exactShape(MultiplayerWebSocketMessageType.Offer),
+    sdp: '',
+});