mockrtc 0.2.0 → 0.3.0

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

@@ -20,76 +20,125 @@ export class WaitForDurationStepDefinition extends Serializable implements Handl
     readonly type = 'wait-for-duration';
 
     constructor(
-        protected durationMs: number
+        public readonly durationMs: number
     ) {
         super();
     }
 
+    explain() {
+        return `wait for ${this.durationMs}ms`;
+    }
+
 }
 
 export class WaitForChannelStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'wait-for-channel';
+    readonly type = 'wait-for-rtc-data-channel';
 
     constructor(
-        protected channelLabel?: string
+        public readonly channelLabel?: string
     ) {
         super();
     }
+
+    explain() {
+        return `wait for an RTC channel${this.channelLabel ? ` labelled '${this.channelLabel}'` : ''}`;
+    }
+
 }
 
 export class WaitForMessageStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'wait-for-message';
+    readonly type = 'wait-for-rtc-message';
 
     constructor(
-        protected channelLabel?: string
+        public readonly channelLabel?: string
     ) {
         super();
     }
 
+    explain() {
+        return `wait for an RTC message${this.channelLabel ? ` on channel '${this.channelLabel}'` : ''}`;
+    }
+
 }
 
 export class WaitForTrackStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'wait-for-track';
+    readonly type = 'wait-for-rtc-track';
+
+    explain() {
+        return `wait for an RTC track`;
+    }
 
 }
 
 export class WaitForMediaStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'wait-for-media';
+    readonly type = 'wait-for-rtc-media';
+
+    explain() {
+        return `wait for RTC media data`;
+    }
+
+}
+
+export class CreateChannelStepDefinition extends Serializable implements HandlerStepDefinition {
+
+    readonly type = 'create-rtc-data-channel';
+
+    constructor(
+        public readonly channelLabel: string
+    ) {
+        super();
+    }
+
+    explain() {
+        return `create an RTC data channel labelled '${this.channelLabel}'`;
+    }
 
 }
 
 export class SendStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'send-message';
+    readonly type = 'send-rtc-data-message';
 
     constructor(
-        protected channelLabel: string | undefined,
-        protected message: string | Buffer
+        public readonly channelLabel: string | undefined,
+        public readonly message: string | Buffer
     ) {
         super();
     }
 
+    explain() {
+        return `send an RTC data message${this.channelLabel ? ` on channel '${this.channelLabel}'` : ''}`;
+    }
+
 }
 
 export class CloseStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'close-connection';
+    readonly type = 'close-rtc-connection';
+
+    explain() {
+        return `close the RTC connection`;
+    }
 
 }
 
 export class EchoStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'echo-channels';
+    readonly type = 'echo-rtc';
+
+    explain() {
+        return `echo all RTC media & data`;
+    }
 
 }
 
 export class PeerProxyStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'peer-proxy';
+    readonly type = 'rtc-peer-proxy';
 
     protected getAnswer: (offer: MockRTCSessionDescription) => Promise<RTCSessionDescriptionInit>;
 
@@ -111,6 +160,10 @@ export class PeerProxyStepDefinition extends Serializable implements HandlerStep
         }
     }
 
+    explain() {
+        return `proxy the RTC connection to the configured peer`;
+    }
+
     serialize(channel: ClientServerChannel): {} {
         channel.onRequest<
             { offer: MockRTCSessionDescription },
@@ -126,19 +179,24 @@ export class PeerProxyStepDefinition extends Serializable implements HandlerStep
 
 export class DynamicProxyStepDefinition extends Serializable implements HandlerStepDefinition {
 
-    readonly type = 'dynamic-proxy';
+    readonly type = 'rtc-dynamic-proxy';
+
+    explain() {
+        return `proxy the RTC connection to a remote peer`;
+    }
 
 }
 
 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
+    'wait-for-rtc-data-channel': WaitForChannelStepDefinition,
+    'wait-for-rtc-track': WaitForTrackStepDefinition,
+    'wait-for-rtc-media': WaitForMediaStepDefinition,
+    'wait-for-rtc-message': WaitForMessageStepDefinition,
+    'create-rtc-data-channel': CreateChannelStepDefinition,
+    'send-rtc-data-message': SendStepDefinition,
+    'close-rtc-connection': CloseStepDefinition,
+    'echo-rtc': EchoStepDefinition,
+    'rtc-peer-proxy': PeerProxyStepDefinition,
+    'rtc-dynamic-proxy': DynamicProxyStepDefinition
 };

package/src/handling/handler-steps.ts

