mockrtc 0.2.0 → 0.3.1

package/src/webrtc/rtc-connection.ts

@@ -20,6 +20,10 @@ import {
 import { DataChannelStream } from './datachannel-stream';
 import { MediaTrackStream } from './mediatrack-stream';
 
+export type ParsedSDP = {
+    parsedSdp: SDP.SessionDescription;
+};
+
 /**
  * An RTC connection is a single connection. This base class defines the raw connection management and
  * tracking logic for a generic connection. The MockRTCConnection subclass extends this and adds
@@ -34,8 +38,8 @@ export class RTCConnection extends EventEmitter {
     private rawConn: NodeDataChannel.PeerConnection | null
         = new NodeDataChannel.PeerConnection("MockRTCConnection", { iceServers: [] });
 
-    private remoteDescription: RTCSessionDescriptionInit | undefined;
-    private localDescription: MockRTCSessionDescription | undefined;
+    private remoteDescription: RTCSessionDescriptionInit & ParsedSDP | undefined;
+    private localDescription: MockRTCSessionDescription & ParsedSDP | undefined;
 
     private _connectionMetadata: ConnectionMetadata = {};
     public get metadata() {
@@ -132,13 +136,13 @@ export class RTCConnection extends EventEmitter {
         channelStream.on('error', (error) => {
             console.error('Channel error:', error);
         });
+        this.emit('channel-created', channelStream);
+        this.emit(`${options.isLocal ? 'local' : 'remote'}-channel-created`, channelStream);
 
-        this.emit('channel-open', channelStream);
-        if (options.isLocal) {
-            this.emit('local-channel-open', channelStream);
-        } else {
-            this.emit('remote-channel-open', channelStream);
-        }
+        channelStream.once('channel-open', () => {
+            this.emit('channel-open', channelStream);
+            this.emit(`${options.isLocal ? 'local' : 'remote'}-channel-open`, channelStream);
+        });
 
         return channelStream;
     }
@@ -150,7 +154,7 @@ export class RTCConnection extends EventEmitter {
         trackStream.on('close', () => {
             const trackIndex = this.trackedMediaTracks.findIndex(c => c.stream === trackStream);
             if (trackIndex !== -1) {
-                this.trackedChannels.splice(trackIndex, 1);
+                this.trackedMediaTracks.splice(trackIndex, 1);
             }
         });
 
@@ -158,12 +162,13 @@ export class RTCConnection extends EventEmitter {
             console.error('Media track error:', error);
         });
 
-        this.emit('track-open', trackStream);
-        if (options.isLocal) {
-            this.emit('local-track-open', trackStream);
-        } else {
-            this.emit('remote-track-open', trackStream);
-        }
+        this.emit('track-created', trackStream);
+        this.emit(`${options.isLocal ? 'local' : 'remote'}-track-created`, trackStream);
+
+        trackStream.once('track-open', () => {
+            this.emit('track-open', trackStream);
+            this.emit(`${options.isLocal ? 'local' : 'remote'}-track-open`, trackStream);
+        });
 
         return trackStream;
     }
@@ -171,7 +176,10 @@ export class RTCConnection extends EventEmitter {
     setRemoteDescription(description: RTCSessionDescriptionInit) {
         if (!this.rawConn) throw new Error("Can't set remote description after connection is closed");
 
-        this.remoteDescription = description;
+        this.remoteDescription = {
+            ...description,
+            parsedSdp: SDP.parse(description.sdp ?? '')
+        };
         const { type: offerType, sdp: offerSdp } = description;
         if (!offerSdp) throw new Error("Cannot set MockRTC peer description without providing an SDP");
         this.rawConn.setRemoteDescription(offerSdp, offerType[0].toUpperCase() + offerType.slice(1) as any);
@@ -207,7 +215,10 @@ export class RTCConnection extends EventEmitter {
 
         const sessionDescription = this.rawConn.localDescription() as MockRTCSessionDescription;
         setupChannel?.close(); // Close the temporary setup channel, if we created one
-        this.localDescription = sessionDescription;
+        this.localDescription = {
+            ...sessionDescription,
+            parsedSdp: SDP.parse(sessionDescription.sdp ?? '')
+        };
         return sessionDescription;
     }
 
@@ -324,7 +335,10 @@ export class RTCConnection extends EventEmitter {
         mirrorMediaParams(offerToMirror, offerSDP);
         localDesc.sdp = SDP.write(offerSDP);
 
-        this.localDescription = localDesc as MockRTCSessionDescription;
+        this.localDescription = {
+            ...localDesc as MockRTCSessionDescription,
+            parsedSdp: offerSDP
+        };
         return this.localDescription;
     }
 
@@ -337,7 +351,10 @@ export class RTCConnection extends EventEmitter {
 
         localDesc.sdp = SDP.write(answerSDP);
 
-        this.localDescription = localDesc as MockRTCSessionDescription;
+        this.localDescription = {
+            ...localDesc as MockRTCSessionDescription,
+            parsedSdp: answerSDP
+        };
         return this.localDescription;
     }
 
@@ -413,7 +430,7 @@ export class RTCConnection extends EventEmitter {
         this.localDescription = undefined;
 
         if (rawConn.state() === 'closed') return;
-        rawConn.close();
+        rawConn.destroy();
         this.emit('connection-closed');
     }
 

package/src/webrtc-hooks.ts

@@ -163,7 +163,10 @@ export function hookWebRTCConnection(conn: RTCPeerConnection, mockPeer: MockRTCP
             mockOffer = mockPeer.createOffer({
                 mirrorSDP: remoteDescription.sdp,
                 addDataStream: true,
-                connectionMetadata: { userAgent: navigator.userAgent }
+                connectionMetadata: {
+                    userAgent: navigator.userAgent,
+                    sourceURL: window.location.href
+                }
             });
 
             await _setRemoteDescription((await mockOffer).offer);
@@ -176,7 +179,10 @@ export function hookWebRTCConnection(conn: RTCPeerConnection, mockPeer: MockRTCP
                 // Complete the internal <-> mock connection:
                 mockPeer.answerOffer(realOffer, {
                     mirrorSDP: remoteDescription.sdp,
-                    connectionMetadata: { userAgent: navigator.userAgent }
+                    connectionMetadata: {
+                        userAgent: navigator.userAgent,
+                        sourceURL: window.location.href
+                    }
                 }).then(({ answer }) => _setRemoteDescription(answer))
             ]);
 

package/test/integration/events.spec.ts

@@ -32,7 +32,8 @@ describe("MockRTC event subscriptions", function () {
 
             const { offer, setAnswer } = await mockPeer.createOffer({
                 connectionMetadata: {
-                    userAgent: navigator.userAgent
+                    userAgent: navigator.userAgent,
+                    sourceURL: 'https://example.com/'
                 }
             });
             await localConnection.setRemoteDescription(offer);
@@ -58,6 +59,7 @@ describe("MockRTC event subscriptions", function () {
             expect(connectionEvent.timingEvents.disconnectTimestamp).to.equal(undefined);
 
             expect(connectionEvent.metadata.userAgent).to.equal(navigator.userAgent);
+            expect(connectionEvent.metadata.sourceURL).to.equal('https://example.com/');
 
             const { selectedLocalCandidate, selectedRemoteCandidate } = connectionEvent;
             [selectedLocalCandidate, selectedRemoteCandidate].forEach((candidate) => {

package/test/integration/matching.spec.ts

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 import {
     MockRTC,
     expect,
@@ -65,4 +70,188 @@ describe("Connection rule matching", () => {
             'local message 3',
         ]);
     });
+
+    it("can match data connections", async () => {
+        // Explicitly hard-close media connections:
+        await mockRTC.forConnections()
+            .withMedia()
+            .thenClose();
+
+        // Send a message on data channels only:
+        await mockRTC.forConnections()
+            .withDataChannels()
+            .waitForChannel()
+            .thenSend('bye');
+
+        const matchingPeer = await mockRTC.getMatchingPeer();
+
+        // Create a local data connection:
+        const localConn = new RTCPeerConnection();
+
+        const dataChannel = localConn.createDataChannel("dataChannel");
+
+        const messagePromise = new Promise((resolve) => {
+            dataChannel.addEventListener('message', ({ data }) => resolve(data));
+        });
+
+        const localOffer = await localConn.createOffer();
+        await localConn.setLocalDescription(localOffer);
+        const { answer } = await matchingPeer.answerOffer(localOffer);
+        await localConn.setRemoteDescription(answer);
+
+        // Wait until the matching handler sends the configured message:
+        const receivedMessage = await messagePromise;
+        expect(receivedMessage).to.equal('bye');
+    });
+
+    it("can match media connections", async () => {
+        // Explicitly hard-close data connections:
+        await mockRTC.forConnections()
+            .withDataChannels()
+            .thenClose();
+
+        // Send a message on media connections only:
+        await mockRTC.forConnections()
+            .withMedia()
+            .thenEcho();
+
+        const matchingPeer = await mockRTC.getMatchingPeer();
+
+        // Create a local connection:
+        const localConn = new RTCPeerConnection();
+        const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+        localConn.addTrack(stream.getTracks()[0], stream);
+
+        // Turn incoming tracks into readable streams of frames:
+        const mediaStreamPromise = new Promise<ReadableStream<VideoFrame>>((resolve) => {
+            localConn.addEventListener('track', ({ track }) => {
+                const streamProcessor = new MediaStreamTrackProcessor({
+                    track: track as MediaStreamVideoTrack
+                });
+                resolve(streamProcessor.readable);
+            });
+        });
+
+        // Connect the local connection to the matching peer:
+        const localOffer = await localConn.createOffer();
+        await localConn.setLocalDescription(localOffer);
+        const { answer } = await matchingPeer.answerOffer(localOffer);
+        await localConn.setRemoteDescription(answer);
+
+        // Check that our video is mirrored as expected:
+        const localMedia = await mediaStreamPromise;
+        const { value: localFrame } = await localMedia!.getReader().read();
+        expect(localFrame!.displayHeight).to.be.greaterThanOrEqual(240);
+        expect(localFrame!.displayWidth).to.be.greaterThanOrEqual(320);
+    });
+
+    it("can match connections by host", async () => {
+        // Send a message for connections made from example.com pages:
+        await mockRTC.forConnections()
+            .fromPageHostname('example.com')
+            .waitForChannel()
+            .thenSend('hello example.com');
+
+        // Close any other connections:
+        await mockRTC.forConnections()
+            .thenClose();
+
+        const matchingPeer = await mockRTC.getMatchingPeer();
+
+        // Create a local data connection:
+        const localConn = new RTCPeerConnection();
+
+        const dataChannel = localConn.createDataChannel("dataChannel");
+
+        const messagePromise = new Promise((resolve) => {
+            dataChannel.addEventListener('message', ({ data }) => resolve(data));
+        });
+
+        const localOffer = await localConn.createOffer();
+        await localConn.setLocalDescription(localOffer);
+        const { answer } = await matchingPeer.answerOffer(localOffer, {
+            connectionMetadata: {
+                sourceURL: 'https://example.com/abc?x=y#123'
+            }
+        });
+        await localConn.setRemoteDescription(answer);
+
+        // Wait until the matching handler sends the configured message:
+        const receivedMessage = await messagePromise;
+        expect(receivedMessage).to.equal('hello example.com');
+    });
+
+    it("can match connections by URL regex", async () => {
+        // Close some other connections:
+        await mockRTC.forConnections()
+            .fromPageUrlMatching(/\?1+1=3/)
+            .thenClose();
+
+        // Send a message for connections made from matching pages:
+        await mockRTC.forConnections()
+            .fromPageUrlMatching(/\?x=y/)
+            .waitForChannel()
+            .thenSend('hello x=y');
+
+        const matchingPeer = await mockRTC.getMatchingPeer();
+
+        // Create a local data connection:
+        const localConn = new RTCPeerConnection();
+
+        const dataChannel = localConn.createDataChannel("dataChannel");
+
+        const messagePromise = new Promise((resolve) => {
+            dataChannel.addEventListener('message', ({ data }) => resolve(data));
+        });
+
+        const localOffer = await localConn.createOffer();
+        await localConn.setLocalDescription(localOffer);
+        const { answer } = await matchingPeer.answerOffer(localOffer, {
+            connectionMetadata: {
+                sourceURL: 'https://example.com/abc?x=y#123'
+            }
+        });
+        await localConn.setRemoteDescription(answer);
+
+        // Wait until the matching handler sends the configured message:
+        const receivedMessage = await messagePromise;
+        expect(receivedMessage).to.equal('hello x=y');
+    });
+
+    it("can match connections by user agent regex", async () => {
+        // Close some other connections:
+        await mockRTC.forConnections()
+            .fromUserAgentMatching(/IE6/)
+            .thenClose();
+
+        // Send a message for connections made from Firefox:
+        await mockRTC.forConnections()
+            .fromUserAgentMatching(/Firefox/)
+            .waitForChannel()
+            .thenSend('hello Firefox');
+
+        const matchingPeer = await mockRTC.getMatchingPeer();
+
+        // Create a local data connection:
+        const localConn = new RTCPeerConnection();
+
+        const dataChannel = localConn.createDataChannel("dataChannel");
+
+        const messagePromise = new Promise((resolve) => {
+            dataChannel.addEventListener('message', ({ data }) => resolve(data));
+        });
+
+        const localOffer = await localConn.createOffer();
+        await localConn.setLocalDescription(localOffer);
+        const { answer } = await matchingPeer.answerOffer(localOffer, {
+            connectionMetadata: {
+                userAgent: 'Mozilla/5.0 (Firefox/123)'
+            }
+        });
+        await localConn.setRemoteDescription(answer);
+
+        // Wait until the matching handler sends the configured message:
+        const receivedMessage = await messagePromise;
+        expect(receivedMessage).to.equal('hello Firefox');
+    });
 });

package/test/integration/proxy.spec.ts

@@ -525,7 +525,7 @@ describe("When proxying WebRTC traffic", () => {
         expect(remoteFrame!.displayWidth).to.be.greaterThanOrEqual(320);
     });
 
-    it("should include user-agent metadata when creating a hooked offer", async () => {
+    it("should include user-agent & URL metadata when creating a hooked offer", async () => {
         const eventPromise = getDeferred<MockRTCEventData['peer-connected']>();
         mockRTC.on('peer-connected', (peer) => eventPromise.resolve(peer));
 
@@ -555,9 +555,10 @@ describe("When proxying WebRTC traffic", () => {
         // Check that the connection event automatically includes the user agent:
         const connectEvent = await eventPromise;
         expect(connectEvent.metadata.userAgent).to.equal(navigator.userAgent);
+        expect(connectEvent.metadata.sourceURL).to.equal(window.location.href);
     });
 
-    it("should include user-agent metadata when creating a hooked answer", async () => {
+    it("should include user-agent & URL metadata when creating a hooked answer", async () => {
         const eventPromise = getDeferred<MockRTCEventData['peer-connected']>();
         mockRTC.on('peer-connected', (peer) => eventPromise.resolve(peer));
 
@@ -586,6 +587,7 @@ describe("When proxying WebRTC traffic", () => {
         // Check that the connection event automatically includes the user agent:
         const connectEvent = await eventPromise;
         expect(connectEvent.metadata.userAgent).to.equal(navigator.userAgent);
+        expect(connectEvent.metadata.sourceURL).to.equal(window.location.href);
     });
 
 });

package/test/integration/send-steps.spec.ts

@@ -73,4 +73,55 @@ describe("Send steps", function () {
         ]);
     });
 
+    it("should be able to create a new data channel, and send a message there", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .createDataChannel('new-channel')
+            .thenSend('Hello from new channel');
+
+        const localConnection = new RTCPeerConnection();
+
+        const messagePromise = new Promise((resolve) => {
+            localConnection.addEventListener('datachannel', ({ channel }) => {
+                expect(channel.label).to.equal('new-channel');
+                channel.addEventListener('message', ({ data }) => resolve(data));
+            });
+        });
+
+        const { offer, setAnswer } = await mockPeer.createOffer();
+        await localConnection.setRemoteDescription(offer);
+        const localAnswer = await localConnection.createAnswer();
+        await localConnection.setLocalDescription(localAnswer);
+        await setAnswer(localAnswer);
+
+        // Wait for a response:
+        const message = await messagePromise;
+        expect(message).to.equal('Hello from new channel');
+    });
+
+    it("should be able to send a Buffer-based message", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForChannel('dataChannel1')
+            .thenSend(Buffer.from('Hello from buffer'));
+
+        const localConnection = new RTCPeerConnection();
+        const dataChannel1 = localConnection.createDataChannel("dataChannel1");
+
+        const localOffer = await localConnection.createOffer();
+        await localConnection.setLocalDescription(localOffer);
+        const { answer } = await mockPeer.answerOffer(localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        // Wait for a response:
+        let messages: Array<any> = [];
+        dataChannel1.addEventListener('message', (event) => {
+            messages.push(Buffer.from(event.data)); // ArrayBuffer -> node Buffer
+        });
+
+        await waitForChannelClose(dataChannel1);
+
+        expect(messages.map(m => m.toString('utf8'))).to.deep.equal([
+            'Hello from buffer'
+        ]);
+    });
+
 });