Skip to content

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

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

import type {ChannelID, GuildID} from '@app/api/BrandedTypes';
import type {IGatewayService} from '@app/api/infrastructure/IGatewayService';
import type {ILiveKitService, LiveKitParticipantRef} from '@app/api/infrastructure/ILiveKitService';
import type {IVoiceRoomStore} from '@app/api/infrastructure/IVoiceRoomStore';
import {SERVER_MUTE_ATTRIBUTE} from '@app/api/infrastructure/LiveKitService';
import {isDMRoom, parseParticipantMetadataWithRaw, parseRoomName} from '@app/api/infrastructure/VoiceRoomContext';
import {Logger} from '@app/api/Logger';
import {
	voiceParticipantConfirmUnavailableTotal,
	voiceParticipantsDisconnectedTotal,
} from '@app/api/voice/VoiceParticipantMetrics';
import type {VoiceTopology} from '@app/api/voice/VoiceTopology';
import {ms} from 'itty-time';
import type {ParticipantPermission, WebhookEvent} from 'livekit-server-sdk';
import {TrackSource, WebhookReceiver} from 'livekit-server-sdk';

const WEBHOOK_CLOCK_TOLERANCE_SECONDS = 60;

interface SourceServer {
	regionId: string;
	serverId: string;
}

export const REXCTL_TEST_ROOM_PREFIX = 'rexctl-test-';

interface VoiceWebhookParticipantContext {
	readonly type: 'dm' | 'guild';
	readonly channelId: ChannelID;
	readonly guildId?: GuildID;
}

type ParticipantContext = NonNullable<ReturnType<typeof parseParticipantMetadataWithRaw>>['context'];

type ConfirmOutcome =
	| {status: 'confirmed'}
	| {status: 'rejected'; error: string | undefined}
	| {status: 'unavailable'; error: unknown};

const CONFIRM_ATTEMPTS = 2;
const DM_CONFIRM_RECHECK_DELAYS_MS = [ms('5 seconds'), ms('10 seconds')];

function sleep(durationMs: number): Promise<void> {
	return new Promise((resolve) => {
		setTimeout(resolve, durationMs);
	});
}

export class LiveKitWebhookService {
	private receivers: Map<string, WebhookReceiver>;
	private serversByKey: Map<string, Array<SourceServer>>;

	constructor(
		private voiceRoomStore: IVoiceRoomStore,
		private gatewayService: IGatewayService,
		private liveKitService: ILiveKitService,
		private voiceTopology: VoiceTopology,
	) {
		this.receivers = new Map();
		this.serversByKey = new Map();
		this.rebuildReceivers();
		this.voiceTopology.registerSubscriber(() => this.rebuildReceivers());
	}

	async verifyAndParse(
		body: string,
		authHeader: string | undefined,
	): Promise<{
		event: WebhookEvent;
		apiKey: string;
	}> {
		if (!authHeader) {
			throw new Error('Missing authorization header');
		}
		let lastError: Error | null = null;
		for (const [apiKey, receiver] of this.receivers.entries()) {
			try {
				const event = await receiver.receive(body, authHeader, false, WEBHOOK_CLOCK_TOLERANCE_SECONDS);
				return {event: event as WebhookEvent, apiKey};
			} catch (error) {
				lastError = error as Error;
			}
		}
		throw lastError || new Error('No webhook receivers configured');
	}

	async handleWebhookRequest(params: {body: string; authHeader: string | undefined}): Promise<{
		status: number;
		body: string | null;
	}> {
		const {body, authHeader} = params;
		Logger.debug(
			{
				bodySize: body.length,
				hasAuthHeader: Boolean(authHeader),
			},
			'Received LiveKit webhook request',
		);
		try {
			const data = await this.verifyAndParse(body, authHeader);
			const eventName = data.event.event;
			Logger.debug(
				{
					apiKey: data.apiKey,
					event: eventName,
					roomName: data.event.room?.name ?? null,
					participantIdentity: data.event.participant?.identity ?? null,
					trackType: data.event.track?.type ?? null,
				},
				'Parsed LiveKit webhook event',
			);
			if (data.event.numDropped != null && data.event.numDropped > 0) {
				Logger.warn(
					{
						numDropped: data.event.numDropped,
						roomName: data.event.room?.name ?? null,
						eventType: data.event.event,
					},
					'LiveKit webhook reports dropped events',
				);
			}
			await this.processEvent(data);
			return {status: 200, body: null};
		} catch (error) {
			Logger.debug({error}, 'Error processing LiveKit webhook');
			return {status: 400, body: 'Invalid webhook'};
		}
	}