@@ -17,6 +17,7 @@ import {
     EchoStepDefinition,
     HandlerStepDefinition,
     PeerProxyStepDefinition,
+    CreateChannelStepDefinition,
     SendStepDefinition,
     WaitForChannelStepDefinition,
     WaitForDurationStepDefinition,
@@ -70,7 +71,7 @@ export class WaitForMessageStep extends WaitForMessageStepDefinition {
     async handle(connection: MockRTCConnection): Promise<void> {
         return new Promise<void>((resolve) => {
             const messageReceived = () => {
-                connection.removeListener('channel-open', listenForMessage);
+                connection.removeListener('channel-created', listenForMessage);
                 connection.channels.forEach((channel) => {
                     channel.removeListener('data', messageReceived);
                     channel.pause();
@@ -85,7 +86,7 @@ export class WaitForMessageStep extends WaitForMessageStepDefinition {
                 }
             }
 
-            connection.on('channel-open', listenForMessage);
+            connection.on('channel-created', listenForMessage);
             connection.channels.forEach(listenForMessage);
         });
     }
@@ -108,7 +109,7 @@ export class WaitForMediaStep extends WaitForMediaStepDefinition {
     async handle(connection: MockRTCConnection): Promise<void> {
         return new Promise<void>((resolve) => {
             const messageReceived = () => {
-                connection.removeListener('track-open', listenForData);
+                connection.removeListener('track-created', listenForData);
                 connection.mediaTracks.forEach((track) => {
                     track.removeListener('data', messageReceived);
                     track.pause();
@@ -121,13 +122,24 @@ export class WaitForMediaStep extends WaitForMediaStepDefinition {
                 track.once('data', messageReceived);
             }
 
-            connection.on('track-open', listenForData);
+            connection.on('track-created', listenForData);
             connection.mediaTracks.forEach(listenForData);
         });
     }
 
 }
 
+export class CreateChannelStep extends CreateChannelStepDefinition {
+
+    async handle(conn: MockRTCConnection): Promise<void> {
+        const channel = conn.createDataChannel(this.channelLabel);
+        return new Promise<void>((resolve) =>
+            channel.once('channel-open', resolve)
+        );
+    }
+
+}
+
 export class SendStep extends SendStepDefinition {
 
     private matchesChannel(channel: DataChannelStream) {
@@ -166,8 +178,8 @@ export class EchoStep extends EchoStepDefinition {
             stream.pipe(stream);
         };
 
-        connection.on('channel-open', echoContent);
-        connection.on('track-open', echoContent);
+        connection.on('channel-created', echoContent);
+        connection.on('track-created', echoContent);
         connection.channels.forEach(echoContent);
         connection.mediaTracks.forEach(echoContent);
 
@@ -243,13 +255,14 @@ export class DynamicProxyStep extends DynamicProxyStepDefinition {
 
 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
+    'wait-for-rtc-data-channel': WaitForChannelStep,
+    'wait-for-rtc-track': WaitForTrackStep,
+    'wait-for-rtc-media': WaitForMediaStep,
+    'wait-for-rtc-message': WaitForMessageStep,
+    'create-rtc-data-channel': CreateChannelStep,
+    'send-rtc-data-message': SendStep,
+    'close-rtc-connection': CloseStep,
+    'echo-rtc': EchoStep,
+    'rtc-peer-proxy': PeerProxyStep,
+    'rtc-dynamic-proxy': DynamicProxyStep
 };

package/src/main-browser.ts

@@ -11,6 +11,7 @@ import { MockRTCClient, MockRTCClientOptions } from "./client/mockrtc-client";
 
 // Export the required structures to remotely build and send rules to the admin API:
 export * as HandlerStepDefinitions from "./handling/handler-step-definitions";
+export * as MatcherDefinitions from "./matching/matcher-definitions";
 export { MockRTCAdminRequestBuilder } from "./client/mockrtc-admin-request-builder";
 
 export type {

package/src/main.ts

@@ -9,6 +9,7 @@ import {
     MockRTCPeerBuilder,
     MockRTCEvent,
     MockRTCEventData,
+    MockRTCRuleDefinition,
     MockRTCSessionDescription,
     SelectedRTCCandidate,
     TimingEvents
@@ -22,16 +23,18 @@ import { MockRTCClient, MockRTCClientOptions } from "./client/mockrtc-client";
 
 // Export the required structures to remotely build and send rules to the admin API:
 export * as HandlerStepDefinitions from "./handling/handler-step-definitions";
+export * as MatcherDefinitions from "./matching/matcher-definitions";
 export { MockRTCAdminRequestBuilder } from "./client/mockrtc-admin-request-builder";
 
 // Re-export lots of types are used in various APIs (mostly to make TypeDoc happy):
 export type { HandlerStep } from "./handling/handler-steps";
 export type { MockRTCHandlerBuilder } from "./handling/handler-builder";
+export type { MockRTCRuleBuilder, RuleHandlerBuilder } from "./rule-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 { RTCConnection, ParsedSDP } 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";
@@ -46,6 +49,7 @@ export type {
     MockRTCAdminServer,
     MockRTCEvent,
     MockRTCEventData,
+    MockRTCRuleDefinition,
     MockRTCSessionDescription,
     SelectedRTCCandidate,
     TimingEvents

package/src/matching/matcher-definitions.ts

@@ -0,0 +1,109 @@
+/*
+ * 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;
+
+export interface MatcherDefinition extends Serializable {
+    readonly type: keyof typeof MatcherDefinitionLookup;
+}
+
+export class HasDataChannelMatcherDefinition extends Serializable implements MatcherDefinition {
+    readonly type = 'has-rtc-data-channel';
+
+    explain() {
+        return `with a data channel`;
+    }
+}
+
+export class HasVideoTrackMatcherDefinition extends Serializable implements MatcherDefinition {
+    readonly type = 'has-rtc-video-track';
+
+    explain() {
+        return `with a video track`;
+    }
+}
+
+export class HasAudioTrackMatcherDefinition extends Serializable implements MatcherDefinition {
+    readonly type = 'has-rtc-audio-track';
+
+    explain() {
+        return `with an audio track`;
+    }
+}
+
+export class HasMediaTrackMatcherDefinition extends Serializable implements MatcherDefinition {
+    readonly type = 'has-rtc-media-track';
+
+    explain() {
+        return `with any media track`;
+    }
+}
+
+export class HostnameMatcherDefinition extends Serializable implements MatcherDefinition {
+
+    readonly type = 'rtc-page-hostname';
+
+    constructor(
+        public readonly hostname: string
+    ) {
+        super();
+    }
+
+    explain() {
+        return `from a page on ${this.hostname}`;
+    }
+
+}
+
+export class UrlRegexMatcherDefinition extends Serializable implements MatcherDefinition {
+
+    readonly type = 'rtc-page-regex';
+
+    readonly regexSource: string;
+    readonly regexFlags: string;
+
+    constructor(regex: RegExp) {
+        super();
+        this.regexSource = regex.source;
+        this.regexFlags = regex.flags;
+    }
+
+    explain() {
+        return `from a page with URL matching /${this.regexSource}/${this.regexFlags}`;
+    }
+
+}
+
+export class UserAgentRegexMatcherDefinition  extends Serializable implements MatcherDefinition {
+
+    readonly type = 'rtc-user-agent-regex';
+
+    readonly regexSource: string;
+    readonly regexFlags: string;
+
+    constructor(regex: RegExp) {
+        super();
+        this.regexSource = regex.source;
+        this.regexFlags = regex.flags;
+    }
+
+    explain() {
+        return `from a user agent matching /${this.regexSource}/${this.regexFlags}`;
+    }
+
+}
+
+export const MatcherDefinitionLookup = {
+    'has-rtc-data-channel': HasDataChannelMatcherDefinition,
+    'has-rtc-video-track': HasVideoTrackMatcherDefinition,
+    'has-rtc-audio-track': HasAudioTrackMatcherDefinition,
+    'has-rtc-media-track': HasMediaTrackMatcherDefinition,
+    'rtc-page-hostname': HostnameMatcherDefinition,
+    'rtc-page-regex': UrlRegexMatcherDefinition,
+    'rtc-user-agent-regex': UserAgentRegexMatcherDefinition
+};

package/src/matching/matchers.ts

@@ -0,0 +1,118 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { RTCConnection } from "../webrtc/rtc-connection";
+import {
+    MatcherDefinition,
+    MatcherDefinitionLookup,
+    HasAudioTrackMatcherDefinition,
+    HasDataChannelMatcherDefinition,
+    HasMediaTrackMatcherDefinition,
+    HasVideoTrackMatcherDefinition,
+    HostnameMatcherDefinition,
+    UrlRegexMatcherDefinition,
+    UserAgentRegexMatcherDefinition
+} from "./matcher-definitions";
+
+export interface Matcher extends MatcherDefinition {
+    matches(connection: RTCConnection): boolean;
+}
+
+export class HasDataChannelMatcher extends HasDataChannelMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        return [
+            ...connection.getLocalDescription()!.parsedSdp.media,
+            ...connection.getRemoteDescription()!.parsedSdp.media
+        ].some(media => media.type === 'application');
+    }
+
+}
+
+export class HasVideoTrackMatcher extends HasVideoTrackMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        return [
+            ...connection.getLocalDescription()!.parsedSdp.media,
+            ...connection.getRemoteDescription()!.parsedSdp.media
+        ].some(media => media.type === 'video');
+    }
+
+}
+
+export class HasAudioTrackMatcher extends HasAudioTrackMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        return [
+            ...connection.getLocalDescription()!.parsedSdp.media,
+            ...connection.getRemoteDescription()!.parsedSdp.media
+        ].some(media => media.type === 'audio');
+    }
+
+}
+
+export class HasMediaTrackMatcher extends HasMediaTrackMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        return [
+            ...connection.getLocalDescription()!.parsedSdp.media,
+            ...connection.getRemoteDescription()!.parsedSdp.media
+        ].some(media => media.type === 'video' || media.type === 'audio');
+    }
+
+}
+
+const getConnectionSourceURL = (connection: RTCConnection): URL | undefined => {
+    const { sourceURL } = connection.metadata;
+    if (!sourceURL) return;
+
+    try {
+        return new URL(sourceURL);
+    } catch (e) {
+        console.warn('Unparseable RTC source URL:', e);
+        return;
+    }
+};
+
+export class HostnameMatcher extends HostnameMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        const url = getConnectionSourceURL(connection);
+        return url?.hostname === this.hostname;
+    }
+
+}
+
+export class UrlRegexMatcher extends UrlRegexMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        const url = getConnectionSourceURL(connection);
+        return !!url?.toString().match(
+            new RegExp(this.regexSource, this.regexFlags)
+        );
+    }
+
+}
+
+export class UserAgentRegexMatcher extends UserAgentRegexMatcherDefinition {
+
+    matches(connection: RTCConnection): boolean {
+        const userAgent = connection.metadata.userAgent;
+        return !!userAgent?.match(
+            new RegExp(this.regexSource, this.regexFlags)
+        );
+    }
+
+}
+
+export const MatcherLookup: typeof MatcherDefinitionLookup = {
+    'has-rtc-data-channel': HasDataChannelMatcher,
+    'has-rtc-video-track': HasVideoTrackMatcher,
+    'has-rtc-audio-track': HasAudioTrackMatcher,
+    'has-rtc-media-track': HasMediaTrackMatcher,
+    'rtc-page-hostname': HostnameMatcher,
+    'rtc-page-regex': UrlRegexMatcher,
+    'rtc-user-agent-regex': UserAgentRegexMatcher
+};

package/src/mockrtc-base.ts

@@ -0,0 +1,49 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    MockRTC,
+    MockRTCEventData,
+    MockRTCPeerBuilder,
+    MockRTCRuleDefinition
+} from "./mockrtc";
+import { MockRTCPeer } from "./mockrtc-peer";
+import { MockRTCHandlerBuilder } from "./handling/handler-builder";
+import { HandlerStepDefinition } from "./handling/handler-step-definitions";
+import { MatcherDefinition } from "./matching/matcher-definitions";
+import { MockRTCRuleBuilder } from "./rule-builder";
+
+export abstract class MockRTCBase implements MockRTC {
+
+    abstract getMatchingPeer(): MockRTCPeer;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract on<E extends keyof MockRTCEventData>(
+        event: E,
+        callback: (param: MockRTCEventData[E]) => void
+    ): Promise<void>;
+
+    buildPeer(): MockRTCPeerBuilder {
+        return new MockRTCHandlerBuilder(this.buildPeerFromDefinition.bind(this));
+    }
+
+    abstract buildPeerFromDefinition(
+        handlerStepDefinitions: HandlerStepDefinition[]
+    ): Promise<MockRTCPeer>;
+
+    forConnections(): MockRTCRuleBuilder {
+        return new MockRTCRuleBuilder(this.addRuleFromDefinition.bind(this));
+    }
+
+    abstract addRuleFromDefinition(
+        matcherDefinitions: MatcherDefinition[],
+        handlerStepDefinitions: HandlerStepDefinition[]
+    ): Promise<void>;
+
+    abstract setRulesFromDefinitions(
+        ruleDefinitions: Array<MockRTCRuleDefinition>
+    ): Promise<void>;
+
+}

package/src/mockrtc-peer.ts

@@ -189,11 +189,18 @@ export interface AnswerOptions {
  * Extra metadata to associate with the connection. This will be exposed on
  * events like peer-connected, and can be used to add context to connections.
  *
- * The only defined value is 'userAgent' which must be a client user agent
- * string (in a browser, the navigator.userAgent value) if defined.
+ * The defined fields may only be used as defined here, but all values are
+ * optional, and any other metadata may be attached in any format here.
+ *
+ * The only defined values are:
+ * - `userAgent` - a client user-agent string (in a browser, the value of
+ *   `navigator.userAgent`)
+ * - `sourceURL` - the URL of the referring page, when the request is sent by
+ *   a browser
  */
 export interface ConnectionMetadata {
     userAgent?: string;
+    sourceURL?: string;
     [k: string]: any;
 }