mockrtc 0.1.0

package/src/main.ts

@@ -0,0 +1,109 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    MockRTC,
+    MockRTCOptions,
+    MockRTCPeerBuilder
+} from "./mockrtc";
+
+import { MockRTCServer } from "./server/mockrtc-server";
+import { MockRTCAdminServer } from "./server/mockrtc-admin-server";
+export { MockRTCAdminPlugin } from "./server/mockrtc-admin-plugin";
+
+import { MockRTCClient, MockRTCClientOptions } from "./client/mockrtc-client";
+
+// Re-export lots of types are used in various APIs (mostly to make TypeDoc happy):
+export type { HandlerStepDefinition } from "./handling/handler-step-definitions";
+export type { HandlerStep } from "./handling/handler-steps";
+export type { MockRTCHandlerBuilder } from "./handling/handler-builder";
+
+export type { MockRTCServerPeer } from "./server/mockrtc-server-peer";
+export type { SessionData } from "./server/mockrtc-admin-plugin";
+
+export type { RTCConnection } from "./webrtc/rtc-connection";
+export type { MockRTCConnection } from "./webrtc/mockrtc-connection";
+export type { DataChannelStream } from "./webrtc/datachannel-stream";
+export type { MediaTrackStream } from "./webrtc/mediatrack-stream";
+
+export type { PluggableAdmin } from 'mockttp';
+
+export type {
+    MockRTC,
+    MockRTCOptions,
+    MockRTCClientOptions,
+    MockRTCPeerBuilder,
+    MockRTCAdminServer
+};
+
+export type {
+    MockRTCPeer,
+    MockRTCPeerOptions,
+    MockRTCSession,
+    MockRTCOfferParams,
+    MockRTCAnswerParams,
+    MockRTCExternalOfferParams,
+    MockRTCExternalAnswerParams,
+    OfferOptions,
+    AnswerOptions
+} from './mockrtc-peer';
+
+export {
+    MOCKRTC_CONTROL_CHANNEL,
+    type MockRTCControlMessage
+} from './webrtc/control-channel';
+export {
+    hookWebRTCConnection,
+    hookAllWebRTC
+} from "./webrtc-hooks";
+
+/**
+ * Get a MockRTC instance on the local machine.
+ *
+ * In most simple environments, you can call this method directly and immediately
+ * get a MockRTC instance and start mocking peers.
+ *
+ * In node, the mocked peers will run in process and require no further setup.
+ *
+ * In browsers this is an alias for {@link getRemote}. You'll need to start a MockRTC
+ * admin server outside your tests before calling this, which will create and manage
+ * your fake peers outside the browser.
+ *
+ * @category API
+ */
+export function getLocal(): MockRTC {
+    return new MockRTCServer();
+}
+
+/**
+ * Get a MockRTC instance, managed by a MockRTC admin server running elsewhere.
+ *
+ * This connects to a MockRTC server, and uses that to start
+ * and stop mock peers.
+ *
+ * @category API
+ */
+export function getRemote(options: MockRTCClientOptions = {}): MockRTC {
+    return new MockRTCClient(options);
+}
+
+/**
+ * Get a MockRTC admin server, which can be used with a MockRTC remote client to create
+ * & manage mock peers either from remote machines or from local environments
+ * that lack necessary capabilities, e.g. to use MockRTC from inside a browser.
+ *
+ * This function exists so you can set up these servers programmatically, but for most
+ * usage you can just run your tests via the `mockrtc` binary, which will automatically
+ * start and stop an admin server for you:
+ *
+ * ```
+ * mockrtc -c <your test command>
+ * ```
+ *
+ * @category API
+ */
+export function getAdminServer(): MockRTCAdminServer {
+    return new MockRTCAdminServer();
+}

package/src/mockrtc-peer.ts