	private rebuildReceivers(): void {
		const newReceivers = new Map<string, WebhookReceiver>();
		const newServersByKey = new Map<string, Array<SourceServer>>();
		const regions = this.voiceTopology.getAllRegions();
		for (const region of regions) {
			const servers = this.voiceTopology.getServersForRegion(region.id);
			for (const server of servers) {
				newReceivers.set(server.apiKey, new WebhookReceiver(server.apiKey, server.apiSecret));
				const sharing = newServersByKey.get(server.apiKey) ?? [];
				sharing.push({regionId: region.id, serverId: server.serverId});
				newServersByKey.set(server.apiKey, sharing);
			}
		}
		this.receivers = newReceivers;
		this.serversByKey = newServersByKey;
		Logger.debug(
			{
				regionCount: regions.length,
				serverCount: newReceivers.size,
			},
			'Rebuilt LiveKit webhook receivers',
		);
	}

	private resolveSource(
		apiKey: string,
		raw: {region_id?: string; server_id?: string} | undefined,
	): SourceServer | undefined {
		const servers = this.serversByKey.get(apiKey) ?? [];
		if (servers.length === 1) {
			return servers[0];
		}
		if (!raw?.region_id || !raw.server_id) {
			return undefined;
		}
		return servers.find((server) => server.regionId === raw.region_id && server.serverId === raw.server_id);
	}

	private async isFromPinnedServer(
		guildId: GuildID | undefined,
		channelId: ChannelID,
		source: SourceServer | undefined,
	): Promise<boolean> {
		if (!source) {
			return false;
		}
		const pinned = await this.voiceRoomStore.getPinnedRoomServer(guildId, channelId);
		if (pinned && (pinned.regionId !== source.regionId || pinned.serverId !== source.serverId)) {
			Logger.debug(
				{
					guildId: guildId?.toString(),
					channelId: channelId.toString(),
					sourceServer: source.serverId,
					pinnedServer: pinned.serverId,
				},
				'Ignoring LiveKit webhook from a server the room is not pinned to',
			);
			return false;
		}
		return true;
	}

	async handleRoomFinished(event: WebhookEvent, apiKey: string): Promise<void> {
		if (event.event !== 'room_finished' || !event.room) {
			return;
		}
		const roomName = event.room.name;
		const context = parseRoomName(roomName);
		if (!context) {
			Logger.warn({roomName}, 'Unknown room name format');
			return;
		}
		const guildId = isDMRoom(context) ? undefined : context.guildId;
		Logger.debug(
			{roomName, contextType: context.type, guildId: guildId?.toString(), channelId: context.channelId.toString()},
			'Processing LiveKit room_finished event',
		);
		const source = this.resolveSource(apiKey, undefined);
		if (!(await this.isFromPinnedServer(guildId, context.channelId, source))) {
			return;
		}
		await this.voiceRoomStore.deleteRoomServer(guildId, context.channelId);
		Logger.debug(
			{guildId: guildId?.toString(), channelId: context.channelId.toString()},
			'Cleared voice room server pinning',
		);
	}

	private async handleParticipantJoined(event: WebhookEvent, apiKey: string): Promise<void> {
		if (event.event !== 'participant_joined' || !event.participant) {
			return;
		}
		const {participant} = event;
		const roomName = event.room?.name ?? null;
		const metadata = participant.metadata ?? '';
		const parsed = metadata ? parseParticipantMetadataWithRaw(metadata) : null;
		if (!parsed) {
			Logger.warn(
				{participantIdentity: participant.identity, roomName, hasMetadata: Boolean(metadata)},
				'LiveKit participant_joined without usable metadata - disconnecting participant',
			);
			await this.removeJoinedParticipant(
				await this.locateJoinedParticipant({apiKey, roomName, identity: participant.identity, metadata}),
				'unidentified',
			);
			return;
		}
		const {context, raw} = parsed;
		const outcome = await this.confirmWithRetry(context, raw.token_nonce);
		const logContext = {
			type: context.type,
			guildId: context.type === 'guild' ? context.guildId.toString() : undefined,
			channelId: context.channelId.toString(),
			connectionId: context.connectionId,
			participantIdentity: participant.identity,
			roomName,
		};
		if (outcome.status === 'confirmed') {
			return;
		}
		if (outcome.status === 'unavailable') {
			voiceParticipantConfirmUnavailableTotal.inc();
			Logger.warn(
				{...logContext, error: outcome.error},
				'LiveKit participant_joined confirm unavailable - leaving participant for the sweep',
			);
			return;
		}
		const located = await this.locateJoinedParticipant({apiKey, roomName, identity: participant.identity, metadata});
		if (context.type === 'dm' && participant.permission) {
			void this.holdDmJoin(context, raw.token_nonce, located, participant.permission, logContext);
			return;
		}
		Logger.warn(
			{...logContext, error: outcome.error},
			'LiveKit participant_joined rejected - disconnecting participant',
		);
		await this.removeJoinedParticipant(located, 'rejected');
	}

