mockrtc 0.1.0

package/src/handling/handler-builder.ts

@@ -0,0 +1,215 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    type HandlerStepDefinition,
+    PeerProxyStepDefinition,
+    SendStepDefinition,
+    DynamicProxyStepDefinition,
+    WaitForChannelStepDefinition,
+    WaitForMessageStepDefinition,
+    WaitForDurationStepDefinition,
+    CloseStepDefinition,
+    EchoStepDefinition,
+    WaitForTrackStepDefinition,
+    WaitForMediaStepDefinition
+} from "./handler-step-definitions";
+
+/**
+ * The builder logic for composing RTC handling behaviour for both mock peers and rules,
+ * by internally queuing defined actions until a `.thenX()` method is called to compile
+ * the actions into either a peer or a rule (handled by an constructor callback param).
+ */
+export class MockRTCHandlerBuilder<R> {
+
+    private handlerSteps: HandlerStepDefinition[] = [];
+
+    constructor(
+        private buildCallback: (handlerSteps: HandlerStepDefinition[]) => Promise<R>
+    ) {}
+
+    /**
+     * Wait for a given duration, in milliseconds
+     *
+     * @category Steps
+     */
+    sleep(duration: number): this {
+        this.handlerSteps.push(new WaitForDurationStepDefinition(duration));
+        return this;
+    }
+
+    /**
+     * Wait until the remote client has created at least one DataChannel.
+     *
+     * @category Steps
+     */
+    waitForChannel(channelLabel?: string): this {
+        this.handlerSteps.push(new WaitForChannelStepDefinition(channelLabel));
+        return this;
+    }
+
+    /**
+     * Wait until the remote client has created at least one media track
+     *
+     * @category Steps
+     */
+    waitForTrack(): this {
+        this.handlerSteps.push(new WaitForTrackStepDefinition());
+        return this;
+    }
+
+    /**
+     * Wait until the remote client next sends a message to us on any DataChannel.
+     *
+     * This looks for new messages, ignoring any messages already consumed by
+     * previous steps.
+     *
+     * @category Steps
+     */
+    waitForNextMessage(): this {
+        this.handlerSteps.push(new WaitForMessageStepDefinition());
+        return this;
+    }
+
+    /**
+     * Wait until the remote client next sends media data on a media track.
+     *
+     * This waits for new media, ignoring any media already consumed by previous steps.
+     *
+     * @category Steps
+     */
+    waitForNextMedia(): this {
+        this.handlerSteps.push(new WaitForMediaStepDefinition());
+        return this;
+    }
+
+    /**
+     * Wait until the remote client sends a message to us on a specific DataChannel.
+     *
+     * This looks for new messages, ignoring any messages already consumed by
+     * previous steps.
+     *
+    * @category Steps
+     */
+    waitForNextMessageOnChannel(channelLabel: string): this {
+        this.handlerSteps.push(new WaitForMessageStepDefinition(channelLabel));
+        return this;
+    }
+
+    /**
+     * Send a message or buffer on the connection's data channels.
+     *
+     * This can take one or two arguments. If only one is provided, it is used
+     * as a message that's sent on all open data channels. If two arguments are
+     * provided, the first must be the data channel label, and the message (the
+     * second) will be sent only to data channel(s) with that label.
+     *
+     * If no matching channels are open, this is a no-op. Use `waitForChannel()`
+     * to ensure the channels you're expecting are open first if necessary.
+     *
+    * @category Steps
+     */
+    send(message: string | Buffer): this;
+    send(channel: string | undefined, message: string | Buffer): this;
+    send(...args: [string | undefined, string | Buffer] | [string | Buffer]): this {
+        if (args[1] !== undefined) {
+            const [channel, message] = args as [string, string | Buffer];
+            this.handlerSteps.push(new SendStepDefinition(channel, message));
+        } else {
+            const [message] = args as [string | Buffer];
+            this.handlerSteps.push(new SendStepDefinition(undefined, message));
+        }
+        return this;
+    }
+
+    /**
+     * Immediately close the connection.
+     *
+     * This defines a final step, and will then create a mock peer from the full
+     * set of steps you've defined, and return it wrapped in a promise. As soon
+     * as the promise resolves the peer is ready to use.
+     *
+     * @category Final Steps
+     */
+    thenClose(): Promise<R> {
+        this.handlerSteps.push(new CloseStepDefinition());
+        return this.buildCallback(this.handlerSteps);
+    }
+
+    /**
+     * Send a message or buffer on the connection's data channels, then close the
+     * connection. This is equivalent to {@link send `.send()`} then
+     * {@link thenClose `.thenClose()`}.
+     *
+     * This defines a final step, and will then create a mock peer from the full
+     * set of steps you've defined, and return it wrapped in a promise. As soon
+     * as the promise resolves the peer is ready to use.
+     *
+     * @category Final Steps
+     */
+    thenSend(message: string | Buffer): Promise<R>;
+    thenSend(channel: string, message: string | Buffer): Promise<R>;
+    thenSend(...args: [string, string | Buffer] | [string | Buffer]): Promise<R> {
+        return this.send(...args as [string | undefined, string | Buffer])
+            .buildCallback(this.handlerSteps);
+    }
+
+    /**
+     * Echo all incoming data channel messages until the other peer closes the
+     * connection.
+     *
+     * This defines a final step, and will then create a mock peer from the full
+     * set of steps you've defined, and return it wrapped in a promise. As soon
+     * as the promise resolves the peer is ready to use.
+     *
+     * @category Final Steps
+     */
+    thenEcho(): Promise<R> {
+        this.handlerSteps.push(new EchoStepDefinition());
+        return this.buildCallback(this.handlerSteps);
+    }
+
+    /**
+     * Creates a new external connection to the given remote peer connection,
+     * matching the existing mocked connection, and then proxies all traffic
+     * through to that peer.
+     *
+     * This defines a final step, and will then create a mock peer from the full
+     * set of steps you've defined, and return it wrapped in a promise. As soon
+     * as the promise resolves the peer is ready to use.
+     *
+     * @category Final Steps
+     */
+    thenForwardTo(peer: RTCPeerConnection): Promise<R> {
+        this.handlerSteps.push(new PeerProxyStepDefinition(peer));
+        return this.buildCallback(this.handlerSteps);
+    }
+
+    /**
+     * Proxy this connection dynamically to the 'real' target peer, whoever
+     * that may be.
+     *
+     * This assumes that you have an existing external connection already
+     * set up and attached to this mock connection.
+     *
+     * You can do that either by using {@link hookWebRTCConnection} or
+     * {@link hookAllWebRTC} to hook your connection during normal setup to
+     * automatically create an external offer to the real remote peer, or you can
+     * do so manually using {@link MockRTCPeer.createExternalOffer} or
+     * {@link MockRTCPeer.answerExternalOffer} and then passing the connection
+     * id as {@link https://github.com/httptoolkit/mockrtc/blob/d0604f3111e0438c52aa514d00cf04ac0718dfeb/src/webrtc-hooks.ts#L83-L93 here}.
+     *
+     * This defines a final step, and will then create a mock peer from the full
+     * set of steps you've defined, and return it wrapped in a promise. As soon
+     * as the promise resolves the peer is ready to use.
+     *
+     * @category Final Steps
+     */
+    thenPassThrough(): Promise<R> {
+        this.handlerSteps.push(new DynamicProxyStepDefinition());
+        return this.buildCallback(this.handlerSteps);
+    }
+
+}

