@antha/multiplayer-core 0.0.1

package/dist/webrtc/webrtc-controller.d.ts

@@ -0,0 +1,104 @@
+import { type JsonCompatibleValue } from '@augment-vir/common';
+import { ListenTarget } from 'typed-event-target';
+import { type ClientId } from '../multiplayer-id.js';
+import { type WebrtcAnswer, type WebrtcOffer } from './web-rtc-communication.js';
+/**
+ * Converts an `RTCSessionDescription` into a plain object so that shape validation works correctly.
+ * Browser `RTCSessionDescription` objects expose `type` and `sdp` as prototype getters rather than
+ * own data properties, which causes `Object.getOwnPropertyNames`-based checks (used by TypeBox /
+ * object-shape-tester) to miss them.
+ *
+ * @category Internal
+ */
+export declare function toPlainSessionDescription(description: Readonly<RTCSessionDescription>): {
+    type: RTCSdpType;
+    sdp: string;
+};
+declare const WebrtcMessageEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: any;
+}) => import("typed-event-target").TypedCustomEvent<any, "webrtc-message">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<any, "webrtc-message">, "type">;
+/**
+ * An event that is omitted from {@link WebrtcController} when a WebRTC message is received.
+ *
+ * @category Internal
+ */
+export declare class WebrtcMessageEvent<MessageData extends JsonCompatibleValue> extends WebrtcMessageEvent_base {
+    detail: MessageData;
+}
+declare const WebrtcConnectEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: boolean;
+}) => import("typed-event-target").TypedCustomEvent<boolean, "webrtc-connect">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<boolean, "webrtc-connect">, "type">;
+/**
+ * An event that is omitted from {@link WebrtcController} when the WebRTC connection is made or lost.
+ * `event.detail` is `true` if the connection has been made; `false` if the connection was lost.
+ *
+ * @category Internal
+ */
+export declare class WebrtcConnectEvent extends WebrtcConnectEvent_base {
+}
+/**
+ * All events fro {@link WebrtcController}.
+ *
+ * @category Internal
+ */
+export type WebrtcEvents<MessageData extends JsonCompatibleValue> = WebrtcMessageEvent<MessageData> | WebrtcConnectEvent;
+/**
+ * A single peer-to-peer WebRTC controller. It is to be used like this:
+ *
+ * 1. Call {@link WebrtcController.createOffer} to start off a WebRTC handshake. Send this offer to
+ *    another WebRTC connection or {@link WebrtcController} instance.
+ * 2. Call {@link WebrtcController.createAnswer} to accept someone else's WebRTC handshake offer and
+ *    create a WebRTC handshake answer. Send this answer back to whoever sent the WebRTC offer.
+ * 3. Call {@link WebrtcController.acceptAnswer} on the {@link WebrtcController} instance that first
+ *    created the offer.
+ *
+ * If everything went well, after those 3 steps you'll now have a live WebRTC connection!
+ *
+ * @category Internal
+ */
+export declare class WebrtcController<MessageData extends JsonCompatibleValue> extends ListenTarget<WebrtcEvents<MessageData>> {
+    readonly clientId: ClientId;
+    private dataChannel;
+    private connection;
+    /** Indicates whether the WebRTC connection is live or not. */
+    readonly isConnected: boolean;
+    constructor(clientId: ClientId);
+    /** Create a WebRTC offer. This is the first step in the WebRTC handshake process. */
+    createOffer(stunServerUrls: ReadonlyArray<string>): Promise<WebrtcOffer>;
+    /** Accepts a WebRTC answer. This is the third (and last) step in the WebRTC handshake process. */
+    acceptAnswer(rawAnswer: string | Readonly<RTCSessionDescriptionInit>): Promise<void>;
+    /**
+     * Accepts a WebRTC offer and creates a WebRTC answer. This is the second step in the WebRTC
+     * handshake process.
+     */
+    createAnswer(rawOffer: string | Readonly<RTCSessionDescriptionInit>, stunServerUrls: ReadonlyArray<string>): Promise<WebrtcAnswer>;
+    /**
+     * Send a message to the other peer in the WebRTC connection. This will throw an error if the
+     * connection has not been established yet.
+     */
+    sendMessage(data: Readonly<MessageData>): void;
+    destroy(): void;
+    private handleDataChannel;
+    private createConnection;
+}
+export {};