	private async holdDmJoin(
		context: ParticipantContext,
		tokenNonce: string,
		located: Array<LiveKitParticipantRef>,
		permission: ParticipantPermission,
		logContext: Record<string, unknown>,
	): Promise<void> {
		const setPermission = async (next: Partial<ParticipantPermission>) => {
			for (const ref of located) {
				await this.liveKitService.setParticipantPermission({...ref, permission: next});
			}
		};
		try {
			await setPermission({...permission, canSubscribe: false});
			let outcome: ConfirmOutcome = {status: 'rejected', error: undefined};
			for (const delayMs of DM_CONFIRM_RECHECK_DELAYS_MS) {
				await sleep(delayMs);
				outcome = await this.confirmWithRetry(context, tokenNonce);
				if (outcome.status !== 'rejected') {
					await setPermission(permission);
					return;
				}
			}
			Logger.warn(
				{...logContext, error: outcome.status === 'rejected' ? outcome.error : undefined},
				'LiveKit participant_joined rejected - disconnecting participant',
			);
			await this.removeJoinedParticipant(located, 'rejected');
		} catch (error) {
			Logger.error({...logContext, error}, 'Failed to recheck LiveKit call participant');
		}
	}

	private async confirmWithRetry(context: ParticipantContext, tokenNonce: string): Promise<ConfirmOutcome> {
		let lastError: unknown = null;
		for (let attempt = 0; attempt < CONFIRM_ATTEMPTS; attempt += 1) {
			try {
				const result = await this.gatewayService.confirmVoiceConnection({
					guildId: context.type === 'guild' ? context.guildId : undefined,
					channelId: context.channelId,
					connectionId: context.connectionId,
					tokenNonce,
				});
				return result.success ? {status: 'confirmed'} : {status: 'rejected', error: result.error};
			} catch (error) {
				lastError = error;
			}
		}
		return {status: 'unavailable', error: lastError};
	}

	private async locateJoinedParticipant(params: {
		apiKey: string;
		roomName: string | null;
		identity: string;
		metadata: string;
	}): Promise<Array<LiveKitParticipantRef>> {
		const {apiKey, roomName, identity, metadata} = params;
		const servers = this.serversByKey.get(apiKey) ?? [];
		if (roomName === null || servers.length === 0) {
			Logger.warn(
				{participantIdentity: identity, roomName, serverCount: servers.length},
				'Cannot determine where to disconnect LiveKit participant',
			);
			return [];
		}
		const refs = servers.map((server) => ({
			regionId: server.regionId,
			serverId: server.serverId,
			roomName,
			identity,
		}));
		if (refs.length === 1) {
			return refs;
		}
		const located: Array<LiveKitParticipantRef> = [];
		for (const ref of refs) {
			const result = await this.liveKitService.getParticipant(ref);
			if (result.status === 'ok' && result.participant?.metadata === metadata) {
				located.push(ref);
			}
		}
		return located;
	}

	private async removeJoinedParticipant(
		located: Array<LiveKitParticipantRef>,
		reason: 'unidentified' | 'rejected',
	): Promise<void> {
		if (located.length === 0) {
			return;
		}
		voiceParticipantsDisconnectedTotal.inc(`reason="${reason}"`);
		for (const ref of located) {
			await this.liveKitService.removeParticipant(ref);
		}
	}

	private async isParticipantStillInRoom(params: {
		participantIdentity: string;
		context: VoiceWebhookParticipantContext;
		source: SourceServer;
	}): Promise<'present' | 'absent' | 'unknown'> {
		const {participantIdentity, context} = params;
		const guildId = context.type === 'guild' ? context.guildId : undefined;
		const {regionId, serverId} = params.source;
		const result = await this.liveKitService.listParticipants({
			guildId,
			channelId: context.channelId,
			regionId,
			serverId,
		});
		if (result.status === 'error') {
			Logger.warn(
				{errorCode: result.errorCode, retryable: result.retryable, participantIdentity},
				'Cannot determine participant presence due to LiveKit lookup failure',
			);
			return 'unknown';
		}
		return result.participants.some((p) => p.identity === participantIdentity) ? 'present' : 'absent';
	}

