Skip to main content

active_call/call/
active_call.rs

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