mockrtc 0.1.0

package/src/server/mockrtc-server.ts

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MockRTC, MockRTCOptions, MockRTCPeerBuilder } from "../mockrtc";
+import { MockRTCServerPeer } from "./mockrtc-server-peer";
+import { MockRTCHandlerBuilder } from "../handling/handler-builder";
+import { HandlerStepDefinition } from "../handling/handler-step-definitions";
+import { StepLookup } from "../handling/handler-steps";
+
+export class MockRTCServer implements MockRTC {
+
+    constructor(
+        private options: MockRTCOptions = {}
+    ) {}
+
+    async start(): Promise<void> {}
+    async stop(): Promise<void> {
+        await Promise.all(
+            this.activePeers.map(peer =>
+                peer.close()
+            )
+        );
+        this._activePeers = {};
+    }
+
+    buildPeer(): MockRTCPeerBuilder {
+        return new MockRTCHandlerBuilder(this.buildPeerFromData);
+    }
+
+    buildPeerFromData = async (handlerStepDefinitions: HandlerStepDefinition[]): Promise<MockRTCServerPeer> => {
+        const handlerSteps = handlerStepDefinitions.map((definition) => {
+            return Object.assign(
+                Object.create(StepLookup[definition.type].prototype),
+                definition
+            );
+        });
+        const peer = new MockRTCServerPeer(handlerSteps, this.options);
+        this._activePeers[peer.peerId] = peer;
+        return peer;
+    }
+
+    private _activePeers: { [id: string]: MockRTCServerPeer } = {};
+    get activePeers(): Readonly<MockRTCServerPeer[]> {
+        return Object.values(this._activePeers);
+    }
+
+    getPeer(id: string): MockRTCServerPeer {
+        return this._activePeers[id];
+    }
+
+}

package/src/webrtc/control-channel.ts

@@ -0,0 +1,13 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// The WebRTC control channel name & protocol used when communicating metadata to about client
+// configuration, e.g. the external connection to bridge to.
+export const MOCKRTC_CONTROL_CHANNEL = "mockrtc.control-channel";
+
+// The type of valid messages that can be sent on a control channel:
+export type MockRTCControlMessage =
+    | { type: 'error', error: string }
+    | { type: 'attach-external', id: string }

package/src/webrtc/datachannel-stream.ts

@@ -0,0 +1,102 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as stream from 'stream';
+import * as NodeDataChannel from 'node-datachannel';
+
+/**
+ * Turns a node-datachannel DataChannel into a real Node.js stream, complete with
+ * buffering, backpressure (up to a point - if the buffer fills up, messages are dropped),
+ * and support for piping data elsewhere.
+ *
+ * Read & written data may be either UTF-8 strings or Buffers - this difference exists at
+ * the protocol level, and is preserved here throughout.
+ */
+export class DataChannelStream extends stream.Duplex {
+
+    constructor(
+        private rawChannel: NodeDataChannel.DataChannel,
+        streamOptions: {
+            // These are the only Duplex options supported:
+            readableHighWaterMark?: number | undefined;
+            writableHighWaterMark?: number | undefined;
+            allowHalfOpen?: boolean;
+        } = {}
+    ) {
+        super({
+            allowHalfOpen: false, // Default to autoclose on end().
+            ...streamOptions,
+            objectMode: true // Preserve the string/buffer distinction (WebRTC treats them differently)
+        });
+
+        rawChannel.onMessage((msg) => {
+            if (!this._readActive) return; // If the buffer is full, drop messages.
+
+            // If the push is rejected, we pause reading until the next call to _read().
+            this._readActive = this.push(msg);
+        });
+
+        // When the DataChannel closes, the readable & writable ends close
+        rawChannel.onClosed(() => {
+            this.push(null);
+            this.destroy();
+        });
+
+        rawChannel.onError((errMsg) => {
+            this.destroy(new Error(`DataChannel error: ${errMsg}`));
+        });
+
+        // Buffer all writes until the DataChannel opens
+        if (!rawChannel.isOpen()) {
+            this.cork();
+            rawChannel.onOpen(() => this.uncork());
+        }
+    }
+
+    private _readActive = true;
+    _read() {
+        // Stop dropping messages, if the buffer filling up meant we were doing so before.
+        this._readActive = true;
+    }
+
+    _write(chunk: string | Buffer | unknown, encoding: string, callback: (error: Error | null) => void) {
+        let sentOk: boolean;
+
+        try {
+            if (Buffer.isBuffer(chunk)) {
+                sentOk = this.rawChannel.sendMessageBinary(chunk);
+            } else if (typeof chunk === 'string') {
+                sentOk = this.rawChannel.sendMessage(chunk);
+            } else {
+                const typeName = (chunk as object).constructor.name || typeof chunk;
+                throw new Error(`Cannot write ${typeName} to DataChannel stream`);
+            }
+        } catch (err: any) {
+            return callback(err);
+        }
+
+        if (sentOk) {
+            callback(null);
+        } else {
+            callback(new Error("Failed to write to DataChannel"));
+        }
+    }
+
+    _final(callback: (error: Error | null) => void) {
+        if (!this.allowHalfOpen) this.destroy();
+        callback(null);
+    }
+
+    _destroy(maybeErr: Error | null, callback: (error: Error | null) => void) {
+        // When the stream is destroyed, we close the DataChannel.
+        this.rawChannel.close();
+        callback(maybeErr);
+    }
+
+    get label() {
+        return this.rawChannel.getLabel();
+    }
+
+}

