mockrtc 0.1.0 → 0.3.0

package/src/client/mockrtc-client.ts

@@ -3,7 +3,6 @@
  * 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.
@@ -12,61 +11,69 @@ import gql from 'graphql-tag';
 import * as BrowserPluggableAdmin from 'mockttp/dist/pluggable-admin-api/pluggable-admin.browser';
 import type { PluggableAdmin } from 'mockttp';
 
-import { MockRTC, MockRTCOptions, MockRTCPeerBuilder } from "../mockrtc";
+import { MockRTC, MockRTCEvent, MockRTCOptions, MockRTCRuleDefinition } from "../mockrtc";
+import { MockRTCBase } from '../mockrtc-base';
 
-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 type { MockRTCAdminPlugin } from "../server/mockrtc-admin-plugin";
+import { MockRTCAdminRequestBuilder } from './mockrtc-admin-request-builder';
 import { HandlerStepDefinition } from '../handling/handler-step-definitions';
+import { MatcherDefinition } from '../matching/matcher-definitions';
 
 export type MockRTCClientOptions =
     PluggableAdmin.AdminClientOptions &
     MockRTCOptions;
 
-export class MockRTCClient implements MockRTC {
+export class MockRTCClient extends MockRTCBase implements MockRTC {
 
     private adminClient: PluggableAdmin.AdminClient<{ webrtc: MockRTCAdminPlugin }>;
+    private requestBuilder: MockRTCAdminRequestBuilder;
 
     constructor(
         private options: MockRTCClientOptions = {}
     ) {
+        super();
+
         this.adminClient = new BrowserPluggableAdmin.AdminClient(options);
+        this.requestBuilder = new MockRTCAdminRequestBuilder();
     }
 
-    buildPeer(): MockRTCPeerBuilder {
-        return new MockRTCHandlerBuilder(this.buildPeerFromData);
+    getMatchingPeer(): MockRTCPeer {
+        return new MockRTCRemotePeer('matching-peer', this.adminClient);
     }
 
-    private buildPeerFromData = async (handlerSteps: HandlerStepDefinition[]): Promise<MockRTCPeer> => {
+    async buildPeerFromDefinition(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 peerData = await this.adminClient.sendQuery(
+            this.requestBuilder.buildCreatePeerQuery(handlerSteps, adminStream)
+        );
 
         const { peerId } = peerData;
 
         return new MockRTCRemotePeer(peerId, this.adminClient);
     }
 
+    async addRuleFromDefinition(
+        matchers: MatcherDefinition[],
+        handlerSteps: HandlerStepDefinition[]
+    ) {
+        const { adminStream } = this.adminClient;
+
+        await this.adminClient.sendQuery(
+            this.requestBuilder.buildAddRuleQuery(matchers, handlerSteps, adminStream)
+        );
+    }
+
+    async setRulesFromDefinitions(rules: Array<MockRTCRuleDefinition>) {
+        const { adminStream } = this.adminClient;
+
+        await this.adminClient.sendQuery(
+            this.requestBuilder.buildSetRulesQuery(rules, adminStream)
+        );
+    }
+
     async start(): Promise<void> {
         await this.adminClient.start({
             webrtc: this.options
@@ -76,4 +83,19 @@ export class MockRTCClient implements MockRTC {
     async stop(): Promise<void> {
         await this.adminClient.stop();
     }
+
+    async on(event: MockRTCEvent, callback: any): Promise<void> {
+        const subscriptionRequest = this.requestBuilder.buildSubscriptionRequest(event);
+
+        if (!subscriptionRequest) {
+            // We just return an immediately promise if we don't recognize the event, which will quietly
+            // succeed but never call the corresponding callback (the same as the server and most event
+            // sources in the same kind of situation). This is what happens when the *client* doesn't
+            // recognize the event. Subscribe() below handles the unknown-to-server case.
+            console.warn(`Ignoring subscription for event unrecognized by MockRTC client: ${event}`);
+            return;
+        }
+
+        return this.adminClient.subscribe(subscriptionRequest, callback);
+    }
 }

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

@@ -6,6 +6,7 @@
 import { gql } from 'graphql-tag';
 import * as PluggableAdmin from 'mockttp/dist/pluggable-admin-api/pluggable-admin.browser';
 
+import { MockRTCSessionDescription } from '../mockrtc';
 import {
     MockRTCPeer,
     MockRTCOfferParams,
@@ -83,7 +84,7 @@ export class MockRTCRemotePeer implements MockRTCPeer {
     }
 
     async answerOffer(
-        offer: RTCSessionDescriptionInit,
+        offer: MockRTCSessionDescription,
         options?: AnswerOptions
     ): Promise<MockRTCAnswerParams> {
         return this.adminClient.sendQuery<
@@ -114,7 +115,7 @@ export class MockRTCRemotePeer implements MockRTCPeer {
     }
 
     async answerExternalOffer(
-        offer: RTCSessionDescriptionInit,
+        offer: MockRTCSessionDescription,
         options?: AnswerOptions
     ): Promise<MockRTCExternalAnswerParams> {
         return this.adminClient.sendQuery<
@@ -211,10 +212,10 @@ class RemoteSessionApi implements MockRTCSession {
         public readonly sessionId: string
     ) {}
 
-    createOffer(options?: OfferOptions): Promise<RTCSessionDescriptionInit> {
+    createOffer(options?: OfferOptions): Promise<MockRTCSessionDescription> {
         return this.adminClient.sendQuery<
             { createOffer: SessionData },
-            RTCSessionDescriptionInit
+            MockRTCSessionDescription
         >({
             query: gql`
                 mutation GetPeerRTCSessionOffer($peerId: ID!, $sessionId: ID!, $options: Raw) {
@@ -231,7 +232,7 @@ class RemoteSessionApi implements MockRTCSession {
         });
     }
 
-    completeOffer(answer: RTCSessionDescriptionInit): Promise<void> {
+    completeOffer(answer: MockRTCSessionDescription): Promise<void> {
         return this.adminClient.sendQuery<void>({
             query: gql`
                 mutation CompletePeerRTCOffer(
@@ -251,12 +252,12 @@ class RemoteSessionApi implements MockRTCSession {
     }
 
     answerOffer(
-        offer: RTCSessionDescriptionInit,
+        offer: MockRTCSessionDescription,
         options?: AnswerOptions
-    ): Promise<RTCSessionDescriptionInit> {
+    ): Promise<MockRTCSessionDescription> {
         return this.adminClient.sendQuery<
             { answerOffer: SessionData },
-            RTCSessionDescriptionInit
+            MockRTCSessionDescription
         >({
             query: gql`
                 mutation GetPeerRTCAnswer(

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

@@ -5,6 +5,8 @@
 
 import * as PluggableAdmin from 'mockttp/dist/pluggable-admin-api/pluggable-admin.browser';
 
+import { MockRTCSessionDescription } from '../mockrtc';
+
 export type Serializable = PluggableAdmin.Serialization.Serializable;
 export const { Serializable } = PluggableAdmin.Serialization;
 type ClientServerChannel = PluggableAdmin.Serialization.ClientServerChannel;
@@ -18,89 +20,138 @@ 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: RTCSessionDescriptionInit) => Promise<RTCSessionDescriptionInit>;
+    protected getAnswer: (offer: MockRTCSessionDescription) => Promise<RTCSessionDescriptionInit>;
 
     constructor(
         connectionTarget:
             | RTCPeerConnection
-            | ((offer: RTCSessionDescriptionInit) => Promise<RTCSessionDescriptionInit>)
+            | ((offer: MockRTCSessionDescription) => Promise<RTCSessionDescriptionInit>)
     ) {
         super();
         if (connectionTarget instanceof Function) {
             this.getAnswer = connectionTarget;
         } else {
-            this.getAnswer = async (offer: RTCSessionDescriptionInit) => {
+            this.getAnswer = async (offer: MockRTCSessionDescription) => {
                 await connectionTarget.setRemoteDescription(offer);
                 const answer = await connectionTarget.createAnswer();
                 await connectionTarget.setLocalDescription(answer);
@@ -109,9 +160,13 @@ export class PeerProxyStepDefinition extends Serializable implements HandlerStep
         }
     }
 
+    explain() {
+        return `proxy the RTC connection to the configured peer`;
+    }
+
     serialize(channel: ClientServerChannel): {} {
         channel.onRequest<
-            { offer: RTCSessionDescriptionInit },
+            { offer: MockRTCSessionDescription },
             { answer: RTCSessionDescriptionInit }
         >(async (msg) => {
             return { answer: await this.getAnswer(msg.offer) };
@@ -124,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

@@ -5,6 +5,7 @@
 
 import { PluggableAdmin } from 'mockttp';
 
+import { MockRTCSessionDescription } from '../mockrtc';
 import type { DataChannelStream } from '../webrtc/datachannel-stream';
 import type { MediaTrackStream } from '../webrtc/mediatrack-stream';
 import type { MockRTCConnection } from '../webrtc/mockrtc-connection';
@@ -16,6 +17,7 @@ import {
     EchoStepDefinition,
     HandlerStepDefinition,
     PeerProxyStepDefinition,
+    CreateChannelStepDefinition,
     SendStepDefinition,
     WaitForChannelStepDefinition,
     WaitForDurationStepDefinition,
@@ -69,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();
@@ -84,7 +86,7 @@ export class WaitForMessageStep extends WaitForMessageStepDefinition {
                 }
             }
 
-            connection.on('channel-open', listenForMessage);
+            connection.on('channel-created', listenForMessage);
             connection.channels.forEach(listenForMessage);
         });
     }
@@ -107,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();
@@ -120,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) {
@@ -165,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);
 
@@ -190,7 +203,7 @@ export class PeerProxyStep extends PeerProxyStepDefinition {
         );
         externalConn.setRemoteDescription(await this.getAnswer(externalOffer));
 
-        connection.proxyTrafficTo(externalConn);
+        await connection.proxyTrafficTo(externalConn);
 
         // This step keeps running indefinitely, until the connection closes
         return new Promise<void>((resolve) => connection.on('connection-closed', resolve));
@@ -198,7 +211,7 @@ export class PeerProxyStep extends PeerProxyStepDefinition {
 
     serialize(channel: ClientServerChannel): {} {
         channel.onRequest<
-            { offer: RTCSessionDescriptionInit },
+            { offer: MockRTCSessionDescription },
             { answer: RTCSessionDescriptionInit }
         >(async (msg) => {
             return { answer: await this.getAnswer(msg.offer) };
@@ -208,10 +221,10 @@ export class PeerProxyStep extends PeerProxyStepDefinition {
     }
 
     static deserialize(_data: {}, channel: ClientServerChannel): PeerProxyStep {
-        return new PeerProxyStep(async (offer: RTCSessionDescriptionInit) => {
+        return new PeerProxyStep(async (offer: MockRTCSessionDescription) => {
             const response = await channel.request<
-                { offer: RTCSessionDescriptionInit },
-                { answer: RTCSessionDescriptionInit }
+                { offer: MockRTCSessionDescription },
+                { answer: MockRTCSessionDescription }
             >({ offer });
             return response.answer;
         });
@@ -242,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

@@ -9,6 +9,11 @@ import type {
 } from "./mockrtc";
 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 {
     MockRTC,
     MockRTCOptions