@pexip/peer-connection-stats 17.2.0

package/src/tests/statsCollector.test.ts

@@ -0,0 +1,480 @@
+import {setImmediate as timersSetImmediate} from 'timers';
+
+import type {Signal} from '@pexip/signal';
+import {isDefined} from '@pexip/utils';
+
+import {
+    inboundAudio,
+    inboundVideo,
+    outboundAudio,
+    outboundVideo,
+    statsFrom,
+    createStatsCollector,
+    createResolver,
+    addDeltaStats,
+} from '../statsCollector';
+import type {
+    AnyStats,
+    CacheStats,
+    CallQualityStats,
+    Codec,
+    InboundAudio,
+    InboundVideo,
+    NormalizedRTCStats,
+    OutboundAudio,
+    OutboundVideo,
+} from '../statsCollector.types';
+import {Quality} from '../statsCollector.types';
+
+import {multiStats as chromeMulti} from './statsCollector.chrome-multiple.fixtures';
+import {statsData as chromeInboundStats} from './statsCollector.chrome-inbound-presentation.fixtures';
+import {statsData as chromeOutboundStats} from './statsCollector.chrome-outbound-presentation.fixtures';
+import {statsData as firefoxStats} from './statsCollector.firefox.fixtures';
+
+jest.useFakeTimers();
+
+describe('StatsCollector', () => {
+    describe('inboundAudio', () => {
+        it('should exist', () => {
+            expect(typeof inboundAudio).toEqual('function');
+        });
+
+        it('should return valid data for all fields', () => {
+            const lookup = chromeInboundStats;
+
+            const audioEntry = lookup.find(
+                entry => entry.type === 'inbound-rtp' && entry.kind === 'audio',
+            ) as InboundAudio;
+
+            const resolver = createResolver(lookup);
+            const metrics = inboundAudio(resolver.expand(audioEntry));
+
+            expect(metrics).toBeDefined();
+            expect(metrics).toMatchSnapshot();
+        });
+    });
+
+    describe('outboundAudio', () => {
+        it('should exist', () => {
+            expect(typeof outboundAudio).toEqual('function');
+        });
+
+        it('should work', () => {
+            const lookup = chromeOutboundStats;
+
+            const audioEntry = lookup.find(
+                entry =>
+                    entry.type === 'outbound-rtp' && entry.kind === 'audio',
+            ) as OutboundAudio;
+
+            const resolver = createResolver(lookup);
+            const metrics = outboundAudio(resolver.expand(audioEntry));
+
+            expect(metrics).toBeDefined();
+            expect(metrics).toMatchSnapshot();
+        });
+    });
+
+    describe('inboundVideo', () => {
+        it('should exist', () => {
+            expect(typeof inboundVideo).toEqual('function');
+        });
+
+        it('should work', () => {
+            const lookup = chromeInboundStats;
+
+            const videoEntry = lookup.find(
+                entry => entry.type === 'inbound-rtp' && entry.kind === 'video',
+            ) as InboundVideo;
+
+            const resolver = createResolver(lookup);
+            const metrics = inboundVideo(resolver.expand(videoEntry));
+
+            expect(metrics).toBeDefined();
+            expect(metrics).toMatchSnapshot();
+        });
+    });
+
+    describe('outboundVideo', () => {
+        it('should exist', () => {
+            expect(typeof outboundVideo).toEqual('function');
+        });
+
+        it('should work', () => {
+            const lookup = chromeOutboundStats;
+
+            const videoEntry = lookup.find(
+                entry =>
+                    entry.type === 'outbound-rtp' && entry.kind === 'video',
+            ) as OutboundVideo;
+
+            const resolver = createResolver(lookup);
+            const metrics = outboundVideo(resolver.expand(videoEntry));
+
+            expect(metrics).toBeDefined();
+            expect(metrics).toMatchSnapshot();
+        });
+    });
+
+    describe('statsFrom', () => {
+        it('should exist', () => {
+            expect(typeof statsFrom).toEqual('function');
+        });
+
+        it('should return complete data for chromeInboundStats', () => {
+            expect(statsFrom(chromeInboundStats)).toMatchSnapshot();
+        });
+
+        it('should return complete data for chromeOutboundStats', () => {
+            expect(statsFrom(chromeOutboundStats)).toMatchSnapshot();
+        });
+
+        it('should return complete data for firefoxStats', () => {
+            expect(statsFrom(firefoxStats)).toMatchSnapshot();
+        });
+    });
+
+    describe('createResolver', () => {
+        it('should exist', () => {
+            expect(typeof createResolver).toEqual('function');
+        });
+
+        it('should work for flat data with strings & numbers', () => {
+            const inboundRtp: InboundAudio = {
+                type: 'inbound-rtp',
+                kind: 'audio',
+                id: '123',
+                packetsLost: 0,
+            };
+
+            const statsData = [inboundRtp];
+
+            const resolver = createResolver(statsData);
+            const expanded = resolver.expand(inboundRtp);
+
+            expect(Object.keys(expanded).length).toEqual(4);
+            expect(expanded).toMatchSnapshot();
+        });
+
+        it('should work for data with only string values', () => {
+            const inboundRtp: InboundAudio = {
+                type: 'inbound-rtp',
+                kind: 'audio',
+                id: '123',
+            };
+
+            const statsData = [inboundRtp];
+
+            const resolver = createResolver(statsData);
+            const expanded = resolver.expand(inboundRtp);
+
+            expect(Object.keys(expanded).length).toEqual(3);
+            expect(expanded).toMatchSnapshot();
+        });
+
+        it('should work for nested data', () => {
+            const inboundRtp: InboundAudio = {
+                type: 'inbound-rtp',
+                kind: 'audio',
+                id: 'abc',
+                codecId: 'codec1',
+                packetsLost: 0,
+            };
+
+            const codec: Codec = {
+                type: 'codec',
+                id: 'codec1',
+            };
+
+            const statsData: AnyStats[] = [inboundRtp, codec];
+
+            const resolver = createResolver(statsData);
+            const expanded = resolver.expand(inboundRtp);
+
+            expect(Object.keys(expanded).length).toEqual(6);
+            expect(expanded).toMatchSnapshot();
+        });
+
+        it('should not modify input', () => {
+            const inboundRtp: InboundAudio = {
+                type: 'inbound-rtp',
+                kind: 'audio',
+                id: 'abc',
+                packetsLost: 0,
+                codecId: 'codec1',
+            };
+
+            const codec: Codec = {
+                type: 'codec',
+                id: 'codec1',
+            };
+
+            const statsData: AnyStats[] = [{...inboundRtp}, {...codec}];
+            const stat = isDefined(statsData[0]);
+            expect(stat).toEqual(inboundRtp);
+
+            const resolver = createResolver(statsData);
+            const expanded = resolver.expand(stat as InboundAudio);
+
+            expect(stat).toEqual(inboundRtp);
+            expect(expanded).not.toEqual(inboundRtp);
+        });
+    });
+
+    describe('addDeltaStats', () => {
+        it('should exist', () => {
+            expect(typeof addDeltaStats).toEqual('function');
+        });
+
+        it('should calculate bitrate when no "previous" arg', () => {
+            const [lookupNew] = chromeMulti;
+
+            const [outboundNew] = [lookupNew].map(l => {
+                const lookup = isDefined(l);
+                const videoEntry = lookup.find(
+                    entry =>
+                        entry.type === 'outbound-rtp' && entry.kind === 'video',
+                ) as OutboundVideo;
+
+                const resolver = createResolver(lookup);
+                const metrics = outboundVideo(resolver.expand(videoEntry));
+
+                expect(metrics).toBeDefined();
+                expect(metrics.bitrate).toEqual(undefined);
+                return metrics;
+            });
+
+            const statsNew = outboundNew as NormalizedRTCStats;
+            const statsCache: CacheStats = {
+                callQuality: Quality.GOOD,
+                callPacketsStats: [],
+                callQualityStats: [],
+            };
+
+            const [stats, callQuality] = addDeltaStats(statsNew, statsCache);
+
+            expect(stats?.bitrate).toEqual(undefined);
+            expect(callQuality).not.toEqual(Quality.TERRIBLE);
+            expect(stats).toMatchSnapshot();
+        });
+
+        it('should calculate bitrate based on "previous" arg', () => {
+            const [lookupOld, lookupNew] = chromeMulti;
+
+            const [outboundOld, outboundNew] = [lookupOld, lookupNew].map(l => {
+                const lookup = isDefined(l);
+                const videoEntry = lookup.find(
+                    entry =>
+                        entry.type === 'outbound-rtp' && entry.kind === 'video',
+                ) as OutboundVideo;
+
+                const resolver = createResolver(lookup);
+                const metrics = outboundVideo(resolver.expand(videoEntry));
+
+                expect(metrics).toBeDefined();
+                expect(metrics.bitrate).toEqual(undefined);
+                return metrics;
+            });
+
+            const statsNew = outboundNew as NormalizedRTCStats;
+            const statsOld: CacheStats = {
+                previous: outboundOld,
+                callQuality: Quality.GOOD,
+                callPacketsStats: [],
+                callQualityStats: [],
+            };
+
+            const [results] = addDeltaStats(statsNew, statsOld);
+
+            expect(typeof results?.bitrate).toEqual('number');
+            expect(results).toMatchSnapshot();
+        });
+
+        it('should calculate bitrate based on "previous" arg for audio and video', () => {
+            const [statsOld, statsLatest] = chromeMulti.map(statsFrom);
+            const statsNew = isDefined(statsLatest);
+
+            expect(typeof statsNew?.bitrate).toEqual('undefined');
+            expect(typeof statsNew?.bitrate).toEqual('undefined');
+
+            const [results] = addDeltaStats(statsNew, {
+                previous: statsOld,
+                callQuality: Quality.GOOD,
+                callPacketsStats: [],
+                callQualityStats: [],
+            });
+
+            expect(typeof results?.bitrate).toEqual('number');
+            expect(isNaN(results?.bitrate as number)).toEqual(false);
+
+            expect(typeof results?.bitrate).toEqual('number');
+            expect(isNaN(results?.bitrate as number)).toEqual(false);
+
+            expect(typeof results?.bitrate).toEqual('number');
+            expect(isNaN(results.bitrate as number)).toEqual(false);
+
+            expect(typeof results?.bitrate).toEqual('number');
+            expect(isNaN(results?.bitrate as number)).toEqual(false);
+
+            expect(results).toMatchSnapshot();
+        });
+    });
+
+    describe('createStatsCollector', () => {
+        // Use setImmediate from the timers module instead of the global
+        // to avoid it being faked by jest
+        const flushPromises = () => new Promise(timersSetImmediate);
+
+        const getStatsCollector = ({
+            statsEmitMock = jest.fn(),
+            qualityEmitMock = jest.fn(),
+            qualityStatsEmitMock = jest.fn(),
+            mockedStats = {},
+            interval = 1000,
+        }) =>
+            createStatsCollector({
+                input: {
+                    getStats: () =>
+                        Promise.resolve({
+                            forEach: (
+                                callbackfn: (
+                                    value: unknown,
+                                    key: string,
+                                    parent: RTCStatsReport,
+                                ) => void,
+                            ) => {
+                                callbackfn(mockedStats, '', {
+                                    forEach: jest.fn(),
+                                });
+                                /* nothing */
+                            },
+                        }),
+                },
+                signals: {
+                    onRtcStats: {
+                        emit: statsEmitMock,
+                    } as unknown as Signal<NormalizedRTCStats>,
+                    onCallQuality: {
+                        emit: qualityEmitMock,
+                    } as unknown as Signal<Quality>,
+                    onCallQualityStats: {
+                        emit: qualityStatsEmitMock,
+                    } as unknown as Signal<CallQualityStats>,
+                },
+                interval,
+            });
+
+        it.each`
+            interval     | emitted
+            ${undefined} | ${2}
+            ${100}       | ${20}
+        `(
+            'given interval = $interval stats should be emitted $emitted times',
+            async ({
+                interval,
+                emitted,
+            }: {
+                interval?: number;
+                emitted: number;
+            }) => {
+                const emit = jest.fn();
+                const {cleanup} = getStatsCollector({
+                    statsEmitMock: emit,
+                    interval,
+                });
+
+                jest.advanceTimersByTime(2000);
+                await flushPromises();
+                cleanup();
+
+                expect(emit).toHaveBeenCalledWith({
+                    kind: 'audio',
+                    packetsLost: 0,
+                    packetsTransmitted: 0,
+                    recentPercentageLost: 0,
+                    type: 'inbound-rtp',
+                });
+                expect(emit).toHaveBeenCalledTimes(emitted);
+                jest.clearAllMocks();
+
+                jest.advanceTimersByTime(2000);
+                await flushPromises();
+
+                expect(emit).not.toHaveBeenCalled();
+            },
+        );
+
+        it('halts stats updates upon stats reset until manually resumed', async () => {
+            const statsEmit = jest.fn();
+            const qualityEmit = jest.fn();
+            const {cleanup, resetStats} = getStatsCollector({
+                statsEmitMock: statsEmit,
+                qualityEmitMock: qualityEmit,
+                mockedStats: {
+                    audioLevel: 0.0017700735496078372,
+                    bytesReceived: 10689,
+                    codecId: 'RTCCodec_0_Inbound_111',
+                    concealedSamples: 38287,
+                    concealmentEvents: 2,
+                    fecPacketsDiscarded: 0,
+                    fecPacketsReceived: 0,
+                    headerBytesReceived: 1780,
+                    id: 'RTCInboundRTPAudioStream_325581171',
+                    insertedSamplesForDeceleration: 3250,
+                    jitter: 0.001,
+                    jitterBufferDelay: 3628.8,
+                    jitterBufferEmittedCount: 84480,
+                    kind: 'audio',
+                    lastPacketReceivedTimestamp: 1660660870114,
+                    mediaType: 'audio',
+                    packetsDiscarded: 0,
+                    packetsLost: 89,
+                    packetsReceived: 89,
+                    removedSamplesForAcceleration: 2254,
+                    silentConcealedSamples: 37240,
+                    ssrc: 325581171,
+                    timestamp: 1660660870129.574,
+                    totalAudioEnergy: 0.0000037897456073932108,
+                    totalSamplesDuration: 4.139999999999956,
+                    totalSamplesReceived: 123200,
+                    trackId: 'RTCMediaStreamTrack_receiver_1',
+                    transportId: 'RTCTransport_0_1',
+                    type: 'inbound-rtp',
+                },
+            });
+
+            // interval works as usual
+            jest.advanceTimersByTime(1000);
+            await flushPromises();
+            expect(statsEmit).toHaveBeenCalledTimes(1);
+            jest.clearAllMocks();
+
+            // interval disabled with stats reset
+            const resumeStatsUpdates = resetStats();
+            jest.advanceTimersByTime(1000);
+            await flushPromises();
+            expect(statsEmit).not.toHaveBeenCalled();
+            expect(qualityEmit).not.toHaveBeenCalled();
+            jest.clearAllMocks();
+
+            // resume stats updates
+            resumeStatsUpdates();
+            await flushPromises();
+            // manual emit upon reset to clear a potential different old state
+            // because the callQuality has init value of quality:GOOD, which will likely be the same after an ice restart.
+            // This results in not emitting the signal as there is no delta
+            expect(qualityEmit).toHaveBeenCalledTimes(1);
+            jest.clearAllMocks();
+
+            // resuming already flowing stats should be ignored
+            resumeStatsUpdates();
+
+            jest.advanceTimersByTime(1000);
+            await flushPromises();
+            expect(statsEmit).toHaveBeenCalledTimes(1);
+            expect(qualityEmit).not.toHaveBeenCalled(); // because the cache is init with quality:GOOD already
+
+            cleanup();
+        });
+    });
+});

