Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

21.8 KB
Raw Blame
//! LiveKit adapter for the [`CallRtcClient`] port.
//!
//! Wraps the `livekit-api` crate to provide room management, token generation,
//! egress recording, and webhook validation.

#[cfg(test)]
mod test;

use bot_id::{BotId, BotIdStr};
use chrono::DateTime;
use futures::future;
use livekit_api::access_token::{AccessToken, TokenVerifier, VideoGrants};
use livekit_api::services::agent_dispatch::AgentDispatchClient;
use livekit_api::services::egress::{EgressClient, EgressOutput, RoomCompositeOptions, encoding};
use livekit_api::services::room::{CreateRoomOptions, RoomClient};
use livekit_api::services::{ServiceError, TwirpError, TwirpErrorCode};
use livekit_api::webhooks::WebhookReceiver;
use livekit_protocol::{
    AudioCodec, CreateAgentDispatchRequest, EncodedFileOutput, EncodedFileType, S3Upload,
    TrackSource, VideoCodec, encoded_file_output, participant_info,
};
use macro_user_id::cowlike::CowLike;
use macro_user_id::user_id::MacroUserIdStr;
use notification::domain::models::apple::VoipPushPayload;

use crate::domain::meetings::GuestId;
use crate::domain::models::{
    CallError, CallWebhookEvent, EgressS3Config, LiveCallParticipant, LiveCallTrack,
    LiveParticipantKind, LiveTrackSource, RtcRoom, VerifiedRingToken, VoipPushPayloadRequest,
};
use crate::domain::ports::CallRtcClient;

const VOIP_TOKEN_MINT_CONCURRENCY: usize = 16;

/// LiveKit implementation of [`CallRtcClient`].
pub struct LivekitRtcClient {
    room_client: RoomClient,
    egress_client: EgressClient,
    agent_dispatch_client: AgentDispatchClient,
    webhook_receiver: WebhookReceiver,
    token_verifier: TokenVerifier,
    api_key: String,
    api_secret: String,
    /// If set, the named agent is dispatched to each new room for transcription.
    transcription_agent_name: Option<String>,
}

impl LivekitRtcClient {
    /// Create a new LiveKit RTC client.
    ///
    /// # Arguments
    /// * `server_url` - LiveKit server URL (e.g. `https://my-livekit.example.com`)
    /// * `api_key` - LiveKit API key
    /// * `api_secret` - LiveKit API secret
    /// * `transcription_agent_name` - If set, this agent is dispatched to new rooms for STT
    pub fn new(
        server_url: &str,
        api_key: impl Into<String>,
        api_secret: impl Into<String>,
        transcription_agent_name: Option<String>,
    ) -> Self {
        let api_key = api_key.into();
        let api_secret = api_secret.into();
        // Twirp RPC requires HTTP(S), not WebSocket. Convert wss:// → https://
        // and ws:// → http:// so the same env var works for both client SDK and
        // server-side API calls.
        let http_url = server_url
            .replace("wss://", "https://")
            .replace("ws://", "http://");
        let room_client = RoomClient::with_api_key(&http_url, &api_key, &api_secret);
        let egress_client = EgressClient::with_api_key(&http_url, &api_key, &api_secret);
        let agent_dispatch_client =
            AgentDispatchClient::with_api_key(&http_url, &api_key, &api_secret);
        let token_verifier = TokenVerifier::with_api_key(&api_key, &api_secret);
        let webhook_receiver = WebhookReceiver::new(token_verifier.clone());
        Self {
            room_client,
            egress_client,
            agent_dispatch_client,
            webhook_receiver,
            token_verifier,
            api_key,
            api_secret,
            transcription_agent_name,
        }
    }
}

struct RoomCompositeEgressRequest {
    room_name: String,
    outputs: Vec<EgressOutput>,
    options: RoomCompositeOptions,
}

