mockrtc 0.2.0 → 0.3.1

package/src/handling/handler-builder.ts

@@ -6,6 +6,7 @@
 import {
     type HandlerStepDefinition,
     PeerProxyStepDefinition,
+    CreateChannelStepDefinition,
     SendStepDefinition,
     DynamicProxyStepDefinition,
     WaitForChannelStepDefinition,
@@ -35,7 +36,7 @@ export class MockRTCHandlerBuilder<R> {
      *
      * @category Steps
      */
-    sleep(duration: number): this {
+    sleep(duration: number): MockRTCHandlerBuilder<R> {
         this.handlerSteps.push(new WaitForDurationStepDefinition(duration));
         return this;
     }
@@ -45,7 +46,7 @@ export class MockRTCHandlerBuilder<R> {
      *
      * @category Steps
      */
-    waitForChannel(channelLabel?: string): this {
+    waitForChannel(channelLabel?: string): MockRTCHandlerBuilder<R> {
         this.handlerSteps.push(new WaitForChannelStepDefinition(channelLabel));
         return this;
     }
@@ -55,7 +56,7 @@ export class MockRTCHandlerBuilder<R> {
      *
      * @category Steps
      */
-    waitForTrack(): this {
+    waitForTrack(): MockRTCHandlerBuilder<R> {
         this.handlerSteps.push(new WaitForTrackStepDefinition());
         return this;
     }
@@ -68,7 +69,7 @@ export class MockRTCHandlerBuilder<R> {
      *
      * @category Steps
      */
-    waitForNextMessage(): this {
+    waitForNextMessage(): MockRTCHandlerBuilder<R> {
         this.handlerSteps.push(new WaitForMessageStepDefinition());
         return this;
     }
@@ -80,7 +81,7 @@ export class MockRTCHandlerBuilder<R> {
      *
      * @category Steps
      */
-    waitForNextMedia(): this {
+    waitForNextMedia(): MockRTCHandlerBuilder<R> {
         this.handlerSteps.push(new WaitForMediaStepDefinition());
         return this;
     }
@@ -91,13 +92,24 @@ export class MockRTCHandlerBuilder<R> {
      * This looks for new messages, ignoring any messages already consumed by
      * previous steps.
      *
-    * @category Steps
+     * @category Steps
      */
-    waitForNextMessageOnChannel(channelLabel: string): this {
+    waitForNextMessageOnChannel(channelLabel: string): MockRTCHandlerBuilder<R> {
         this.handlerSteps.push(new WaitForMessageStepDefinition(channelLabel));
         return this;
     }
 
+    /**
+     * Creates a new data channel with the given name, waiting until it opens
+     * before continuing.
+     *
+     * @category Steps
+     */
+    createDataChannel(channelLabel: string): MockRTCHandlerBuilder<R> {
+        this.handlerSteps.push(new CreateChannelStepDefinition(channelLabel));
+        return this;
+    }
+
     /**
      * Send a message or buffer on the connection's data channels.
      *
@@ -111,9 +123,9 @@ export class MockRTCHandlerBuilder<R> {
      *
     * @category Steps
      */
-    send(message: string | Buffer): this;
-    send(channel: string | undefined, message: string | Buffer): this;
-    send(...args: [string | undefined, string | Buffer] | [string | Buffer]): this {
+    send(message: string | Buffer): MockRTCHandlerBuilder<R>;
+    send(channel: string | undefined, message: string | Buffer): MockRTCHandlerBuilder<R>;
+    send(...args: [string | undefined, string | Buffer] | [string | Buffer]): MockRTCHandlerBuilder<R> {
         if (args[1] !== undefined) {
             const [channel, message] = args as [string, string | Buffer];
             this.handlerSteps.push(new SendStepDefinition(channel, message));

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) {
@@ -149,6 +161,20 @@ export class SendStep extends SendStepDefinition {
         );
     }
 
+    static deserialize(data: {
+        channelLabel: string | undefined,
+        message: string | { type: 'Buffer', data: number[] }
+    }): SendStep {
+        return new SendStep(
+            data.channelLabel,
+            typeof data.message === 'string'
+                ? data.message
+                // Buffers are serialized very roughly, so here we
+                // turn them back into real Buffer instances:
+                : Buffer.from(data.message.data)
+        );
+    }
+
 }
 
 export class CloseStep extends CloseStepDefinition {
@@ -166,8 +192,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 +269,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
+};