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