fn build_room_composite_egress_request(
    room_name: &str,
    s3_config: &EgressS3Config,
) -> RoomCompositeEgressRequest {
    let output = EgressOutput::File(EncodedFileOutput {
        file_type: EncodedFileType::Mp4 as i32,
        filepath: format!("calls/{room_name}/{{time}}"),
        output: Some(encoded_file_output::Output::S3(S3Upload {
            bucket: s3_config.bucket.clone(),
            region: s3_config.region.clone(),
            access_key: s3_config.access_key.clone(),
            secret: s3_config.secret.clone(),
            ..Default::default()
        })),
        ..Default::default()
    });

    let options = RoomCompositeOptions {
        layout: "speaker".to_owned(),
        encoding: encoding::EncodingOptions {
            audio_codec: AudioCodec::Aac,
            video_codec: VideoCodec::H264Main,
            ..Default::default()
        },
        ..Default::default()
    };

    RoomCompositeEgressRequest {
        room_name: room_name.to_owned(),
        outputs: vec![output],
        options,
    }
}

impl CallRtcClient for LivekitRtcClient {
    #[tracing::instrument(err, skip(self))]
    async fn prepare_room(&self, room_name: &str) -> anyhow::Result<()> {
        self.room_client
            .create_room(
                room_name,
                CreateRoomOptions {
                    empty_timeout: 300,
                    ..Default::default()
                },
            )
            .await?;
        Ok(())
    }
    #[tracing::instrument(err, skip(self))]
    async fn create_room(&self, room_name: &str) -> anyhow::Result<()> {
        self.room_client
            .create_room(
                room_name,
                CreateRoomOptions {
                    empty_timeout: 60,
                    ..Default::default()
                },
            )
            .await?;
        Ok(())
    }

    #[tracing::instrument(err, skip(self))]
    async fn delete_room(&self, room_name: &str) -> anyhow::Result<()> {
        ignore_not_found(self.room_client.delete_room(room_name).await)
    }

    #[tracing::instrument(err, skip(self))]
    async fn list_rooms(&self) -> anyhow::Result<Vec<RtcRoom>> {
        let rooms = self.room_client.list_rooms(Vec::new()).await?;
        Ok(rooms
            .into_iter()
            .filter_map(|room| {
                let Some(created_at) = DateTime::from_timestamp(room.creation_time, 0) else {
                    tracing::warn!(
                        room_name = room.name,
                        creation_time = room.creation_time,
                        "skipping RTC room with an unrepresentable creation time"
                    );
                    return None;
                };
                Some(RtcRoom {
                    name: room.name,
                    created_at,
                })
            })
            .collect())
    }

    #[tracing::instrument(err, skip(self))]
    async fn generate_token(
        &self,
        room_name: &str,
        participant_identity: MacroUserIdStr<'_>,
    ) -> anyhow::Result<String> {
        // Pinned so VoIP-delivered tokens survive push delay and lock-screen ringing.
        // TODO(call-phase-2): add token refresh before supporting calls over 6h.
        let token = AccessToken::with_api_key(&self.api_key, &self.api_secret)
            .with_identity(participant_identity.as_ref())
            .with_ttl(std::time::Duration::from_secs(6 * 3600))
            .with_grants(VideoGrants {
                room_join: true,
                room: room_name.to_string(),
                can_publish: true,
                can_subscribe: true,
                can_publish_data: true,
                ..Default::default()
            })
            .to_jwt()?;
        Ok(token)
    }

    #[tracing::instrument(err, skip(self))]
    async fn generate_program_token(
        &self,
        room_name: &str,
        participant_identity: MacroUserIdStr<'_>,
        program: &str,
        name: Option<String>,
    ) -> anyhow::Result<String> {
        let mut token = AccessToken::with_api_key(&self.api_key, &self.api_secret)
            .with_identity(participant_identity.as_ref())
            .with_attributes([("macro.program", program)])
            .with_ttl(std::time::Duration::from_secs(6 * 3600))
            .with_grants(VideoGrants {
                room_join: true,
                room: room_name.to_string(),
                can_publish: true,
                can_subscribe: true,
                can_publish_data: true,
                ..Default::default()
            });
        if let Some(name) = name {
            token = token.with_name(&name);
        }
        token.to_jwt().map_err(Into::into)
    }