package/dist/webrtc/webrtc-controller.js

@@ -0,0 +1,170 @@
+import { assert, assertWrap, check } from '@augment-vir/assert';
+import { addPrefix, DeferredPromise, makeWritable, wrapInTry, } from '@augment-vir/common';
+import { assertValidShape } from 'object-shape-tester';
+import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+import { webrtcAnswerShape, webrtcOfferShape, } from './web-rtc-communication.js';
+/**
+ * Converts an `RTCSessionDescription` into a plain object so that shape validation works correctly.
+ * Browser `RTCSessionDescription` objects expose `type` and `sdp` as prototype getters rather than
+ * own data properties, which causes `Object.getOwnPropertyNames`-based checks (used by TypeBox /
+ * object-shape-tester) to miss them.
+ *
+ * @category Internal
+ */
+export function toPlainSessionDescription(description) {
+    return {
+        type: description.type,
+        sdp: description.sdp,
+    };
+}
+/**
+ * An event that is omitted from {@link WebrtcController} when a WebRTC message is received.
+ *
+ * @category Internal
+ */
+export class WebrtcMessageEvent extends defineTypedCustomEvent()('webrtc-message') {
+}
+/**
+ * An event that is omitted from {@link WebrtcController} when the WebRTC connection is made or lost.
+ * `event.detail` is `true` if the connection has been made; `false` if the connection was lost.
+ *
+ * @category Internal
+ */
+export class WebrtcConnectEvent extends defineTypedCustomEvent()('webrtc-connect') {
+}
+function formatStunServerUrls(stunServerUrls) {
+    return stunServerUrls.map((stunServerUrl) => {
+        return {
+            urls: addPrefix({
+                value: stunServerUrl,
+                prefix: 'stun:',
+            }),
+        };
+    });
+}
+/**
+ * A single peer-to-peer WebRTC controller. It is to be used like this:
+ *
+ * 1. Call {@link WebrtcController.createOffer} to start off a WebRTC handshake. Send this offer to
+ *    another WebRTC connection or {@link WebrtcController} instance.
+ * 2. Call {@link WebrtcController.createAnswer} to accept someone else's WebRTC handshake offer and
+ *    create a WebRTC handshake answer. Send this answer back to whoever sent the WebRTC offer.
+ * 3. Call {@link WebrtcController.acceptAnswer} on the {@link WebrtcController} instance that first
+ *    created the offer.
+ *
+ * If everything went well, after those 3 steps you'll now have a live WebRTC connection!
+ *
+ * @category Internal
+ */
+export class WebrtcController extends ListenTarget {
+    clientId;
+    dataChannel;
+    connection;
+    /** Indicates whether the WebRTC connection is live or not. */
+    isConnected = false;
+    constructor(clientId) {
+        super();
+        this.clientId = clientId;
+    }
+    /** Create a WebRTC offer. This is the first step in the WebRTC handshake process. */
+    async createOffer(stunServerUrls) {
+        const candidatePromise = this.createConnection(stunServerUrls);
+        assert.isDefined(this.connection);
+        this.handleDataChannel(this.connection.createDataChannel('chat'));
+        await this.connection.setLocalDescription(await this.connection.createOffer());
+        await candidatePromise;
+        const offer = toPlainSessionDescription(assertWrap.isDefined(this.connection.localDescription));
+        assertValidShape(offer, webrtcOfferShape);
+        return offer;
+    }
+    /** Accepts a WebRTC answer. This is the third (and last) step in the WebRTC handshake process. */
+    async acceptAnswer(rawAnswer) {
+        const answer = check.isString(rawAnswer) ? JSON.parse(rawAnswer) : rawAnswer;
+        assert.isDefined(this.connection);
+        assertValidShape(answer, webrtcAnswerShape);
+        await this.connection.setRemoteDescription(answer);
+    }
+    /**
+     * Accepts a WebRTC offer and creates a WebRTC answer. This is the second step in the WebRTC
+     * handshake process.
+     */
+    async createAnswer(rawOffer, stunServerUrls) {
+        const offer = check.isString(rawOffer)
+            ? JSON.parse(rawOffer)
+            : rawOffer;
+        const candidatePromise = this.createConnection(stunServerUrls);
+        assert.isDefined(this.connection);
+        this.connection.addEventListener('datachannel', (event) => {
+            this.handleDataChannel(event.channel);
+        });
+        await this.connection.setRemoteDescription(offer);
+        await this.connection.setLocalDescription(await this.connection.createAnswer());
+        if (stunServerUrls.length) {
+            await candidatePromise;
+        }
+        const answer = toPlainSessionDescription(assertWrap.isDefined(this.connection.localDescription));
+        assertValidShape(answer, webrtcAnswerShape);
+        return answer;
+    }
+    /**
+     * Send a message to the other peer in the WebRTC connection. This will throw an error if the
+     * connection has not been established yet.
+     */
+    sendMessage(data) {
+        assert.isTrue(this.isConnected, `There is no WebRTC connection to send a message to from ${this.clientId}.`);
+        assert.isDefined(this.dataChannel, `There is no WebRTC connection to send a message to from ${this.clientId}.`);
+        this.dataChannel.send(JSON.stringify(data));
+    }
+    destroy() {
+        this.dataChannel?.close();
+        this.connection?.close();
+        super.destroy();
+    }
+    handleDataChannel(dataChannel) {
+        this.dataChannel?.close();
+        this.dataChannel = dataChannel;
+        this.dataChannel.addEventListener('open', () => {
+            makeWritable(this).isConnected = true;
+            this.dispatch(new WebrtcConnectEvent({
+                detail: true,
+            }));
+        });
+        this.dataChannel.addEventListener('closing', () => {
+            makeWritable(this).isConnected = false;
+            this.dispatch(new WebrtcConnectEvent({
+                detail: false,
+            }));
+        });
+        this.dataChannel.addEventListener('message', (event) => {
+            const detail = wrapInTry(() => (check.isString(event.data) ? JSON.parse(event.data) : event.data), {
+                fallbackValue: event.data,
+            });
+            this.dispatch(new WebrtcMessageEvent({
+                detail,
+            }));
+        });
+    }
+    createConnection(stunServerUrls) {
+        if (this.connection) {
+            throw new Error('Connection already created!');
+        }
+        const deferredIceCandidatePromise = new DeferredPromise();
+        const iceCandidateListener = (event) => {
+            // all candidates are done
+            if (!event.candidate) {
+                assert.isDefined(this.connection);
+                deferredIceCandidatePromise.resolve();
+                this.connection.removeEventListener('icecandidate', iceCandidateListener);
+            }
+        };
+        this.connection = new RTCPeerConnection({
+            iceServers: formatStunServerUrls(stunServerUrls),
+        });
+        this.connection.addEventListener('icecandidate', iceCandidateListener);
+        /**
+         * This must be awaited so the candidate list can finish populating before we present the
+         * offer to the user.
+         */
+        return deferredIceCandidatePromise.promise;
+    }
+}