@@ -0,0 +1,176 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface MockRTCPeerOptions {
+    recordMessages?: boolean;
+}
+
+/**
+ * A MockRTC peer represents a target you can connect to, and exposes an API to create
+ * offers or answers to create new connections.
+ *
+ * Peers have defined behaviour, and each connection will be handled accordingly and
+ * independently.
+ *
+ * Peers can also optionally track all the messages and metadata across all their
+ * connections.
+ */
+export interface MockRTCPeer {
+    readonly peerId: string;
+
+    /**
+     * Creates an offer for a new connection to this mock peer.
+     *
+     * Returns a set of offer parameters: the offer itself, a session to renegotiate
+     * the connection in future, and a setAnswer callback to call with an answer
+     * once you have one.
+     */
+    createOffer(options?: OfferOptions): Promise<MockRTCOfferParams>;
+
+    /**
+     * Takes an offer for a WebRTC connection elsewhere, and creates an answer to
+     * connect that to this peer.
+     *
+     * Returns a set of answer parameters: the answer itself, and a session to renegotiate
+     * the connection in future.
+     */
+    answerOffer(
+        offer: RTCSessionDescriptionInit,
+        options?: AnswerOptions
+    ): Promise<MockRTCAnswerParams>;
+
+    /**
+     * Creates an offer for a new external connection to this mock peer.
+     *
+     * External connections are used for proxying traffic. They do not do anything
+     * by default (so they ignore this peer's configured steps) but a mock connection
+     * can be connected to an external connection using methods like
+     * {@link MockRTCHandlerBuilder.thenPassThrough thenPassThrough}.
+     *
+     * Returns a set of offer parameters: an external connection id, the offer itself,
+     * a session to renegotiate the connection in future, and a setAnswer callback to
+     * call with an answer once you have one.
+     */
+    createExternalOffer(options?: OfferOptions): Promise<MockRTCExternalOfferParams>;
+
+    /**
+     * Takes an offer for a WebRTC connection elsewhere, and creates an answer to create
+     * an external connection to this peer.
+     *
+     * External connections are used for proxying traffic. They do not do anything
+     * by default (so they ignore this peer's configured steps) but a mock connection
+     * can be connected to an external connection using methods like
+     * {@link MockRTCHandlerBuilder.thenPassThrough thenPassThrough}.
+     *
+     * Returns a set of answer parameters: an external connection id, the answer itself,
+     * and a session to renegotiate the connection in future.
+     */
+    answerExternalOffer(
+        offer: RTCSessionDescriptionInit,
+        options?: AnswerOptions
+    ): Promise<MockRTCExternalAnswerParams>;
+
+    /**
+     * Takes a connection id, and returns the associated session.
+     *
+     * This is useful for advanced use cases, where keeping the session returned by other
+     * setup methods is inconvenient, and it's easier to keep ids and look up sessions
+     * on demand instead.
+     */
+    getSession(id: string): MockRTCSession;
+
+    /**
+     * Retrieve an array of all data channel messages that this peer has received on
+     * all connections.
+     */
+    getAllMessages(): Promise<Array<string | Buffer>>;
+
+    /**
+     * Retrieve an array of all data channel messages on a specific channel that this
+     * peer has received on all connections.
+     */
+    getMessagesOnChannel(channelName: string): Promise<Array<string | Buffer>>;
+}
+
+/**
+ * Once a connection has been created, you can access its session API. This allows
+ * for renegotiation of an existing session, while persisting the same connection
+ * and ongoing handling process.
+ */
+export interface MockRTCSession {
+    /**
+     * For most use cases explicitly using the session ID isn't necessary.
+     *
+     * For some advanced use cases though, it's more convenient to store session ids and use
+     * peer.getSession, rather than using the session property from the setup methods directly.
+     */
+    readonly sessionId: string;
+
+    /**
+     * Create a new offer for this session, to renegotiate the existing connection.
+     */
+    createOffer(options?: OfferOptions): Promise<RTCSessionDescriptionInit>;
+
+    /**
+     * Provide an answer to complete an offer for this session, to renegotiate the existing connection.
+     */
+    completeOffer(answer: RTCSessionDescriptionInit): Promise<void>;
+
+    /**
+     * Get an answer given an offer from elsewhere, to renegotiate the existing connection.
+     */
+    answerOffer(offer: RTCSessionDescriptionInit, options?: AnswerOptions): Promise<RTCSessionDescriptionInit>;
+}
+
+export interface MockRTCOfferParams {
+    offer: RTCSessionDescriptionInit;
+    setAnswer: (answer: RTCSessionDescriptionInit) => Promise<void>;
+    session: MockRTCSession;
+}
+
+export interface MockRTCAnswerParams {
+    answer: RTCSessionDescriptionInit;
+    session: MockRTCSession;
+}
+
+export interface OfferOptions {
+    /**
+     * A raw SDP string that should be mirrored (best efforts) where possible to
+     * create an equivalent offer, including the same media with the same params.
+     */
+    mirrorSDP?: string;
+
+    /**
+     * When using mirrorSDP, for SDP that only defines video/audio media we will
+     * receive an offer with no data stream attached. This can be a problem for
+     * proxied connections, which need a data stream to hook up the external
+     * connection later. If addDataStream is set to true, a data stream will always
+     * be created even if not present in the mirrored SDP.
+     *
+     * This option has no effect if mirrorSDP is not set.
+     */
+    addDataStream?: boolean;
+}
+
+export interface AnswerOptions {
+    /**
+     * A raw SDP string that should be mirrored (best efforts) where possible to
+     * create an equivalent answer, including the same media params.
+     */
+    mirrorSDP?: string;
+}
+
+export interface MockRTCExternalOfferParams {
+    id: string; // Used for external attach control messages
+    offer: RTCSessionDescriptionInit;
+    setAnswer: (answer: RTCSessionDescriptionInit) => Promise<void>;
+    session: MockRTCSession;
+}
+
+export interface MockRTCExternalAnswerParams {
+    id: string; // Used for external attach control messagesz
+    answer: RTCSessionDescriptionInit;
+    session: MockRTCSession;
+}