    async fn generate_bot_token(
        &self,
        room_name: &str,
        bot_id: BotId,
        name: Option<String>,
    ) -> anyhow::Result<String> {
        let identity = bot_id.into_storage_id();
        let mut token = AccessToken::with_api_key(&self.api_key, &self.api_secret)
            .with_identity(identity.as_ref())
            .with_attributes([("macro.program", "bot")])
            .with_ttl(std::time::Duration::from_secs(6 * 3600))
            .with_grants(VideoGrants {
                room_join: true,
                room: room_name.to_string(),
                can_publish: true,
                can_subscribe: true,
                can_publish_data: true,
                ..Default::default()
            });
        if let Some(name) = name {
            token = token.with_name(&name);
        }
        token.to_jwt().map_err(Into::into)
    }

    #[tracing::instrument(err, skip(self))]
    async fn generate_named_token(
        &self,
        room_name: &str,
        participant_identity: MacroUserIdStr<'_>,
        name: &str,
    ) -> anyhow::Result<String> {
        AccessToken::with_api_key(&self.api_key, &self.api_secret)
            .with_identity(participant_identity.as_ref())
            .with_name(name)
            .with_ttl(std::time::Duration::from_secs(6 * 3600))
            .with_grants(VideoGrants {
                room_join: true,
                room: room_name.to_string(),
                can_publish: true,
                can_subscribe: true,
                can_publish_data: true,
                ..Default::default()
            })
            .to_jwt()
            .map_err(Into::into)
    }

    #[tracing::instrument(err, skip(self))]
    async fn generate_guest_token(
        &self,
        room_name: &str,
        guest_id: GuestId,
        display_name: &str,
    ) -> anyhow::Result<String> {
        Ok(AccessToken::with_api_key(&self.api_key, &self.api_secret)
            .with_identity(&guest_id.to_string())
            .with_name(display_name)
            .with_ttl(std::time::Duration::from_secs(6 * 3600))
            .with_grants(VideoGrants {
                room_join: true,
                room: room_name.to_string(),
                can_publish: true,
                can_subscribe: true,
                can_publish_data: true,
                ..Default::default()
            })
            .to_jwt()?)
    }

    #[tracing::instrument(err, skip(self))]
    async fn remove_guest(&self, room_name: &str, guest_id: GuestId) -> anyhow::Result<()> {
        ignore_not_found(
            self.room_client
                .remove_participant(room_name, &guest_id.to_string())
                .await,
        )
    }

    async fn remove_bot(&self, room_name: &str, bot_id: BotId) -> anyhow::Result<()> {
        ignore_not_found(
            self.room_client
                .remove_participant(room_name, bot_id.into_storage_id().as_ref())
                .await,
        )
    }

