Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
15.7 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {
	createVoiceLatencySnapshot,
	observeVoiceLatencyGap,
	recordVoiceLatencySample,
	resetVoiceLatencySnapshot,
	startVoiceLatencyTracking,
	stopVoiceLatencyTracking,
	type VoiceLatencySnapshot,
} from '@app/features/voice/engine/VoiceLatencyTracker';
import type {
	VoiceEngineV2LatencyDataPoint as LatencyDataPoint,
	VoiceEngineV2PerTrackStats as PerTrackStats,
	VoiceEngineV2TransportInfo as TransportInfo,
	VoiceEngineV2VoiceStats as VoiceStats,
	VoiceEngineV2StatsSample as VoiceStatsSample,
} from '@fluxer/voice_engine_v2/src/protocol/types';
import {assign, initialTransition, type SnapshotFrom, setup, transition} from 'xstate';

const MAX_LATENCY_HISTORY = 60;
const MAX_TIME_SERIES_SAMPLES = 60;

export interface VoiceStatsRtpCounter {
	bytes?: number;
	packetsLost?: number;
	packetsReceived?: number;
	timestamp: number;
}

interface VoiceStatsMachineContext {
	roomIdentity: unknown | null;
	latencyIntervalActive: boolean;
	statsIntervalActive: boolean;
	statsCollectionInFlight: boolean;
	statsGeneration: number;
	latency: VoiceLatencySnapshot;
	currentLatency: number | null;
	averageLatency: number | null;
	latencyHistory: Array<LatencyDataPoint>;
	voiceStats: VoiceStats;
	perTrackStats: Array<PerTrackStats>;
	statsTimeSeries: Array<VoiceStatsSample>;
	publisherTransport: TransportInfo | null;
	subscriberTransport: TransportInfo | null;
	rtpCounters: Map<string, VoiceStatsRtpCounter>;
	connectionStartTime: number | null;
	reconnectionCount: number;
}

export type VoiceStatsEvent =
	| {type: 'room.set'; roomIdentity: unknown | null; now: number}
	| {type: 'latency.start'}
	| {type: 'latency.stop'}
	| {type: 'latency.sample'; timestamp: number; latency: number}
	| {type: 'latency.gap'; timestamp: number}
	| {type: 'stats.start'}
	| {type: 'stats.stop'}
	| {type: 'stats.tick'; timestamp: number}
	| {type: 'stats.collectionStarted'; generation: number; roomIdentity: unknown}
	| {
			type: 'stats.collectionSucceeded';
			generation: number;
			roomIdentity: unknown;
			timestamp: number;
			participantCount: number;
			rtt: number;
			tracks: Array<PerTrackStats>;
			publisherTransport: TransportInfo | null;
			subscriberTransport: TransportInfo | null;
			rtpCounters: Map<string, VoiceStatsRtpCounter>;
			activeCounterIds: Set<string>;
	  }
	| {type: 'stats.collectionFinished'; generation: number}
	| {type: 'reconnection.increment'}
	| {type: 'stats.reset'}
	| {type: 'stats.cleanup'};

export type VoiceStatsCollectionDecision =
	| {type: 'skip'; reason: 'no-room' | 'not-tracking' | 'in-flight'}
	| VoiceStatsCollectDecision;

export interface VoiceStatsCollectDecision {
	type: 'collect';
	generation: number;
	roomIdentity: unknown;
	rtpCounters: Map<string, VoiceStatsRtpCounter>;
}

export function createInitialVoiceStats(): VoiceStats {
	return {
		audioSendBitrate: 0,
		audioRecvBitrate: 0,
		videoSendBitrate: 0,
		videoRecvBitrate: 0,
		audioPacketLoss: 0,
		videoPacketLoss: 0,
		rtt: 0,
		jitter: 0,
		participantCount: 0,
		duration: 0,
	};
}

function initialContext(): VoiceStatsMachineContext {
	return {
		roomIdentity: null,
		latencyIntervalActive: false,
		statsIntervalActive: false,
		statsCollectionInFlight: false,
		statsGeneration: 0,
		latency: createVoiceLatencySnapshot(),
		currentLatency: null,
		averageLatency: null,
		latencyHistory: [],
		voiceStats: createInitialVoiceStats(),
		perTrackStats: [],
		statsTimeSeries: [],
		publisherTransport: null,
		subscriberTransport: null,
		rtpCounters: new Map(),
		connectionStartTime: null,
		reconnectionCount: 0,
	};
}