	private async handleParticipantLeft(event: WebhookEvent, apiKey: string): Promise<void> {
		if (event.event !== 'participant_left' && event.event !== 'participant_connection_aborted') {
			return;
		}
		const {participant} = event;
		if (!participant?.metadata) {
			Logger.debug('Participant left without metadata, skipping');
			return;
		}
		const parsed = parseParticipantMetadataWithRaw(participant.metadata);
		if (!parsed) {
			Logger.warn({metadata: participant.metadata}, 'Failed to parse participant metadata');
			return;
		}
		const {context, raw} = parsed;
		const source = this.resolveSource(apiKey, raw);
		Logger.debug(
			{
				type: context.type,
				participantIdentity: participant.identity,
				roomName: event.room?.name ?? null,
				channelId: context.channelId.toString(),
				guildId: context.type === 'guild' ? context.guildId.toString() : undefined,
				userId: context.userId.toString(),
				connectionId: context.connectionId,
			},
			`Processing LiveKit ${event.event} event`,
		);
		try {
			const guildIdForPin = context.type === 'guild' ? context.guildId : undefined;
			if (!source || !(await this.isFromPinnedServer(guildIdForPin, context.channelId, source))) {
				return;
			}
			const presenceStatus = await this.isParticipantStillInRoom({
				participantIdentity: participant.identity,
				context,
				source,
			});
			if (presenceStatus === 'present') {
				Logger.warn(
					{
						type: context.type,
						participantIdentity: participant.identity,
						channelId: context.channelId.toString(),
						guildId: context.type === 'guild' ? context.guildId.toString() : undefined,
						connectionId: context.connectionId,
					},
					'Ignoring stale participant_left event because participant is still present in room',
				);
				return;
			}
			if (presenceStatus === 'unknown') {
				Logger.warn(
					{
						type: context.type,
						participantIdentity: participant.identity,
						channelId: context.channelId.toString(),
						guildId: context.type === 'guild' ? context.guildId.toString() : undefined,
						connectionId: context.connectionId,
					},
					'Skipping participant_left disconnect because participant presence is uncertain',
				);
				return;
			}
			const guildId = context.type === 'guild' ? context.guildId : undefined;
			Logger.info(
				{
					type: context.type,
					guildId: guildId?.toString(),
					userId: context.userId.toString(),
					channelId: context.channelId.toString(),
					connectionId: context.connectionId,
				},
				'LiveKit participant_left - disconnecting voice user',
			);
			const result = await this.gatewayService.disconnectVoiceUserIfInChannel({
				guildId,
				channelId: context.channelId,
				userId: context.userId,
				connectionId: context.connectionId,
			});
			Logger.debug(
				{
					type: context.type,
					guildId: guildId?.toString(),
					userId: context.userId.toString(),
					channelId: context.channelId.toString(),
					connectionId: context.connectionId,
					result,
				},
				'LiveKit participant_left voice disconnect result',
			);
		} catch (error) {
			Logger.error({error, type: context.type}, 'Error processing participant_left');
		}
	}

	private async handleTrackPublished(event: WebhookEvent, apiKey: string): Promise<void> {
		if (event.event !== 'track_published') {
			return;
		}
		const {participant, track} = event;
		if (!participant?.metadata || track?.source !== TrackSource.MICROPHONE || !track.sid) {
			return;
		}
		if (participant.attributes[SERVER_MUTE_ATTRIBUTE] !== 'true') {
			return;
		}
		const parsed = parseParticipantMetadataWithRaw(participant.metadata);
		if (!parsed) {
			Logger.warn({metadata: participant.metadata}, 'Failed to parse participant metadata');
			return;
		}
		const {context, raw} = parsed;
		const source = this.resolveSource(apiKey, raw);
		const guildId = context.type === 'guild' ? context.guildId : undefined;
		if (!source || !(await this.isFromPinnedServer(guildId, context.channelId, source))) {
			return;
		}
		Logger.debug(
			{participantIdentity: participant.identity, trackSid: track.sid},
			'Muting microphone published while server muted',
		);
		await this.liveKitService.muteMicrophoneTrack({
			guildId,
			channelId: context.channelId,
			userId: context.userId,
			connectionId: context.connectionId,
			regionId: source.regionId,
			serverId: source.serverId,
			trackSid: track.sid,
		});
	}

	async processEvent(data: {event: WebhookEvent; apiKey: string}): Promise<void> {
		const {event, apiKey} = data;
		Logger.debug({event: event.event, apiKey}, 'Dispatching LiveKit webhook event');
		if (event.room?.name.startsWith(REXCTL_TEST_ROOM_PREFIX)) {
			return;
		}
		switch (event.event) {
			case 'participant_joined':
				await this.handleParticipantJoined(event, apiKey);
				break;
			case 'participant_left':
			case 'participant_connection_aborted':
				await this.handleParticipantLeft(event, apiKey);
				break;
			case 'room_finished':
				await this.handleRoomFinished(event, apiKey);
				break;
			case 'track_published':
				await this.handleTrackPublished(event, apiKey);
				break;
			default:
				Logger.debug({event: event.event}, 'Ignoring LiveKit webhook event');
		}
		Logger.debug({event: event.event, apiKey}, 'Finished LiveKit webhook event');
	}
}