package/src/mockrtc.ts

@@ -0,0 +1,36 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { MockRTCHandlerBuilder } from "./handling/handler-builder";
+import type { MockRTCPeer } from "./mockrtc-peer";
+
+export interface MockRTCPeerBuilder extends MockRTCHandlerBuilder<MockRTCPeer> {}
+
+export interface MockRTCOptions {
+    /**
+     * Whether or not all DataChannel messages should be saved for later examination.
+     * This can be useful in quick testing, but may use large amounts of data if
+     * enabled when proxying lots of traffic.
+     *
+     * Defaults to false.
+     */
+    recordMessages?: boolean;
+}
+
+export interface MockRTC {
+
+    /**
+     * Start creating a mock WebRTC peer. This method returns a builder, who
+     * must be configured with the mock peer's settings. Once configured the
+     * peer can be created by calling any `.thenX()` method to define the
+     * peer's behaviour.
+     */
+    buildPeer(): MockRTCPeerBuilder;
+
+    start(): Promise<void>;
+
+    stop(): Promise<void>;
+
+}

package/src/server/mockrtc-admin-plugin.ts

@@ -0,0 +1,196 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as stream from 'stream';
+import { gql } from 'graphql-tag';
+import { PluggableAdmin } from 'mockttp';
+import type { IResolvers } from "@graphql-tools/utils";
+
+import { HandlerStep, StepLookup } from '../handling/handler-steps';
+import { MockRTCOptions } from '../mockrtc';
+import { MockRTCServer } from './mockrtc-server';
+import { AnswerOptions, OfferOptions } from '../mockrtc-peer';
+
+const { deserialize } = PluggableAdmin.Serialization;
+type SerializedValue<T> = PluggableAdmin.Serialization.SerializedValue<T>;
+
+export interface SessionData {
+    id: string;
+    description: RTCSessionDescriptionInit
+}
+
+export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOptions, {}> {
+
+    private mockRTCServer!: MockRTCServer;
+
+    start(options: MockRTCOptions) {
+        this.mockRTCServer = new MockRTCServer(options);
+        return this.mockRTCServer.start();
+    }
+
+    reset() {}
+
+    stop() {
+        return this.mockRTCServer.stop();
+    }
+
+    schema = gql`
+        extend type Mutation {
+            createPeer(data: RTCHandlerData!): MockedPeer!
+
+            createOffer(peerId: ID!, sessionId: ID, options: Raw): Session!
+            createExternalOffer(peerId: ID!, options: Raw): Session!
+            completeOffer(peerId: ID!, sessionId: ID!, answer: SessionDescriptionInput!): Void
+
+            answerOffer(peerId: ID!, sessionId: ID, offer: SessionDescriptionInput!, options: Raw): Session!
+            answerExternalOffer(peerId: ID!, offer: SessionDescriptionInput!, options: Raw): Session!
+        }
+
+        input RTCHandlerData {
+            steps: [Raw!]!
+        }
+
+        type MockedPeer {
+            peerId: ID!
+        }
+
+        input SessionDescriptionInput {
+            type: String!
+            sdp: String!
+        }
+
+        type SessionDescriptionResult {
+            type: String!
+            sdp: String!
+        }
+
+        type Session {
+            id: ID!
+            description: SessionDescriptionResult
+        }
+
+        extend type Query {
+            getSeenMessages(peerId: ID!, channelName: String): [Raw!]
+        }
+
+        scalar HandlerStep
+    `;
+
+    buildResolvers(adminStream: stream.Duplex, ruleParams: {}): IResolvers {
+        return {
+            Mutation: {
+                createPeer: (__: any, { data: { steps } }: { data: {
+                    steps: Array<SerializedValue<HandlerStep>>
+                } }) => {
+                    return this.mockRTCServer.buildPeerFromData(
+                        steps.map((stepData) =>
+                            deserialize(stepData, adminStream, ruleParams, StepLookup)
+                        )
+                    );
+                },
+                createOffer: async (__: any, { peerId, sessionId, options }: {
+                    peerId: string,
+                    sessionId?: string,
+                    options?: OfferOptions
+                }): Promise<SessionData> => {
+                    const peer = this.mockRTCServer.getPeer(peerId);
+                    if (!peer) throw new Error("Id matches no active peer");
+
+                    if (sessionId) {
+                        const session = peer.getSession(sessionId);
+                        return {
+                            id: sessionId,
+                            description: await session.createOffer(options)
+                        };
+                    } else {
+                        const offerParams = await peer.createOffer(options);
+                        return {
+                            id: offerParams.session.sessionId,
+                            description: offerParams.offer
+                        };
+                    }
+                },
+                createExternalOffer: async (__: any, { peerId, options }: {
+                    peerId: string,
+                    options?: OfferOptions
+                }): Promise<SessionData> => {
+                    const peer = this.mockRTCServer.getPeer(peerId);
+                    if (!peer) throw new Error("Id matches no active peer");
+
+                    const offerParams = await peer.createExternalOffer(options);
+                    return {
+                        id: offerParams.id,
+                        description: offerParams.offer
+                    };
+                },
+                completeOffer: async (__: any, { peerId, sessionId, answer } : {
+                    peerId: string,
+                    sessionId: string,
+                    answer: RTCSessionDescriptionInit
+                }): Promise<void> => {
+                    const session = this.mockRTCServer.getPeer(peerId).getSession(sessionId);
+                    await session.completeOffer(answer);
+                },
+                answerOffer: async (__: any, { peerId, sessionId, offer, options } : {
+                    peerId: string,
+                    sessionId?: string,
+                    offer: RTCSessionDescriptionInit,
+                    options?: AnswerOptions
+                }): Promise<SessionData> => {
+                    const peer = this.mockRTCServer.getPeer(peerId);
+                    if (!peer) throw new Error("Id matches no active peer");
+
+                    if (sessionId) {
+                        const session = peer.getSession(sessionId);
+                        const answer = await session.answerOffer(offer, options);
+                        return { id: sessionId, description: answer };
+                    } else {
+                        const answerParams = await peer.answerOffer(offer, options);
+                        return {
+                            id: answerParams.session.sessionId,
+                            description: answerParams.answer
+                        };
+                    }
+                },
+                answerExternalOffer: async (__: any, { peerId, offer, options } : {
+                    peerId: string,
+                    offer: RTCSessionDescriptionInit,
+                    options?: AnswerOptions
+                }): Promise<SessionData> => {
+                    const peer = this.mockRTCServer.getPeer(peerId);
+                    if (!peer) throw new Error("Id matches no active peer");
+
+                    const answerParams = await peer.answerExternalOffer(offer, options);
+                    return {
+                        id: answerParams.id,
+                        description: answerParams.answer
+                    };
+                }
+            },
+            Query: {
+                getSeenMessages: async (__: any, { peerId, channelName }: {
+                    peerId: string,
+                    channelName?: string
+                }) => {
+                    const peer = this.mockRTCServer.getPeer(peerId);
+                    if (!peer) throw new Error("Id matches no active peer");
+
+                    const messages = await (channelName != undefined
+                        ? peer.getMessagesOnChannel(channelName)
+                        : peer.getAllMessages()
+                    );
+
+                    return messages.map((message) => {
+                        if (Buffer.isBuffer(message)) {
+                            return { type: 'buffer', value: message.toString('base64') };
+                        } else {
+                            return message;
+                        }
+                    });
+                }
+            }
+        };
+    }
+}

