Skip to main content

active_call/call/
active_call.rs

1use super::Command;
2use crate::{
3    CallOption, ReferOption,
4    call::state::{ActorMsg, CallProgress, CallRuntime, Extras, LegShared, build_callrecord},
5    event::{EventReceiver, EventSender, SessionEvent},
6    media::{
7        TrackId,
8        engine::StreamEngine,
9        recorder::RecorderOption,
10        stream::{MediaStream, MediaStreamBuilder, SERVER_SIDE_TRACK_ID},
11        track::{
12            Track, TrackConfig, forwarding::ForwardingTrack, media_pass::MediaPassTrack,
13            tts::SynthesisHandle, websocket::WebsocketBytesReceiver,
14        },
15    },
16    synthesis::SynthesisCommand,
17    transcription::TranscriptionOption,
18};
19use crate::{
20    app::AppState,
21    call::{CommandReceiver, CommandSender, sip::Invitation},
22    callrecord::{CallRecord, CallRecordEvent, CallRecordEventType, CallRecordHangupReason},
23};
24use anyhow::Result;
25use arc_swap::{ArcSwap, ArcSwapOption};
26use chrono::{DateTime, Utc};
27use rsipstack::dialog::invite_dialog::InviteDialog;
28use serde::{Deserialize, Serialize};
29use std::{
30    collections::HashMap,
31    path::Path,
32    sync::{
33        Arc,
34        atomic::{AtomicBool, Ordering},
35    },
36    time::Duration,
37};
38use tokio::{fs::File, select, sync::mpsc};
39use tokio_util::sync::CancellationToken;
40use tracing::{debug, info, warn};
41
42/// Describes the state of the caller track when an incoming SIP call is waiting to be answered.
43pub enum PendingCallerTrack {
44    /// The track has been started in the media stream during ringing (early media).
45    /// Processors must be built from the accept option and appended to it.
46    StartedForEarlyMedia,
47    /// The track has not been added to the media stream yet.
48    /// setup_track_with_stream will start it and build processors from the accept option.
49    NotStarted(Box<dyn Track>),
50}
51
52#[cfg(test)]
53mod tests {
54    use super::*;
55    use crate::app::AppStateBuilder;
56    use crate::config::Config;
57    use crate::media::track::tts::SynthesisHandle;
58    use crate::synthesis::SynthesisCommand;
59    use tokio::sync::mpsc;
60
61    async fn make_active_call_with_option(option: CallOption) -> Arc<ActiveCall> {
62        let mut config = Config::default();
63        config.udp_port = 0; // Use random port
64        config.media_cache_path = "/tmp/mediacache".to_string();
65        let app_state = AppStateBuilder::new()
66            .with_config(config)
67            .with_stream_engine(Arc::new(StreamEngine::default()))
68            .build()
69            .await
70            .unwrap();
71        let active_call = Arc::new(ActiveCall::new(CallSpec {
72            call_type: ActiveCallType::Sip,
73            cancel_token: CancellationToken::new(),
74            session_id: "test-session".to_string(),
75            invitation: app_state.invitation.clone(),
76            app_state: app_state.clone(),
77            track_config: TrackConfig::default(),
78            audio_receiver: None,
79            dump_events: false,
80            server_side_track_id: None,
81            extras: None,
82        }));
83        active_call.set_option(option);
84        active_call
85    }
86
87    #[tokio::test]
88    async fn test_tts_ssrc_reuse_for_autohangup() -> Result<()> {
89        let mut option = crate::CallOption::default();
90        option.tts = Some(crate::synthesis::SynthesisOption::default());
91        let active_call = make_active_call_with_option(option).await;
92
93        let (tx, mut rx) = mpsc::unbounded_channel::<SynthesisCommand>();
94        let initial_ssrc = 12345;
95        let handle = SynthesisHandle::new(tx, Some("play_1".to_string()), initial_ssrc);
96
97        // 1. Set initial TTS handle
98        active_call.tts_handle.store(Some(Arc::new(handle)));
99        active_call.set_current_play(Some("play_1".to_string()));
100
101        // 2. Call do_tts with auto_hangup=true and same play_id
102        active_call
103            .do_tts(Command::Tts {
104                text: "hangup now".to_string(),
105                speaker: None,
106                play_id: Some("play_1".to_string()),
107                auto_hangup: Some(true),
108                streaming: Some(false),
109                end_of_stream: Some(true),
110                option: None,
111                wait_input_timeout: None,
112                base64: Some(false),
113                cache_key: None,
114            })
115            .await?;
116
117        // 3. Verify the hangup intent rides on the command sent to the existing track
118        let cmd = rx.try_recv().expect("Should have received tts command");
119        assert_eq!(cmd.text, "hangup now");
120        assert_eq!(cmd.auto_hangup, Some(true));
121
122        Ok(())
123    }
124
125    #[tokio::test]
126    async fn test_tts_new_ssrc_for_different_play_id() -> Result<()> {
127        let mut tts_opt = crate::synthesis::SynthesisOption::default();
128        tts_opt.provider = Some(crate::synthesis::SynthesisType::Aliyun);
129        let mut option = crate::CallOption::default();
130        option.tts = Some(tts_opt);
131        let active_call = make_active_call_with_option(option).await;
132
133        let (tx, _rx) = mpsc::unbounded_channel();
134        let initial_ssrc = 111;
135        let handle = SynthesisHandle::new(tx, Some("play_1".to_string()), initial_ssrc);
136
137        active_call.tts_handle.store(Some(Arc::new(handle)));
138        active_call.set_current_play(Some("play_1".to_string()));
139
140        // Call do_tts with DIFFERENT play_id
141        active_call
142            .do_tts(Command::Tts {
143                text: "new play".to_string(),
144                speaker: None,
145                play_id: Some("play_2".to_string()),
146                auto_hangup: Some(true),
147                streaming: Some(false),
148                end_of_stream: Some(true),
149                option: None,
150                wait_input_timeout: None,
151                base64: Some(false),
152                cache_key: None,
153            })
154            .await?;
155
156        // Verify a NEW track was started (new handle with a different ssrc,
157        // because a different play_id interrupts and starts fresh)
158        {
159            let handle = active_call.tts_handle.load_full();
160            assert!(handle.is_some(), "new tts handle should be stored");
161            let handle = handle.unwrap();
162            assert_ne!(
163                handle.ssrc, initial_ssrc,
164                "Should use a new SSRC for different play_id"
165            );
166        }
167
168        Ok(())
169    }
170
171    // refer=Some(true): only the refer call is cancelled, media stream stays alive.
172    #[tokio::test]
173    async fn test_hangup_refer_true_cancels_refer_only() -> Result<()> {
174        let active_call = make_active_call_with_option(crate::CallOption::default()).await;
175
176        let refer_token = active_call.cancel_token.child_token();
177        let refer_leg = LegShared::new(1, true, CallProgress::default());
178        active_call.set_refer_call_token(refer_token.clone());
179        active_call.set_refer_leg(Some(refer_leg.clone()));
180
181        active_call.do_hangup(None, None, None, Some(true)).await?;
182
183        assert!(
184            refer_token.is_cancelled(),
185            "refer token should be cancelled"
186        );
187        assert!(
188            !active_call.media_stream.cancel_token.is_cancelled(),
189            "media stream should NOT stop"
190        );
191        assert!(
192            refer_leg.progress.load_full().hangup_reason.is_some(),
193            "hangup_reason should be set on refer leg"
194        );
195        Ok(())
196    }
197
198    // refer=None: media stream stops and the refer token is also cancelled.
199    #[tokio::test]
200    async fn test_hangup_none_cancels_refer_too() -> Result<()> {
201        let active_call = make_active_call_with_option(crate::CallOption::default()).await;
202
203        let refer_token = active_call.cancel_token.child_token();
204        active_call.set_refer_call_token(refer_token.clone());
205
206        active_call.do_hangup(None, None, None, None).await?;
207
208        assert!(
209            refer_token.is_cancelled(),
210            "refer token should be cancelled"
211        );
212        assert!(
213            active_call.media_stream.cancel_token.is_cancelled(),
214            "media stream should stop"
215        );
216        Ok(())
217    }
218
219    // ---------------------------------------------------------------------------
220    // Regression: ringing-before-accept leaves caller track without processors
221    // ---------------------------------------------------------------------------
222    //
223    // When Ringing is issued before Accept on an incoming SIP call,
224    // prepare_incoming_sip_track starts the caller track in the media stream
225    // (needed for early-media ringtone) with the empty ringing option — no
226    // VAD/ASR/AGC processors.  It stores PendingCallerTrack::StartedForEarlyMedia
227    // in ready_to_answer.  At accept time, finish_caller_stack matches that variant
228    // and calls create_processors + append_processor with the real accept option.
229    //
230    // This test verifies that setup_track_with_stream (same processor-creation path)
231    // fires the ASR builder when given the accept option, proving the fix is sound.
232
233    struct MockCallerTrack {
234        id: TrackId,
235        config: crate::media::track::TrackConfig,
236        processor_chain: crate::media::processor::ProcessorChain,
237    }
238
239    impl MockCallerTrack {
240        fn new(id: TrackId) -> Self {
241            Self {
242                id,
243                config: crate::media::track::TrackConfig::default(),
244                processor_chain: crate::media::processor::ProcessorChain::new(16000),
245            }
246        }
247    }
248
249    #[async_trait::async_trait]
250    impl crate::media::track::Track for MockCallerTrack {
251        fn ssrc(&self) -> u32 {
252            0
253        }
254        fn id(&self) -> &TrackId {
255            &self.id
256        }
257        fn config(&self) -> &crate::media::track::TrackConfig {
258            &self.config
259        }
260        fn processor_chain(&mut self) -> &mut crate::media::processor::ProcessorChain {
261            &mut self.processor_chain
262        }
263        async fn handshake(
264            &mut self,
265            _o: String,
266            _t: Option<tokio::time::Duration>,
267        ) -> Result<String> {
268            Ok(String::new())
269        }
270        async fn update_remote_description(&mut self, _a: &String) -> Result<()> {
271            Ok(())
272        }
273        async fn start(
274            &mut self,
275            _e: crate::event::EventSender,
276            _p: crate::media::track::TrackPacketSender,
277        ) -> Result<()> {
278            Ok(())
279        }
280        async fn stop(&self) -> Result<()> {
281            Ok(())
282        }
283        async fn send_packet(&mut self, _f: &crate::media::AudioFrame) -> Result<()> {
284            Ok(())
285        }
286    }
287
288    struct MockAsrClient;
289
290    #[async_trait::async_trait]
291    impl crate::transcription::TranscriptionClient for MockAsrClient {
292        fn send_audio(
293            &self,
294            _s: &[crate::media::Sample],
295            _src: Option<&crate::media::SourcePacket>,
296        ) -> Result<()> {
297            Ok(())
298        }
299    }
300
301    async fn make_active_call_with_engine_and_option(
302        engine: Arc<StreamEngine>,
303        cache_dir: &str,
304        option: crate::CallOption,
305    ) -> Arc<ActiveCall> {
306        let mut config = Config::default();
307        config.udp_port = 0;
308        config.media_cache_path = cache_dir.to_string();
309        let app_state = AppStateBuilder::new()
310            .with_config(config)
311            .with_stream_engine(engine)
312            .build()
313            .await
314            .unwrap();
315        let session_id = format!("test-{}-{}", cache_dir, uuid::Uuid::new_v4());
316        let active_call = Arc::new(ActiveCall::new(CallSpec {
317            call_type: ActiveCallType::Sip,
318            cancel_token: CancellationToken::new(),
319            session_id: session_id.clone(),
320            invitation: app_state.invitation.clone(),
321            app_state: app_state.clone(),
322            track_config: TrackConfig::default(),
323            audio_receiver: None,
324            dump_events: false,
325            server_side_track_id: None,
326            extras: None,
327        }));
328        active_call.set_option(option);
329        active_call
330    }
331
332    #[tokio::test]
333    async fn test_setup_track_with_stream_builds_processors_from_accept_option() -> Result<()> {
334        let (asr_created_tx, mut asr_created_rx) = mpsc::channel::<()>(1);
335
336        let mock_provider =
337            crate::transcription::TranscriptionType::Other("mock-ringing-asr".to_string());
338
339        let mut engine = StreamEngine::new();
340        engine.register_asr(
341            mock_provider.clone(),
342            Box::new(move |_tid, _tok, _opt, _es| {
343                let tx = asr_created_tx.clone();
344                Box::pin(async move {
345                    let _ = tx.send(()).await;
346                    Ok(Box::new(MockAsrClient)
347                        as Box<dyn crate::transcription::TranscriptionClient>)
348                })
349            }),
350        );
351        let engine = Arc::new(engine);
352
353        let accept_option = crate::CallOption {
354            asr: Some(crate::transcription::TranscriptionOption {
355                provider: Some(mock_provider),
356                ..Default::default()
357            }),
358            ..Default::default()
359        };
360        let active_call = make_active_call_with_engine_and_option(
361            engine,
362            "mediacache_ringing_accept_test",
363            accept_option,
364        )
365        .await;
366        let cancel_token = active_call.cancel_token.clone();
367
368        // Simulate the fixed prepare_incoming_sip_track: track is held in
369        // ready_to_answer, NOT yet added to the media stream.
370        let mock_track = Box::new(MockCallerTrack::new(active_call.session_id.clone()));
371
372        // Simulate finish_caller_stack at accept time: setup_track_with_stream
373        // is called with the full accept option (the code path under test).
374        let accept_option = active_call.progress.load_full().option.clone().unwrap();
375        active_call
376            .setup_track_with_stream(&accept_option, mock_track)
377            .await?;
378
379        // The mock ASR builder must have fired, proving processors were built
380        // from the accept option and attached to the caller track.
381        let received =
382            tokio::time::timeout(std::time::Duration::from_secs(3), asr_created_rx.recv()).await;
383        assert!(
384            received.is_ok() && received.unwrap().is_some(),
385            "ASR processor was NOT created — setup_track_with_stream did not build \
386             processors from the accept option (regression: ringing-before-accept)"
387        );
388
389        cancel_token.cancel();
390        Ok(())
391    }
392
393    // ---------------------------------------------------------------------------
394    // Regression: double-ASR when Accept arrives without a prior Ringing
395    // ---------------------------------------------------------------------------
396    //
397    // prepare_incoming_sip_track starts the caller track during ringing. It must
398    // NOT build VAD/ASR/AGC processors at that point: the stored option already
399    // carries `asr` in the accept-first path, so finish_caller_stack would build a
400    // second set at accept time, producing two ASR clients (two WebSocket
401    // connections) on the same track.
402    //
403    // This test verifies that update_track_wrapper (the prepare-time path) never
404    // fires the ASR builder even when the option carries an asr config.
405
406    #[tokio::test]
407    async fn test_update_track_wrapper_does_not_build_asr_processor() -> Result<()> {
408        let (asr_created_tx, mut asr_created_rx) = mpsc::channel::<()>(1);
409
410        let mock_provider =
411            crate::transcription::TranscriptionType::Other("mock-ringing-asr".to_string());
412
413        let mut engine = StreamEngine::new();
414        engine.register_asr(
415            mock_provider.clone(),
416            Box::new(move |_tid, _tok, _opt, _es| {
417                let tx = asr_created_tx.clone();
418                Box::pin(async move {
419                    let _ = tx.send(()).await;
420                    Ok(Box::new(MockAsrClient)
421                        as Box<dyn crate::transcription::TranscriptionClient>)
422                })
423            }),
424        );
425        let engine = Arc::new(engine);
426
427        // Simulate the accept-first path: setup_caller_track has already stored the
428        // full accept option (with asr) before the track is prepared.
429        let accept_option = crate::CallOption {
430            asr: Some(crate::transcription::TranscriptionOption {
431                provider: Some(mock_provider),
432                ..Default::default()
433            }),
434            ..Default::default()
435        };
436        let active_call = make_active_call_with_engine_and_option(
437            engine,
438            "mediacache_update_track_wrapper_test",
439            accept_option,
440        )
441        .await;
442        let cancel_token = active_call.cancel_token.clone();
443
444        let mock_track = Box::new(MockCallerTrack::new(active_call.session_id.clone()));
445        active_call.update_track_wrapper(mock_track, None).await;
446
447        // update_track_wrapper must NOT fire the ASR builder; the processors are
448        // deferred to finish_caller_stack(StartedForEarlyMedia) at accept time.
449        let received =
450            tokio::time::timeout(std::time::Duration::from_millis(500), asr_created_rx.recv())
451                .await;
452        assert!(
453            received.is_err(),
454            "ASR builder fired during track preparation — double-ASR regression"
455        );
456
457        cancel_token.cancel();
458        Ok(())
459    }
460}
461
462#[derive(Deserialize)]
463#[serde(rename_all = "camelCase")]
464pub struct CallParams {
465    pub id: Option<String>,
466    #[serde(rename = "dump")]
467    pub dump_events: Option<bool>,
468    #[serde(rename = "ping")]
469    pub ping_interval: Option<u32>,
470    pub server_side_track: Option<String>,
471    /// Set when this connection is a one-hop find from another node.
472    /// Only an empty `forward` may be forwarded. A present value is answered
473    /// locally only and must never hop again. `forward=true` must 404 if the
474    /// session is absent (do not create a new call).
475    #[serde(default)]
476    pub forward: Option<bool>,
477    /// Ignored. Kept so older nodes that still send `visited=` can deserialize.
478    #[serde(default)]
479    pub visited: Option<String>,
480}
481
482impl CallParams {
483    /// Build the query string used when forwarding this request to a peer.
484    /// Sets `forward=true` so the peer will not hop (`forward` is no longer empty).
485    pub fn to_forward_query(&self) -> String {
486        let mut parts: Vec<String> = Vec::new();
487        if let Some(id) = &self.id {
488            parts.push(format!("id={}", urlencoding::encode(id)));
489        }
490        if let Some(dump) = self.dump_events {
491            parts.push(format!("dump={}", dump));
492        }
493        if let Some(ping) = self.ping_interval {
494            parts.push(format!("ping={}", ping));
495        }
496        if let Some(track) = &self.server_side_track {
497            parts.push(format!("server_side_track={}", urlencoding::encode(track)));
498        }
499        parts.push("forward=true".to_string());
500        parts.join("&")
501    }
502}
503
504#[derive(Debug, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
505#[serde(rename_all = "camelCase")]
506pub enum ActiveCallType {
507    Webrtc,
508    B2bua,
509    WebSocket,
510    #[default]
511    Sip,
512}
513
514pub type ActiveCallRef = Arc<ActiveCall>;
515
516/// A call: immutable identity + lock-free shared state (see `call::state`)
517/// plus the infrastructure handles. Actor-owned mutable state lives in
518/// [`CallRuntime`] inside `serve`.
519pub struct ActiveCall {
520    pub cancel_token: CancellationToken,
521    pub call_type: ActiveCallType,
522    pub session_id: String,
523    pub start_time: DateTime<Utc>,
524    pub media_stream: Arc<MediaStream>,
525    pub track_config: TrackConfig,
526    pub event_sender: EventSender,
527    pub app_state: AppState,
528    pub invitation: Invitation,
529    pub cmd_sender: CommandSender,
530    pub dump_events: bool,
531    pub server_side_track_id: TrackId,
532
533    /// Immutable main-leg SSRC.
534    pub ssrc: u32,
535    /// Bridge pause flag shared with the peer call during bridging.
536    pub bridge_paused: Arc<AtomicBool>,
537    /// Main-leg lifecycle progress (dialog id, ring/answer times, answer SDP, option...).
538    pub progress: Arc<ArcSwap<CallProgress>>,
539    /// Main-leg variables (playbook set_var, SIP headers, hangup headers).
540    pub extras: Extras,
541    /// Active music-on-hold path (shared with the spawned refer task).
542    pub moh: ArcSwapOption<String>,
543    /// play id of the current server-side playback (shared for TrackEnd matching).
544    pub current_play_id: ArcSwapOption<String>,
545    /// Live TTS handle (shared so spawned tasks and post-serve cleanup can drop it).
546    pub tts_handle: ArcSwapOption<SynthesisHandle>,
547    /// Shared state of the refer leg, when one is active.
548    pub refer_leg: ArcSwapOption<LegShared>,
549    /// Answer prepared during ringing (SDP + running track + dialog); taken
550    /// by accept/reject. Shared so post-serve `cleanup` can still reject.
551    pub ready_to_answer: ArcSwapOption<ReadyAnswer>,
552    /// Answer prepared for the underlying SIP dialog of non-SIP call types
553    /// (WebSocket/Webrtc); taken by accept, rejected on reject/cleanup.
554    /// Same slot family as `ready_to_answer`: lock-free set/take on the
555    /// actor path, with ownership recoverable from `cleanup`.
556    pub pending_sip_answer: ArcSwapOption<PendingSipAnswer>,
557    /// Cancel this token to hang up only the refer call, leaving the main call alive.
558    pub refer_call_token: ArcSwapOption<CancellationToken>,
559    /// Pending wait-input timeout set by the last Tts/Play command.
560    pub wait_input_timeout: ArcSwapOption<u32>,
561    /// ASR config to resume on the parent leg once the refer leg ends.
562    pub pending_asr_resume: ArcSwapOption<(u32, TranscriptionOption)>,
563    /// RFC 3515 notifier for a transfer triggered by an incoming REFER;
564    /// reports the refer leg's final status back to the referrer.
565    pub refer_notifier: ArcSwapOption<crate::call::sip::ReferProgressNotifier>,
566    /// WebSocket audio receiver injected at construction, taken once by setup.
567    pub audio_receiver: std::sync::Mutex<Option<WebsocketBytesReceiver>>,
568}
569
570impl ActiveCall {
571    /// Lock-free shared state of the main leg.
572    pub fn leg(&self) -> LegShared {
573        LegShared {
574            ssrc: self.ssrc,
575            is_refer: false,
576            progress: self.progress.clone(),
577            extras: self.extras.clone(),
578        }
579    }
580
581    /// Store/replace the main-leg option in the progress snapshot.
582    pub fn set_option(&self, option: CallOption) {
583        self.progress.rcu(|p| {
584            let mut p = CallProgress::clone(p);
585            p.option = Some(option.clone());
586            p
587        });
588    }
589
590    pub fn moh_path(&self) -> Option<String> {
591        self.moh.load_full().map(|s| s.to_string())
592    }
593
594    pub fn set_moh(&self, v: Option<String>) {
595        self.moh.store(v.map(Arc::new));
596    }
597
598    pub fn current_play(&self) -> Option<String> {
599        self.current_play_id.load_full().map(|s| s.to_string())
600    }
601
602    pub fn set_current_play(&self, v: Option<String>) {
603        self.current_play_id.store(v.map(Arc::new));
604    }
605
606    pub fn refer_leg_value(&self) -> Option<LegShared> {
607        self.refer_leg.load_full().map(|l| l.as_ref().clone())
608    }
609
610    pub fn set_refer_leg(&self, v: Option<LegShared>) {
611        self.refer_leg.store(v.map(Arc::new));
612    }
613
614    /// Prepared answer during ringing; taken once by accept/reject.
615    pub fn set_ready_to_answer(&self, ready: ReadyAnswer) {
616        self.ready_to_answer.store(Some(Arc::new(ready)));
617    }
618
619    pub fn take_ready_to_answer(&self) -> Option<Arc<ReadyAnswer>> {
620        self.ready_to_answer.swap(None)
621    }
622
623    pub fn has_ready_to_answer(&self) -> bool {
624        self.ready_to_answer.load().is_some()
625    }
626
627    /// Prepared 200 OK for the underlying SIP dialog of non-SIP call types.
628    pub fn set_pending_sip_answer(&self, pending: PendingSipAnswer) {
629        self.pending_sip_answer.store(Some(Arc::new(pending)));
630    }
631
632    pub fn take_pending_sip_answer(&self) -> Option<Arc<PendingSipAnswer>> {
633        self.pending_sip_answer.swap(None)
634    }
635
636    /// Cancel token that hangs up only the refer leg, leaving the main call
637    /// alive; set by `do_refer`, taken by hangup.
638    pub fn take_refer_call_token(&self) -> Option<CancellationToken> {
639        self.refer_call_token.swap(None).map(|t| (*t).clone())
640    }
641
642    pub fn set_refer_call_token(&self, token: CancellationToken) {
643        self.refer_call_token.store(Some(Arc::new(token)));
644    }
645
646    /// Pending wait-input timeout set by the last Tts/Play command, consumed
647    /// when the track ends.
648    pub fn take_wait_input_timeout(&self) -> Option<u32> {
649        self.wait_input_timeout.swap(None).map(|t| *t)
650    }
651
652    pub fn set_wait_input_timeout(&self, v: Option<u32>) {
653        self.wait_input_timeout.store(v.map(Arc::new));
654    }
655
656    /// ASR config to resume on the parent leg once the refer leg ends.
657    pub fn set_pending_asr_resume(&self, v: (u32, TranscriptionOption)) {
658        self.pending_asr_resume.store(Some(Arc::new(v)));
659    }
660
661    pub fn take_pending_asr_resume(&self) -> Option<(u32, TranscriptionOption)> {
662        self.pending_asr_resume.swap(None).map(|a| (*a).clone())
663    }
664
665    /// RFC 3515 notifier of the pending incoming-REFER transfer (if any).
666    pub fn set_refer_notifier(&self, v: Option<Arc<crate::call::sip::ReferProgressNotifier>>) {
667        self.refer_notifier.store(v);
668    }
669
670    pub fn take_refer_notifier(&self) -> Option<Arc<crate::call::sip::ReferProgressNotifier>> {
671        self.refer_notifier.swap(None)
672    }
673
674    /// Insert/overwrite one main-leg extras variable.
675    pub fn set_extra(&self, key: &str, value: serde_json::Value) {
676        self.leg().set_extra(key, value);
677    }
678
679    /// Whether a pending (not yet answered) incoming dialog exists for this call.
680    fn has_pending_invite(&self) -> bool {
681        self.invitation
682            .find_dialog_id_by_session_id(&self.session_id)
683            .is_some()
684    }
685
686    /// One-shot hangup for error-cleanup paths outside the actor loop.
687    async fn hangup_now(&self, reason: Option<CallRecordHangupReason>) {
688        self.do_hangup(reason, None, None, None).await.ok();
689    }
690
691    /// One-shot reject for teardown paths outside the actor loop.
692    async fn reject_now(&self, code: Option<rsipstack::rsip::StatusCode>, reason: Option<String>) {
693        self.do_reject(code, reason).await.ok();
694    }
695}
696
697/// Answer prepared during ringing: the SDP to answer with, the already
698/// running caller track (started for early media), and the dialog to accept.
699pub struct ReadyAnswer {
700    pub answer: String,
701    pub track: PendingCallerTrack,
702    pub dialog: InviteDialog,
703}
704
705/// Answer prepared for the underlying inbound SIP dialog of a non-SIP call
706/// type (WebSocket/Webrtc): the 200 OK SDP, the dialog to accept, and the RTP
707/// track that bridges the SIP leg into the media stream.
708pub struct PendingSipAnswer {
709    pub answer: String,
710    pub dialog: InviteDialog,
711    pub track: Box<dyn Track>,
712}
713
714pub struct ActiveCallGuard {
715    pub call: ActiveCallRef,
716    pub active_calls: usize,
717}
718
719impl ActiveCallGuard {
720    pub fn new(call: ActiveCallRef) -> Self {
721        let active_calls = {
722            call.app_state
723                .total_calls
724                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
725            let mut calls = call.app_state.active_calls.lock().unwrap();
726            calls.insert(call.session_id.clone(), call.clone());
727            calls.len()
728        };
729        Self { call, active_calls }
730    }
731}
732
733impl Drop for ActiveCallGuard {
734    fn drop(&mut self) {
735        self.call
736            .app_state
737            .active_calls
738            .lock()
739            .unwrap()
740            .remove(&self.call.session_id);
741        // Idempotent cleanup of the incoming-call session-id mapping (no-op
742        // for outgoing/websocket sessions that were never registered).
743        self.call
744            .invitation
745            .unregister_session(&self.call.session_id);
746    }
747}
748
749pub struct ActiveCallReceiver {
750    pub cmd_receiver: CommandReceiver,
751    pub dump_cmd_receiver: CommandReceiver,
752    pub dump_event_receiver: EventReceiver,
753}
754
755/// Construction parameters for [`ActiveCall::new`].
756pub struct CallSpec {
757    pub call_type: ActiveCallType,
758    pub cancel_token: CancellationToken,
759    pub session_id: String,
760    pub invitation: Invitation,
761    pub app_state: AppState,
762    pub track_config: TrackConfig,
763    /// WebSocket audio receiver (WebSocket calls only), taken once by setup.
764    pub audio_receiver: Option<WebsocketBytesReceiver>,
765    pub dump_events: bool,
766    /// Overrides the default server-side track id.
767    pub server_side_track_id: Option<TrackId>,
768    /// Initial session variables; built-ins (session id, call type, start
769    /// time) are injected for missing keys.
770    pub extras: Option<HashMap<String, serde_json::Value>>,
771}
772
773impl ActiveCall {
774    pub fn new(spec: CallSpec) -> Self {
775        let CallSpec {
776            call_type,
777            cancel_token,
778            session_id,
779            invitation,
780            app_state,
781            track_config,
782            audio_receiver,
783            dump_events,
784            server_side_track_id,
785            extras,
786        } = spec;
787        let event_sender = crate::event::create_event_sender();
788        let cmd_sender = tokio::sync::broadcast::Sender::<Command>::new(32);
789        let server_side_track_id = server_side_track_id.unwrap_or(SERVER_SIDE_TRACK_ID.to_string());
790        let media_stream_builder = MediaStreamBuilder::new(event_sender.clone())
791            .with_id(session_id.clone())
792            .with_cancel_token(cancel_token.child_token());
793        let media_stream = Arc::new(media_stream_builder.build());
794        let start_time = Utc::now();
795        // Inject built-in session variables into extras
796        let call_type_str = match &call_type {
797            ActiveCallType::Sip => "sip",
798            ActiveCallType::WebSocket => "websocket",
799            ActiveCallType::Webrtc => "webrtc",
800            ActiveCallType::B2bua => "b2bua",
801        };
802        let mut extras = extras.unwrap_or_default();
803        extras
804            .entry(crate::playbook::BUILTIN_SESSION_ID.to_string())
805            .or_insert_with(|| serde_json::Value::String(session_id.clone()));
806        extras
807            .entry(crate::playbook::BUILTIN_CALL_TYPE.to_string())
808            .or_insert_with(|| serde_json::Value::String(call_type_str.to_string()));
809        extras
810            .entry(crate::playbook::BUILTIN_START_TIME.to_string())
811            .or_insert_with(|| serde_json::Value::String(start_time.to_rfc3339()));
812
813        let progress = CallProgress {
814            session_id: session_id.clone(),
815            start_time: Some(start_time),
816            ..Default::default()
817        };
818
819        Self {
820            cancel_token,
821            call_type,
822            session_id,
823            start_time,
824            media_stream,
825            track_config,
826            event_sender,
827            app_state,
828            invitation,
829            cmd_sender,
830            dump_events,
831            server_side_track_id,
832            ssrc: rand::random::<u32>(),
833            bridge_paused: Arc::new(AtomicBool::new(false)),
834            progress: Arc::new(ArcSwap::from_pointee(progress)),
835            extras: Arc::new(ArcSwap::from_pointee(extras)),
836            moh: ArcSwapOption::new(None),
837            current_play_id: ArcSwapOption::new(None),
838            tts_handle: ArcSwapOption::new(None),
839            refer_leg: ArcSwapOption::new(None),
840            ready_to_answer: ArcSwapOption::new(None),
841            pending_sip_answer: ArcSwapOption::new(None),
842            refer_call_token: ArcSwapOption::new(None),
843            wait_input_timeout: ArcSwapOption::new(None),
844            pending_asr_resume: ArcSwapOption::new(None),
845            refer_notifier: ArcSwapOption::new(None),
846            audio_receiver: std::sync::Mutex::new(audio_receiver),
847        }
848    }
849
850    pub async fn enqueue_command(&self, command: Command) -> Result<()> {
851        self.cmd_sender
852            .send(command)
853            .map_err(|e| anyhow::anyhow!("Failed to send command: {}", e))?;
854        Ok(())
855    }
856
857    /// Create a new ActiveCallReceiver for this ActiveCall
858    /// `tokio::sync::broadcast` not cached messages, so need to early create receiver
859    /// before calling `serve()`
860    pub fn new_receiver(&self) -> ActiveCallReceiver {
861        ActiveCallReceiver {
862            cmd_receiver: self.cmd_sender.subscribe(),
863            dump_cmd_receiver: self.cmd_sender.subscribe(),
864            dump_event_receiver: self.event_sender.subscribe(),
865        }
866    }
867
868    /// The call actor: a single select loop owning the [`CallRuntime`].
869    ///
870    /// Commands, session events, background-completion messages, the
871    /// wait-input timeout tick, the media stream and cancellation all meet in
872    /// one place, so runtime state is plain (lock-free) data owned by this
873    /// task — mirroring the concurrency of the previous separate
874    /// command/event loops without their shared locks.
875    pub async fn serve(self: Arc<Self>, receiver: ActiveCallReceiver) -> Result<()> {
876        let ActiveCallReceiver {
877            mut cmd_receiver,
878            dump_cmd_receiver,
879            dump_event_receiver,
880        } = receiver;
881
882        let mut event_receiver = self.event_sender.subscribe();
883        let (actor_tx, mut actor_rx) = mpsc::channel::<ActorMsg>(16);
884        let mut runtime = CallRuntime::new(actor_tx);
885        runtime.me = Some(self.clone());
886
887        self.app_state
888            .total_calls
889            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
890
891        let me = self.clone();
892        let actor = async move {
893            // RAII: whatever way the loop exits (break, panic, early drop),
894            // the call's cancel token fires so every child task and the media
895            // stream shut down.
896            let _cancel_on_exit = CancelOnExit(&me.cancel_token);
897            let mut ticker = tokio::time::interval(Duration::from_millis(100));
898            // Keep the media-serve future alive across select iterations.
899            let mut media_serve = Box::pin(me.media_stream.serve());
900            loop {
901                tokio::select! {
902                    cmd = cmd_receiver.recv() => {
903                        match cmd {
904                            Ok(command) => {
905                                // Box::pin keeps the deep do_* future tree off
906                                // the select's stack frame (debug builds overflow
907                                // otherwise).
908                                if let Err(e) = Box::pin(me.dispatch(&mut runtime, command)).await {
909                                    warn!(session_id = me.session_id, "{}", e);
910                                    me.event_sender
911                                        .send(SessionEvent::Error {
912                                            track_id: me.session_id.clone(),
913                                            timestamp: crate::media::get_timestamp(),
914                                            sender: "command".to_string(),
915                                            error: e.to_string(),
916                                            code: None,
917                                        })
918                                        .ok();
919                                }
920                            }
921                            Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => continue,
922                            Err(_) => {
923                                info!(session_id = me.session_id, "command loop done");
924                                break;
925                            }
926                        }
927                    }
928                    ev = event_receiver.recv() => {
929                        match ev {
930                            Ok(event) => Box::pin(me.handle_event(&mut runtime, event)).await,
931                            Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => continue,
932                            Err(_) => {
933                                info!(session_id = me.session_id, "event loop done");
934                                break;
935                            }
936                        }
937                    }
938                    Some(msg) = actor_rx.recv() => {
939                        if let Err(e) = Box::pin(me.handle_actor_msg(msg)).await {
940                            warn!(session_id = me.session_id, "{}", e);
941                            me.event_sender
942                                .send(SessionEvent::Error {
943                                    track_id: me.session_id.clone(),
944                                    timestamp: crate::media::get_timestamp(),
945                                    sender: "command".to_string(),
946                                    error: e.to_string(),
947                                    code: None,
948                                })
949                                .ok();
950                        }
951                    }
952                    _ = ticker.tick() => {
953                        Box::pin(me.check_input_timeout(&mut runtime)).await;
954                    }
955                    _ = &mut media_serve => {
956                        info!(session_id = me.session_id, "media stream loop done");
957                        break;
958                    }
959                    _ = me.cancel_token.cancelled() => {
960                        info!(session_id = me.session_id, "call cancelled - cleaning up resources");
961                        break;
962                    }
963                }
964            }
965        };
966
967        tokio::join!(
968            self.dump_loop(self.dump_events, dump_cmd_receiver, dump_event_receiver),
969            actor
970        );
971        Ok(())
972    }
973
974    /// Wait-input silence timeout tick (formerly its own loop + mutex).
975    async fn check_input_timeout(&self, runtime: &mut CallRuntime) {
976        let (start_time, expire) = runtime.input_timeout_expire;
977        if expire > 0 && crate::media::get_timestamp() >= start_time + expire as u64 {
978            info!(session_id = self.session_id, "wait input timeout reached");
979            runtime.input_timeout_expire = (0, 0);
980            self.event_sender
981                .send(SessionEvent::Silence {
982                    track_id: self.server_side_track_id.clone(),
983                    timestamp: crate::media::get_timestamp(),
984                    start_time,
985                    duration: expire as u64,
986                    samples: None,
987                    refer: Some(false),
988                })
989                .ok();
990        }
991    }
992
993    /// Handle a session event (formerly the concurrent event-hook loop).
994    async fn handle_event(&self, runtime: &mut CallRuntime, event: SessionEvent) {
995        match event {
996            SessionEvent::Speaking { .. }
997            | SessionEvent::Dtmf { .. }
998            | SessionEvent::AsrDelta { .. }
999            | SessionEvent::AsrFinal { .. }
1000            | SessionEvent::TrackStart { .. } => {
1001                runtime.input_timeout_expire = (0, 0);
1002            }
1003            SessionEvent::TrackEnd {
1004                track_id,
1005                play_id,
1006                ssrc,
1007                auto_hangup,
1008                ..
1009            } => {
1010                if track_id != self.server_side_track_id {
1011                    return;
1012                }
1013
1014                if play_id != self.current_play() {
1015                    debug!(
1016                        session_id = self.session_id,
1017                        ?play_id,
1018                        current = ?self.current_play(),
1019                        "ignoring interrupted track end"
1020                    );
1021                    return;
1022                }
1023                self.set_current_play(None);
1024                let moh_path = self.moh_path();
1025                let wait_timeout_val = self.take_wait_input_timeout();
1026
1027                if let Some(path) = moh_path {
1028                    info!(session_id = self.session_id, "looping moh: {}", path);
1029                    let ssrc = rand::random::<u32>();
1030                    let file_track = self.make_file_track(path.clone(), ssrc);
1031                    self.update_track_wrapper(Box::new(file_track), Some(path))
1032                        .await;
1033                    return;
1034                }
1035
1036                if let Some(hangup_reason) = auto_hangup {
1037                    info!(
1038                        session_id = self.session_id,
1039                        ssrc, "auto hangup when track end track_id:{}", track_id
1040                    );
1041                    self.do_hangup(Some(hangup_reason), None, None, None)
1042                        .await
1043                        .ok();
1044                }
1045
1046                if let Some(timeout) = wait_timeout_val {
1047                    runtime.input_timeout_expire = if timeout > 0 {
1048                        (crate::media::get_timestamp(), timeout)
1049                    } else {
1050                        (0, 0)
1051                    };
1052                }
1053            }
1054            SessionEvent::Interrupt { receiver } => {
1055                let track_id = receiver.unwrap_or_else(|| self.server_side_track_id.clone());
1056                if track_id == self.server_side_track_id {
1057                    debug!(
1058                        session_id = self.session_id,
1059                        "received interrupt event, stopping playback"
1060                    );
1061                    self.do_interrupt(true).await.ok();
1062                }
1063            }
1064            SessionEvent::Inactivity { track_id, .. } => {
1065                info!(
1066                    session_id = self.session_id,
1067                    track_id, "inactivity timeout reached, hanging up"
1068                );
1069                self.do_hangup(
1070                    Some(CallRecordHangupReason::InactivityTimeout),
1071                    None,
1072                    None,
1073                    None,
1074                )
1075                .await
1076                .ok();
1077            }
1078            SessionEvent::Hangup { refer, .. } => {
1079                // Check if we need to resume ASR after refer hangup
1080                if refer == Some(true) {
1081                    if let Some((refer_ssrc, asr_option)) = self.take_pending_asr_resume() {
1082                        // Verify it's the refer call that ended
1083                        let is_refer_hangup = self
1084                            .refer_leg
1085                            .load_full()
1086                            .map(|leg| leg.ssrc == refer_ssrc)
1087                            .unwrap_or(false);
1088
1089                        if is_refer_hangup {
1090                            info!(
1091                                session_id = self.session_id,
1092                                "Refer call ended, resuming parent ASR"
1093                            );
1094
1095                            // Resume ASR
1096                            match self
1097                                .app_state
1098                                .stream_engine
1099                                .create_asr_processor(
1100                                    self.server_side_track_id.clone(),
1101                                    self.cancel_token.child_token(),
1102                                    asr_option,
1103                                    self.event_sender.clone(),
1104                                )
1105                                .await
1106                            {
1107                                Ok(asr_processor) => {
1108                                    if let Err(e) = self
1109                                        .media_stream
1110                                        .append_processor(&self.server_side_track_id, asr_processor)
1111                                        .await
1112                                    {
1113                                        warn!(
1114                                            session_id = self.session_id,
1115                                            "Failed to resume ASR after refer: {}", e
1116                                        );
1117                                    }
1118                                }
1119                                Err(e) => {
1120                                    warn!(
1121                                        session_id = self.session_id,
1122                                        "Failed to create ASR processor for resume: {}", e
1123                                    );
1124                                }
1125                            }
1126                        }
1127                    }
1128                }
1129            }
1130            SessionEvent::Error { track_id, .. } => {
1131                if track_id != self.server_side_track_id {
1132                    return;
1133                }
1134
1135                let moh_info = {
1136                    let path = self.moh_path();
1137                    path.map(|path| {
1138                        let fallback = "./config/sounds/refer_moh.wav".to_string();
1139                        if path != fallback && std::path::Path::new(&fallback).exists() {
1140                            info!(
1141                                session_id = self.session_id,
1142                                "moh error, switching to fallback: {}", fallback
1143                            );
1144                            self.set_moh(Some(fallback.clone()));
1145                            fallback
1146                        } else {
1147                            info!(
1148                                session_id = self.session_id,
1149                                "looping moh on error: {}", path
1150                            );
1151                            path
1152                        }
1153                    })
1154                };
1155
1156                if let Some(next_path) = moh_info {
1157                    let ssrc = rand::random::<u32>();
1158                    let file_track = self.make_file_track(next_path.clone(), ssrc);
1159                    self.update_track_wrapper(Box::new(file_track), Some(next_path))
1160                        .await;
1161                }
1162            }
1163            SessionEvent::Hold { on_hold, .. } => {
1164                self.bridge_paused.store(on_hold, Ordering::Relaxed);
1165            }
1166            SessionEvent::TransferRequest {
1167                refer_to,
1168                referred_by,
1169                refer,
1170                notify,
1171                ..
1172            } => {
1173                // Parent-leg transfers only: a refer leg must never start
1174                // another transfer of its own.
1175                if refer == Some(true) {
1176                    return;
1177                }
1178                let Some(notifier) = notify else {
1179                    return;
1180                };
1181                // Remember the notifier so ReferDone can report the final
1182                // status to the referrer whatever we decide below.
1183                self.set_refer_notifier(Some(notifier.clone()));
1184                if !self.app_state.config.auto_refer() {
1185                    info!(
1186                        session_id = self.session_id,
1187                        %refer_to,
1188                        "auto refer disabled, terminating refer subscription with 403"
1189                    );
1190                    notifier.finished(403).await;
1191                    return;
1192                }
1193                if self.refer_leg.load().is_some() {
1194                    warn!(
1195                        session_id = self.session_id,
1196                        %refer_to,
1197                        "refer already in progress, rejecting new transfer"
1198                    );
1199                    notifier.finished(491).await;
1200                    return;
1201                }
1202                let Some(callee) = crate::sip_util::parse_refer_to_target(&refer_to) else {
1203                    warn!(
1204                        session_id = self.session_id,
1205                        %refer_to,
1206                        "unparsable Refer-To target, rejecting transfer"
1207                    );
1208                    notifier.finished(400).await;
1209                    return;
1210                };
1211                let caller = referred_by
1212                    .as_deref()
1213                    .and_then(crate::sip_util::parse_refer_to_target)
1214                    .or_else(|| {
1215                        self.progress
1216                            .load_full()
1217                            .option
1218                            .as_ref()
1219                            .and_then(|o| o.caller.clone())
1220                    })
1221                    .unwrap_or_default();
1222                let refer_option = ReferOption {
1223                    auto_hangup: Some(true),
1224                    forward_dtmf: Some(true),
1225                    timeout: Some(self.app_state.config.auto_refer_timeout()),
1226                    denoise: None,
1227                    agc: None,
1228                    moh: None,
1229                    vad: None,
1230                    asr: None,
1231                    sip: None,
1232                    call_id: None,
1233                    pause_parent_asr: None,
1234                };
1235                info!(
1236                    session_id = self.session_id,
1237                    %caller,
1238                    %callee,
1239                    "auto refer: following incoming REFER"
1240                );
1241                if let Err(e) = self
1242                    .do_refer(runtime, caller, callee, Some(refer_option))
1243                    .await
1244                {
1245                    warn!(
1246                        session_id = self.session_id,
1247                        "auto refer failed to start: {}", e
1248                    );
1249                    if let Some(notifier) = self.take_refer_notifier() {
1250                        notifier.finished(500).await;
1251                    }
1252                }
1253            }
1254            _ => {}
1255        }
1256    }
1257
1258    /// Completion of background work spawned by a `do_*` command.
1259    async fn handle_actor_msg(&self, msg: ActorMsg) -> Result<()> {
1260        match msg {
1261            ActorMsg::ReferDone {
1262                track_id,
1263                forward_dtmf,
1264                result,
1265                code,
1266            } => match result {
1267                Ok(answer) => {
1268                    self.media_stream
1269                        .set_track_refer(&track_id, Some(true))
1270                        .await;
1271                    if !forward_dtmf {
1272                        self.media_stream
1273                            .set_track_dtmf_forward(&track_id, false)
1274                            .await;
1275                    }
1276                    self.event_sender
1277                        .send(SessionEvent::Answer {
1278                            timestamp: crate::media::get_timestamp(),
1279                            track_id,
1280                            sdp: answer,
1281                            refer: Some(true),
1282                        })
1283                        .ok();
1284                    if let Some(notifier) = self.take_refer_notifier() {
1285                        notifier.finished(code.unwrap_or(200)).await;
1286                    }
1287                    Ok(())
1288                }
1289                Err(e) => {
1290                    warn!(
1291                        session_id = self.session_id,
1292                        "failed to create refer sip track: {}", e
1293                    );
1294                    self.emit_reject_from_rsip_error(track_id, true, &e);
1295                    let status = code
1296                        .or_else(|| match &e {
1297                            rsipstack::Error::DialogError(_, _, status) => Some(status.code()),
1298                            _ => None,
1299                        })
1300                        .unwrap_or(500);
1301                    if let Some(notifier) = self.take_refer_notifier() {
1302                        notifier.finished(status).await;
1303                    }
1304                    Err(e.into())
1305                }
1306            },
1307        }
1308    }
1309
1310    async fn dispatch(&self, runtime: &mut CallRuntime, command: Command) -> Result<()> {
1311        match command {
1312            Command::Invite { option } => self.do_invite(runtime, option).await,
1313            Command::Accept { option } => self.do_accept(option).await,
1314            Command::Reject { reason, code } => {
1315                self.do_reject(code.map(|c| (c as u16).into()), Some(reason))
1316                    .await
1317            }
1318            Command::Ringing { .. } => self.do_ringing(command).await,
1319            Command::Tts { .. } => self.do_tts(command).await,
1320            Command::Play { .. } => self.do_play(command).await,
1321            Command::Hangup {
1322                reason,
1323                initiator,
1324                headers,
1325                refer,
1326            } => {
1327                let reason = reason.map(|r| {
1328                    r.parse::<CallRecordHangupReason>()
1329                        .unwrap_or(CallRecordHangupReason::BySystem)
1330                });
1331                self.do_hangup(reason, initiator, headers, refer).await
1332            }
1333            Command::Refer {
1334                caller,
1335                callee,
1336                options,
1337            } => self.do_refer(runtime, caller, callee, options).await,
1338            Command::Message {
1339                body,
1340                content_type,
1341                headers,
1342                refer,
1343            } => self.do_message(body, content_type, headers, refer).await,
1344            Command::Bridge { target_session_id } => self.do_bridge(target_session_id).await,
1345            Command::Unbridge { target_session_id } => self.do_unbridge(target_session_id).await,
1346            Command::Mute { track_id } => self.do_mute(track_id).await,
1347            Command::Unmute { track_id } => self.do_unmute(track_id).await,
1348            Command::Pause {} => self.do_pause().await,
1349            Command::Resume {} => self.do_resume().await,
1350            Command::Interrupt {
1351                graceful: passage,
1352                fade_out_ms: _,
1353            } => self.do_interrupt(passage.unwrap_or_default()).await,
1354            Command::History { speaker, text } => self.do_history(speaker, text).await,
1355            Command::Custom { sender, data } => self.do_custom(sender, data),
1356            Command::AddIceCandidate {
1357                candidate,
1358                sdp_mid,
1359                sdp_mline_index,
1360            } => {
1361                self.media_stream
1362                    .add_ice_candidate(&candidate, sdp_mid.as_deref(), sdp_mline_index)
1363                    .await
1364            }
1365        }
1366    }
1367
1368    fn build_record_option(&self, option: &CallOption) -> Option<RecorderOption> {
1369        if let Some(recorder_option) = &option.recorder {
1370            let mut recorder_file = recorder_option.recorder_file.clone();
1371            if recorder_file.contains("{id}") {
1372                recorder_file = recorder_file.replace("{id}", &self.session_id);
1373            }
1374
1375            let recorder_file = if recorder_file.is_empty() {
1376                self.app_state.get_recorder_file(&self.session_id)
1377            } else {
1378                let p = Path::new(&recorder_file);
1379                p.is_absolute()
1380                    .then(|| recorder_file.clone())
1381                    .unwrap_or_else(|| self.app_state.get_recorder_file(&recorder_file))
1382            };
1383            info!(
1384                session_id = self.session_id,
1385                recorder_file, "created recording file"
1386            );
1387
1388            let track_samplerate = self.track_config.samplerate;
1389            let recorder_samplerate = if track_samplerate > 0 {
1390                track_samplerate
1391            } else {
1392                recorder_option.samplerate
1393            };
1394            let recorder_ptime = if recorder_option.ptime == 0 {
1395                200
1396            } else {
1397                recorder_option.ptime
1398            };
1399            let requested_format = recorder_option
1400                .format
1401                .unwrap_or(self.app_state.config.recorder_format());
1402            let format = requested_format.effective();
1403            if requested_format != format {
1404                warn!(
1405                    session_id = self.session_id,
1406                    requested = requested_format.extension(),
1407                    "Recorder format fallback to wav due to unsupported feature"
1408                );
1409            }
1410            let mut recorder_config = RecorderOption {
1411                recorder_file,
1412                samplerate: recorder_samplerate,
1413                ptime: recorder_ptime,
1414                format: Some(format),
1415                native_samplerate: Some(
1416                    recorder_option.native_samplerate.unwrap_or(false)
1417                        || self.app_state.config.recorder_native_samplerate(),
1418                ),
1419            };
1420            recorder_config.ensure_path_extension(format);
1421            Some(recorder_config)
1422        } else {
1423            None
1424        }
1425    }
1426
1427    async fn invite_or_accept(&self, mut option: CallOption, sender: String) -> Result<CallOption> {
1428        // Merge with existing configuration (e.g., from playbook)
1429        {
1430            let state = self.progress.load_full();
1431            option = state.merge_option(option);
1432        }
1433
1434        option.check_default();
1435        if let Some(opt) = self.build_record_option(&option) {
1436            self.media_stream.update_recorder_option(opt).await;
1437        }
1438        self.ensure_call_ambiance(&option).await;
1439
1440        if let Some(opt) = &option.media_pass {
1441            let track_id = self.server_side_track_id.clone();
1442            let cancel_token = self.cancel_token.child_token();
1443            let ssrc = rand::random::<u32>();
1444            let media_pass_track = MediaPassTrack::new(
1445                self.session_id.clone(),
1446                ssrc,
1447                track_id,
1448                cancel_token,
1449                opt.clone(),
1450            );
1451            self.update_track_wrapper(Box::new(media_pass_track), None)
1452                .await;
1453        }
1454
1455        info!(
1456            session_id = self.session_id,
1457            call_type = ?self.call_type,
1458            sender,
1459            ?option,
1460            "caller with option"
1461        );
1462
1463        match self.setup_caller_track(&option).await {
1464            Ok(_) => return Ok(option),
1465            Err(e) => {
1466                self.app_state
1467                    .total_failed_calls
1468                    .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1469                let error_event = crate::event::SessionEvent::Error {
1470                    track_id: self.session_id.clone(),
1471                    timestamp: crate::media::get_timestamp(),
1472                    sender,
1473                    error: e.to_string(),
1474                    code: None,
1475                };
1476                self.event_sender.send(error_event).ok();
1477                self.hangup_now(Some(CallRecordHangupReason::BySystem))
1478                    .await;
1479                return Err(e);
1480            }
1481        }
1482    }
1483
1484    async fn do_invite(&self, runtime: &mut CallRuntime, option: CallOption) -> Result<()> {
1485        // Run the INVITE handshake in the background so the actor keeps
1486        // serving media (and everything else) while the call rings - same
1487        // reasoning as do_refer below. invite_or_accept blocks on the SIP
1488        // transaction for the entire ring duration; handling that inline on
1489        // the actor's own select loop would freeze media_stream.serve() (and
1490        // therefore all live audio bridging for this leg) for just as long.
1491        let me = runtime
1492            .me
1493            .clone()
1494            .ok_or_else(|| anyhow::anyhow!("invite is only supported inside serve()"))?;
1495        crate::spawn(async move {
1496            if let Err(e) = me.invite_or_accept(option, "invite".to_string()).await {
1497                warn!(session_id = me.session_id, "{}", e);
1498                me.event_sender
1499                    .send(SessionEvent::Error {
1500                        track_id: me.session_id.clone(),
1501                        timestamp: crate::media::get_timestamp(),
1502                        sender: "command".to_string(),
1503                        error: e.to_string(),
1504                        code: None,
1505                    })
1506                    .ok();
1507            }
1508        });
1509        Ok(())
1510    }
1511
1512    async fn do_accept(&self, mut option: CallOption) -> Result<()> {
1513        let has_pending = self.has_pending_invite();
1514        let ready_to_answer_val = !self.has_ready_to_answer();
1515
1516        if ready_to_answer_val {
1517            if !has_pending {
1518                // emit reject event
1519                warn!(session_id = self.session_id, "no pending call to accept");
1520                let rejet_event = crate::event::SessionEvent::Reject {
1521                    track_id: self.session_id.clone(),
1522                    timestamp: crate::media::get_timestamp(),
1523                    reason: "no pending call".to_string(),
1524                    refer: None,
1525                    code: Some(486),
1526                };
1527                self.event_sender.send(rejet_event).ok();
1528                self.hangup_now(Some(CallRecordHangupReason::BySystem))
1529                    .await;
1530                return Err(anyhow::anyhow!("no pending call to accept"));
1531            }
1532            option = self.invite_or_accept(option, "accept".to_string()).await?;
1533        } else {
1534            option.check_default();
1535            if let Some(opt) = self.build_record_option(&option) {
1536                self.media_stream.update_recorder_option(opt).await;
1537            }
1538            self.set_option(option.clone());
1539            self.ensure_call_ambiance(&option).await;
1540        }
1541        info!(session_id = self.session_id, ?option, "accepting call");
1542        let ready = self.take_ready_to_answer();
1543        if let Some(ready) = ready {
1544            // Exclusive since `take` swapped it out and the actor serializes
1545            // commands, so the unwrap cannot race another holder.
1546            let ReadyAnswer {
1547                answer,
1548                track: pending_track,
1549                dialog,
1550            } = match Arc::try_unwrap(ready) {
1551                Ok(ready) => ready,
1552                Err(_) => {
1553                    warn!(
1554                        session_id = self.session_id,
1555                        "ready_to_answer held elsewhere; skipping accept"
1556                    );
1557                    return Ok(());
1558                }
1559            };
1560            info!(session_id = self.session_id, "ready to answer with track");
1561
1562            let headers = vec![rsipstack::rsip::Header::ContentType(
1563                "application/sdp".to_string().into(),
1564            )];
1565
1566            match dialog.accept(Some(headers), Some(answer.as_bytes().to_vec())) {
1567                Ok(_) => {
1568                    self.leg().update_progress(|p| {
1569                        p.answer = Some(answer.clone());
1570                        p.answer_time.get_or_insert_with(Utc::now);
1571                    });
1572                    self.finish_caller_stack(&option, pending_track).await?;
1573                }
1574                Err(e) => {
1575                    warn!(session_id = self.session_id, "failed to accept call: {}", e);
1576                    return Err(anyhow::anyhow!("failed to accept call"));
1577                }
1578            }
1579        }
1580
1581        // Non-SIP call types (WebSocket/Webrtc) created by an inbound SIP
1582        // INVITE never go through `ready_to_answer`; the underlying dialog is
1583        // answered here. Without this the carrier leg stays in `Trying` until
1584        // the far end times out and CANCELs (production: VOS3000 20s timeout).
1585        if let Some(pending) = self.take_pending_sip_answer() {
1586            let Ok(pending) = Arc::try_unwrap(pending) else {
1587                warn!(
1588                    session_id = self.session_id,
1589                    "pending sip answer held elsewhere; skipping sip accept"
1590                );
1591                return Ok(());
1592            };
1593            let headers = vec![rsipstack::rsip::Header::ContentType(
1594                "application/sdp".to_string().into(),
1595            )];
1596            match pending
1597                .dialog
1598                .accept(Some(headers), Some(pending.answer.as_bytes().to_vec()))
1599            {
1600                Ok(_) => {
1601                    info!(
1602                        session_id = self.session_id,
1603                        "answered underlying sip dialog"
1604                    );
1605                    self.leg().update_progress(|p| {
1606                        p.answer = Some(pending.answer.clone());
1607                        p.answer_time.get_or_insert_with(Utc::now);
1608                    });
1609                    // Register the SIP leg so customer audio is bridged with
1610                    // the caller track (and later the refer leg).
1611                    self.media_stream.update_track(pending.track, None).await;
1612                }
1613                Err(e) => {
1614                    warn!(
1615                        session_id = self.session_id,
1616                        "failed to accept underlying sip dialog: {}", e
1617                    );
1618                }
1619            }
1620        }
1621        Ok(())
1622    }
1623
1624    async fn do_reject(
1625        &self,
1626        code: Option<rsipstack::rsip::StatusCode>,
1627        reason: Option<String>,
1628    ) -> Result<()> {
1629        if let Some(pending) = self.take_pending_sip_answer() {
1630            info!(
1631                session_id = self.session_id,
1632                ?reason,
1633                ?code,
1634                "rejecting underlying sip dialog"
1635            );
1636            if let Ok(pending) = Arc::try_unwrap(pending) {
1637                pending.dialog.reject(code.clone(), reason.clone()).ok();
1638                self.invitation
1639                    .dialog_layer
1640                    .remove_dialog(&pending.dialog.id());
1641            }
1642        }
1643        match self
1644            .invitation
1645            .find_dialog_id_by_session_id(&self.session_id)
1646        {
1647            Some(id) => {
1648                info!(
1649                    session_id = self.session_id,
1650                    ?reason,
1651                    ?code,
1652                    "rejecting call"
1653                );
1654                let result = self.invitation.hangup(id, code, reason).await;
1655                if result.is_ok() {
1656                    self.cancel_token.cancel();
1657                }
1658                result
1659            }
1660            None => {
1661                if let Some(ready) = self.take_ready_to_answer() {
1662                    info!(
1663                        session_id = self.session_id,
1664                        ?reason,
1665                        ?code,
1666                        "rejecting call from ready_to_answer"
1667                    );
1668                    let dialog = &ready.dialog;
1669                    let dialog_id = dialog.id();
1670                    dialog.reject(code, reason).ok();
1671                    self.invitation.dialog_layer.remove_dialog(&dialog_id);
1672                    self.cancel_token.cancel();
1673                }
1674                Ok(())
1675            }
1676        }
1677    }
1678
1679    async fn do_ringing(&self, command: Command) -> Result<()> {
1680        let Command::Ringing {
1681            ringtone,
1682            recorder,
1683            early_media,
1684        } = command
1685        else {
1686            unreachable!("do_ringing called with non-Ringing command");
1687        };
1688
1689        if !self.has_ready_to_answer() {
1690            let option = CallOption {
1691                recorder,
1692                ..Default::default()
1693            };
1694            let _ = self.invite_or_accept(option, "ringing".to_string()).await?;
1695        }
1696
1697        if let Some(ready) = self.ready_to_answer.load_full() {
1698            let (headers, body) = if early_media.unwrap_or_default() || ringtone.is_some() {
1699                let headers = vec![rsipstack::rsip::Header::ContentType(
1700                    "application/sdp".to_string().into(),
1701                )];
1702                (Some(headers), Some(ready.answer.as_bytes().to_vec()))
1703            } else {
1704                (None, None)
1705            };
1706
1707            ready.dialog.ringing(headers, body).ok();
1708            info!(
1709                session_id = self.session_id,
1710                ringtone, early_media, "playing ringtone"
1711            );
1712            if let Some(ringtone_url) = ringtone {
1713                self.do_play(Command::Play {
1714                    url: ringtone_url,
1715                    play_id: None,
1716                    auto_hangup: None,
1717                    wait_input_timeout: None,
1718                    offset_ms: None,
1719                })
1720                .await
1721                .ok();
1722            } else {
1723                info!(session_id = self.session_id, "no ringtone to play");
1724            }
1725        }
1726        Ok(())
1727    }
1728
1729    async fn do_tts(&self, command: Command) -> Result<()> {
1730        let Command::Tts {
1731            text,
1732            speaker,
1733            play_id,
1734            auto_hangup,
1735            streaming,
1736            end_of_stream,
1737            option,
1738            wait_input_timeout,
1739            base64,
1740            cache_key,
1741        } = command
1742        else {
1743            unreachable!("do_tts called with non-Tts command");
1744        };
1745        let streaming = streaming.unwrap_or_default();
1746        let end_of_stream = end_of_stream.unwrap_or_default();
1747        let base64 = base64.unwrap_or_default();
1748
1749        let tts_option = {
1750            let call_state = self.progress.load_full();
1751            match call_state.option.clone().unwrap_or_default().tts {
1752                Some(opt) => opt.merge_with(option),
1753                None => {
1754                    if let Some(opt) = option {
1755                        opt
1756                    } else {
1757                        return Err(anyhow::anyhow!("no tts option available"));
1758                    }
1759                }
1760            }
1761        };
1762        let speaker = match speaker {
1763            Some(s) => Some(s),
1764            None => tts_option.speaker.clone(),
1765        };
1766
1767        let mut play_command = SynthesisCommand {
1768            text,
1769            speaker,
1770            play_id: play_id.clone(),
1771            streaming,
1772            end_of_stream: if !streaming { true } else { end_of_stream },
1773            option: tts_option,
1774            base64,
1775            cache_key,
1776            auto_hangup,
1777        };
1778        info!(
1779            session_id = self.session_id,
1780            provider = ?play_command.option.provider,
1781            text = %play_command.text.chars().take(10).collect::<String>(),
1782            speaker = play_command.speaker.as_deref(),
1783            auto_hangup = auto_hangup.unwrap_or_default(),
1784            play_id = play_command.play_id.as_deref(),
1785            streaming = play_command.streaming,
1786            end_of_stream = play_command.end_of_stream,
1787            wait_input_timeout = wait_input_timeout.unwrap_or_default(),
1788            is_base64 = play_command.base64,
1789            cache_key = play_command.cache_key.as_deref(),
1790            "new synthesis"
1791        );
1792
1793        let ssrc = rand::random::<u32>();
1794        let (should_interrupt, picked_ssrc) = {
1795            let existing_handle = self.tts_handle.load_full();
1796            let current_play_id = self.current_play();
1797
1798            let (target_ssrc, changed) = if let Some(handle) = &existing_handle {
1799                if play_id.is_some() && current_play_id != play_id {
1800                    (ssrc, true)
1801                } else {
1802                    (handle.ssrc, false)
1803                }
1804            } else {
1805                (ssrc, false)
1806            };
1807
1808            // Defer auto_hangup setting until after potential interrupt.
1809            // auto_hangup will be set below after do_interrupt() to avoid being cleared.
1810            self.set_wait_input_timeout(wait_input_timeout);
1811
1812            self.set_current_play(play_id.clone());
1813            (changed, target_ssrc)
1814        };
1815
1816        if should_interrupt {
1817            let _ = self.do_interrupt(false).await;
1818        }
1819
1820        // auto_hangup rides on the track: armed via `with_auto_hangup` when a
1821        // new track is created, or by the command itself for an existing track.
1822
1823        let existing_handle = self.tts_handle.load_full();
1824        if let Some(tts_handle) = existing_handle {
1825            match tts_handle.try_send(play_command) {
1826                Ok(_) => return Ok(()),
1827                Err(e) => {
1828                    play_command = e.0;
1829                }
1830            }
1831        }
1832
1833        let (new_handle, tts_track) = StreamEngine::create_tts_track(
1834            self.app_state.stream_engine.clone(),
1835            self.cancel_token.child_token(),
1836            self.session_id.clone(),
1837            self.server_side_track_id.clone(),
1838            picked_ssrc,
1839            play_id.clone(),
1840            streaming,
1841            &play_command.option,
1842            play_command.auto_hangup,
1843        )
1844        .await?;
1845
1846        new_handle.try_send(play_command)?;
1847        self.tts_handle.store(Some(Arc::new(new_handle)));
1848        self.update_track_wrapper(tts_track, play_id).await;
1849        Ok(())
1850    }
1851
1852    async fn do_play(&self, command: Command) -> Result<()> {
1853        let Command::Play {
1854            url,
1855            play_id,
1856            auto_hangup,
1857            wait_input_timeout,
1858            offset_ms,
1859        } = command
1860        else {
1861            unreachable!("do_play called with non-Play command");
1862        };
1863        let ssrc = rand::random::<u32>();
1864        info!(
1865            session_id = self.session_id,
1866            ssrc, url, play_id, auto_hangup, "play file track"
1867        );
1868
1869        let play_id = play_id.or(Some(url.clone()));
1870
1871        // make_file_track uses the path as play_id; honor an explicit play_id here.
1872        let mut file_track = self
1873            .make_file_track(url, ssrc)
1874            .with_play_id(play_id.clone())
1875            .with_auto_hangup(auto_hangup);
1876
1877        if let Some(offset) = offset_ms {
1878            file_track = file_track.with_offset_ms(offset);
1879        }
1880
1881        {
1882            self.tts_handle.store(None);
1883            self.set_wait_input_timeout(wait_input_timeout);
1884        }
1885
1886        self.update_track_wrapper(Box::new(file_track), play_id)
1887            .await;
1888        Ok(())
1889    }
1890
1891    async fn do_history(&self, speaker: String, text: String) -> Result<()> {
1892        self.event_sender
1893            .send(SessionEvent::AddHistory {
1894                sender: Some(self.session_id.clone()),
1895                timestamp: crate::media::get_timestamp(),
1896                speaker,
1897                text,
1898            })
1899            .map(|_| ())
1900            .map_err(Into::into)
1901    }
1902
1903    fn do_custom(&self, sender: Option<String>, data: serde_json::Value) -> Result<()> {
1904        self.event_sender
1905            .send(SessionEvent::Custom {
1906                timestamp: crate::media::get_timestamp(),
1907                sender,
1908                data,
1909            })
1910            .map(|_| ())
1911            .map_err(Into::into)
1912    }
1913
1914    async fn do_interrupt(&self, graceful: bool) -> Result<()> {
1915        {
1916            self.tts_handle.store(None);
1917            self.set_moh(None);
1918        }
1919        self.media_stream
1920            .remove_track(&self.server_side_track_id, graceful)
1921            .await;
1922        Ok(())
1923    }
1924    async fn do_pause(&self) -> Result<()> {
1925        self.media_stream
1926            .pause_playback(self.server_side_track_id.clone())
1927            .await?;
1928        Ok(())
1929    }
1930    async fn do_resume(&self) -> Result<()> {
1931        self.media_stream
1932            .resume_playback(self.server_side_track_id.clone())
1933            .await?;
1934        Ok(())
1935    }
1936    async fn do_hangup(
1937        &self,
1938        reason: Option<CallRecordHangupReason>,
1939        initiator: Option<String>,
1940        headers: Option<HashMap<String, String>>,
1941        refer: Option<bool>,
1942    ) -> Result<()> {
1943        info!(
1944            session_id = self.session_id,
1945            ?reason,
1946            ?initiator,
1947            ?headers,
1948            ?refer,
1949            "do_hangup"
1950        );
1951
1952        let hangup_reason = match initiator.as_deref() {
1953            Some("caller") => CallRecordHangupReason::ByCaller,
1954            Some("callee") => CallRecordHangupReason::ByCallee,
1955            Some("system") => CallRecordHangupReason::Autohangup,
1956            _ => reason.unwrap_or(CallRecordHangupReason::BySystem),
1957        };
1958
1959        match refer {
1960            Some(true) => {
1961                // Hang up only the refer call, leaving the main call alive.
1962                let refer_token = self.take_refer_call_token();
1963                let refer_leg = self.refer_leg_value();
1964                let has_refer_leg = refer_leg.is_some();
1965                if let Some(leg) = refer_leg {
1966                    if let Some(headers) = headers {
1967                        let h_val = serde_json::to_value(&headers).unwrap_or_default();
1968                        leg.set_extra("_hangup_headers", h_val);
1969                    }
1970                    // Set reason before cancelling so on_terminated() sees it.
1971                    let reason = hangup_reason.clone();
1972                    leg.update_progress(|p| p.set_hangup_reason(reason.clone()));
1973                }
1974                if let Some(token) = refer_token {
1975                    token.cancel();
1976                }
1977                if has_refer_leg {
1978                    self.media_stream
1979                        .remove_track(&self.server_side_track_id, false)
1980                        .await;
1981                }
1982            }
1983            _ => {
1984                if let Some(headers) = headers {
1985                    let h_val = serde_json::to_value(&headers).unwrap_or_default();
1986                    self.leg().set_extra("_hangup_headers", h_val);
1987                }
1988                self.leg()
1989                    .update_progress(|p| p.set_hangup_reason(hangup_reason.clone()));
1990                let refer_token = self.take_refer_call_token();
1991                self.media_stream
1992                    .stop(Some(hangup_reason.to_string()), initiator);
1993                if let Some(token) = refer_token {
1994                    token.cancel();
1995                }
1996            }
1997        }
1998        tokio::task::yield_now().await;
1999        Ok(())
2000    }
2001
2002    /// Initiate a refer (attended transfer) leg.
2003    ///
2004    /// The INVITE handshake can take up to `timeout` seconds, so it runs in a
2005    /// spawned task and reports back through [`ActorMsg::ReferDone`]; the
2006    /// actor loop keeps serving events (e.g. MOH looping) meanwhile.
2007    async fn do_refer(
2008        &self,
2009        runtime: &mut CallRuntime,
2010        caller: String,
2011        callee: String,
2012        refer_option: Option<ReferOption>,
2013    ) -> Result<()> {
2014        self.do_interrupt(false).await.ok();
2015
2016        // Check if we should pause parent ASR
2017        let pause_parent_asr = refer_option
2018            .as_ref()
2019            .and_then(|o| o.pause_parent_asr)
2020            .unwrap_or(false);
2021
2022        // Save original ASR option for later resume
2023        let original_asr_option = if pause_parent_asr {
2024            self.progress
2025                .load_full()
2026                .option
2027                .as_ref()
2028                .and_then(|o| o.asr.clone())
2029        } else {
2030            None
2031        };
2032
2033        // Pause parent ASR if requested
2034        if pause_parent_asr {
2035            info!(
2036                session_id = self.session_id,
2037                "Pausing parent call ASR during refer"
2038            );
2039            self.media_stream
2040                .remove_processor::<crate::media::asr_processor::AsrProcessor>(
2041                    &self.server_side_track_id,
2042                )
2043                .await
2044                .ok();
2045        }
2046
2047        let mut moh = refer_option.as_ref().and_then(|o| o.moh.clone());
2048        if let Some(ref path) = moh {
2049            if !path.starts_with("http") && !std::path::Path::new(path).exists() {
2050                let fallback = "./config/sounds/refer_moh.wav";
2051                if std::path::Path::new(fallback).exists() {
2052                    info!(
2053                        session_id = self.session_id,
2054                        "moh {} not found, using fallback {}", path, fallback
2055                    );
2056                    moh = Some(fallback.to_string());
2057                }
2058            }
2059        }
2060        let ref_call_id = refer_option
2061            .as_ref()
2062            .and_then(|o| o.call_id.clone())
2063            .unwrap_or_else(|| format!("ref-{}-{}", rand::random::<u32>(), self.session_id));
2064
2065        let session_id = self.session_id.clone();
2066        let track_id = self.server_side_track_id.clone();
2067
2068        let (recorder, parent_caller) = {
2069            let progress = self.progress.load_full();
2070            let option = progress.option.as_ref();
2071            (
2072                option.map(|o| o.recorder.clone()).unwrap_or_default(),
2073                option.and_then(|o| o.caller.clone()),
2074            )
2075        };
2076        let caller = if caller.trim().is_empty() {
2077            parent_caller.unwrap_or_default()
2078        } else {
2079            caller
2080        };
2081
2082        let mut call_option = CallOption {
2083            caller: Some(caller),
2084            callee: Some(callee.clone()),
2085            sip: refer_option.as_ref().and_then(|o| o.sip.clone()),
2086            vad: refer_option
2087                .as_ref()
2088                .and_then(|o| o.vad.clone())
2089                .map(|mut opts| {
2090                    opts.refer = Some(true);
2091                    opts
2092                }),
2093            asr: refer_option
2094                .as_ref()
2095                .and_then(|o| o.asr.clone())
2096                .map(|mut opts| {
2097                    opts.refer = Some(true);
2098                    opts
2099                }),
2100            denoise: refer_option.as_ref().and_then(|o| o.denoise.clone()),
2101            agc: refer_option.as_ref().and_then(|o| o.agc.clone()),
2102            recorder,
2103            ..Default::default()
2104        };
2105        call_option.check_default();
2106
2107        let mut invite_option = call_option.build_invite_option()?;
2108        invite_option.call_id = Some(ref_call_id.clone());
2109
2110        let headers = invite_option.headers.get_or_insert_with(|| Vec::new());
2111
2112        {
2113            let progress = self.progress.load_full();
2114            if let Some(opt) = progress.option.as_ref() {
2115                if let Some(callee) = opt.callee.as_ref() {
2116                    headers.push(rsipstack::rsip::Header::Other(
2117                        "X-Referred-To".to_string(),
2118                        callee.clone(),
2119                    ));
2120                }
2121                if let Some(caller) = opt.caller.as_ref() {
2122                    headers.push(rsipstack::rsip::Header::Other(
2123                        "X-Referred-From".to_string(),
2124                        caller.clone(),
2125                    ));
2126                }
2127            }
2128        }
2129
2130        headers.push(rsipstack::rsip::Header::Other(
2131            "X-Referred-Id".to_string(),
2132            self.session_id.clone(),
2133        ));
2134
2135        let ssrc = rand::random::<u32>();
2136        let refer_leg = LegShared::new(
2137            ssrc,
2138            true,
2139            CallProgress {
2140                session_id: ref_call_id.clone(),
2141                start_time: Some(Utc::now()),
2142                option: Some(call_option.clone()),
2143                ..Default::default()
2144            },
2145        );
2146        self.set_refer_leg(Some(refer_leg.clone()));
2147
2148        let auto_hangup_requested = refer_option
2149            .as_ref()
2150            .and_then(|o| o.auto_hangup)
2151            .unwrap_or(true);
2152
2153        // auto_hangup rides on the refer leg's TrackEnd (InviteDialogStates).
2154
2155        // Setup ASR resume after refer ends (if not auto_hangup and ASR was paused)
2156        if !auto_hangup_requested && pause_parent_asr && original_asr_option.is_some() {
2157            let asr_option = original_asr_option.unwrap();
2158            self.set_pending_asr_resume((ssrc, asr_option));
2159        }
2160
2161        let timeout_secs = refer_option.as_ref().and_then(|o| o.timeout).unwrap_or(30);
2162        let forward_dtmf = refer_option
2163            .as_ref()
2164            .and_then(|o| o.forward_dtmf)
2165            .unwrap_or(true);
2166
2167        info!(
2168            session_id = self.session_id,
2169            ssrc,
2170            auto_hangup = auto_hangup_requested,
2171            callee,
2172            timeout_secs,
2173            "do_refer"
2174        );
2175
2176        let refer_cancel_token = self.cancel_token.child_token();
2177        self.set_refer_call_token(refer_cancel_token.clone());
2178
2179        // Run the INVITE handshake in the background so the actor keeps
2180        // serving events (MOH looping, auto-hangup...) while it is in flight.
2181        let me = runtime
2182            .me
2183            .clone()
2184            .ok_or_else(|| anyhow::anyhow!("refer is only supported inside serve()"))?;
2185        let actor_tx = runtime.actor_tx.clone();
2186        let event_sender = self.event_sender.clone();
2187        let log_session_id = session_id.clone();
2188        let reject_track_id = track_id.clone();
2189        crate::spawn(async move {
2190            let out = crate::call::tracks::OutgoingLeg {
2191                cancel_token: refer_cancel_token,
2192                leg: refer_leg,
2193                track_id: track_id.clone(),
2194                invite_option,
2195                call_option,
2196                moh,
2197                auto_hangup: auto_hangup_requested,
2198            };
2199            let mut timed_out = false;
2200            let result = match tokio::time::timeout(
2201                Duration::from_secs(timeout_secs as u64),
2202                me.create_outgoing_sip_track(out),
2203            )
2204            .await
2205            {
2206                Ok(res) => res,
2207                Err(_) => {
2208                    warn!(
2209                        session_id = log_session_id,
2210                        "refer sip track creation timed out after {} seconds", timeout_secs
2211                    );
2212                    event_sender
2213                        .send(SessionEvent::Reject {
2214                            track_id: reject_track_id,
2215                            timestamp: crate::media::get_timestamp(),
2216                            reason: "Timeout when refer".into(),
2217                            code: Some(408),
2218                            refer: Some(true),
2219                        })
2220                        .ok();
2221                    timed_out = true;
2222                    Err(rsipstack::Error::Error(
2223                        "refer sip track creation timed out".to_string(),
2224                    ))
2225                }
2226            };
2227            me.set_moh(None);
2228            let code = match &result {
2229                Ok(_) => Some(200u16),
2230                Err(rsipstack::Error::DialogError(_, _, status)) => Some(status.code()),
2231                Err(_) if timed_out => Some(408),
2232                Err(_) => None,
2233            };
2234            actor_tx
2235                .send(ActorMsg::ReferDone {
2236                    track_id,
2237                    forward_dtmf,
2238                    result,
2239                    code,
2240                })
2241                .await
2242                .ok();
2243        });
2244
2245        Ok(())
2246    }
2247
2248    async fn do_message(
2249        &self,
2250        body: String,
2251        content_type: Option<String>,
2252        headers: Option<HashMap<String, String>>,
2253        refer: Option<bool>,
2254    ) -> Result<()> {
2255        if !matches!(self.call_type, ActiveCallType::Sip | ActiveCallType::B2bua) {
2256            return Err(anyhow::anyhow!(
2257                "message command is only supported for SIP calls"
2258            ));
2259        }
2260
2261        let dialog_key = if refer == Some(true) {
2262            self.refer_leg_value()
2263                .map(|leg| leg.progress.load_full().session_id.clone())
2264        } else {
2265            Some(self.progress.load_full().session_id.clone())
2266        };
2267
2268        let mut dialog = dialog_key
2269            .as_ref()
2270            .filter(|id| !id.is_empty())
2271            .and_then(|id| self.invitation.dialog_layer.get_dialog_with(id));
2272
2273        // Incoming sessions use short session ids, so resolve them through the
2274        // session-id mapping before falling back to a dialog-id string scan.
2275        if dialog.is_none() {
2276            if let Some(target_id) = dialog_key.as_ref().filter(|id| !id.is_empty()) {
2277                dialog = self
2278                    .invitation
2279                    .find_dialog_id_by_session_id(target_id)
2280                    .and_then(|dialog_id| self.invitation.dialog_layer.get_dialog(&dialog_id));
2281            }
2282        }
2283
2284        if dialog.is_none() {
2285            if let Some(target_id) = dialog_key.as_ref().filter(|id| !id.is_empty()) {
2286                dialog = self
2287                    .invitation
2288                    .dialog_layer
2289                    .all_dialog_ids()
2290                    .into_iter()
2291                    .filter_map(|id| self.invitation.dialog_layer.get_dialog_with(&id))
2292                    .find(|dialog| dialog.id().to_string() == *target_id);
2293            }
2294        }
2295
2296        // Last resort: look up a confirmed client dialog by call id (the
2297        // dialog id for refer legs, the session id otherwise).
2298        if dialog.is_none() {
2299            let call_id = match (refer == Some(true), dialog_key.as_deref()) {
2300                (true, Some(id)) if !id.is_empty() => Some(id),
2301                (false, _) => Some(self.session_id.as_str()),
2302                _ => None,
2303            };
2304            if let Some(call_id) = call_id {
2305                dialog = self
2306                    .invitation
2307                    .dialog_layer
2308                    .get_client_dialog_by_call_id(call_id)
2309                    .into_iter()
2310                    .find(|d| {
2311                        matches!(
2312                            d.state(),
2313                            rsipstack::dialog::dialog::DialogState::Confirmed(_, _)
2314                        )
2315                    })
2316                    .map(rsipstack::dialog::dialog::Dialog::Invite);
2317            }
2318        }
2319
2320        let dialog = dialog.ok_or_else(|| {
2321            anyhow::anyhow!(
2322                "no established SIP dialog found for message command, refer={}",
2323                refer.unwrap_or_default()
2324            )
2325        })?;
2326
2327        let mut sip_headers = vec![rsipstack::rsip::Header::ContentType(
2328            content_type
2329                .clone()
2330                .unwrap_or_else(|| "text/plain;charset=utf-8".to_string())
2331                .into(),
2332        )];
2333        if let Some(headers) = &headers {
2334            sip_headers.extend(crate::sip_util::sip_headers_from_map(headers));
2335        }
2336
2337        info!(
2338            session_id = self.session_id,
2339            dialog_id = %dialog.id(),
2340            content_type = content_type.as_deref().unwrap_or("text/plain;charset=utf-8"),
2341            refer = refer.unwrap_or_default(),
2342            body = %body.chars().take(64).collect::<String>(),
2343            "sending SIP MESSAGE"
2344        );
2345
2346        let response = dialog
2347            .message(Some(sip_headers), Some(body.into_bytes()))
2348            .await?;
2349        match response {
2350            Some(resp)
2351                if resp.status_code.kind() == rsipstack::rsip::StatusCodeKind::Successful =>
2352            {
2353                Ok(())
2354            }
2355            Some(resp) => Err(anyhow::anyhow!(
2356                "SIP MESSAGE rejected with status {}",
2357                resp.status_code
2358            )),
2359            None => Err(anyhow::anyhow!(
2360                "SIP MESSAGE was not sent because dialog is not confirmed"
2361            )),
2362        }
2363    }
2364
2365    fn bridge_track_id(source_session_id: &str, target_session_id: &str) -> TrackId {
2366        format!("bridge:{}:to:{}", source_session_id, target_session_id)
2367    }
2368
2369    async fn do_bridge(&self, target_session_id: String) -> Result<()> {
2370        let target = {
2371            let calls = self.app_state.active_calls.lock().unwrap();
2372            calls.get(&target_session_id).cloned()
2373        };
2374        let target = target.ok_or_else(|| {
2375            anyhow::anyhow!("bridge target session not found: {}", target_session_id)
2376        })?;
2377
2378        if target.session_id == self.session_id {
2379            return Err(anyhow::anyhow!("cannot bridge a call to itself").into());
2380        }
2381
2382        let self_bridge_track_id = Self::bridge_track_id(&self.session_id, &target.session_id);
2383        let target_bridge_track_id = Self::bridge_track_id(&target.session_id, &self.session_id);
2384
2385        self.media_stream
2386            .remove_track(&self_bridge_track_id, false)
2387            .await;
2388        target
2389            .media_stream
2390            .remove_track(&target_bridge_track_id, false)
2391            .await;
2392
2393        let (self_bridge_sender, self_bridge_receiver) = mpsc::channel(25);
2394        let (target_bridge_sender, target_bridge_receiver) = mpsc::channel(25);
2395
2396        let self_paused = self.bridge_paused.clone();
2397        let target_paused = target.bridge_paused.clone();
2398
2399        let self_forwarding_track = ForwardingTrack::new(
2400            self_bridge_track_id.clone(),
2401            self.session_id.clone(),
2402            target_bridge_sender,
2403            self_bridge_receiver,
2404            self.track_config.clone(),
2405            self.cancel_token.child_token(),
2406            rand::random::<u32>(),
2407            self_paused,
2408        );
2409
2410        let target_forwarding_track = ForwardingTrack::new(
2411            target_bridge_track_id.clone(),
2412            target.session_id.clone(),
2413            self_bridge_sender,
2414            target_bridge_receiver,
2415            target.track_config.clone(),
2416            target.cancel_token.child_token(),
2417            rand::random::<u32>(),
2418            target_paused,
2419        );
2420
2421        self.media_stream
2422            .update_track(Box::new(self_forwarding_track), None)
2423            .await;
2424        target
2425            .media_stream
2426            .update_track(Box::new(target_forwarding_track), None)
2427            .await;
2428
2429        info!(
2430            session_id = self.session_id,
2431            target = target_session_id,
2432            self_bridge_track_id,
2433            target_bridge_track_id,
2434            "audio bridge established"
2435        );
2436        Ok(())
2437    }
2438
2439    async fn do_unbridge(&self, target_session_id: String) -> Result<()> {
2440        let target = {
2441            let calls = self.app_state.active_calls.lock().unwrap();
2442            calls.get(&target_session_id).cloned()
2443        };
2444
2445        let self_bridge_track_id = Self::bridge_track_id(&self.session_id, &target_session_id);
2446        self.media_stream
2447            .remove_track(&self_bridge_track_id, false)
2448            .await;
2449
2450        if let Some(target) = target {
2451            let target_bridge_track_id =
2452                Self::bridge_track_id(&target.session_id, &self.session_id);
2453            target
2454                .media_stream
2455                .remove_track(&target_bridge_track_id, false)
2456                .await;
2457            info!(
2458                session_id = self.session_id,
2459                target = target.session_id,
2460                self_bridge_track_id,
2461                target_bridge_track_id,
2462                "audio bridge removed"
2463            );
2464        } else {
2465            info!(
2466                session_id = self.session_id,
2467                target = target_session_id,
2468                self_bridge_track_id,
2469                "audio bridge removed locally; target session not active"
2470            );
2471        }
2472
2473        Ok(())
2474    }
2475
2476    async fn do_mute(&self, track_id: Option<String>) -> Result<()> {
2477        self.media_stream.mute_track(track_id).await;
2478        Ok(())
2479    }
2480
2481    async fn do_unmute(&self, track_id: Option<String>) -> Result<()> {
2482        self.media_stream.unmute_track(track_id).await;
2483        Ok(())
2484    }
2485
2486    pub async fn cleanup(&self) -> Result<()> {
2487        if matches!(self.call_type, ActiveCallType::Sip | ActiveCallType::B2bua) {
2488            self.reject_now(
2489                Some(rsipstack::rsip::StatusCode::Decline),
2490                Some("handler disconnected".to_string()),
2491            )
2492            .await;
2493        }
2494        // A prepared-but-unaccepted SIP answer (non-SIP call types) must not
2495        // leave the carrier leg ringing forever.
2496        if let Some(pending) = self.take_pending_sip_answer() {
2497            if let Ok(pending) = Arc::try_unwrap(pending) {
2498                pending
2499                    .dialog
2500                    .reject(
2501                        Some(rsipstack::rsip::StatusCode::Decline),
2502                        Some("handler disconnected".to_string()),
2503                    )
2504                    .ok();
2505                self.invitation
2506                    .dialog_layer
2507                    .remove_dialog(&pending.dialog.id());
2508            }
2509        }
2510        self.tts_handle.store(None);
2511        self.media_stream.cleanup().await.ok();
2512        Ok(())
2513    }
2514
2515    /// Build the call record from lock-free snapshots; never blocks, so it is
2516    /// safe (and lossless) from synchronous `Drop`.
2517    pub fn get_callrecord(&self) -> Option<CallRecord> {
2518        let progress = self.progress.load_full();
2519        let extras = self.extras.load_full();
2520        let refer_leg = self.refer_leg_value();
2521        Some(build_callrecord(
2522            &progress,
2523            &extras,
2524            refer_leg.as_ref(),
2525            &self.app_state,
2526            self.session_id.clone(),
2527            self.call_type.clone(),
2528        ))
2529    }
2530
2531    async fn dump_to_file(
2532        &self,
2533        dump_file: &mut File,
2534        cmd_receiver: &mut CommandReceiver,
2535        event_receiver: &mut EventReceiver,
2536    ) {
2537        loop {
2538            select! {
2539                _ = self.cancel_token.cancelled() => {
2540                    break;
2541                }
2542                Ok(cmd) = cmd_receiver.recv() => {
2543                    CallRecordEvent::write(CallRecordEventType::Command, cmd, dump_file)
2544                        .await;
2545                }
2546                Ok(event) = event_receiver.recv() => {
2547                    if matches!(event, SessionEvent::Binary{..}) {
2548                        continue;
2549                    }
2550                    CallRecordEvent::write(CallRecordEventType::Event, event, dump_file)
2551                        .await;
2552                }
2553            };
2554        }
2555    }
2556
2557    async fn dump_loop(
2558        &self,
2559        dump_events: bool,
2560        mut dump_cmd_receiver: CommandReceiver,
2561        mut dump_event_receiver: EventReceiver,
2562    ) {
2563        if !dump_events {
2564            return;
2565        }
2566
2567        let file_name = self.app_state.get_dump_events_file(&self.session_id);
2568        let mut dump_file = match File::options()
2569            .create(true)
2570            .append(true)
2571            .open(&file_name)
2572            .await
2573        {
2574            Ok(file) => file,
2575            Err(e) => {
2576                warn!(
2577                    session_id = self.session_id,
2578                    file_name, "failed to open dump events file: {}", e
2579                );
2580                return;
2581            }
2582        };
2583        self.dump_to_file(
2584            &mut dump_file,
2585            &mut dump_cmd_receiver,
2586            &mut dump_event_receiver,
2587        )
2588        .await;
2589
2590        while let Ok(event) = dump_event_receiver.try_recv() {
2591            if matches!(event, SessionEvent::Binary { .. }) {
2592                continue;
2593            }
2594            CallRecordEvent::write(CallRecordEventType::Event, event, &mut dump_file).await;
2595        }
2596    }
2597}
2598
2599/// Cancels the token on drop, guaranteeing shutdown on every exit path of the
2600/// actor loop (normal break, panic, or task abort).
2601struct CancelOnExit<'a>(&'a CancellationToken);
2602
2603impl Drop for CancelOnExit<'_> {
2604    fn drop(&mut self) {
2605        self.0.cancel();
2606    }
2607}
2608
2609impl Drop for ActiveCall {
2610    fn drop(&mut self) {
2611        info!(session_id = self.session_id, "dropping active call");
2612        if let Some(sender) = self.app_state.callrecord_sender.as_ref() {
2613            if let Some(record) = self.get_callrecord() {
2614                if let Err(e) = sender.send(record) {
2615                    warn!(
2616                        session_id = self.session_id,
2617                        "failed to send call record: {}", e
2618                    );
2619                }
2620            }
2621        }
2622    }
2623}