package/src/handling/handler-step-definitions.ts

@@ -0,0 +1,142 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as PluggableAdmin from 'mockttp/dist/pluggable-admin-api/pluggable-admin.browser';
+
+export type Serializable = PluggableAdmin.Serialization.Serializable;
+export const { Serializable } = PluggableAdmin.Serialization;
+type ClientServerChannel = PluggableAdmin.Serialization.ClientServerChannel;
+
+export interface HandlerStepDefinition extends Serializable {
+    readonly type: keyof typeof StepDefinitionLookup;
+}
+
+export class WaitForDurationStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'wait-for-duration';
+
+    constructor(
+        protected durationMs: number
+    ) {
+        super();
+    }
+
+}
+
+export class WaitForChannelStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'wait-for-channel';
+
+    constructor(
+        protected channelLabel?: string
+    ) {
+        super();
+    }
+}
+
+export class WaitForMessageStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'wait-for-message';
+
+    constructor(
+        protected channelLabel?: string
+    ) {
+        super();
+    }
+
+}
+
+export class WaitForTrackStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'wait-for-track';
+
+}
+
+export class WaitForMediaStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'wait-for-media';
+
+}
+
+export class SendStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'send-message';
+
+    constructor(
+        protected channelLabel: string | undefined,
+        protected message: string | Buffer
+    ) {
+        super();
+    }
+
+}
+
+export class CloseStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'close-connection';
+
+}
+
+export class EchoStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'echo-channels';
+
+}
+
+export class PeerProxyStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'peer-proxy';
+
+    protected getAnswer: (offer: RTCSessionDescriptionInit) => Promise<RTCSessionDescriptionInit>;
+
+    constructor(
+        connectionTarget:
+            | RTCPeerConnection
+            | ((offer: RTCSessionDescriptionInit) => Promise<RTCSessionDescriptionInit>)
+    ) {
+        super();
+        if (connectionTarget instanceof Function) {
+            this.getAnswer = connectionTarget;
+        } else {
+            this.getAnswer = async (offer: RTCSessionDescriptionInit) => {
+                await connectionTarget.setRemoteDescription(offer);
+                const answer = await connectionTarget.createAnswer();
+                await connectionTarget.setLocalDescription(answer);
+                return answer;
+            };
+        }
+    }
+
+    serialize(channel: ClientServerChannel): {} {
+        channel.onRequest<
+            { offer: RTCSessionDescriptionInit },
+            { answer: RTCSessionDescriptionInit }
+        >(async (msg) => {
+            return { answer: await this.getAnswer(msg.offer) };
+        });
+
+        return { type: this.type };
+    }
+
+}
+
+export class DynamicProxyStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'dynamic-proxy';
+
+}
+
+export const StepDefinitionLookup = {
+    'wait-for-duration': WaitForDurationStepDefinition,
+    'wait-for-channel': WaitForChannelStepDefinition,
+    'wait-for-track': WaitForTrackStepDefinition,
+    'wait-for-media': WaitForMediaStepDefinition,
+    'wait-for-message': WaitForMessageStepDefinition,
+    'send-message': SendStepDefinition,
+    'close-connection': CloseStepDefinition,
+    'echo-channels': EchoStepDefinition,
+    'peer-proxy': PeerProxyStepDefinition,
+    'dynamic-proxy': DynamicProxyStepDefinition
+};

