mockrtc 0.1.0 → 0.2.0

package/src/mockrtc-peer.ts

@@ -3,7 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { MockRTCSessionDescription } from './mockrtc';
+
 export interface MockRTCPeerOptions {
+    debug?: boolean;
     recordMessages?: boolean;
 }
 
@@ -111,7 +114,7 @@ export interface MockRTCSession {
     /**
      * Create a new offer for this session, to renegotiate the existing connection.
      */
-    createOffer(options?: OfferOptions): Promise<RTCSessionDescriptionInit>;
+    createOffer(options?: OfferOptions): Promise<MockRTCSessionDescription>;
 
     /**
      * Provide an answer to complete an offer for this session, to renegotiate the existing connection.
@@ -121,17 +124,17 @@ export interface MockRTCSession {
     /**
      * Get an answer given an offer from elsewhere, to renegotiate the existing connection.
      */
-    answerOffer(offer: RTCSessionDescriptionInit, options?: AnswerOptions): Promise<RTCSessionDescriptionInit>;
+    answerOffer(offer: RTCSessionDescriptionInit, options?: AnswerOptions): Promise<MockRTCSessionDescription>;
 }
 
 export interface MockRTCOfferParams {
-    offer: RTCSessionDescriptionInit;
+    offer: MockRTCSessionDescription;
     setAnswer: (answer: RTCSessionDescriptionInit) => Promise<void>;
     session: MockRTCSession;
 }
 
 export interface MockRTCAnswerParams {
-    answer: RTCSessionDescriptionInit;
+    answer: MockRTCSessionDescription;
     session: MockRTCSession;
 }
 