package/src/utils.ts

@@ -0,0 +1,41 @@
+import type {Signal} from '@pexip/signal';
+import {createSignal} from '@pexip/signal';
+
+import type {StatsSignals} from './statsCollector.types';
+
+const SIGNAL_PREFIX = 'call:peerConnection:stats';
+
+const REQUIRED_STATS_SIGNAL_KEYS = [
+    'onRtcStats',
+    'onCallQualityStats',
+    'onCallQuality',
+] as const;
+
+/**
+ * Create and return all required and optional (if specified with `more`),
+ * signals for infinity client to work
+ *
+ * @param scope - any scope prefix for the generated signal name, @see Signal
+ * @param more - Keys from `InfinitySignalsOptional`, @see InfinitySignalsOptional
+ *
+ * The following signals created by default
+ * - 'onConnected',
+ * - 'onAnswer',
+ *
+ * @see REQUIRED_STATS_SIGNAL_KEYS
+ */
+export const createStatsSignals = (scope = '') => {
+    const signalScope = scope && [scope, ':'].join('');
+    return REQUIRED_STATS_SIGNAL_KEYS.reduce(
+        (signals, key) => ({
+            ...signals,
+            [key]: createSignal<
+                StatsSignals[typeof key] extends Signal<infer S> ? S : never
+            >({
+                name: `${SIGNAL_PREFIX}:${signalScope}:${key}`,
+                allowEmittingWithoutObserver: true,
+            }),
+        }),
+        {} as StatsSignals,
+    );
+};