mockrtc 0.1.0

package/karma.conf.ts

@@ -0,0 +1,89 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const CONTINUOUS = process.env.CONTINUOUS_TEST === 'true';
+const HEADFUL = process.env.HEADFUL_TEST === 'true';
+
+import * as ChildProcess from 'child_process';
+
+import { NodeModulesPolyfillPlugin } from '@esbuild-plugins/node-modules-polyfill';
+import { NodeGlobalsPolyfillPlugin } from '@esbuild-plugins/node-globals-polyfill';
+
+if (CONTINUOUS) {
+    const adminProc = ChildProcess.spawn(
+        "./node_modules/.bin/node-dev",
+        [
+            '--notify=false',
+            './test/start-test-admin-server.ts'
+        ],
+        { stdio: 'inherit' }
+    );
+
+    process.on('exit', () => adminProc.kill());
+
+    adminProc.on('exit', (code) => {
+        process.exit(code ?? 0); // Signalled = null = we killed it
+    });
+} else {
+    require('./test/start-test-admin-server');
+}
+
+module.exports = function(config: any) {
+    config.set({
+        frameworks: ['mocha', 'chai'],
+        files: [
+            'test/**/*.spec.ts'
+        ],
+        preprocessors: {
+            'src/**/*.ts': ['esbuild'],
+            'test/**/*.ts': ['esbuild']
+        },
+        esbuild: {
+            format: 'esm',
+            target: 'esnext',
+            plugins: [
+                NodeModulesPolyfillPlugin(),
+                NodeGlobalsPolyfillPlugin({
+                    process: true,
+                    buffer: true
+                })
+            ]
+        },
+        plugins: [
+            'karma-chrome-launcher',
+            'karma-chai',
+            'karma-mocha',
+            'karma-mocha-reporter',
+            'karma-esbuild'
+        ],
+
+        reporters: ['mocha'],
+        mochaReporter: {
+            showDiff: true
+        },
+
+        port: 9876,
+        logLevel: config.LOG_INFO,
+
+        browsers: HEADFUL
+            ? ['ChromeWithFakeMedia']
+            : ['ChromeHeadlessWithFakeMedia'],
+
+        customLaunchers: {
+            ChromeHeadlessWithFakeMedia: {
+                base: 'ChromeHeadless',
+                flags: ['--use-fake-ui-for-media-stream', '--use-fake-device-for-media-stream']
+            },
+            ChromeWithFakeMedia: {
+                base: 'Chrome',
+                flags: ['--use-fake-ui-for-media-stream', '--use-fake-device-for-media-stream']
+            }
+        },
+
+        autoWatch: CONTINUOUS,
+        singleRun: !CONTINUOUS,
+        concurrency: Infinity
+    });
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "mockrtc",
+  "version": "0.1.0",
+  "description": "Powerful friendly WebRTC mock peer & proxy",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
+  "browser": {
+    "dist/main.js": "./dist/main-browser.js",
+    "node-datachannel": false
+  },
+  "bin": {
+    "mockrtc": "./dist/admin-bin.js"
+  },
+  "sideEffects": [
+    "./test/**/*.spec.ts"
+  ],
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "build": "npm run build:src && npm run build:doc",
+    "build:src": "tsc && chmod +x ./dist/admin-bin.js",
+    "build:doc": "typedoc src/main.ts",
+    "prepack": "npm run build",
+    "test": "karma start",
+    "test:dev": "CONTINUOUS_TEST=true npm run test",
+    "test:dev:debug": "HEADFUL_TEST=true CONTINUOUS_TEST=true npm run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/httptoolkit/mockrtc.git"
+  },
+  "keywords": [
+    "webrtc",
+    "rtc",
+    "mock",
+    "test",
+    "proxy"
+  ],
+  "author": "Tim Perry <tim@httptoolkit.tech>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/httptoolkit/mockrtc/issues"
+  },
+  "homepage": "https://github.com/httptoolkit/mockrtc#readme",
+  "engines": {
+    "node": ">=14.17.0"
+  },
+  "devDependencies": {
+    "@esbuild-plugins/node-globals-polyfill": "^0.1.1",
+    "@esbuild-plugins/node-modules-polyfill": "^0.1.4",
+    "@types/chai": "4.3.0",
+    "@types/dom-mediacapture-transform": "0.1.2",
+    "@types/dom-webcodecs": "0.1.3",
+    "@types/mocha": "^9.1.0",
+    "buffer": "^6.0.3",
+    "chai": "^4.3.6",
+    "esbuild": "^0.14.23",
+    "karma": "^6.3.16",
+    "karma-chai": "^0.1.0",
+    "karma-chrome-launcher": "^3.1.0",
+    "karma-esbuild": "^2.2.2",
+    "karma-mocha": "^2.0.1",
+    "karma-mocha-reporter": "^2.2.5",
+    "mocha": "^9.2.0",
+    "node-dev": "^7.1.0",
+    "rollup-plugin-node-polyfills": "^0.2.1",
+    "ts-node": "^10.5.0",
+    "typedoc": "^0.23.0-beta.1",
+    "typescript": "^4.6.4",
+    "util": "^0.12.4"
+  },
+  "dependencies": {
+    "@types/sdp-transform": "^2.4.5",
+    "graphql": "^15.8.0",
+    "graphql-tag": "^2.12.6",
+    "mockttp": "^3.0.0",
+    "node-datachannel": "^0.3.0",
+    "sdp-transform": "^2.14.1"
+  },
+  "overrides": {
+    "ts-node": {
+      "typescript": "*"
+    }
+  }
+}