package/src/server/mockrtc-admin-server.ts

@@ -0,0 +1,17 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { PluggableAdmin } from 'mockttp';
+import { MockRTCAdminPlugin } from './mockrtc-admin-plugin';
+
+export class MockRTCAdminServer extends PluggableAdmin.AdminServer<{ webrtc: MockRTCAdminPlugin }> {
+
+    constructor() {
+        super({
+            adminPlugins: { webrtc: MockRTCAdminPlugin }
+        });
+    }
+
+}

package/src/server/mockrtc-server-peer.ts

@@ -0,0 +1,159 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { randomUUID } from 'crypto';
+
+import {
+    MockRTCPeer,
+    MockRTCPeerOptions,
+    MockRTCSession,
+    MockRTCAnswerParams,
+    MockRTCOfferParams,
+    MockRTCExternalAnswerParams,
+    MockRTCExternalOfferParams,
+    OfferOptions,
+    AnswerOptions
+} from "../mockrtc-peer";
+import { HandlerStep } from '../handling/handler-steps';
+
+import { RTCConnection } from '../webrtc/rtc-connection';
+import { MockRTCConnection } from '../webrtc/mockrtc-connection';
+import { DataChannelStream } from '../webrtc/datachannel-stream';
+
+export class MockRTCServerPeer implements MockRTCPeer {
+
+    readonly peerId = randomUUID();
+
+    // A list of all currently open connections managed by this peer
+    private readonly connections: { [id: string]: RTCConnection } = {};
+
+    // A subset of the connections: external connections with no assigned internal connection
+    private readonly unassignedExternalConnections: { [id: string]: RTCConnection } = {};
+
+    constructor(
+        private handlerSteps: HandlerStep[],
+        private options: MockRTCPeerOptions = {}
+    ) {}
+
+    private trackConnection(conn: RTCConnection) {
+        this.connections[conn.id] = conn;
+        conn.once('connection-closed', () => {
+            delete this.connections[conn.id];
+        });
+    }
+
+    private getExternalConnection = (id: string) => {
+        const externalConn = this.unassignedExternalConnections[id];
+        if (!externalConn) throw new Error(`Attempted to connect unknown external conn ${id}`);
+        delete this.unassignedExternalConnections[id];
+        return externalConn;
+    }
+
+    async createExternalOffer(options: OfferOptions = {}): Promise<MockRTCExternalOfferParams> {
+        const externalConn = new RTCConnection();
+        this.unassignedExternalConnections[externalConn.id] = externalConn;
+        this.trackConnection(externalConn);
+
+        return {
+            id: externalConn.id,
+            offer: await externalConn.sessionApi.createOffer(options),
+            session: externalConn.sessionApi,
+            setAnswer: async (answer: RTCSessionDescriptionInit) => {
+                externalConn.sessionApi.completeOffer(answer);
+            }
+        };
+    }
+
+    async answerExternalOffer(
+        offer: RTCSessionDescriptionInit,
+        options?: AnswerOptions
+    ): Promise<MockRTCExternalAnswerParams> {
+        const externalConn = new RTCConnection();
+        this.unassignedExternalConnections[externalConn.id] = externalConn;
+        this.trackConnection(externalConn);
+
+        return {
+            id: externalConn.id,
+            answer: await externalConn.sessionApi.answerOffer(offer, options),
+            session: externalConn.sessionApi
+        };
+    }
+
+    private createConnection() {
+        const conn = new MockRTCConnection(this.getExternalConnection);
+        this.trackConnection(conn);
+
+        this.handleConnection(conn).catch((error) => {
+            console.error("Error handling WebRTC connection:", error);
+            conn.close().catch(() => {});
+        });
+
+        if (this.options.recordMessages) {
+            conn.on('channel-open', (channel: DataChannelStream) => {
+                const channelLabel = channel.label;
+                const messageLog = (this.messages[channelLabel] ??= []);
+
+                channel.on('data', d => {
+                    messageLog.push(d);
+                });
+            });
+        }
+
+        return conn;
+    }
+
+    async createOffer(options: OfferOptions = {}): Promise<MockRTCOfferParams> {
+        const conn = this.createConnection();
+
+        return {
+            offer: await conn.sessionApi.createOffer(options),
+            session: conn.sessionApi,
+            setAnswer: async (answer) => {
+                conn.sessionApi.completeOffer(answer);
+            }
+        }
+    }
+
+    async answerOffer(offer: RTCSessionDescriptionInit, options: AnswerOptions = {}): Promise<MockRTCAnswerParams> {
+        const conn = this.createConnection();
+        return {
+            answer: await conn.sessionApi.answerOffer(offer, options),
+            session: conn.sessionApi
+        };
+    }
+
+    getSession(id: string): MockRTCSession {
+        return this.connections[id].sessionApi;
+    }
+
+    private async handleConnection(conn: MockRTCConnection) {
+        await conn.waitUntilConnected();
+
+        for (const step of this.handlerSteps) {
+            await step.handle(conn);
+        }
+
+        await conn.close();
+    }
+
+    async close() {
+        await Promise.all(
+            Object.values(this.connections).map(c =>
+                c.close()
+            )
+        );
+    }
+
+    private messages: { [channelName: string]: Array<string | Buffer> } = {};
+
+    async getAllMessages() {
+        return Object.values(this.messages).flat();
+    }
+
+    async getMessagesOnChannel(channelName: string) {
+        return this.messages[channelName].flat();
+    }
+
+}