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