From 874c4d239b6084f94fb7ba4c587f67f902a9ffc7 Mon Sep 17 00:00:00 2001 From: Joshua Smotritsky Date: Wed, 18 Nov 2026 15:00:54 -0500 Subject: [PATCH] feat(rwi): answer an SDP offer in call.leg_add call.leg_add accepts an optional offer instead of a target. The session creates the leg's media peer from the offer (ICE + DTLS selects the same rustrtc WebRTC transport WebRTC SIP callers use), answers it, and the command completes with data.answer. The leg is connected at once and joins media only through call.bridge, so a controller can attach a browser or WebRTC agent to any call without a SIP registration. The answer prefers the caller's negotiated codec when offered, so the bridge passes audio through, and otherwise follows the codec policy. --- docs/rwi.md | 27 +- docs/rwi_zh.md | 13 +- src/call/domain/command.rs | 14 ++ src/proxy/proxy_call/sip_session/session.rs | 133 ++++++++++ src/proxy/proxy_call/sip_session/tests/mod.rs | 231 ++++++++++++++++++ src/rwi/handler.rs | 7 +- src/rwi/processor.rs | 43 +++- src/rwi/session.rs | 3 + 8 files changed, 465 insertions(+), 6 deletions(-) diff --git a/docs/rwi.md b/docs/rwi.md index d3b153d6d..e79c6607f 100644 --- a/docs/rwi.md +++ b/docs/rwi.md @@ -207,7 +207,7 @@ Some commands support aliases for convenience: | `call.set_userdata` / `call.get_userdata` | Replace / read the session user data object (see below) | | `call.send_dtmf` | Send DTMF digits to the remote party | | `dtmf.collect` | Collect a multi-digit DTMF string | -| `call.leg_add` / `call.leg_remove` | Dynamically add / remove a call leg | +| `call.leg_add` / `call.leg_remove` | Dynamically add / remove a call leg (dialed, or answered from an SDP offer) | | `call.app_start` / `call.app_stop` | Start / stop a call application on the session | | `call.resume` | Resume receiving events for a call after re-attach | | `app.chain` | Chain into another call application | @@ -309,6 +309,31 @@ without changing other legs. `call.hangup` still ends the whole call. Unbridge leaves the legs alive and disconnected; subsequent leg state changes do not select a replacement pair automatically. Caller hangup still ends the session. +**Add a leg from an SDP offer (WebRTC join):** + +Instead of a `target`, `call.leg_add` may carry an `offer`: an SDP offer from +a client that joins the call directly, such as a browser or a WebRTC agent +whose controller relays signaling over RWI. The session creates the leg's media +peer from the offer (ICE + DTLS → WebRTC, the same transport WebRTC SIP callers +use), answers it, and returns the SDP answer with the leg ID. `target` and +`offer` are exclusive. + +```json +{"action":"call.leg_add","action_id":"join-1","params":{"call_id":"session-1","leg_id":"0192f0c4a8e47b3c9d2e5f6a7b8c9d0e","offer":"v=0\r\n..."}} +{"type":"command_completed","action_id":"join-1","status":"success","data":{"leg_id":"0192f0c4a8e47b3c9d2e5f6a7b8c9d0e","answer":"v=0\r\n..."}} +``` + +Unlike a dialed leg, the command completes after the answer is ready (ICE +candidates gathered, at most 10 s), and the leg is connected at once: it emits a +leg-scoped `call_answered` with no `call_ringing`. The answer prefers the +caller's negotiated codec when the offer carries it, so the bridge passes audio +through; otherwise it follows the codec policy (G.711 when none is configured) +and transcodes. ICE uses the media `external_ip`, `webrtc_port_start`/`end` and +`ice_servers` settings. The leg has no SIP dialog: bridge it with `call.bridge`, +end it with `call.leg_remove`, and it ends with the call. `call.bridge` checks +leg IDs before dispatch and accepts `caller`, `callee`, `consult*` or at least +32 hex characters, so give the leg such an ID. + **Reject call:** ```json diff --git a/docs/rwi_zh.md b/docs/rwi_zh.md index 070f0518e..998c6e1ca 100644 --- a/docs/rwi_zh.md +++ b/docs/rwi_zh.md @@ -211,7 +211,7 @@ RWI 命令使用 JSON 带标签联合格式。`action` 标识命令类型,`par | `call.set_userdata` / `call.get_userdata` | 全量替换/读取会话用户数据对象(见下) | | `call.send_dtmf` | 向远端发送 DTMF 数字 | | `dtmf.collect` | 收集多位 DTMF 字符串 | -| `call.leg_add` / `call.leg_remove` | 动态添加/移除通话腿 | +| `call.leg_add` / `call.leg_remove` | 动态添加/移除通话腿(拨号,或由 SDP offer 应答) | | `call.app_start` / `call.app_stop` | 在会话上启动/停止通话应用 | | `call.resume` | 重新附着后恢复接收某通通话事件 | | `app.chain` | 串联进入另一个通话应用 | @@ -268,6 +268,17 @@ RWI 命令使用 JSON 带标签联合格式。`action` 标识命令类型,`par 有效 `reason` 值:`busy`、`forbidden`、`not_found`。 +**由 SDP offer 添加通话腿(WebRTC 加入):** + +`call.leg_add` 可以不带 `target`,改带 `offer`:由直接加入通话的客户端(如浏览器,或经控制方通过 RWI 中转信令的 WebRTC 坐席)生成的 SDP offer。会话按 offer 创建该腿的媒体端点(ICE + DTLS → WebRTC,与 WebRTC SIP 主叫相同的传输),生成应答,并随腿 ID 返回 SDP answer。`target` 与 `offer` 互斥。 + +```json +{"action":"call.leg_add","action_id":"join-1","params":{"call_id":"session-1","leg_id":"0192f0c4a8e47b3c9d2e5f6a7b8c9d0e","offer":"v=0\r\n..."}} +{"type":"command_completed","action_id":"join-1","status":"success","data":{"leg_id":"0192f0c4a8e47b3c9d2e5f6a7b8c9d0e","answer":"v=0\r\n..."}} +``` + +与拨号腿不同,命令在应答就绪(ICE 候选收集完成,最长 10 秒)后才完成,且该腿立即处于已接通状态:发出带 `leg_id` 的 `call_answered`,不发 `call_ringing`。若 offer 含主叫已协商的编解码,应答优先使用它,桥接时音频直通;否则按编解码策略(未配置时为 G.711)协商并转码。ICE 使用媒体配置中的 `external_ip`、`webrtc_port_start`/`end` 与 `ice_servers`。该腿没有 SIP 对话:用 `call.bridge` 桥接,用 `call.leg_remove` 结束,通话结束时随之结束。`call.bridge` 在派发前校验腿 ID,只接受 `caller`、`callee`、`consult*` 或至少 32 位十六进制字符,因此请为该腿使用这样的 ID。 + **设置会话用户数据**(全量替换——旧对象整体丢弃): ```json diff --git a/src/call/domain/command.rs b/src/call/domain/command.rs index 9f904b8d2..8b2afc92f 100644 --- a/src/call/domain/command.rs +++ b/src/call/domain/command.rs @@ -762,6 +762,20 @@ pub enum CallCommand { purpose: Option, }, + /// Add a leg whose media peer answers a remote SDP offer (e.g. a WebRTC + /// client joining over RWI) instead of dialing SIP. The leg is connected + /// once the local answer is committed and is never bridged implicitly. + /// Internal request/reply command, never serialized. + #[serde(skip)] + LegAddOffer { + /// Optional leg ID (auto-generated if not provided) + leg_id: Option, + /// Remote SDP offer + offer: String, + /// The added leg and the local SDP answer, or why the leg was refused + reply: oneshot::Sender>, + }, + /// Remove a leg from the session LegRemove { /// Leg ID to remove diff --git a/src/proxy/proxy_call/sip_session/session.rs b/src/proxy/proxy_call/sip_session/session.rs index d6796d6fa..87d406664 100644 --- a/src/proxy/proxy_call/sip_session/session.rs +++ b/src/proxy/proxy_call/sip_session/session.rs @@ -457,6 +457,30 @@ impl SipSessionHandle { .map_err(|_| anyhow::anyhow!("session closed before answering recorder query"))? } + /// Add a leg answering `offer` and return its ID with the local SDP + /// answer. ICE gathering runs before the answer is returned, so this + /// waits up to ten seconds for the session to finish it. + pub async fn add_offer_leg( + &self, + leg_id: Option, + offer: String, + ) -> Result<(LegId, String), String> { + const OFFER_LEG_TIMEOUT: Duration = Duration::from_secs(10); + let (reply, response) = oneshot::channel(); + self.cmd_tx + .send(self.sourced_command(CallCommand::LegAddOffer { + leg_id, + offer, + reply, + })) + .await + .map_err(|_| "session closed".to_string())?; + tokio::time::timeout(OFFER_LEG_TIMEOUT, response) + .await + .map_err(|_| "timed out waiting for the leg answer".to_string())? + .map_err(|_| "session closed before answering the offer".to_string())? + } + /// Query the owning session and queue loops; no cached snapshot is consulted. pub async fn queue_dispatch_diagnostic( &self, @@ -11928,6 +11952,20 @@ impl SipSession { } } + CallCommand::LegAddOffer { + leg_id, + offer, + reply, + } => { + let added = self.handle_add_offer_leg(leg_id, &offer).await; + let result = match &added { + Ok((leg_id, _)) => CommandResult::success_with_leg(leg_id.clone()), + Err(error) => CommandResult::failure(error.to_string()), + }; + let _ = reply.send(added.map_err(|error| error.to_string())); + result + } + CallCommand::LegRemove { leg_id, reason } => { Self::ok_or_failure(self.handle_remove_leg(leg_id, reason).await) } @@ -13831,6 +13869,101 @@ impl SipSession { Ok(location) } + /// Add a leg whose media peer answers `offer` directly, with no SIP + /// dialog. The transport follows the offer (ICE + DTLS → WebRTC), so a + /// browser or WebRTC agent can join the call through its controller. The + /// leg is connected once the answer is committed; like `call.leg_add`, it + /// joins media only through an explicit bridge and ends through leg + /// removal or session hangup. + pub(super) async fn handle_add_offer_leg( + &mut self, + leg_id: Option, + offer: &str, + ) -> Result<(LegId, String)> { + let leg_id = leg_id.unwrap_or_else(|| LegId::new(format!("leg-{}", uuid::Uuid::new_v4()))); + if self + .legs + .get(&leg_id) + .is_some_and(|leg| leg.state != LegState::Ended) + { + return Err(anyhow!("Leg already exists: {}", leg_id)); + } + let transport = Self::sdp_transport_mode(offer); + let codecs = self.offer_leg_codecs(offer); + let video = self.video_caps_from_sdp(offer); + let cfg = self.build_leg_config(&leg_id, transport.clone(), codecs, video); + let peer = crate::media::create_leg( + leg_id.as_str(), + &cfg, + self.media.recording.capture_sender(), + crate::media::CaptureRoute::Deferred, + )?; + let answer = async { + peer.apply_remote_sdp(offer, rustrtc::SdpType::Offer) + .await?; + let mut answer = peer.prepare_answer().await?.to_sdp_string(); + if !self.video_relay_enabled() + && let Some(stripped) = MediaNegotiator::strip_video_from_sdp(&answer) + { + answer = stripped; + } + peer.commit_local_answer(&answer, rustrtc::SdpType::Answer) + .await + } + .await; + let answer = match answer { + Ok(answer) => answer, + Err(error) => { + peer.stop(); + return Err(error); + } + }; + peer.accept(); + info!(session_id = %self.id, %leg_id, transport = ?transport, "Adding offer-answered leg to session"); + self.legs.insert( + leg_id.clone(), + crate::call::domain::Leg::new(leg_id.clone()), + ); + self.update_leg_state(&leg_id, LegState::Initializing); + self.record_leg_event( + &leg_id.0, + crate::callrecord::LegTimelineEventType::Added, + None, + None, + ); + self.attach_media_leg(&leg_id, peer); + self.legs.set_transport(leg_id.clone(), transport); + self.legs.set_answer(leg_id.clone(), answer.clone()); + self.update_leg_state(&leg_id, LegState::Connected); + self.update_media_path().await; + Ok((leg_id, answer)) + } + + /// Audio codecs for an offer-answered leg: the caller's negotiated codec + /// when offered, so a later bridge passes audio through untranscoded; + /// otherwise the effective codec policy (G.711 when none is configured), + /// falling back to the offerer's own order when nothing intersects. + fn offer_leg_codecs(&self, offer: &str) -> Vec { + let offered = MediaNegotiator::build_codec_list_from_offer(offer, &[]); + let caller_codec = self + .media_leg(&LegId::from("caller")) + .and_then(|peer| peer.negotiated()) + .and_then(|profile| profile.audio.map(|audio| audio.codec)) + .filter(|codec| offered.iter().any(|offered| offered.codec == *codec)); + let policy = match caller_codec { + Some(codec) => vec![codec], + None => { + let configured = self.resolve_effective_codecs(); + if configured.is_empty() { + vec![CodecType::PCMU, CodecType::PCMA] + } else { + configured + } + } + }; + MediaNegotiator::build_codec_list_from_offer(offer, &policy) + } + /// Remove a leg from the session. pub(super) async fn handle_remove_leg( &mut self, diff --git a/src/proxy/proxy_call/sip_session/tests/mod.rs b/src/proxy/proxy_call/sip_session/tests/mod.rs index f0b8c52b2..f8bfde463 100644 --- a/src/proxy/proxy_call/sip_session/tests/mod.rs +++ b/src/proxy/proxy_call/sip_session/tests/mod.rs @@ -11499,12 +11499,14 @@ async fn rwi_manual_parallel_retry_and_leg_cleanup_body() { call_id: "rwi-manual".into(), target: format!("sip:alice@{addr}"), leg_id: None, + offer: None, }) .await }); // Acknowledge enqueueing before the session executes the dial. let RwiResult::LegAdded { leg_id: returned_id, + answer: None, } = timeout(Duration::from_secs(3), task) .await .unwrap() @@ -11860,6 +11862,235 @@ async fn rwi_manual_parallel_retry_and_leg_cleanup_body() { serving.await.unwrap(); } +#[test] +fn rwi_leg_add_offer_answers_webrtc_and_bridges_to_caller() { + // Same DEBUG-build frame depth as rwi_manual_parallel_retry_and_leg_cleanup. + std::thread::Builder::new() + .stack_size(64 * 1024 * 1024) + .spawn(|| { + tokio::runtime::Builder::new_current_thread() + .enable_all() + .build() + .expect("rwi-offer runtime") + .block_on(rwi_leg_add_offer_body()) + }) + .expect("spawn rwi-offer test thread") + .join() + .expect("rwi-offer test body panicked"); +} + +async fn rwi_leg_add_offer_body() { + use crate::call::{DialDirection, Dialplan, TransactionCookie}; + use crate::config::ProxyConfig; + use crate::media::TransportMode; + use crate::media::leg::{LegConfig, LegInner}; + use crate::media::negotiate::CodecInfo; + use crate::proxy::tests::common::{create_test_request, create_test_server_with_rwi_gateway}; + use crate::rwi::processor::{CommandResult as RwiResult, RwiCommandProcessor}; + use crate::rwi::{RwiCommandPayload, RwiGateway}; + use rsipstack::sip::Method; + use tokio::time::timeout; + + let gateway = Arc::new(parking_lot::RwLock::new(RwiGateway::new())); + let mut events = gateway.read().subscribe_events(); + let (server, _) = + create_test_server_with_rwi_gateway(ProxyConfig::default(), gateway.clone()).await; + let request = create_test_request(Method::Invite, "bob", None, "rustpbx.com", None); + let context = CallContext { + session_id: "rwi-offer".into(), + dialplan: Arc::new(Dialplan::new( + "rwi-offer".into(), + request, + DialDirection::Inbound, + )), + cookie: TransactionCookie::default(), + start_time: Instant::now(), + original_caller: "sip:bob@rustpbx.com".into(), + original_callee: "sip:alice@rustpbx.com".into(), + max_forwards: 70, + created_at: chrono::Utc::now().to_rfc3339(), + metadata: None, + }; + let cancel = CancellationToken::new(); + let _guard = cancel.clone().drop_guard(); + let (mut session, handle, mut commands) = + SipSession::new_uac(server.clone(), cancel.clone(), None, context, true); + server + .active_call_registry + .register_handle("rwi-offer".into(), handle); + let processor = Arc::new(RwiCommandProcessor::new( + server.active_call_registry.clone(), + gateway, + Arc::new(crate::call::runtime::ConferenceManager::new()), + )); + + // A connected PCMU caller, as a carrier leg would be. + let caller = LegInner::new("caller", &LegConfig::rtp_pcmu(), None).unwrap(); + let caller_remote = LegInner::new("caller-remote", &LegConfig::rtp_pcmu(), None).unwrap(); + let offer = caller_remote.create_offer().await.unwrap(); + let answer = caller.answer(&offer).await.unwrap(); + caller_remote + .apply_remote_sdp(&answer, rustrtc::SdpType::Answer) + .await + .unwrap(); + caller.accept(); + caller_remote.accept(); + session + .legs + .set_media_leg(&LegId::from("caller"), caller.clone()); + session.update_leg_state(&LegId::from("caller"), LegState::Connected); + + // A WebRTC client that prefers Opus, as browsers do. + let client = LegInner::new( + "client", + &LegConfig { + transport: TransportMode::WebRtc, + codecs: vec![ + CodecInfo { + payload_type: 111, + codec: CodecType::Opus, + clock_rate: 48000, + channels: 2, + fmtp: None, + }, + CodecInfo { + payload_type: 0, + codec: CodecType::PCMU, + clock_rate: 8000, + channels: 1, + fmtp: None, + }, + ], + ..LegConfig::rtp_pcmu() + }, + None, + ) + .unwrap(); + let client_offer = client.create_offer().await.unwrap(); + + // A target and an offer are exclusive. + let both = processor + .process_command(RwiCommandPayload::LegAdd { + call_id: "rwi-offer".into(), + target: "sip:alice@rustpbx.com".into(), + leg_id: None, + offer: Some(client_offer.clone()), + }) + .await; + assert!(both.is_err(), "{both:?}"); + + let task = { + let processor = processor.clone(); + let offer = client_offer.clone(); + tokio::spawn(async move { + processor + .process_command(RwiCommandPayload::LegAdd { + call_id: "rwi-offer".into(), + target: String::new(), + leg_id: Some("agent".into()), + offer: Some(offer), + }) + .await + }) + }; + // The processor waits for the session to answer the offer. + let command = timeout(Duration::from_secs(3), commands.recv()) + .await + .unwrap() + .unwrap(); + assert!( + matches!(&command, CallCommand::LegAddOffer { leg_id: Some(id), .. } if id.as_str() == "agent") + ); + assert!(session.execute_command(command, None).await.success); + let RwiResult::LegAdded { + leg_id, + answer: Some(answer), + } = timeout(Duration::from_secs(10), task) + .await + .unwrap() + .unwrap() + .unwrap() + else { + panic!("expected leg ID and answer in result"); + }; + assert_eq!(leg_id, "agent"); + assert!( + answer.contains("a=ice-ufrag") && answer.contains("a=fingerprint"), + "{answer}" + ); + let audio = answer + .lines() + .find(|line| line.starts_with("m=audio")) + .expect("audio m-line"); + assert!(audio.contains("UDP/TLS/RTP/SAVPF"), "{audio}"); + assert_eq!( + audio.split_whitespace().nth(3), + Some("0"), + "the caller's PCMU is answered first so the bridge passes audio through: {answer}" + ); + assert!(!answer.to_lowercase().contains("opus"), "{answer}"); + client + .apply_remote_sdp(&answer, rustrtc::SdpType::Answer) + .await + .unwrap(); + + let agent = LegId::from("agent"); + assert_eq!( + session.legs.get(&agent).map(|leg| leg.state), + Some(LegState::Connected) + ); + let mut answered = false; + while let Ok(entry) = events.try_recv() { + if entry.event.event_type == "call_answered" && entry.event.payload["leg_id"] == "agent" { + answered = true; + } + } + assert!(answered, "the added leg reports call_answered"); + + // A duplicate ID is refused while the leg is live. + let (reply, refused) = tokio::sync::oneshot::channel(); + let duplicate = session + .execute_command( + CallCommand::LegAddOffer { + leg_id: Some(agent.clone()), + offer: client_offer, + reply, + }, + None, + ) + .await; + assert!(!duplicate.success); + assert!(refused.await.unwrap().is_err()); + + let bridged = session + .execute_command( + CallCommand::Bridge { + leg_a: LegId::from("caller"), + leg_b: agent.clone(), + mode: crate::call::domain::P2PMode::Audio, + }, + None, + ) + .await; + assert!(bridged.success, "{bridged:?}"); + assert!(session.bridge.contains_leg(&agent)); + + let removed = session + .execute_command( + CallCommand::LegRemove { + leg_id: agent.clone(), + reason: None, + }, + None, + ) + .await; + assert!(removed.success, "{removed:?}"); + assert!(session.legs.get(&agent).is_none()); + caller_remote.stop(); + client.stop(); + session.cleanup().await; +} + #[test] fn added_legs_require_explicit_bridge_and_allow_removed_ids() { // Same DEBUG-build frame depth as diff --git a/src/rwi/handler.rs b/src/rwi/handler.rs index 80a93482a..0e31d6d9a 100644 --- a/src/rwi/handler.rs +++ b/src/rwi/handler.rs @@ -401,9 +401,12 @@ fn build_command_result_event( CommandResult::Success => { event["status"] = serde_json::json!("success"); } - CommandResult::LegAdded { leg_id } => { + CommandResult::LegAdded { leg_id, answer } => { event["status"] = serde_json::json!("success"); - event["data"] = serde_json::json!({ "leg_id": leg_id }); + event["data"] = match answer { + Some(answer) => serde_json::json!({ "leg_id": leg_id, "answer": answer }), + None => serde_json::json!({ "leg_id": leg_id }), + }; } CommandResult::ListCalls(calls) => { event["status"] = serde_json::json!("success"); diff --git a/src/rwi/processor.rs b/src/rwi/processor.rs index d3403b9bc..4deb76399 100644 --- a/src/rwi/processor.rs +++ b/src/rwi/processor.rs @@ -646,6 +646,20 @@ impl RwiCommandProcessor { call_id, target, leg_id, + offer: Some(offer), + } => { + if !target.is_empty() { + return Err(CommandError::CommandFailed( + "call.leg_add takes either target or offer, not both".to_string(), + )); + } + return self.leg_add_offer(call_id, leg_id.as_deref(), offer).await; + } + RwiCommandPayload::LegAdd { + call_id, + target, + leg_id, + offer: None, } => { return self.leg_add(call_id, target, leg_id.as_deref(), None).await; } @@ -2400,7 +2414,28 @@ impl RwiCommandProcessor { leg_id: Some(LegId::new(&leg_id)), headers: Vec::new(), purpose, }).map_err(|error| CommandError::CommandFailed(error.to_string()))?; - Ok(CommandResult::LegAdded { leg_id }) + Ok(CommandResult::LegAdded { + leg_id, + answer: None, + }) + } + + /// Add a leg answering `offer`; completes once the session committed the answer. + async fn leg_add_offer( + &self, + call_id: &str, + leg_id: Option<&str>, + offer: &str, + ) -> Result { + let handle = self.get_handle(call_id).await?; + let (leg_id, answer) = handle + .add_offer_leg(leg_id.map(LegId::new), offer.to_string()) + .await + .map_err(CommandError::CommandFailed)?; + Ok(CommandResult::LegAdded { + leg_id: leg_id.to_string(), + answer: Some(answer), + }) } async fn leg_remove(&self, call_id: &str, leg_id: &str) -> Result { @@ -3710,7 +3745,11 @@ impl RwiCommandProcessor { #[derive(Debug, serde::Serialize, serde::Deserialize)] pub enum CommandResult { /// Dial request queued; progress is reported by leg lifecycle events. - LegAdded { leg_id: String }, + /// `answer` carries the local SDP answer of a leg added from an offer. + LegAdded { + leg_id: String, + answer: Option, + }, Success, ListCalls(Vec), CallFound { diff --git a/src/rwi/session.rs b/src/rwi/session.rs index 5572e8cf2..2547be822 100644 --- a/src/rwi/session.rs +++ b/src/rwi/session.rs @@ -330,6 +330,9 @@ pub enum RwiCommandPayload { #[serde(default)] target: String, leg_id: Option, + /// SDP offer answered by a new media leg instead of dialing `target` + #[serde(default)] + offer: Option, }, #[serde(rename = "call.leg_remove")] LegRemove {