function syncLatencyContext(
	context: VoiceStatsMachineContext,
	latency: VoiceLatencySnapshot,
): VoiceStatsMachineContext {
	return {
		...context,
		latency,
		latencyIntervalActive: latency.tracking,
		currentLatency: latency.currentLatency,
		averageLatency: latency.averageLatency,
		latencyHistory: latency.latencyHistory,
	};
}

function setRoom(
	context: VoiceStatsMachineContext,
	roomIdentity: unknown | null,
	now: number,
): VoiceStatsMachineContext {
	const roomChanged = context.roomIdentity !== roomIdentity;
	const nextContext = {
		...context,
		roomIdentity,
		connectionStartTime: roomIdentity !== null ? now : null,
		statsCollectionInFlight: roomChanged ? false : context.statsCollectionInFlight,
		statsGeneration: roomChanged ? context.statsGeneration + 1 : context.statsGeneration,
		rtpCounters: roomChanged ? new Map() : context.rtpCounters,
	};
	if (!roomChanged) return nextContext;
	return syncLatencyContext(
		nextContext,
		resetVoiceLatencySnapshot({tracking: context.latency.tracking && roomIdentity != null, now}),
	);
}

function startLatency(context: VoiceStatsMachineContext): VoiceStatsMachineContext {
	if (context.latencyIntervalActive) return context;
	return syncLatencyContext(context, startVoiceLatencyTracking(context.latency));
}

function stopLatency(context: VoiceStatsMachineContext): VoiceStatsMachineContext {
	if (!context.latencyIntervalActive) return context;
	return syncLatencyContext(context, stopVoiceLatencyTracking(context.latency));
}

function recordLatencySample(
	context: VoiceStatsMachineContext,
	timestamp: number,
	latency: number,
): VoiceStatsMachineContext {
	if (!context.latencyIntervalActive) return context;
	return syncLatencyContext(
		context,
		recordVoiceLatencySample(context.latency, timestamp, latency, {historyLimit: MAX_LATENCY_HISTORY}),
	);
}

function recordLatencyGap(context: VoiceStatsMachineContext, timestamp: number): VoiceStatsMachineContext {
	if (!context.latencyIntervalActive) return context;
	return syncLatencyContext(context, observeVoiceLatencyGap(context.latency, timestamp));
}

function startStats(context: VoiceStatsMachineContext): VoiceStatsMachineContext {
	if (context.statsIntervalActive) return context;
	return {
		...context,
		statsIntervalActive: true,
		statsGeneration: context.statsGeneration + 1,
		statsCollectionInFlight: false,
	};
}

function stopStats(context: VoiceStatsMachineContext): VoiceStatsMachineContext {
	if (!context.statsIntervalActive && !context.statsCollectionInFlight) return context;
	return {
		...context,
		statsIntervalActive: false,
		statsGeneration: context.statsGeneration + 1,
		statsCollectionInFlight: false,
	};
}

function tickStats(context: VoiceStatsMachineContext, timestamp: number): VoiceStatsMachineContext {
	if (!context.statsIntervalActive || context.connectionStartTime == null) return context;
	const duration = Math.floor((timestamp - context.connectionStartTime) / 1000);
	if (duration === context.voiceStats.duration) return context;
	return {
		...context,
		voiceStats: {
			...context.voiceStats,
			duration,
		},
	};
}

function startCollection(
	context: VoiceStatsMachineContext,
	generation: number,
	roomIdentity: unknown,
): VoiceStatsMachineContext {
	if (
		!context.statsIntervalActive ||
		context.statsCollectionInFlight ||
		context.roomIdentity !== roomIdentity ||
		context.statsGeneration !== generation
	) {
		return context;
	}
	return {...context, statsCollectionInFlight: true};
}

function pruneRtpCounters(
	rtpCounters: Map<string, VoiceStatsRtpCounter>,
	activeCounterIds: Set<string>,
): Map<string, VoiceStatsRtpCounter> {
	const next = new Map<string, VoiceStatsRtpCounter>();
	for (const [counterId, counter] of rtpCounters) {
		if (activeCounterIds.has(counterId)) {
			next.set(counterId, counter);
		}
	}
	return next;
}