package/src/webrtc/mediatrack-stream.ts

@@ -0,0 +1,135 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as stream from 'stream';
+import * as NodeDataChannel from 'node-datachannel';
+
+const { Direction } = NodeDataChannel;
+
+/**
+ * Turns a node-datachannel media track into a real Node.js stream, complete with
+ * buffering, backpressure (up to a point - if the buffer fills up, messages are dropped),
+ * and support for piping data elsewhere.
+ */
+export class MediaTrackStream extends stream.Duplex {
+
+    constructor(
+        private rawTrack: NodeDataChannel.Track,
+        streamOptions: {
+            // These are the only Duplex options supported:
+            readableHighWaterMark?: number | undefined;
+            writableHighWaterMark?: number | undefined;
+            allowHalfOpen?: boolean;
+        } = {}
+    ) {
+        super({
+            allowHalfOpen: false, // Default to autoclose on end().
+            ...streamOptions,
+        });
+
+        rawTrack.onMessage((msg) => {
+            if (!this._readActive) return; // If the buffer is full, drop messages.
+
+            // If the push is rejected, we pause reading until the next call to _read().
+            this._readActive = this.push(msg);
+        });
+
+        // When the DataChannel closes, the readable & writable ends close
+        rawTrack.onClosed(() => this.close());
+
+        rawTrack.onError((errMsg) => {
+            this.destroy(new Error(`Media track error: ${errMsg}`));
+        });
+
+        // Buffer all writes until the DataChannel opens
+        if (!rawTrack.isOpen()) {
+            this.cork();
+            rawTrack.onOpen(() => this.uncork());
+        }
+    }
+
+    private close() {
+        this.push(null);
+        this.destroy();
+    }
+
+    private _readActive = true;
+    _read() {
+        // Stop dropping messages, if the buffer filling up meant we were doing so before.
+        this._readActive = true;
+    }
+
+    _write(chunk: Buffer, _encoding: string, callback: (error: Error | null) => void) {
+        let sentOk: boolean;
+
+        if (this.rawTrack.isClosed()) {
+            // isClosed becomes true and writes start failing just before onClosed() fires, so here we
+            // drop pending writes as soon as we notice.
+            this.close();
+            return;
+        }
+
+        try {
+            sentOk = this.rawTrack.sendMessageBinary(chunk);
+        } catch (err: any) {
+            return callback(err);
+        }
+
+        if (sentOk) {
+            callback(null);
+        } else {
+            callback(new Error("Failed to write to media track"));
+        }
+    }
+
+    _writev(chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, callback: (error?: Error | null) => void) {
+        let sentOk: boolean;
+
+        if (this.rawTrack.isClosed()) {
+            // isClosed becomes true and writes start failing just before onClosed() fires, so here we
+            // drop pending writes as soon as we notice.
+            this.close();
+            return;
+        }
+
+        try {
+            sentOk = this.rawTrack.sendMessageBinary(
+                Buffer.concat(chunks.map(c => c.chunk))
+            );
+        } catch (err: any) {
+            return callback(err);
+        }
+
+        if (sentOk) {
+            callback(null);
+        } else {
+            callback(new Error("Failed to write to media track"));
+        }
+    }
+
+    _final(callback: (error: Error | null) => void) {
+        if (!this.allowHalfOpen) this.destroy();
+        callback(null);
+    }
+
+    _destroy(maybeErr: Error | null, callback: (error: Error | null) => void) {
+        // When the stream is destroyed, we close the DataChannel.
+        this.rawTrack.close();
+        callback(maybeErr);
+    }
+
+    get direction() {
+        return this.rawTrack.direction();
+    }
+
+    get mid() {
+        return this.rawTrack.mid();
+    }
+
+    get type() {
+        return this.rawTrack.type();
+    }
+
+}