package/src/admin-bin.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import childProcess = require('child_process');
+import MockRTC = require('./main');
+
+handleArgs(process.argv).catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
+
+async function handleArgs(args: string[]) {
+    const remainingArgs = args.slice(2);
+    let nextArg = remainingArgs.shift();
+    while (nextArg) {
+        if (nextArg === '-c') {
+            await runCommandWithServer(remainingArgs.join(' '));
+            return;
+        } else {
+            break;
+        }
+    }
+
+    console.log("Usage: mockrtc -c <test command>");
+    process.exit(1);
+}
+
+async function runCommandWithServer(command: string) {
+    const server = MockRTC.getAdminServer();
+    await server.start();
+
+    let realProcess = childProcess.spawn(command, [], {
+        shell: true,
+        stdio: 'inherit'
+    });
+
+    realProcess.on('error', (error) => {
+        server.stop().then(function () {
+            console.error(error);
+            process.exit(1);
+        });
+    });
+
+    realProcess.on('exit', (code, signal) => {
+        server.stop().then(function () {
+            if (code == null) {
+                console.error('Executed process exited due to signal: ' + signal);
+                process.exit(1);
+            } else {
+                process.exit(code);
+            }
+        });
+    });
+}

package/src/client/mockrtc-client.ts

@@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import gql from 'graphql-tag';
+
+// Long-term, it'd be great to use the 'official' export path of mockttp/pluggable-admin, but
+// if we do so, then TypeScript <4.7 doesn't understand it here or downstream, so we get errors.
+// We don't want to use the main-exported version to avoid bundling all of Mockttp in browsers.
+// For now we have to use the direct import. We can update once TS 4.7 is widely used.
+import * as BrowserPluggableAdmin from 'mockttp/dist/pluggable-admin-api/pluggable-admin.browser';
+import type { PluggableAdmin } from 'mockttp';
+
+import { MockRTC, MockRTCOptions, MockRTCPeerBuilder } from "../mockrtc";
+
+import type { MockRTCAdminPlugin } from "../server/mockrtc-admin-plugin";
+import type { MockRTCPeer } from '../mockrtc-peer';
+import { MockRTCRemotePeer } from './mockrtc-remote-peer';
+import { MockRTCHandlerBuilder } from '../handling/handler-builder';
+import { HandlerStepDefinition } from '../handling/handler-step-definitions';
+
+export type MockRTCClientOptions =
+    PluggableAdmin.AdminClientOptions &
+    MockRTCOptions;
+
+export class MockRTCClient implements MockRTC {
+
+    private adminClient: PluggableAdmin.AdminClient<{ webrtc: MockRTCAdminPlugin }>;
+
+    constructor(
+        private options: MockRTCClientOptions = {}
+    ) {
+        this.adminClient = new BrowserPluggableAdmin.AdminClient(options);
+    }
+
+    buildPeer(): MockRTCPeerBuilder {
+        return new MockRTCHandlerBuilder(this.buildPeerFromData);
+    }
+
+    private buildPeerFromData = async (handlerSteps: HandlerStepDefinition[]): Promise<MockRTCPeer> => {
+        const { adminStream } = this.adminClient;
+
+        const peerData = await this.adminClient.sendQuery<
+            { createPeer: { peerId: string } },
+            { peerId: string }
+        >({
+            query: gql`
+                mutation CreatePeer($peerData: RTCHandlerData!) {
+                    createPeer(data: $peerData) {
+                        peerId
+                    }
+                }
+            `,
+            variables: {
+                peerData: {
+                    steps: handlerSteps.map(step =>
+                        BrowserPluggableAdmin.Serialization.serialize(step, adminStream)
+                    )
+                }
+            },
+            transformResponse: ({ createPeer }) => createPeer
+        });
+
+        const { peerId } = peerData;
+
+        return new MockRTCRemotePeer(peerId, this.adminClient);
+    }
+
+    async start(): Promise<void> {
+        await this.adminClient.start({
+            webrtc: this.options
+        });
+    }
+
+    async stop(): Promise<void> {
+        await this.adminClient.stop();
+    }
+}