@@ -152,6 +155,16 @@ export interface OfferOptions {
      * This option has no effect if mirrorSDP is not set.
      */
     addDataStream?: boolean;
+
+    /**
+     * 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.
+     *
+     * If this value is provided during renegotiation, it is merged key-wise with
+     * any existing metadata value for the connection (i.e. existing metadata
+     * values will not change, unless a new value for the same key is provided).
+     */
+    connectionMetadata?: ConnectionMetadata;
 }
 
 export interface AnswerOptions {
@@ -160,17 +173,39 @@ export interface AnswerOptions {
      * create an equivalent answer, including the same media params.
      */
     mirrorSDP?: string;
+
+    /**
+     * 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.
+     *
+     * If this value is provided during renegotiation, it is merged key-wise with
+     * any existing metadata value for the connection (i.e. existing metadata
+     * values will not change, unless a new value for the same key is provided).
+     */
+    connectionMetadata?: ConnectionMetadata;
+}
+
+/**
+ * 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.
+ */
+export interface ConnectionMetadata {
+    userAgent?: string;
+    [k: string]: any;
 }
 
 export interface MockRTCExternalOfferParams {
     id: string; // Used for external attach control messages
-    offer: RTCSessionDescriptionInit;
+    offer: MockRTCSessionDescription;
     setAnswer: (answer: RTCSessionDescriptionInit) => Promise<void>;
     session: MockRTCSession;
 }
 
 export interface MockRTCExternalAnswerParams {
     id: string; // Used for external attach control messagesz
-    answer: RTCSessionDescriptionInit;
+    answer: MockRTCSessionDescription;
     session: MockRTCSession;
 }

package/src/mockrtc.ts

@@ -4,11 +4,17 @@
  */
 
 import type { MockRTCHandlerBuilder } from "./handling/handler-builder";
-import type { MockRTCPeer } from "./mockrtc-peer";
+import type { ConnectionMetadata, MockRTCPeer } from "./mockrtc-peer";
 
 export interface MockRTCPeerBuilder extends MockRTCHandlerBuilder<MockRTCPeer> {}
 
 export interface MockRTCOptions {
+
+    /**
+     * Should the server print extra debug information?
+     */
+    debug?: boolean;
+
     /**
      * Whether or not all DataChannel messages should be saved for later examination.
      * This can be useful in quick testing, but may use large amounts of data if
@@ -19,6 +25,136 @@ export interface MockRTCOptions {
     recordMessages?: boolean;
 }
 
+export interface MockRTCSessionDescription {
+    type: 'offer' | 'answer';
+    sdp: string;
+}
+
+export interface SelectedRTCCandidate {
+    address: string;
+    port: number;
+    protocol: 'udp' | 'tcp';
+    type: RTCIceCandidateType;
+};
+
+export interface TimingEvents {
+    // Milliseconds since unix epoch
+    startTime: number;
+
+    // High-precision floating-point monotonically increasing timestamps.
+    // Comparable and precise, but not related to specific current time.
+    connectTimestamp: number;
+    disconnectTimestamp?: number;
+    externalAttachTimestamp?: number;
+
+    // Other events (everything that might not be a on-off) each come with their
+    // eventTimestamp property for that specific event.
+}
+
+export type MockRTCEventData = {
+    "peer-connected": {
+        peerId: string;
+        sessionId: string;
+        metadata: ConnectionMetadata;
+        localSessionDescription: MockRTCSessionDescription;
+        remoteSessionDescription: MockRTCSessionDescription;
+        selectedLocalCandidate: SelectedRTCCandidate;
+        selectedRemoteCandidate: SelectedRTCCandidate;
+
+        timingEvents: TimingEvents;
+    },
+    "peer-disconnected": {
+        peerId: string;
+        sessionId: string;
+
+        timingEvents: TimingEvents;
+    },
+    "external-peer-attached": {
+        peerId: string;
+        sessionId: string;
+        externalConnection: {
+            peerId: string;
+            sessionId: string;
+            localSessionDescription: MockRTCSessionDescription;
+            remoteSessionDescription: MockRTCSessionDescription;
+            selectedLocalCandidate: SelectedRTCCandidate;
+            selectedRemoteCandidate: SelectedRTCCandidate;
+        };
+        timingEvents: TimingEvents;
+    },
+    "data-channel-opened": {
+        peerId: string;
+        sessionId: string;
+        channelId: number;
+        channelLabel: string;
+        channelProtocol: string;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    },
+    "data-channel-message-sent": {
+        peerId: string;
+        sessionId: string;
+        channelId: number;
+        direction: 'sent';
+        content: Buffer;
+        isBinary: boolean;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    },
+    "data-channel-message-received": {
+        peerId: string;
+        sessionId: string;
+        channelId: number;
+        direction: 'received';
+        content: Buffer;
+        isBinary: boolean;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    },
+    "data-channel-closed": {
+        peerId: string;
+        sessionId: string;
+        channelId: number;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    }
+    "media-track-opened": {
+        peerId: string;
+        sessionId: string;
+        trackMid: string;
+        trackType: string;
+        trackDirection: string;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    },
+    "media-track-stats": {
+        peerId: string;
+        sessionId: string;
+        trackMid: string;
+
+        totalBytesSent: number;
+        totalBytesReceived: number;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    },
+    "media-track-closed": {
+        peerId: string;
+        sessionId: string;
+        trackMid: string;
+
+        eventTimestamp: number;
+        timingEvents: TimingEvents;
+    }
+};
+
+export type MockRTCEvent = keyof MockRTCEventData;
+
 export interface MockRTC {
 
     /**
@@ -26,11 +162,37 @@ export interface MockRTC {
      * must be configured with the mock peer's settings. Once configured the
      * peer can be created by calling any `.thenX()` method to define the
      * peer's behaviour.
+     *
+     * This API allows you to define a single set of handling steps, and then
+     * connect directly to the resulting peer to run those steps directly.
+     *
+     * To instead define multiple behaviours that match different conditions, and
+     * then connect clients who may each see different behaviour, define your
+     * rules using the `forX()` methods, and connect by using `getMatchingPeer()`.
      */
     buildPeer(): MockRTCPeerBuilder;
 
+    /**
+     * Get the rule-matching peer.
+     *
+     * This peer accepts connections, matches them against defined rules (defined
+     * via the `.forX()` methods) and then handles them according to the steps
+     * for the defined rule.
+     *
+     * To more directly define a set of steps and make a connection that will
+     * follow those steps, define a peer with `.buildPeer()` and then connect
+     * to that directly.
+     *
+     * The default behaviour of this peer for unmatched connections is equivalent
+     * to `.thenPassThrough()` - it will accept all incoming data without response
+     * initially, and proxy all data to a remote peer if one is attached.
+     */
+    getMatchingPeer(): MockRTCPeer;
+
     start(): Promise<void>;
 
     stop(): Promise<void>;
 
+    on<E extends MockRTCEvent>(event: E, callback: (param: MockRTCEventData[E]) => void): Promise<void>;
+
 }

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

@@ -3,13 +3,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import * as _ from 'lodash';
 import * as stream from 'stream';
 import { gql } from 'graphql-tag';
 import { PluggableAdmin } from 'mockttp';
 import type { IResolvers } from "@graphql-tools/utils";
+import { PubSub } from "graphql-subscriptions";
 
 import { HandlerStep, StepLookup } from '../handling/handler-steps';
-import { MockRTCOptions } from '../mockrtc';
+import { MockRTCOptions, MockRTCSessionDescription } from '../mockrtc';
 import { MockRTCServer } from './mockrtc-server';
 import { AnswerOptions, OfferOptions } from '../mockrtc-peer';
 
@@ -18,9 +20,22 @@ type SerializedValue<T> = PluggableAdmin.Serialization.SerializedValue<T>;
 
 export interface SessionData {
     id: string;
-    description: RTCSessionDescriptionInit
+    description: MockRTCSessionDescription
 }
 
+const EVENTS = [
+    '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'
+] as const;
+
 export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOptions, {}> {
 
     private mockRTCServer!: MockRTCServer;
@@ -30,7 +45,9 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
         return this.mockRTCServer.start();
     }
 
-    reset() {}
+    reset() {
+        this.mockRTCServer.reset();
+    }
 
     stop() {
         return this.mockRTCServer.stop();
@@ -76,9 +93,137 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
         }
 
         scalar HandlerStep
+
+        extend type Subscription {
+            peerConnected: RTCPeerConnectionEvent!
+            peerDisconnected: RTCPeerDisconnectionEvent!
+            externalPeerAttached: RTCAttachmentEvent!
+
+            dataChannelOpened: DataChannelOpenEvent!
+            dataChannelMessageSent: DataChannelMessageEvent!
+            dataChannelMessageReceived: DataChannelMessageEvent!
+            dataChannelClosed: DataChannelCloseEvent!
+
+            mediaTrackOpened: MediaTrackOpenEvent!
+            mediaTrackStats: MediaTrackStatsEvent!
+            mediaTrackClosed: MediaTrackCloseEvent!
+        }
+
+        type RTCPeerConnectionEvent {
+            peerId: ID!
+            sessionId: ID!
+
+            metadata: Raw!
+            timingEvents: Raw!
+
+            localSessionDescription: SessionDescriptionResult!
+            remoteSessionDescription: SessionDescriptionResult!
+            selectedLocalCandidate: RTCSelectedCandidate!
+            selectedRemoteCandidate: RTCSelectedCandidate!
+        }
+
+        type RTCSelectedCandidate {
+            address: String!
+            port: Int!
+            protocol: String!
+            type: String!
+        }
+
+        type RTCPeerDisconnectionEvent {
+            peerId: ID!
+            sessionId: ID!
+            timingEvents: Raw!
+        }
+
+        type RTCAttachmentEvent {
+            peerId: ID!
+            sessionId: ID!
+            externalConnection: RTCExternalPeerConnectionEvent!
+            timingEvents: Raw!
+        }
+
+        type RTCExternalPeerConnectionEvent {
+            sessionId: ID!
+            localSessionDescription: SessionDescriptionResult!
+            remoteSessionDescription: SessionDescriptionResult!
+            selectedLocalCandidate: RTCSelectedCandidate!
+            selectedRemoteCandidate: RTCSelectedCandidate!
+        }
+
+        type DataChannelOpenEvent {
+            peerId: ID!
+            sessionId: ID!
+            channelId: Int!
+            channelLabel: String!
+            channelProtocol: String!
+
+            eventTimestamp: Float!
+            timingEvents: Raw!
+        }
+
+        type DataChannelMessageEvent {
+            peerId: ID!
+            sessionId: ID!
+            channelId: Int!
+            direction: String!
+            content: Buffer!
+            isBinary: Boolean!
+
+            eventTimestamp: Float!
+            timingEvents: Raw!
+        }
+
+        type DataChannelCloseEvent {
+            peerId: ID!
+            sessionId: ID!
+            channelId: Int!
+
+            eventTimestamp: Float!
+            timingEvents: Raw!
+        }
+
+        type MediaTrackOpenEvent {
+            peerId: ID!
+            sessionId: ID!
+            trackMid: ID!
+            trackType: String!
+            trackDirection: String!
+
+            eventTimestamp: Float!
+            timingEvents: Raw!
+        }
+
+        type MediaTrackStatsEvent {
+            peerId: ID!
+            sessionId: ID!
+            trackMid: ID!
+
+            totalBytesSent: Int!
+            totalBytesReceived: Int!
+
+            eventTimestamp: Float!
+            timingEvents: Raw!
+        }
+
+        type MediaTrackCloseEvent {
+            peerId: ID!
+            sessionId: ID!
+            trackMid: ID!
+
+            eventTimestamp: Float!
+            timingEvents: Raw!
+        }
     `;
 
     buildResolvers(adminStream: stream.Duplex, ruleParams: {}): IResolvers {
+        const pubsub = new PubSub();
+
+        EVENTS.forEach((eventName) => {
+            this.mockRTCServer.on(eventName, (peer) => {
+                pubsub.publish(eventName, { [_.camelCase(eventName)]: peer });
+            });
+        });
+
         return {
             Mutation: {
                 createPeer: (__: any, { data: { steps } }: { data: {
@@ -128,7 +273,7 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
                 completeOffer: async (__: any, { peerId, sessionId, answer } : {
                     peerId: string,
                     sessionId: string,
-                    answer: RTCSessionDescriptionInit
+                    answer: MockRTCSessionDescription
                 }): Promise<void> => {
                     const session = this.mockRTCServer.getPeer(peerId).getSession(sessionId);
                     await session.completeOffer(answer);
@@ -136,7 +281,7 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
                 answerOffer: async (__: any, { peerId, sessionId, offer, options } : {
                     peerId: string,
                     sessionId?: string,
-                    offer: RTCSessionDescriptionInit,
+                    offer: MockRTCSessionDescription,
                     options?: AnswerOptions
                 }): Promise<SessionData> => {
                     const peer = this.mockRTCServer.getPeer(peerId);
@@ -156,7 +301,7 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
                 },
                 answerExternalOffer: async (__: any, { peerId, offer, options } : {
                     peerId: string,
-                    offer: RTCSessionDescriptionInit,
+                    offer: MockRTCSessionDescription,
                     options?: AnswerOptions
                 }): Promise<SessionData> => {
                     const peer = this.mockRTCServer.getPeer(peerId);
@@ -190,6 +335,14 @@ export class MockRTCAdminPlugin implements PluggableAdmin.AdminPlugin<MockRTCOpt
                         }
                     });
                 }
+            },
+            Subscription: {
+                ...(EVENTS.reduce((acc, eventName) => ({
+                    ...acc,
+                    [_.camelCase(eventName)]: {
+                        subscribe: () => pubsub.asyncIterator(eventName)
+                    }
+                }), {}))
             }
         };
     }