mockrtc 0.2.0 → 0.3.0

package/src/mockrtc.ts

@@ -4,7 +4,10 @@
  */
 
 import type { MockRTCHandlerBuilder } from "./handling/handler-builder";
+import { HandlerStepDefinition } from "./handling/handler-step-definitions";
+import { MatcherDefinition } from "./matching/matcher-definitions";
 import type { ConnectionMetadata, MockRTCPeer } from "./mockrtc-peer";
+import { MockRTCRuleBuilder } from "./rule-builder";
 
 export interface MockRTCPeerBuilder extends MockRTCHandlerBuilder<MockRTCPeer> {}
 
@@ -155,6 +158,11 @@ export type MockRTCEventData = {
 
 export type MockRTCEvent = keyof MockRTCEventData;
 
+export type MockRTCRuleDefinition = {
+    matchers: MatcherDefinition[];
+    steps: HandlerStepDefinition[];
+};
+
 export interface MockRTC {
 
     /**
@@ -172,6 +180,23 @@ export interface MockRTC {
      */
     buildPeer(): MockRTCPeerBuilder;
 
+    /**
+     * Starting defining a mock WebRTC rule. This methods returns a rule builder,
+     * which can be configured to define which incoming connections should be
+     * matched, with methods like `.fromPageHostname(hostname)`.
+     *
+     * Once the matching is configured, start calling handler methods like
+     * `.send()` to define a series of steps to run for matching connections,
+     * and then call a `.thenX()` method to complete the definition and
+     * define the rule.
+     *
+     * The rule definition is not complete until the returned promise resolves.
+     * Once it has resolved successfully, any future connections to the peer
+     * returned by `getMatchingPeer()` will be matched against these rules,
+     * and will run the steps for the first matching rule found.
+     */
+    forConnections(): MockRTCRuleBuilder;
+
     /**
      * Get the rule-matching peer.
      *
@@ -193,6 +218,53 @@ export interface MockRTC {
 
     stop(): Promise<void>;
 
+    /**
+     * Subscribe to events to monitor WebRTC interactions across all peers managed by
+     * this MockRTC session. The events available include:
+     *
+     * - `peer-connected`
+     * - `peer-disconnected`
+     * - `external-peer-attached`
+     * - `data-channel-opened`
+     * - `data-channel-message-sent`
+     * - `data-channel-message-received`
+     * - `data-channel-closed`
+     * - `media-track-opened`
+     * - `media-track-stats`
+     * - `media-track-closed`
+     */
     on<E extends MockRTCEvent>(event: E, callback: (param: MockRTCEventData[E]) => void): Promise<void>;
 
+    /**
+     * Create a peer from a set of step definitions.
+     *
+     * This API is only useful if you're building peers from data programmatically,
+     * rather than using `buildPeer()` and `MockRTCPeerBuilder`, which are generally
+     * preferable otherwise.
+     */
+    buildPeerFromDefinition(
+        handlerStepDefinitions: HandlerStepDefinition[]
+    ): Promise<MockRTCPeer>;
+
+    /**
+     * Create a connection-matching rule from a set of matchers and step definitions.
+     *
+     * This API is only useful if you're building rule from data programmatically,
+     * rather than using `forX()` and `MockRTCHandlerBuilder`, which are generally
+     * preferable otherwise.
+     */
+    addRuleFromDefinition(
+        matcherDefinitions: MatcherDefinition[],
+        handlerStepDefinitions: HandlerStepDefinition[]
+    ): Promise<void>;
+
+    /**
+     * Create a connection-matching rule from a set of matchers and step definitions.
+     *
+     * This API is only useful if you're building rule from data programmatically,
+     * rather than using `forX()` and `MockRTCHandlerBuilder`, which are generally
+     * preferable otherwise.
+     */
+    setRulesFromDefinitions(rules: Array<MockRTCRuleDefinition>): Promise<void>;
+
 }

package/src/rule-builder.ts

@@ -0,0 +1,142 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MockRTCHandlerBuilder } from "./handling/handler-builder";
+import { HandlerStepDefinition } from "./handling/handler-step-definitions";
+import {
+    MatcherDefinition,
+    HostnameMatcherDefinition,
+    UrlRegexMatcherDefinition,
+    UserAgentRegexMatcherDefinition,
+    HasAudioTrackMatcherDefinition,
+    HasVideoTrackMatcherDefinition,
+    HasMediaTrackMatcherDefinition,
+    HasDataChannelMatcherDefinition
+} from "./matching/matcher-definitions";
+
+export type RuleHandlerBuilder = MockRTCHandlerBuilder<void>;
+
+/**
+ * Rule builders allow you to combine sets of matchers, progressively
+ * building a set of matching conditions, before defining the resulting
+ * behaviour that will be applied to matching traffic.
+ */
+export class MockRTCRuleBuilder implements Omit<RuleHandlerBuilder, 'handlerSteps' | 'buildCallback'> {
+
+    constructor(
+        private addRuleCallback: (
+            matcherDefinitions: MatcherDefinition[],
+            handlerStepDefinitions: HandlerStepDefinition[]
+        ) => Promise<void>
+    ) {}
+
+    private matchers: MatcherDefinition[] = [];
+
+    /**
+     * Match RTC connections whose initial negotiation includes a data channel.
+     */
+    withDataChannels() {
+        this.matchers.push(new HasDataChannelMatcherDefinition());
+        return this;
+    }
+
+    /**
+     * Match RTC connections whose initial negotiation includes either an audio or video
+     * media track.
+     */
+    withMedia() {
+        this.matchers.push(new HasMediaTrackMatcherDefinition());
+        return this;
+    }
+
+    /**
+     * Match RTC connections whose initial negotiation includes a video media track
+     */
+    withVideo() {
+        this.matchers.push(new HasVideoTrackMatcherDefinition());
+        return this;
+    }
+
+    /**
+     * Match RTC connections whose initial negotiation includes an audio media track
+     */
+    withAudio() {
+        this.matchers.push(new HasAudioTrackMatcherDefinition());
+        return this;
+    }
+
+    /**
+     * Match RTC connections made from hooked JavaScript running on a given hostname.
+     *
+     * This only matches connections with explicit `sourceURL` metadata, which must be
+     * either added automatically (by using the `hookAllWebRTC` or `hookWebRTCConnection`
+     * methods) or manually (by providing `metadata: { sourceURL: '...' }` options
+     * during mock connection setup).
+     *
+     * @category Matcher
+     */
+    fromPageHostname(hostname: string): this {
+        this.matchers.push(new HostnameMatcherDefinition(hostname));
+        return this;
+    }
+
+    /**
+     * Match RTC connections made from hooked JavaScript running on a matching URL.
+     *
+     * This only matches connections with explicit `sourceURL` metadata, which must be
+     * either added automatically (by using the `hookAllWebRTC` or `hookWebRTCConnection`
+     * methods) or manually (by providing `metadata: { sourceURL: '...' }` options
+     * during mock connection setup).
+     *
+     * @category Matcher
+     */
+    fromPageUrlMatching(urlRegex: RegExp): this {
+        this.matchers.push(new UrlRegexMatcherDefinition(urlRegex));
+        return this;
+    }
+
+    /**
+     * Match RTC connections made by hooked JavaScript running within a browser with a
+     * matching user agent string.
+     *
+     * This only matches connections with explicit `userAgent` metadata, which must be
+     * either added automatically (by using the `hookAllWebRTC` or `hookWebRTCConnection`
+     * methods) or manually (by providing `metadata: { userAgent: '...' }` options
+     * during mock connection setup).
+     *
+     * @category Matcher
+     */
+    fromUserAgentMatching(userAgentRegEx: RegExp): this {
+        this.matchers.push(new UserAgentRegexMatcherDefinition(userAgentRegEx));
+        return this;
+    }
+
+    // For all handler methods, return a handler builder - i.e. once you start calling
+    // any of these step-definition methods, you can't keep calling matcher methods:
+    private buildDefinitionMethod = <K extends keyof RuleHandlerBuilder>(
+        methodName: K
+    ) => ((...args: any[]) => {
+        const handlerBuilder = new MockRTCHandlerBuilder(
+            (steps) => this.addRuleCallback(this.matchers, steps)
+        );
+
+        return (handlerBuilder as any)[methodName](...args);
+    }) as RuleHandlerBuilder[K];
+
+    sleep = this.buildDefinitionMethod('sleep');
+    waitForChannel = this.buildDefinitionMethod('waitForChannel');
+    waitForTrack = this.buildDefinitionMethod('waitForTrack');
+    waitForNextMessage = this.buildDefinitionMethod('waitForNextMessage');
+    waitForNextMedia = this.buildDefinitionMethod('waitForNextMedia');
+    waitForNextMessageOnChannel = this.buildDefinitionMethod('waitForNextMessageOnChannel');
+    createDataChannel = this.buildDefinitionMethod('createDataChannel');
+    send = this.buildDefinitionMethod('send');
+    thenClose = this.buildDefinitionMethod('thenClose');
+    thenSend = this.buildDefinitionMethod('thenSend');
+    thenEcho = this.buildDefinitionMethod('thenEcho');
+    thenForwardTo = this.buildDefinitionMethod('thenForwardTo');
+    thenPassThrough = this.buildDefinitionMethod('thenPassThrough');
+
+}

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