    #[tracing::instrument(
        skip(self, request),
        fields(
            recipient_count = request.recipients.len(),
            room_name = request.room_name,
            call_id = %request.call_id,
            channel_id = request.channel_id,
        )
    )]
    async fn build_voip_push_payloads<'a>(
        &self,
        request: VoipPushPayloadRequest<'a>,
    ) -> Vec<(MacroUserIdStr<'static>, VoipPushPayload)> {
        let room_name = request.room_name;
        let call_id = request.call_id;
        let channel_id = request.channel_id;
        let channel_name = request.channel_name;
        let caller_name = request.caller_name;
        let livekit_server_url = request.livekit_server_url;
        let ring_status_url = request.ring_status_url;

        let mut payloads = Vec::new();
        for batch in request.recipients.chunks(VOIP_TOKEN_MINT_CONCURRENCY) {
            let results = future::join_all(batch.iter().map(|recipient_id| {
                let recipient_id = recipient_id.clone();
                async move {
                    match self.generate_token(room_name, recipient_id.clone()).await {
                        Ok(livekit_token) => Some((
                            recipient_id,
                            VoipPushPayload {
                                aps: Default::default(),
                                call_id: call_id.to_string(),
                                channel_id: channel_id.to_string(),
                                channel_name: channel_name.to_string(),
                                caller_name: caller_name.to_string(),
                                livekit_server_url: Some(livekit_server_url.to_string()),
                                livekit_token: Some(livekit_token),
                                ring_status_url: ring_status_url.map(str::to_string),
                            },
                        )),
                        Err(e) => {
                            tracing::error!(
                                error=?e,
                                "failed to mint LiveKit token for VoIP push"
                            );
                            None
                        }
                    }
                }
            }))
            .await;
            payloads.extend(results.into_iter().flatten());
        }

        payloads
    }

    #[tracing::instrument(err, skip(self))]
    async fn remove_participant(
        &self,
        room_name: &str,
        participant_identity: MacroUserIdStr<'_>,
    ) -> anyhow::Result<()> {
        ignore_not_found(
            self.room_client
                .remove_participant(room_name, participant_identity.as_ref())
                .await,
        )
    }

    #[tracing::instrument(err, skip(self))]
    async fn list_meeting_participants(
        &self,
        room_name: &str,
    ) -> anyhow::Result<Option<Vec<crate::domain::meetings::MeetingRtcParticipant>>> {
        match self.room_client.list_participants(room_name).await {
            Ok(participants) => Ok(Some(
                participants
                    .into_iter()
                    .map(
                        |participant| crate::domain::meetings::MeetingRtcParticipant {
                            identity: participant.identity,
                            name: participant.name,
                        },
                    )
                    .collect(),
            )),
            Err(error) if is_not_found(&error) => Ok(None),
            Err(error) => Err(error.into()),
        }
    }

    #[tracing::instrument(err, skip(self))]
    async fn list_live_participants(
        &self,
        room_name: &str,
    ) -> anyhow::Result<Option<Vec<LiveCallParticipant>>> {
        let participants = match self.room_client.list_participants(room_name).await {
            Ok(participants) => participants,
            Err(error) if is_not_found(&error) => return Ok(None),
            Err(error) => return Err(error.into()),
        };
        Ok(Some(
            participants
                .into_iter()
                .filter(|participant| participant.kind != participant_info::Kind::Agent as i32)
                .map(|participant| {
                    let user_id = MacroUserIdStr::parse_from_str(&participant.identity)
                        .ok()
                        .map(|_| participant.identity.clone());
                    let kind = if user_id.is_some() {
                        LiveParticipantKind::User
                    } else if GuestId::parse_rtc_identity(&participant.identity).is_some() {
                        LiveParticipantKind::Guest
                    } else if BotIdStr::parse_from_str(&participant.identity).is_ok() {
                        LiveParticipantKind::Bot
                    } else {
                        LiveParticipantKind::Guest
                    };
                    let tracks = participant
                        .tracks
                        .into_iter()
                        .map(|track| LiveCallTrack {
                            source: match TrackSource::try_from(track.source)
                                .unwrap_or(TrackSource::Unknown)
                            {
                                TrackSource::Microphone => LiveTrackSource::Microphone,
                                TrackSource::Camera => LiveTrackSource::Camera,
                                TrackSource::ScreenShare => LiveTrackSource::ScreenShare,
                                TrackSource::ScreenShareAudio => LiveTrackSource::ScreenShareAudio,
                                TrackSource::Unknown => LiveTrackSource::Unknown,
                            },
                            muted: track.muted,
                        })
                        .collect();
                    LiveCallParticipant {
                        identity: participant.identity,
                        display_name: participant.name,
                        kind,
                        user_id,
                        is_program: participant.attributes.contains_key("macro.program"),
                        joined_at: DateTime::from_timestamp(participant.joined_at, 0),
                        tracks,
                    }
                })
                .collect(),
        ))
    }

    #[tracing::instrument(err, skip(self))]
    async fn list_participant_identities(
        &self,
        room_name: &str,
    ) -> anyhow::Result<Option<Vec<String>>> {
        Ok(self
            .list_meeting_participants(room_name)
            .await?
            .map(|participants| {
                participants
                    .into_iter()
                    .map(|participant| participant.identity)
                    .collect()
            }))
    }

    #[tracing::instrument(err, skip(self, s3_config))]
    async fn start_room_composite_egress(
        &self,
        room_name: &str,
        s3_config: &EgressS3Config,
    ) -> anyhow::Result<String> {
        let request = build_room_composite_egress_request(room_name, s3_config);

        let info = self
            .egress_client
            .start_room_composite_egress(&request.room_name, request.outputs, request.options)
            .await?;

        Ok(info.egress_id)
    }

    #[tracing::instrument(err, skip(self))]
    async fn stop_egress(&self, egress_id: &str) -> anyhow::Result<()> {
        self.egress_client.stop_egress(egress_id).await?;
        Ok(())
    }

    #[tracing::instrument(err, skip(self))]
    async fn dispatch_transcription_agent(&self, room_name: &str) -> anyhow::Result<()> {
        let Some(agent_name) = &self.transcription_agent_name else {
            return Ok(());
        };

        self.agent_dispatch_client
            .create_dispatch(CreateAgentDispatchRequest {
                agent_name: agent_name.clone(),
                room: room_name.to_owned(),
                ..Default::default()
            })
            .await?;

        tracing::info!(room_name, agent_name, "dispatched transcription agent");
        Ok(())
    }

    fn verify_access_token(&self, token: &str) -> anyhow::Result<VerifiedRingToken> {
        let claims = self
            .token_verifier
            .verify(token)
            .map_err(|e| anyhow::anyhow!("access token verification failed: {e}"))?;

        Ok(VerifiedRingToken {
            identity: claims.sub,
            room: Some(claims.video.room).filter(|r| !r.is_empty()),
        })
    }

    fn receive_webhook(&self, body: &str, auth_token: &str) -> Result<CallWebhookEvent, CallError> {
        let event = self
            .webhook_receiver
            .receive(body, auth_token)
            .map_err(|e| {
                tracing::warn!(error=?e, "webhook signature validation failed");
                CallError::Auth
            })?;

        // Extract file URL from egress info if available.
        let (egress_id, file_url) = match &event.egress_info {
            Some(info) => {
                let url = info.file_results.first().map(|f| f.location.clone());
                let id = if info.egress_id.is_empty() {
                    None
                } else {
                    Some(info.egress_id.clone())
                };
                (id, url)
            }
            None => (None, None),
        };

        // Keep UUID guests separate from Macro users and agent identities.
        let guest_identity = event
            .participant
            .as_ref()
            .filter(|p| MacroUserIdStr::parse_from_str(&p.identity).is_err())
            .and_then(|p| GuestId::parse_rtc_identity(&p.identity));
        let bot_identity = event
            .participant
            .as_ref()
            .and_then(|p| BotIdStr::parse_from_str(&p.identity).ok())
            .map(|id| id.bot_id());

        Ok(CallWebhookEvent {
            guest_identity,
            event: event.event,
            id: event.id,
            room_name: event.room.map(|r| r.name),
            participant_identity: event.participant.and_then(|p| {
                match MacroUserIdStr::parse_from_str(&p.identity) {
                    Ok(id) => Some(id.into_owned()),
                    Err(_) => {
                        tracing::debug!(
                            identity = %p.identity,
                            "skipping non-user LiveKit participant identity"
                        );
                        None
                    }
                }
            }),
            bot_identity,
            egress_id,
            file_url,
            created_at: event.created_at,
        })
    }
}

/// Treat a room or participant that is already gone as removed.
fn ignore_not_found(result: Result<(), ServiceError>) -> anyhow::Result<()> {
    match result {
        Ok(()) => Ok(()),
        Err(error) if is_not_found(&error) => Ok(()),
        Err(error) => Err(error.into()),
    }
}

fn is_not_found(error: &ServiceError) -> bool {
    matches!(
        error,
        ServiceError::Twirp(TwirpError::Twirp(code)) if code.code == TwirpErrorCode::NOT_FOUND
    )
}