Skip to main content

active_call/call/
active_call.rs

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