@@ -10,10 +10,13 @@ import { PluggableAdmin } from 'mockttp';
 import type { IResolvers } from "@graphql-tools/utils";
 import { PubSub } from "graphql-subscriptions";
 
-import { HandlerStep, StepLookup } from '../handling/handler-steps';
+import { StepLookup } from '../handling/handler-steps';
 import { MockRTCOptions, MockRTCSessionDescription } from '../mockrtc';
 import { MockRTCServer } from './mockrtc-server';
 import { AnswerOptions, OfferOptions } from '../mockrtc-peer';
+import { MatcherDefinition } from '../matching/matcher-definitions';
+import { MatcherLookup } from '../matching/matchers';
+import { HandlerStepDefinition } from '../handling/handler-step-definitions';
 
 const { deserialize } = PluggableAdmin.Serialization;
 type SerializedValue<T> = PluggableAdmin.Serialization.SerializedValue<T>;
@@ -56,6 +59,8 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
     schema = gql`
         extend type Mutation {
             createPeer(data: RTCHandlerData!): MockedPeer!
+            addRTCRule(data: RTCRuleData!): Void
+            setRTCRules(data: [RTCRuleData!]!): Void
 
             createOffer(peerId: ID!, sessionId: ID, options: Raw): Session!
             createExternalOffer(peerId: ID!, options: Raw): Session!
@@ -69,6 +74,11 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
             steps: [Raw!]!
         }
 
+        input RTCRuleData {
+            matchers: [Raw!]!
+            steps: [Raw!]!
+        }
+
         type MockedPeer {
             peerId: ID!
         }
@@ -227,14 +237,42 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
         return {
             Mutation: {
                 createPeer: (__: any, { data: { steps } }: { data: {
-                    steps: Array<SerializedValue<HandlerStep>>
+                    steps: Array<SerializedValue<HandlerStepDefinition>>
                 } }) => {
-                    return this.mockRTCServer.buildPeerFromData(
+                    return this.mockRTCServer.buildPeerFromDefinition(
                         steps.map((stepData) =>
                             deserialize(stepData, adminStream, ruleParams, StepLookup)
                         )
                     );
                 },
+                addRTCRule: (__: any, { data: { steps, matchers } }: { data: {
+                    matchers: Array<SerializedValue<MatcherDefinition>>
+                    steps: Array<SerializedValue<HandlerStepDefinition>>
+                } }) => {
+                    return this.mockRTCServer.addRuleFromDefinition(
+                        matchers.map((matcherData) =>
+                            deserialize(matcherData, adminStream, ruleParams, MatcherLookup)
+                        ),
+                        steps.map((stepData) =>
+                            deserialize(stepData, adminStream, ruleParams, StepLookup)
+                        )
+                    );
+                },
+                setRTCRules: (__: any, { data: rules }: { data: Array<{
+                    matchers: Array<SerializedValue<MatcherDefinition>>
+                    steps: Array<SerializedValue<HandlerStepDefinition>>
+                }> }) => {
+                    return this.mockRTCServer.setRulesFromDefinitions(
+                        rules.map(({ matchers, steps }) => ({
+                            matchers: matchers.map((matcherData) =>
+                                deserialize(matcherData, adminStream, ruleParams, MatcherLookup)
+                            ),
+                            steps: steps.map((stepData) =>
+                                deserialize(stepData, adminStream, ruleParams, StepLookup)
+                            )
+                        }))
+                    );
+                },
                 createOffer: async (__: any, { peerId, sessionId, options }: {
                     peerId: string,
                     sessionId?: string,

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

@@ -39,7 +39,8 @@ export class MockRTCServerPeer implements MockRTCPeer {
     private readonly unassignedExternalConnections: { [id: string]: RTCConnection } = {};
 
     constructor(
-        private getHandlerSteps: (conn: RTCConnection) => HandlerStep[],
+        private getHandlerSteps: (conn: RTCConnection) =>
+            (HandlerStep[] | Promise<HandlerStep[]>),
         private options: MockRTCPeerOptions & { peerId?: string } = {},
         private eventEmitter: EventEmitter
     ) {
@@ -105,12 +106,16 @@ export class MockRTCServerPeer implements MockRTCPeer {
                         channelId: channelStream.id,
                     };
 
-                    this.eventEmitter.emit('data-channel-opened', {
-                        ...channelEventParams,
-                        channelLabel: channelStream.label,
-                        channelProtocol: channelStream.protocol,
-                        eventTimestamp: now()
-                    });
+                    const announceOpen = () => {
+                        this.eventEmitter.emit('data-channel-opened', {
+                            ...channelEventParams,
+                            channelLabel: channelStream.label,
+                            channelProtocol: channelStream.protocol,
+                            eventTimestamp: now()
+                        });
+                    };
+                    if (channelStream.isOpen) announceOpen();
+                    else channelStream.on('channel-open', announceOpen);
 
                     const emitMessage = (direction: 'sent' | 'received') => (data: Buffer | string) => {
                         const isBinary = Buffer.isBuffer(data);
@@ -137,7 +142,7 @@ export class MockRTCServerPeer implements MockRTCPeer {
                     }));
                 }
 
-                conn.on('channel-open', emitChannelEvents);
+                conn.on('channel-created', emitChannelEvents);
                 // Due to race conditions somewhere (?) presumably in node-datachannel, channels can
                 // be created before the 'connected' event fires, so we need to handle already
                 // existing channels here too:
@@ -149,12 +154,17 @@ export class MockRTCServerPeer implements MockRTCPeer {
                         trackMid: mediaTrack.mid
                     };
 
-                    this.eventEmitter.emit('media-track-opened', {
-                        ...trackEventParams,
-                        trackType: mediaTrack.type,
-                        trackDirection: mediaTrack.direction,
-                        eventTimestamp: now()
-                    });
+                    const announceOpen = () => {
+                        this.eventEmitter.emit('media-track-opened', {
+                            ...trackEventParams,
+                            trackType: mediaTrack.type,
+                            trackDirection: mediaTrack.direction,
+                            eventTimestamp: now()
+                        });
+                    };
+
+                    if (mediaTrack.isOpen) announceOpen();
+                    else mediaTrack.on('track-open', announceOpen);
 
                     let previousBytesSent = 0;
                     let previousBytesReceived = 0;
@@ -185,7 +195,7 @@ export class MockRTCServerPeer implements MockRTCPeer {
                     });
                 }
 
-                conn.on('track-open', emitTrackEvents);
+                conn.on('track-created', emitTrackEvents);
                 // Due to race conditions somewhere (?) presumably in node-datachannel, tracks can
                 // be created before the 'connected' event fires, so we need to handle already
                 // existing tracks here too:
@@ -255,13 +265,13 @@ export class MockRTCServerPeer implements MockRTCPeer {
                 const channelLabel = channel.label;
                 const messageLog = (this.messages[channelLabel] ??= []);
 
-                channel.on('data', d => {
+                channel.on('read-data', d => {
                     messageLog.push(d);
                 });
             };
 
             conn.channels.forEach(logChannelMessages);
-            conn.on('channel-open', logChannelMessages);
+            conn.on('channel-created', logChannelMessages);
         }
 
         return conn;
@@ -298,7 +308,7 @@ export class MockRTCServerPeer implements MockRTCPeer {
     private async handleConnection(conn: MockRTCConnection) {
         await conn.waitUntilConnected();
 
-        const handlerSteps = this.getHandlerSteps(conn);
+        const handlerSteps = await this.getHandlerSteps(conn);
 
         for (const step of handlerSteps) {
             await step.handle(conn);

package/src/server/mockrtc-server.ts

@@ -5,23 +5,27 @@
 
 import { EventEmitter } from "events";
 
-import { MockRTC, MockRTCEvent, MockRTCOptions, MockRTCPeerBuilder } from "../mockrtc";
+import { MockRTC, MockRTCEvent, MockRTCOptions } from "../mockrtc";
+import { MockRTCBase } from "../mockrtc-base";
 import { MockRTCServerPeer } from "./mockrtc-server-peer";
-import { MockRTCHandlerBuilder } from "../handling/handler-builder";
-import { HandlerStepDefinition } from "../handling/handler-step-definitions";
-import { DynamicProxyStep, StepLookup } from "../handling/handler-steps";
-import { RTCConnection } from "../main";
 import { MockRTCPeer } from "../mockrtc-peer";
+import { RTCConnection } from "../webrtc/rtc-connection";
+
+import type { MatcherDefinition } from "../matching/matcher-definitions";
+import { Matcher, MatcherLookup } from "../matching/matchers";
+import type { HandlerStepDefinition } from "../handling/handler-step-definitions";
+import { DynamicProxyStep, HandlerStep, StepLookup } from "../handling/handler-steps";
 
 const MATCHING_PEER_ID = 'matching-peer';
 
-export class MockRTCServer implements MockRTC {
+export class MockRTCServer extends MockRTCBase implements MockRTC {
 
     private debug: boolean = false;
 
     constructor(
         private options: MockRTCOptions = {}
     ) {
+        super();
         this.debug = !!options.debug;
     }
 
@@ -51,6 +55,7 @@ export class MockRTCServer implements MockRTC {
 
         this._activePeers = {};
         this.matchingPeer = undefined;
+        this.rules = [];
 
         this.eventEmitter.removeAllListeners();
     }
@@ -80,20 +85,71 @@ export class MockRTCServer implements MockRTC {
         return this.matchingPeer;
     }
 
-    private matchConnection(connection: RTCConnection) {
-        return [
-            new DynamicProxyStep()
-        ];
+    private rules: Array<{
+        matchers: Matcher[],
+        handlerSteps: HandlerStep[]
+    }> = [];
+
+    async setRulesFromDefinitions(
+        rules: Array<{
+            matchers: MatcherDefinition[],
+            steps: HandlerStepDefinition[]
+        }>
+    ) {
+        this.rules = [];
+        await Promise.all(rules.map(({ matchers, steps }) =>
+            this.addRuleFromDefinition(matchers, steps)
+        ));
     }
 
-    // Peer definition API:
+    async addRuleFromDefinition(
+        matcherDefinitions: MatcherDefinition[],
+        handlerStepDefinitions: HandlerStepDefinition[]
+    ) {
+        const matchers = matcherDefinitions.map((definition): Matcher => {
+            return Object.assign(
+                Object.create(MatcherLookup[definition.type].prototype),
+                definition
+            );
+        });
 
-    buildPeer(): MockRTCPeerBuilder {
-        return new MockRTCHandlerBuilder(this.buildPeerFromData);
+        const handlerSteps = handlerStepDefinitions.map((definition): HandlerStep => {
+            return Object.assign(
+                Object.create(StepLookup[definition.type].prototype),
+                definition
+            );
+        });
+
+        this.rules.push({ matchers, handlerSteps });
+    }
+
+    private async matchConnection(connection: RTCConnection) {
+        if (this.debug) console.log('Matching incoming RTC connection...');
+        await connection.waitUntilConnected();
+
+        for (const rule of this.rules) {
+            const matches = rule.matchers.every(matcher => matcher.matches(connection));
+
+            if (matches) {
+                if (this.debug) console.log(`Matched incoming RTC connection, running steps: ${
+                    rule.handlerSteps.map(s => s.type).join(', ')
+                }`);
+
+                return rule.handlerSteps;
+            }
+        }
+
+        if (this.debug) console.log('RTC connection did not match any rules');
+
+        // Unmatched connections are proxied dynamically. In practice, that means they're accepted
+        // and ignored initially, unless an external peer also connects and is attached:
+        return [new DynamicProxyStep()];
     }
 
-    buildPeerFromData = async (handlerStepDefinitions: HandlerStepDefinition[]): Promise<MockRTCServerPeer> => {
-        const handlerSteps = handlerStepDefinitions.map((definition) => {
+    // Peer definition API:
+
+    async buildPeerFromDefinition(handlerStepDefinitions: HandlerStepDefinition[]): Promise<MockRTCServerPeer> {
+        const handlerSteps = handlerStepDefinitions.map((definition): HandlerStep => {
             return Object.assign(
                 Object.create(StepLookup[definition.type].prototype),
                 definition

package/src/webrtc/datachannel-stream.ts

@@ -57,10 +57,24 @@ export class DataChannelStream extends stream.Duplex {
         // Buffer all writes until the DataChannel opens
         if (!rawChannel.isOpen()) {
             this.cork();
-            rawChannel.onOpen(() => this.uncork());
+            rawChannel.onOpen(() => {
+                this.uncork();
+                this._isOpen = true;
+                this.emit('channel-open');
+            });
+        } else {
+            setImmediate(() => {
+                this._isOpen = true;
+                this.emit('channel-open');
+            });
         }
     }
 
+    private _isOpen = false;
+    get isOpen() {
+        return this._isOpen;
+    }
+
     private _readActive = true;
     _read() {
         // Stop dropping messages, if the buffer filling up meant we were doing so before.

package/src/webrtc/mediatrack-stream.ts

@@ -48,10 +48,24 @@ export class MediaTrackStream extends stream.Duplex {
         // Buffer all writes until the DataChannel opens
         if (!rawTrack.isOpen()) {
             this.cork();
-            rawTrack.onOpen(() => this.uncork());
+            rawTrack.onOpen(() => {
+                this.uncork();
+                this._isOpen = true;
+                this.emit('track-open');
+            });
+        } else {
+            setImmediate(() => {
+                this._isOpen = true;
+                this.emit('track-open');
+            });
         }
     }
 
+    private _isOpen = false;
+    get isOpen() {
+        return this._isOpen;
+    }
+
     private _totalBytesSent = 0;
     get totalBytesSent() {
         return this._totalBytesSent;

package/src/webrtc/mockrtc-connection.ts

@@ -143,7 +143,7 @@ export class MockRTCConnection extends RTCConnection {
 
         // 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) => {
+            connA.on('remote-channel-created', (incomingChannel: DataChannelStream) => {
                 const mirrorChannelStream = connB.createDataChannel(incomingChannel.label);
                 incomingChannel.pipe(mirrorChannelStream).pipe(incomingChannel);
             });