function buildVoiceStats(
	context: VoiceStatsMachineContext,
	event: Extract<VoiceStatsEvent, {type: 'stats.collectionSucceeded'}>,
): {stats: VoiceStats; sample: VoiceStatsSample} {
	let audioSendBitrate = 0;
	let audioRecvBitrate = 0;
	let videoSendBitrate = 0;
	let videoRecvBitrate = 0;
	let audioPacketLossSum = 0;
	let videoPacketLossSum = 0;
	let jitterSumMs = 0;
	let audioPacketLossCount = 0;
	let videoPacketLossCount = 0;
	let jitterCount = 0;
	for (const track of event.tracks) {
		if (track.direction === 'send' && track.kind === 'audio') audioSendBitrate += track.bitrateKbps;
		else if (track.direction === 'send' && track.kind === 'video') videoSendBitrate += track.bitrateKbps;
		else if (track.direction === 'recv' && track.kind === 'audio') {
			audioRecvBitrate += track.bitrateKbps;
			if (typeof track.packetsLossPercent === 'number') {
				audioPacketLossSum += track.packetsLossPercent;
				audioPacketLossCount += 1;
			}
			if (typeof track.jitterMs === 'number') {
				jitterSumMs += track.jitterMs;
				jitterCount += 1;
			}
		} else if (track.direction === 'recv' && track.kind === 'video') {
			videoRecvBitrate += track.bitrateKbps;
			if (typeof track.packetsLossPercent === 'number') {
				videoPacketLossSum += track.packetsLossPercent;
				videoPacketLossCount += 1;
			}
		}
	}
	const audioPacketLoss = audioPacketLossCount > 0 ? audioPacketLossSum / audioPacketLossCount : 0;
	const videoPacketLoss = videoPacketLossCount > 0 ? videoPacketLossSum / videoPacketLossCount : 0;
	const jitter = jitterCount > 0 ? jitterSumMs / jitterCount : 0;
	const duration = context.connectionStartTime ? Math.floor((event.timestamp - context.connectionStartTime) / 1000) : 0;
	const stats: VoiceStats = {
		audioSendBitrate: Math.round(audioSendBitrate),
		audioRecvBitrate: Math.round(audioRecvBitrate),
		videoSendBitrate: Math.round(videoSendBitrate),
		videoRecvBitrate: Math.round(videoRecvBitrate),
		audioPacketLoss: Math.round(audioPacketLoss * 10) / 10,
		videoPacketLoss: Math.round(videoPacketLoss * 10) / 10,
		rtt: Math.round(event.rtt),
		jitter: Math.round(jitter),
		participantCount: event.participantCount,
		duration,
	};
	return {
		stats,
		sample: {
			timestamp: event.timestamp,
			rtt: stats.rtt,
			jitter: stats.jitter,
			audioPacketLoss: stats.audioPacketLoss,
			videoPacketLoss: stats.videoPacketLoss,
			audioSendBitrate: stats.audioSendBitrate,
			audioRecvBitrate: stats.audioRecvBitrate,
			videoSendBitrate: stats.videoSendBitrate,
			videoRecvBitrate: stats.videoRecvBitrate,
		},
	};
}

function appendVoiceStatsSample(
	timeSeries: ReadonlyArray<VoiceStatsSample>,
	sample: VoiceStatsSample,
	limit: number,
): Array<VoiceStatsSample> {
	if (limit <= 0) return [];
	const retainedCount = Math.min(timeSeries.length, limit - 1);
	const nextTimeSeries = new Array<VoiceStatsSample>(retainedCount + 1);
	const startIndex = timeSeries.length - retainedCount;
	for (let i = 0; i < retainedCount; i += 1) {
		nextTimeSeries[i] = timeSeries[startIndex + i];
	}
	nextTimeSeries[retainedCount] = sample;
	return nextTimeSeries;
}

function applyCollectionResult(
	context: VoiceStatsMachineContext,
	event: Extract<VoiceStatsEvent, {type: 'stats.collectionSucceeded'}>,
): VoiceStatsMachineContext {
	if (
		!context.statsIntervalActive ||
		!context.statsCollectionInFlight ||
		context.statsGeneration !== event.generation ||
		context.roomIdentity !== event.roomIdentity
	) {
		return context;
	}
	const {stats, sample} = buildVoiceStats(context, event);
	return {
		...context,
		voiceStats: stats,
		perTrackStats: event.tracks,
		publisherTransport: event.publisherTransport,
		subscriberTransport: event.subscriberTransport,
		statsTimeSeries: appendVoiceStatsSample(context.statsTimeSeries, sample, MAX_TIME_SERIES_SAMPLES),
		rtpCounters: pruneRtpCounters(event.rtpCounters, event.activeCounterIds),
	};
}

function finishCollection(context: VoiceStatsMachineContext, generation: number): VoiceStatsMachineContext {
	if (context.statsGeneration !== generation) return context;
	return {...context, statsCollectionInFlight: false};
}

function incrementReconnectionCount(context: VoiceStatsMachineContext): VoiceStatsMachineContext {
	return {...context, reconnectionCount: context.reconnectionCount + 1};
}

function resetState(context: VoiceStatsMachineContext): VoiceStatsMachineContext {
	return {
		...initialContext(),
		statsGeneration: context.statsGeneration + 1,
	};
}