package/dist/webrtc/webrtc-multiplayer-controller.d.ts

@@ -0,0 +1,263 @@
+import { type JsonCompatibleValue, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type RequireExactlyOne } from 'type-fest';
+import { ListenTarget } from 'typed-event-target';
+import { type MultiplayerConnectClientMessage } from '../multiplayer-api/multiplayer-api.js';
+import { type MultiplayerApiClient } from '../multiplayer-api/multiplayer-client.js';
+import { type ClientId } from '../multiplayer-id.js';
+import { MultiplayerWebSocketMessageType } from './web-rtc-communication.js';
+declare const WebrtcMultiplayerMessageEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: any;
+}) => import("typed-event-target").TypedCustomEvent<any, "webrtc-multiplayer-message">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<any, "webrtc-multiplayer-message">, "type">;
+/**
+ * An event that is omitted from {@link WebrtcController} when a WebRTC message is received.
+ *
+ * @category Internal
+ */
+export declare class WebrtcMultiplayerMessageEvent<MessageData extends JsonCompatibleValue> extends WebrtcMultiplayerMessageEvent_base {
+    readonly sourceClientId: ClientId;
+    detail: MessageData;
+    constructor(sourceClientId: ClientId, detail: MessageData);
+}
+/**
+ * Type for data in {@link WebrtcMultiplayerConnectionUpdateEvent}.
+ *
+ * @category Internal
+ */
+export type MultiplayerConnectionUpdate = RequireExactlyOne<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}>;
+declare const WebrtcMultiplayerConnectionUpdateEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: ((Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "newHost">> & Partial<Record<"newMember" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "newMember">> & Partial<Record<"newHost" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "lostHost">> & Partial<Record<"newHost" | "newMember" | "lostMember", never>>) | (Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "lostMember">> & Partial<Record<"newHost" | "newMember" | "lostHost", never>>)) & Omit<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "newHost" | "newMember" | "lostHost" | "lostMember">;
+}) => import("typed-event-target").TypedCustomEvent<((Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost">> & Partial<Record<"newMember" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newMember">> & Partial<Record<"newHost" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostHost">> & Partial<Record<"newHost" | "newMember" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostMember">> & Partial<Record<"newHost" | "newMember" | "lostHost", never>>)) & Omit<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost" | "newMember" | "lostHost" | "lostMember">, "webrtc-multiplayer-connection-update">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<((Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost">> & Partial<Record<"newMember" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newMember">> & Partial<Record<"newHost" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostHost">> & Partial<Record<"newHost" | "newMember" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostMember">> & Partial<Record<"newHost" | "newMember" | "lostHost", never>>)) & Omit<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost" | "newMember" | "lostHost" | "lostMember">, "webrtc-multiplayer-connection-update">, "type">;
+/**
+ * An event that is omitted from {@link WebrtcMultiplayerController} when the multiplayer room host
+ * is updated.
+ *
+ * @category Internal
+ */
+export declare class WebrtcMultiplayerConnectionUpdateEvent extends WebrtcMultiplayerConnectionUpdateEvent_base {
+}
+/**
+ * A helper for creating a new empty room.
+ *
+ * @category Internal
+ */
+export declare function createNewRoom(params?: Readonly<PartialWithUndefined<Omit<RoomInput, 'roomId'>>>): RoomInput;
+/**
+ * Room selection input for {@link WebrtcMultiplayerController}.
+ *
+ * @category Internal
+ */
+export type RoomInput = Pick<Extract<MultiplayerConnectClientMessage, {
+    type: MultiplayerWebSocketMessageType.Offer;
+}>, 'roomPassword' | 'roomId' | 'roomName'>;
+/**
+ * This is used to check if a new WebRTC connection should be allowed. This will only be triggered
+ * on a room host client. Return `true`
+ *
+ * @category Internal
+ */
+export type ShouldAllowConnectionCheck<Controller> = (data: {
+    connectingClientId: ClientId;
+    controller: Controller;
+}) => MaybePromise<boolean>;
+/**
+ * A controller that connects to the multiplayer api and establishes a WebRTC connection to the
+ * selected room, or, if the room does not exist yet, creates the room and becomes the host.
+ *
+ * Make sure, after constructing this class, to call
+ * {@link WebrtcMultiplayerController.initConnection} when you're ready to being the connection.
+ *
+ * @category Internal
+ */
+export declare class WebrtcMultiplayerController<MessageData extends JsonCompatibleValue = any> extends ListenTarget<WebrtcMultiplayerMessageEvent<MessageData> | WebrtcMultiplayerConnectionUpdateEvent> {
+    private readonly gameId;
+    private readonly multiplayerApiClient;
+    readonly stunServerUrls: ReadonlyArray<string>;
+    readonly multiplayerRoom: Readonly<RoomInput>;
+    /** The randomized client id for this controller and client. */
+    readonly clientId: ClientId;
+    /**
+     * This is fired when a WebRTC peer attempts to connect to the host client (this will only
+     * be fired if your client is the host). Return `true` to accept the connection. Return
+     * `false` to reject it.
+     *
+     * @default accept all connections
+     */
+    private readonly shouldAllowConnectionCheck;
+    readonly hostClientId: ClientId | undefined;
+    /**
+     * Connections between multiple WebRTC peers.
+     *
+     * A connection with the current client's id is the init connection.
+     */
+    private connections;
+    private webSocket;
+    private readonly clientSecret;
+    readonly isDestroyed: boolean;
+    constructor(gameId: string, multiplayerApiClient: Readonly<MultiplayerApiClient>, stunServerUrls: ReadonlyArray<string>, multiplayerRoom: Readonly<RoomInput>, 
+    /** The randomized client id for this controller and client. */
+    clientId?: ClientId, 
+    /**
+     * This is fired when a WebRTC peer attempts to connect to the host client (this will only
+     * be fired if your client is the host). Return `true` to accept the connection. Return
+     * `false` to reject it.
+     *
+     * @default accept all connections
+     */
+    shouldAllowConnectionCheck?: ShouldAllowConnectionCheck<WebrtcMultiplayerController<MessageData>>);
+    /**
+     * If this controller is the host, it'll behave differently:
+     *
+     * - Hosts hold WebRTC connections to all clients (non-hosts only hold a WebRTC connection to the
+     *   host).
+     * - Hosts hold a WebSocket connection to the signal server so they can receive more clients at
+     *   any time.
+     */
+    isHost(): boolean;
+    /**
+     * Get all connected client ids.
+     *
+     * - For host clients, this indicates how many member clients are connected to the host client,
+     *   _not_ including the host itself.
+     * - For non-host clients, this only lists the local connection used to reach the host.
+     *
+     * For host clients, this does ont include the host client id whereas
+     * {@link WebrtcMultiplayerController.getAllClientIds} does.
+     */
+    getConnectedClientIds(): ClientId[];
+    /**
+     * Get all room client ids.
+     *
+     * - For host clients, this indicates how many clients are connected to the room, including the
+     *   host client itself.
+     * - For non-host clients, this includes the member client and the host client once connected.
+     *
+     * For host clients, this includes the host client id whereas
+     * {@link WebrtcMultiplayerController.getConnectedClientIds} does not.
+     */
+    getAllClientIds(): ClientId[];
+    /** Indicates whether ths client is connected to a multiplayer room. */
+    isConnected(): boolean;
+    /** Destroy this controller and clean everything up. */
+    destroy(): void;
+    /**
+     * Send a message to the room participants.
+     *
+     * - If the current client is the room host, this message is sent to all other room clients.
+     * - If the current client is just a room member (not the host), the message is sent to the host.
+     */
+    sendMessage(data: Readonly<MessageData>): void;
+    /** Send a message to just a single client. This is only allowed on a host client. */
+    sendToOnlyOneClient(clientId: ClientId, data: Readonly<MessageData>): void;
+    /**
+     * Call this to connect to the multiplayer server.
+     *
+     * @returns Whether or not the connection was initialized (it won't be initialized, for example,
+     *   if the WebRTC connections already exist).
+     */
+    initConnection(): Promise<boolean>;
+    private sendHostPing;
+    private connectionQueue;
+    private setupWebSocket;
+    private createNewConnection;
+}
+export {};