diff --git a/docs/rwi.md b/docs/rwi.md index d3b153d6..e79c6607 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 070f0518..998c6e1c 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 9f904b8d..8b2afc92 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 d6796d6f..87d40666 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 f0b8c52b..f8bfde46 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 80a93482..0e31d6d9 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 d3403b9b..4deb7639 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 5572e8cf..2547be82 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 {