const voiceStatsStateMachine = setup({
	types: {} as {
		context: VoiceStatsMachineContext;
		events: VoiceStatsEvent;
	},
	actions: {
		setRoom: assign(({context, event}) =>
			event.type === 'room.set' ? setRoom(context, event.roomIdentity, event.now) : context,
		),
		startLatency: assign(({context}) => startLatency(context)),
		stopLatency: assign(({context}) => stopLatency(context)),
		recordLatencySample: assign(({context, event}) =>
			event.type === 'latency.sample' ? recordLatencySample(context, event.timestamp, event.latency) : context,
		),
		recordLatencyGap: assign(({context, event}) =>
			event.type === 'latency.gap' ? recordLatencyGap(context, event.timestamp) : context,
		),
		startStats: assign(({context}) => startStats(context)),
		stopStats: assign(({context}) => stopStats(context)),
		tickStats: assign(({context, event}) =>
			event.type === 'stats.tick' ? tickStats(context, event.timestamp) : context,
		),
		startCollection: assign(({context, event}) =>
			event.type === 'stats.collectionStarted'
				? startCollection(context, event.generation, event.roomIdentity)
				: context,
		),
		applyCollectionResult: assign(({context, event}) =>
			event.type === 'stats.collectionSucceeded' ? applyCollectionResult(context, event) : context,
		),
		finishCollection: assign(({context, event}) =>
			event.type === 'stats.collectionFinished' ? finishCollection(context, event.generation) : context,
		),
		incrementReconnectionCount: assign(({context}) => incrementReconnectionCount(context)),
		reset: assign(({context}) => resetState(context)),
	},
	guards: {
		trackingBoth: ({context}) => context.latencyIntervalActive && context.statsIntervalActive,
		trackingLatency: ({context}) => context.latencyIntervalActive,
		trackingStats: ({context}) => context.statsIntervalActive,
	},
}).createMachine({
	id: 'voiceStats',
	context: () => initialContext(),
	initial: 'routing',
	on: {
		'room.set': {target: '.routing', actions: 'setRoom'},
		'latency.start': {target: '.routing', actions: 'startLatency'},
		'latency.stop': {target: '.routing', actions: 'stopLatency'},
		'latency.sample': {target: '.routing', actions: 'recordLatencySample'},
		'latency.gap': {target: '.routing', actions: 'recordLatencyGap'},
		'stats.start': {target: '.routing', actions: 'startStats'},
		'stats.stop': {target: '.routing', actions: 'stopStats'},
		'stats.tick': {target: '.routing', actions: 'tickStats'},
		'stats.collectionStarted': {target: '.routing', actions: 'startCollection'},
		'stats.collectionSucceeded': {target: '.routing', actions: 'applyCollectionResult'},
		'stats.collectionFinished': {target: '.routing', actions: 'finishCollection'},
		'reconnection.increment': {target: '.routing', actions: 'incrementReconnectionCount'},
		'stats.reset': {target: '.routing', actions: 'reset'},
		'stats.cleanup': {target: '.routing', actions: 'reset'},
	},
	states: {
		routing: {
			always: [
				{guard: 'trackingBoth', target: 'trackingBoth'},
				{guard: 'trackingLatency', target: 'trackingLatency'},
				{guard: 'trackingStats', target: 'trackingStats'},
				{target: 'idle'},
			],
		},
		idle: {},
		trackingLatency: {},
		trackingStats: {},
		trackingBoth: {},
	},
});

export type VoiceStatsSnapshot = SnapshotFrom<typeof voiceStatsStateMachine>;

export function createVoiceStatsSnapshot(): VoiceStatsSnapshot {
	return initialTransition(voiceStatsStateMachine)[0];
}

export function transitionVoiceStatsSnapshot(snapshot: VoiceStatsSnapshot, event: VoiceStatsEvent): VoiceStatsSnapshot {
	return transition(voiceStatsStateMachine, snapshot, event)[0] as VoiceStatsSnapshot;
}

export function selectVoiceStatsCollectionDecision(snapshot: VoiceStatsSnapshot): VoiceStatsCollectionDecision {
	if (snapshot.context.roomIdentity === null) return {type: 'skip', reason: 'no-room'};
	if (!snapshot.context.statsIntervalActive) return {type: 'skip', reason: 'not-tracking'};
	if (snapshot.context.statsCollectionInFlight) return {type: 'skip', reason: 'in-flight'};
	return {
		type: 'collect',
		generation: snapshot.context.statsGeneration,
		roomIdentity: snapshot.context.roomIdentity,
		rtpCounters: new Map(snapshot.context.rtpCounters),
	};
}