package/src/handling/handler-steps.ts

@@ -0,0 +1,254 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { PluggableAdmin } from 'mockttp';
+
+import type { DataChannelStream } from '../webrtc/datachannel-stream';
+import type { MediaTrackStream } from '../webrtc/mediatrack-stream';
+import type { MockRTCConnection } from '../webrtc/mockrtc-connection';
+import { RTCConnection } from '../webrtc/rtc-connection';
+import {
+    StepDefinitionLookup,
+    CloseStepDefinition,
+    DynamicProxyStepDefinition,
+    EchoStepDefinition,
+    HandlerStepDefinition,
+    PeerProxyStepDefinition,
+    SendStepDefinition,
+    WaitForChannelStepDefinition,
+    WaitForDurationStepDefinition,
+    WaitForMediaStepDefinition,
+    WaitForMessageStepDefinition,
+    WaitForTrackStepDefinition
+} from './handler-step-definitions';
+
+type ClientServerChannel = PluggableAdmin.Serialization.ClientServerChannel;
+
+export interface HandlerStep extends HandlerStepDefinition {
+    handle(connection: MockRTCConnection): Promise<void>;
+}
+
+export class WaitForDurationStep extends WaitForDurationStepDefinition {
+
+    async handle(): Promise<void> {
+        return new Promise<void>((resolve) => setTimeout(resolve, this.durationMs));
+    }
+
+}
+
+export class WaitForChannelStep extends WaitForChannelStepDefinition {
+
+    private matchesChannel(channel: DataChannelStream) {
+        return this.channelLabel === undefined || this.channelLabel === channel.label;
+    }
+
+    async handle(connection: MockRTCConnection): Promise<void> {
+        return new Promise<void>((resolve) => {
+            const channelOpened = (channel: DataChannelStream) => {
+                if (this.matchesChannel(channel)) {
+                    connection.removeListener('remote-channel-open', channelOpened);
+                    resolve();
+                }
+            };
+
+            connection.on('remote-channel-open', channelOpened);
+            connection.remoteChannels.forEach(channelOpened);
+        });
+    }
+
+}
+
+export class WaitForMessageStep extends WaitForMessageStepDefinition {
+
+    private matchesChannel(channel: DataChannelStream) {
+        return this.channelLabel === undefined || this.channelLabel === channel.label;
+    }
+
+    async handle(connection: MockRTCConnection): Promise<void> {
+        return new Promise<void>((resolve) => {
+            const messageReceived = () => {
+                connection.removeListener('channel-open', listenForMessage);
+                connection.channels.forEach((channel) => {
+                    channel.removeListener('data', messageReceived);
+                    channel.pause();
+                });
+
+                resolve();
+            };
+
+            const listenForMessage = (channel: DataChannelStream) => {
+                if (this.matchesChannel(channel)) {
+                    channel.once('data', messageReceived);
+                }
+            }
+
+            connection.on('channel-open', listenForMessage);
+            connection.channels.forEach(listenForMessage);
+        });
+    }
+
+}
+
+export class WaitForTrackStep extends WaitForTrackStepDefinition {
+
+    async handle(connection: MockRTCConnection): Promise<void> {
+        await new Promise<void>((resolve) => {
+            if (connection.remoteMediaTracks.length) resolve();
+            else connection.once('remote-track-open', () => resolve());
+        });
+    }
+
+}
+
+export class WaitForMediaStep extends WaitForMediaStepDefinition {
+
+    async handle(connection: MockRTCConnection): Promise<void> {
+        return new Promise<void>((resolve) => {
+            const messageReceived = () => {
+                connection.removeListener('track-open', listenForData);
+                connection.mediaTracks.forEach((track) => {
+                    track.removeListener('data', messageReceived);
+                    track.pause();
+                });
+
+                resolve();
+            };
+
+            const listenForData = (track: MediaTrackStream) => {
+                track.once('data', messageReceived);
+            }
+
+            connection.on('track-open', listenForData);
+            connection.mediaTracks.forEach(listenForData);
+        });
+    }
+
+}
+
+export class SendStep extends SendStepDefinition {
+
+    private matchesChannel(channel: DataChannelStream) {
+        return this.channelLabel === undefined || this.channelLabel === channel.label;
+    }
+
+    async handle({ channels }: MockRTCConnection): Promise<void> {
+        await Promise.all(
+            channels
+            .filter((channel) => this.matchesChannel(channel))
+            .map((channel) => {
+                return new Promise<void>((resolve, reject) => {
+                    channel.write(this.message, (error: Error | null | undefined) => {
+                        if (error) reject(error);
+                        else resolve();
+                    });
+                });
+            })
+        );
+    }
+
+}
+
+export class CloseStep extends CloseStepDefinition {
+
+    async handle(connection: MockRTCConnection): Promise<void> {
+        await connection.close();
+    }
+
+}
+
+export class EchoStep extends EchoStepDefinition {
+
+    async handle(connection: MockRTCConnection): Promise<void> {
+        const echoContent = (stream: DataChannelStream | MediaTrackStream) => {
+            stream.pipe(stream);
+        };
+
+        connection.on('channel-open', echoContent);
+        connection.on('track-open', echoContent);
+        connection.channels.forEach(echoContent);
+        connection.mediaTracks.forEach(echoContent);
+
+        // This step keeps running indefinitely, until the connection closes
+        return new Promise<void>((resolve) => connection.on('connection-closed', resolve));
+    }
+
+}
+
+export class PeerProxyStep extends PeerProxyStepDefinition {
+
+    private externalConnections: RTCConnection[] = [];
+
+    async handle(connection: MockRTCConnection) {
+        const externalConn = new RTCConnection();
+        this.externalConnections.push(externalConn);
+
+        // We mirror the internal peer's SDP as an offer to the given connection:
+        const externalOffer = await externalConn.getMirroredLocalOffer(
+            connection.getRemoteDescription()!.sdp!
+        );
+        externalConn.setRemoteDescription(await this.getAnswer(externalOffer));
+
+        connection.proxyTrafficTo(externalConn);
+
+        // This step keeps running indefinitely, until the connection closes
+        return new Promise<void>((resolve) => connection.on('connection-closed', resolve));
+    }
+
+    serialize(channel: ClientServerChannel): {} {
+        channel.onRequest<
+            { offer: RTCSessionDescriptionInit },
+            { answer: RTCSessionDescriptionInit }
+        >(async (msg) => {
+            return { answer: await this.getAnswer(msg.offer) };
+        });
+
+        return { type: this.type };
+    }
+
+    static deserialize(_data: {}, channel: ClientServerChannel): PeerProxyStep {
+        return new PeerProxyStep(async (offer: RTCSessionDescriptionInit) => {
+            const response = await channel.request<
+                { offer: RTCSessionDescriptionInit },
+                { answer: RTCSessionDescriptionInit }
+            >({ offer });
+            return response.answer;
+        });
+    }
+
+    dispose(): void {
+        this.externalConnections.forEach(conn => conn.close());
+    }
+
+}
+
+export class DynamicProxyStep extends DynamicProxyStepDefinition {
+
+    private externalConnections: RTCConnection[] = [];
+
+    async handle(connection: MockRTCConnection) {
+        await connection.proxyTrafficToExternalConnection();
+
+        // This step keeps running indefinitely, until the connection closes
+        return new Promise<void>((resolve) => connection.on('connection-closed', resolve));
+    }
+
+    dispose(): void {
+        this.externalConnections.forEach(conn => conn.close());
+    }
+
+}
+
+export const StepLookup: typeof StepDefinitionLookup = {
+    'wait-for-duration': WaitForDurationStep,
+    'wait-for-channel': WaitForChannelStep,
+    'wait-for-track': WaitForTrackStep,
+    'wait-for-media': WaitForMediaStep,
+    'wait-for-message': WaitForMessageStep,
+    'send-message': SendStep,
+    'close-connection': CloseStep,
+    'echo-channels': EchoStep,
+    'peer-proxy': PeerProxyStep,
+    'dynamic-proxy': DynamicProxyStep
+};

package/src/main-browser.ts

@@ -0,0 +1,44 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+    MockRTC,
+    MockRTCOptions,
+} from "./mockrtc";
+import { MockRTCClient, MockRTCClientOptions } from "./client/mockrtc-client";
+
+export type {
+    MockRTC,
+    MockRTCOptions
+};
+
+export type {
+    MockRTCPeer,
+    MockRTCSession,
+    MockRTCOfferParams,
+    MockRTCAnswerParams,
+    MockRTCExternalOfferParams,
+    MockRTCExternalAnswerParams,
+    OfferOptions,
+    AnswerOptions
+} from './mockrtc-peer';
+
+export { MOCKRTC_CONTROL_CHANNEL } from './webrtc/control-channel';
+export {
+    hookWebRTCConnection,
+    hookAllWebRTC
+} from "./webrtc-hooks";
+
+export function getLocal(): MockRTC {
+    return new MockRTCClient();
+}
+
+export function getRemote(options: MockRTCClientOptions = {}): MockRTC {
+    return new MockRTCClient(options);
+}
+
+export function getAdminServer(): never {
+    throw new Error("Can't use MockRTC.getLocal() in a browser");
+}