package/src/webrtc/mockrtc-connection.ts

@@ -0,0 +1,164 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as NodeDataChannel from 'node-datachannel';
+
+import { MockRTCControlMessage, MOCKRTC_CONTROL_CHANNEL } from './control-channel';
+
+import { DataChannelStream } from './datachannel-stream';
+import { MediaTrackStream } from './mediatrack-stream';
+import { RTCConnection } from './rtc-connection';
+
+export class MockRTCConnection extends RTCConnection {
+
+    // If the client supports a MockRTC control channge to send extra metadata during mocking,
+    // they will create this at startup, and we'll track it here, separately from all other channels.
+    private controlChannel: DataChannelStream | undefined;
+    private externalConnection: RTCConnection | undefined;
+
+    constructor(
+        private getExternalConnection: (id: string) => RTCConnection
+    ) {
+        super();
+    }
+
+    protected trackNewChannel(channel: NodeDataChannel.DataChannel, options: { isLocal: boolean }) {
+        if (channel.getLabel() === MOCKRTC_CONTROL_CHANNEL && !options.isLocal) {
+            // We don't track the control channel like other channels - we handle it specially.
+            if (this.controlChannel) {
+                const error = new Error('Cannot open multiple control channels simultaneously');
+                channel.sendMessage(JSON.stringify({
+                    type: 'error',
+                    error: error.message
+                }));
+                setTimeout(() => channel.close(), 100);
+                throw error;
+            }
+
+            this.controlChannel = new DataChannelStream(channel);
+
+            this.controlChannel.on('data', (msg) => {
+                try {
+                    const controlMessage = JSON.parse(msg) as MockRTCControlMessage;
+
+                    if (controlMessage.type === 'attach-external') {
+                        if (this.externalConnection) {
+                            throw new Error('Cannot attach mock connection to multiple external connections');
+                        }
+                        this.externalConnection = this.getExternalConnection(controlMessage.id);
+
+                        this.emit('external-connection-attached');
+
+                        // We don't necessarily proxy traffic through to the external connection at this point,
+                        // that depends on the specific handling that's used here.
+                    } else {
+                        throw new Error(`Unrecognized control channel message: ${controlMessage.type}`);
+                    }
+                } catch (e: any) {
+                    console.warn("Failed to handle control channel message", e);
+                    this.controlChannel?.write(JSON.stringify({
+                        type: 'error',
+                        error: e.message || e
+                    }));
+                }
+            });
+
+            this.controlChannel.on('close', () => {
+                this.controlChannel = undefined;
+            });
+
+            this.controlChannel.on('error', (error) => {
+                console.error('Control channel error:', error);
+            });
+
+            return this.controlChannel!;
+        } else {
+            return super.trackNewChannel(channel, options);
+        }
+    }
+
+    async proxyTrafficToExternalConnection() {
+        if (!this.externalConnection) {
+            await new Promise((resolve) => this.once('external-connection-attached', resolve));
+        }
+
+        this.proxyTrafficTo(this.externalConnection!);
+    }
+
+    proxyTrafficTo(externalConnection: RTCConnection) {
+        /**
+         * When proxying traffic, you effectively have four peers, each with a connection endpoint:
+         * - The incoming RTCPeerConnection that we're mocking ('internal')
+         * - This MockRTC connection, with an associated MockRTCPeer that it will actually connect to ('mock')
+         * - A MockRTC external connection that will connect to the remote peer ('external')
+         * - The original remote peer that we're connecting to ('remote')
+         *
+         * Once the proxy is set up, the the connection structure works like so:
+         * INTERNAL <--> MOCK <--> EXTERNAL <--> REMOTE
+         *
+         * Here we connect the internal & external connections together, proxying all behaviours between the
+         * two so that from this point forwards every event on one is reflected on the other.
+         *
+         * Note that this isn't necessarily the initialization of either connection: the remote peer could
+         * have been connected for a while (sending data with no response), and the internal peer could have
+         * been fully interacting with steps before this point.
+         */
+
+
+        // Mirror connection closure:
+        this.on('connection-closed', () => externalConnection.close());
+        externalConnection.on('connection-closed', () => this.close());
+
+        /// --- Data channels: --- ///
+
+        // Forward *all* existing internal channels to the external connection:
+        this.channels.forEach((channel: DataChannelStream) => { // All channels, in case a previous step created one
+            const mirrorChannelStream = externalConnection.createDataChannel(channel.label);
+            channel.pipe(mirrorChannelStream).pipe(channel);
+        });
+
+        // Forward any existing external channels back to this peer connection. Note that we're mirroring
+        // *remote* channels only, so we skip the channels that we've just created above.
+        externalConnection.remoteChannels.forEach((channel: DataChannelStream) => {
+            const mirrorChannelStream = this.createDataChannel(channel.label);
+            channel.pipe(mirrorChannelStream).pipe(channel);
+        });
+
+        // If any new channels open in future, mirror them to the other peer:
+        [[this, externalConnection], [externalConnection, this]].forEach(([connA, connB]) => {
+            connA.on('remote-channel-open', (incomingChannel: DataChannelStream) => {
+                const mirrorChannelStream = connB.createDataChannel(incomingChannel.label);
+                incomingChannel.pipe(mirrorChannelStream).pipe(incomingChannel);
+            });
+        });
+
+        /// --- Media tracks: --- ///
+
+        // Note that while data channels will *not* have been negotiated before this point, so
+        // we can always assume that mock data channels need mirroring, media tracks are negotiated
+        // in the SDP, not in-band, and so any media track could already exist on the other side.
+
+        // For each track on the internal connection, proxy it to the corresponding external track:
+        this.mediaTracks.forEach((track: MediaTrackStream) => {
+            const externalStream = externalConnection.mediaTracks.find(({ mid }) => mid === track.mid);
+            if (externalStream) {
+                if (externalStream.type === track.type) {
+                    track.pipe(externalStream).pipe(track);
+                } else {
+                    throw new Error(`Mock & external streams with mid ${track.mid} have mismatched types (${
+                        track.type
+                    }/${
+                        externalStream.type
+                    })`);
+                }
+            } else {
+                // A mismatch in media streams means the external & mock peer negotiation isn't in sync!
+                // For now we just reject this case - later we should try to prompt a renegotiation.
+                throw new Error(`Mock has ${track.type} ${track.mid} but external does not`);
+            }
+        });
+    }
+
+}