package/src/client/mockrtc-remote-peer.ts

@@ -0,0 +1,286 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { gql } from 'graphql-tag';
+import * as PluggableAdmin from 'mockttp/dist/pluggable-admin-api/pluggable-admin.browser';
+
+import {
+    MockRTCPeer,
+    MockRTCOfferParams,
+    MockRTCExternalOfferParams,
+    MockRTCExternalAnswerParams,
+    MockRTCAnswerParams,
+    MockRTCSession,
+    OfferOptions,
+    AnswerOptions
+} from "../mockrtc-peer";
+import type { SessionData } from '../server/mockrtc-admin-plugin';
+
+export class MockRTCRemotePeer implements MockRTCPeer {
+
+    constructor(
+        readonly peerId: string,
+        private adminClient: PluggableAdmin.AdminClient<{}>
+    ) {}
+
+    createOffer(options?: OfferOptions): Promise<MockRTCOfferParams> {
+        return this.adminClient.sendQuery<
+            { createOffer: SessionData },
+            MockRTCOfferParams
+        >({
+            query: gql`
+                mutation GetPeerRTCOffer($peerId: ID!, $options: Raw) {
+                    createOffer(peerId: $peerId, options: $options) {
+                        id
+                        description {
+                            type
+                            sdp
+                        }
+                    }
+                }
+            `,
+            variables: { peerId: this.peerId, options },
+            transformResponse: ({ createOffer }) => {
+                const session = this.getSession(createOffer.id);
+                return {
+                    offer: createOffer.description,
+                    session,
+                    setAnswer: session.completeOffer.bind(session)
+                };
+            }
+        });
+    }
+
+    createExternalOffer(options?: OfferOptions): Promise<MockRTCExternalOfferParams> {
+        return this.adminClient.sendQuery<
+            { createExternalOffer: SessionData },
+            MockRTCExternalOfferParams
+        >({
+            query: gql`
+                mutation GetPeerRTCExternalOffer($peerId: ID!, $options: Raw) {
+                    createExternalOffer(peerId: $peerId, options: $options) {
+                        id
+                        description {
+                            type
+                            sdp
+                        }
+                    }
+                }
+            `,
+            variables: { peerId: this.peerId, options },
+            transformResponse: ({ createExternalOffer }) => {
+                const session = this.getSession(createExternalOffer.id);
+                return {
+                    id: createExternalOffer.id,
+                    offer: createExternalOffer.description,
+                    session,
+                    setAnswer: session.completeOffer.bind(session)
+                };
+            }
+        });
+    }
+
+    async answerOffer(
+        offer: RTCSessionDescriptionInit,
+        options?: AnswerOptions
+    ): Promise<MockRTCAnswerParams> {
+        return this.adminClient.sendQuery<
+            { answerOffer: SessionData },
+            MockRTCAnswerParams
+        >({
+            query: gql`
+                mutation GetPeerRTCAnswer(
+                    $peerId: ID!,
+                    $offer: SessionDescriptionInput!,
+                    $options: Raw
+                ) {
+                    answerOffer(peerId: $peerId, offer: $offer, options: $options) {
+                        id
+                        description {
+                            type
+                            sdp
+                        }
+                    }
+                }
+            `,
+            variables: { peerId: this.peerId, offer, options },
+            transformResponse: ({ answerOffer }) => ({
+                answer: answerOffer.description,
+                session: this.getSession(answerOffer.id)
+            })
+        });
+    }
+
+    async answerExternalOffer(
+        offer: RTCSessionDescriptionInit,
+        options?: AnswerOptions
+    ): Promise<MockRTCExternalAnswerParams> {
+        return this.adminClient.sendQuery<
+            { answerExternalOffer: SessionData },
+            MockRTCExternalAnswerParams
+        >({
+            query: gql`
+                mutation GetPeerRTCExternalAnswer(
+                    $peerId: ID!,
+                    $offer: SessionDescriptionInput!,
+                    $options: Raw
+                ) {
+                    answerExternalOffer(peerId: $peerId, offer: $offer, options: $options) {
+                        id
+                        description {
+                            type
+                            sdp
+                        }
+                    }
+                }
+            `,
+            variables: { peerId: this.peerId, offer, options },
+            transformResponse: ({ answerExternalOffer }) => {
+                const session = this.getSession(answerExternalOffer.id);
+                return {
+                    id: answerExternalOffer.id,
+                    answer: answerExternalOffer.description,
+                    session
+                }
+            }
+        });
+    }
+
+    getSession(sessionId: string): MockRTCSession {
+        return new RemoteSessionApi(this.adminClient, this.peerId, sessionId);
+    }
+
+    getAllMessages() {
+        return this.adminClient.sendQuery<
+            { getSeenMessages: Array<string | { type: 'buffer', value: string }> },
+            Array<string | Buffer>
+        >({
+            query: gql`
+                query GetPeerSeenMessages($peerId: ID!) {
+                    getSeenMessages(peerId: $peerId)
+                }
+            `,
+            variables: { peerId: this.peerId },
+            transformResponse: ({ getSeenMessages }) => {
+                return getSeenMessages.map((message) => {
+                    if (typeof message === 'string') {
+                        return message;
+                    } else if (message.type === 'buffer') {
+                        return Buffer.from(message.value, 'base64');
+                    } else {
+                        throw new Error(`Unparseable message data: ${JSON.stringify(message)}`);
+                    }
+                });
+            }
+        });
+    }
+
+    getMessagesOnChannel(channelName: string): Promise<Array<string | Buffer>> {
+        return this.adminClient.sendQuery<
+            { getSeenMessages: Array<string | { type: 'buffer', value: string }> },
+            Array<string | Buffer>
+        >({
+            query: gql`
+                query GetPeerSeenMessages($peerId: ID!, $channelName: String) {
+                    getSeenMessages(peerId: $peerId, channelName: $channelName)
+                }
+            `,
+            variables: { peerId: this.peerId, channelName },
+            transformResponse: ({ getSeenMessages }) => {
+                return getSeenMessages.map((message) => {
+                    if (typeof message === 'string') {
+                        return message;
+                    } else if (message.type === 'buffer') {
+                        return Buffer.from(message.value, 'base64');
+                    } else {
+                        throw new Error(`Unparseable message data: ${JSON.stringify(message)}`);
+                    }
+                });
+            }
+        });
+    }
+
+}
+
+class RemoteSessionApi implements MockRTCSession {
+    constructor(
+        private adminClient: PluggableAdmin.AdminClient<{}>,
+        private peerId: string,
+        public readonly sessionId: string
+    ) {}
+
+    createOffer(options?: OfferOptions): Promise<RTCSessionDescriptionInit> {
+        return this.adminClient.sendQuery<
+            { createOffer: SessionData },
+            RTCSessionDescriptionInit
+        >({
+            query: gql`
+                mutation GetPeerRTCSessionOffer($peerId: ID!, $sessionId: ID!, $options: Raw) {
+                    createOffer(peerId: $peerId, sessionId: $sessionId, options: $options) {
+                        description {
+                            type
+                            sdp
+                        }
+                    }
+                }
+            `,
+            variables: { peerId: this.peerId, sessionId: this.sessionId, options },
+            transformResponse: ({ createOffer }) => createOffer.description
+        });
+    }
+
+    completeOffer(answer: RTCSessionDescriptionInit): Promise<void> {
+        return this.adminClient.sendQuery<void>({
+            query: gql`
+                mutation CompletePeerRTCOffer(
+                    $peerId: ID!,
+                    $sessionId: ID!,
+                    $answer: SessionDescriptionInput!
+                ) {
+                    completeOffer(peerId: $peerId, sessionId: $sessionId, answer: $answer)
+                }
+            `,
+            variables: {
+                peerId: this.peerId,
+                sessionId: this.sessionId,
+                answer: answer
+            }
+        });
+    }
+
+    answerOffer(
+        offer: RTCSessionDescriptionInit,
+        options?: AnswerOptions
+    ): Promise<RTCSessionDescriptionInit> {
+        return this.adminClient.sendQuery<
+            { answerOffer: SessionData },
+            RTCSessionDescriptionInit
+        >({
+            query: gql`
+                mutation GetPeerRTCAnswer(
+                    $peerId: ID!,
+                    $sessionId: ID!,
+                    $offer: SessionDescriptionInput!,
+                    $options: Raw
+                ) {
+                    answerOffer(peerId: $peerId, sessionId: $sessionId, offer: $offer, options: $options) {
+                        description {
+                            type
+                            sdp
+                        }
+                    }
+                }
+            `,
+            variables: {
+                peerId: this.peerId,
+                sessionId: this.sessionId,
+                offer,
+                options
+            },
+            transformResponse: ({ answerOffer }) => answerOffer.description
+        });
+    }
+
+}