Skip to main content

active_call/sipflow/
mod.rs

1//! In-process SIP signaling capture ("sipflow").
2//!
3//! Every SIP message that crosses the endpoint (both directions, including
4//! the dialogs created for REFER transfers) is recorded into a bounded
5//! in-memory store keyed by Call-ID. When a call ends, the callrecord upload
6//! hook ([`SipFlowUploadHook`]) merges the flows of all dialogs belonging to
7//! the session (primary leg, bridge legs, REFER transfer legs) into a single
8//! time-sorted JSONL document and uploads it to S3 or HTTP — the same wire
9//! format rustpbx exports, plus a per-line `callId` so merged legs stay
10//! identifiable.
11//!
12//! This is deliberately a lightweight store (no SQLite, no collector): it
13//! only needs to survive until the callrecord is saved at hangup. Bounds:
14//! `max_calls` (LRU over Call-IDs) and `max_items_per_call` (per-dialog
15//! cap); both overflow paths count dropped messages instead of blocking the
16//! SIP endpoint.
17//!
18//! ```toml
19//! [sipflow]
20//! max_calls = 4096
21//! max_items_per_call = 8192
22//!
23//! [sipflow.upload]
24//! type = "s3"
25//! vendor = "aliyun"
26//! bucket = "..."
27//! ```
28
29mod upload;
30
31pub use upload::SipFlowUploadHook;
32
33use lru::LruCache;
34use rsipstack::rsip::prelude::HeadersExt;
35use rsipstack::rsip::SipMessage;
36use rsipstack::transaction::endpoint::MessageInspector;
37use rsipstack::transport::SipAddr;
38use serde::Serialize;
39use std::collections::{HashMap, VecDeque};
40use std::num::NonZeroUsize;
41use std::sync::atomic::{AtomicU64, Ordering};
42use std::sync::{Arc, Mutex};
43
44/// Default bound on tracked Call-IDs (LRU).
45pub const DEFAULT_MAX_CALLS: usize = 4096;
46/// Default bound on captured messages per Call-ID.
47pub const DEFAULT_MAX_ITEMS_PER_CALL: usize = 8192;
48/// Upper bound on the session → Call-IDs association table.
49pub const DEFAULT_MAX_SESSIONS: usize = 10_000;
50
51/// One captured SIP message. The serialized field names match rustpbx's
52/// sipflow JSONL export (`timestamp`/`seq`/`leg`/`msgType`/`srcAddr`/
53/// `dstAddr`/`payload`); `callId` is an active-call extension so a merged
54/// multi-leg export stays attributable per dialog.
55#[derive(Debug, Clone, Serialize)]
56pub struct SipFlowItem {
57    /// Unix timestamp in microseconds.
58    pub timestamp: u64,
59    /// Capture sequence within one Call-ID.
60    pub seq: u64,
61    /// RTP leg marker in rustpbx exports; always `null` for SIP signaling.
62    pub leg: Option<i32>,
63    /// Always `"Sip"`.
64    pub msg_type: &'static str,
65    /// SIP Call-ID this message belongs to.
66    pub call_id: String,
67    pub src_addr: String,
68    pub dst_addr: String,
69    /// Full raw SIP message text.
70    pub payload: String,
71}
72
73/// `[sipflow]` — in-process SIP signaling capture.
74#[derive(Debug, Clone, serde::Deserialize, serde::Serialize, Default)]
75pub struct SipFlowConfig {
76    /// Set to `false` to disable capture even though the section exists.
77    #[serde(default, skip_serializing_if = "Option::is_none")]
78    pub enabled: Option<bool>,
79    /// LRU bound on tracked Call-IDs (default 4096).
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub max_calls: Option<usize>,
82    /// Per-Call-ID message cap; further messages are dropped and counted
83    /// (default 8192).
84    #[serde(default, skip_serializing_if = "Option::is_none")]
85    pub max_items_per_call: Option<usize>,
86    /// Post-call JSONL upload. Without it the flows are captured and
87    /// discarded at hangup.
88    #[serde(default, skip_serializing_if = "Option::is_none")]
89    pub upload: Option<SipFlowUploadConfig>,
90}
91
92impl SipFlowConfig {
93    /// Capture is on when the section exists, unless `enabled = false`.
94    pub fn enabled(&self) -> bool {
95        self.enabled.unwrap_or(true)
96    }
97
98    pub fn max_calls(&self) -> usize {
99        self.max_calls.unwrap_or(DEFAULT_MAX_CALLS).max(1)
100    }
101
102    pub fn max_items_per_call(&self) -> usize {
103        self.max_items_per_call
104            .unwrap_or(DEFAULT_MAX_ITEMS_PER_CALL)
105            .max(1)
106    }
107}
108
109/// `[sipflow.upload]` — where the per-session signaling JSONL goes after the
110/// call ends. S3 mirrors `[callrecord]`'s S3 flavour; HTTP posts the JSONL
111/// as one multipart file part.
112#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
113#[serde(tag = "type", rename_all = "snake_case")]
114pub enum SipFlowUploadConfig {
115    S3 {
116        vendor: crate::config::S3Vendor,
117        bucket: String,
118        region: String,
119        access_key: String,
120        secret_key: String,
121        endpoint: String,
122        /// Object key prefix (no leading/trailing slashes); the key is
123        /// `{root}/{YYYYMMDD}/{session_id}.jsonl`.
124        #[serde(default)]
125        root: String,
126    },
127    Http {
128        url: String,
129        #[serde(default, skip_serializing_if = "Option::is_none")]
130        headers: Option<HashMap<String, String>>,
131        /// Multipart field name (default `signaling`).
132        #[serde(default, skip_serializing_if = "Option::is_none")]
133        file_field: Option<String>,
134        /// Uploaded file name (default `{session_id}.jsonl`).
135        #[serde(default, skip_serializing_if = "Option::is_none")]
136        file_name: Option<String>,
137    },
138}
139
140struct CallFlow {
141    items: Vec<SipFlowItem>,
142    next_seq: u64,
143    dropped: u64,
144}
145
146/// session_id -> the SIP Call-IDs of every dialog seen for it (primary leg,
147/// bridge legs, REFER transfer legs), insertion-ordered and bounded.
148#[derive(Default)]
149struct SessionRegistry {
150    map: HashMap<String, Vec<String>>,
151    order: VecDeque<String>,
152}
153
154impl SessionRegistry {
155    fn associate(&mut self, session_id: &str, call_id: &str, capacity: usize) {
156        if session_id.is_empty() || call_id.is_empty() {
157            return;
158        }
159        if let Some(entry) = self.map.get_mut(session_id) {
160            if !entry.iter().any(|id| id == call_id) {
161                entry.push(call_id.to_string());
162            }
163            return;
164        }
165        // Bound the table: drop the oldest session when over capacity.
166        while self.map.len() >= capacity {
167            match self.order.pop_front() {
168                Some(oldest) => {
169                    self.map.remove(&oldest);
170                }
171                None => break,
172            }
173        }
174        self.map
175            .insert(session_id.to_string(), vec![call_id.to_string()]);
176        self.order.push_back(session_id.to_string());
177    }
178
179    fn evict(&mut self, session_id: &str) {
180        self.map.remove(session_id);
181        if let Some(pos) = self.order.iter().position(|id| id == session_id) {
182            self.order.remove(pos);
183        }
184    }
185}
186
187struct SipFlowInner {
188    max_items: usize,
189    local_addr: String,
190    flows: Mutex<LruCache<String, CallFlow>>,
191    sessions: Mutex<(SessionRegistry, usize)>,
192    dropped: AtomicU64,
193    next: Mutex<Option<Box<dyn MessageInspector>>>,
194}
195
196/// Cloneable handle to the signaling recorder. Implements
197/// [`MessageInspector`], recording every message and passing it through to
198/// the next inspector in the chain unmodified.
199#[derive(Clone)]
200pub struct SipFlow {
201    inner: Arc<SipFlowInner>,
202}
203
204impl SipFlow {
205    pub fn new(
206        config: SipFlowConfig,
207        local_addr: String,
208        next: Option<Box<dyn MessageInspector>>,
209    ) -> Self {
210        let max_calls = config.max_calls();
211        let max_items = config.max_items_per_call();
212        Self {
213            inner: Arc::new(SipFlowInner {
214                max_items,
215                local_addr,
216                flows: Mutex::new(LruCache::new(
217                    NonZeroUsize::new(max_calls).unwrap_or(NonZeroUsize::MIN),
218                )),
219                sessions: Mutex::new((
220                    SessionRegistry::default(),
221                    DEFAULT_MAX_SESSIONS.max(max_calls),
222                )),
223                dropped: AtomicU64::new(0),
224                next: Mutex::new(next),
225            }),
226        }
227    }
228
229    /// The local address recorded as the near end of each flow.
230    pub fn local_addr(&self) -> &str {
231        &self.inner.local_addr
232    }
233
234    /// Chains the next inspector behind this recorder (used by
235    /// `AppStateBuilder` when this recorder is injected instead of built
236    /// from config, where the rest of the inspector chain only exists at
237    /// build time).
238    pub fn set_next(&self, next: Option<Box<dyn MessageInspector>>) {
239        if let Ok(mut guard) = self.inner.next.lock() {
240            *guard = next;
241        }
242    }
243
244    /// Total messages dropped due to the per-Call-ID cap.
245    pub fn dropped_count(&self) -> u64 {
246        self.inner.dropped.load(Ordering::Relaxed)
247    }
248
249    /// Number of Call-IDs currently tracked.
250    pub fn tracked_calls(&self) -> usize {
251        self.inner.flows.lock().map(|f| f.len()).unwrap_or(0)
252    }
253
254    /// Associates a SIP Call-ID with a session so the callrecord hook can
255    /// merge all of a session's dialogs (REFER transfers included) into one
256    /// JSONL. Called at dialog creation points: incoming INVITE accept and
257    /// every outgoing INVITE (bridge leg, transfer leg, dial-out).
258    pub fn associate(&self, session_id: &str, call_id: &str) {
259        if let Ok(mut guard) = self.inner.sessions.lock() {
260            let (registry, capacity) = &mut *guard;
261            registry.associate(session_id, call_id, *capacity);
262        }
263    }
264
265    /// All Call-IDs associated with a session (may be empty when capture is
266    /// disabled or the session never had a SIP dialog).
267    pub fn get_session_call_ids(&self, session_id: &str) -> Vec<String> {
268        match self.inner.sessions.lock() {
269            Ok(guard) => {
270                let (registry, _) = &*guard;
271                registry.map.get(session_id).cloned().unwrap_or_default()
272            }
273            Err(_) => Vec::new(),
274        }
275    }
276
277    /// Captured items for one Call-ID within `[start_us, end_us]` (unix
278    /// microseconds, inclusive bounds like the time window slack).
279    pub fn query_flow(&self, call_id: &str, start_us: u64, end_us: u64) -> Vec<SipFlowItem> {
280        match self.inner.flows.lock() {
281            Ok(flows) => match flows.peek(call_id) {
282                Some(flow) => flow
283                    .items
284                    .iter()
285                    .filter(|item| item.timestamp >= start_us && item.timestamp <= end_us)
286                    .cloned()
287                    .collect(),
288                None => Vec::new(),
289            },
290            Err(_) => Vec::new(),
291        }
292    }
293
294    /// Drops the flows and associations of a finished session (called by the
295    /// upload hook after export/upload so memory does not grow unbounded).
296    pub fn evict(&self, session_id: &str, call_ids: &[String]) {
297        if let Ok(mut flows) = self.inner.flows.lock() {
298            for call_id in call_ids {
299                flows.pop(call_id);
300            }
301        }
302        if let Ok(mut guard) = self.inner.sessions.lock() {
303            let (registry, _) = &mut *guard;
304            registry.evict(session_id);
305        }
306    }
307
308    /// Serializes items as JSONL (one JSON object per line), the wire format
309    /// uploaded at call end. Items are expected pre-sorted by
310    /// `(timestamp, seq)`.
311    pub fn export_jsonl(items: &[SipFlowItem]) -> String {
312        let mut out = String::new();
313        for item in items {
314            if let Ok(line) = serde_json::to_string(item) {
315                out.push_str(&line);
316                out.push('\n');
317            }
318        }
319        out
320    }
321
322    fn record_sip(&self, is_outgoing: bool, msg: &SipMessage, addr: Option<&SipAddr>) {
323        let Ok(call_id_header) = msg.call_id_header() else {
324            return;
325        };
326        let call_id = call_id_header.value().trim().to_string();
327        if call_id.is_empty() {
328            return;
329        }
330        let timestamp = chrono::Utc::now().timestamp_micros().max(0) as u64;
331        let payload = msg.to_string();
332        let remote = addr.map(sip_addr_to_string).unwrap_or_default();
333        let local = self.inner.local_addr.clone();
334        let (src_addr, dst_addr) = if is_outgoing {
335            let dst = if remote.is_empty() {
336                via_sent_by(msg).unwrap_or_default()
337            } else {
338                remote
339            };
340            (local, dst)
341        } else {
342            let src = if remote.is_empty() {
343                via_sent_by(msg).unwrap_or_default()
344            } else {
345                remote
346            };
347            (src, local)
348        };
349
350        let mut overflow = false;
351        if let Ok(mut flows) = self.inner.flows.lock() {
352            if !flows.contains(&call_id) {
353                flows.put(
354                    call_id.clone(),
355                    CallFlow {
356                        items: Vec::new(),
357                        next_seq: 0,
358                        dropped: 0,
359                    },
360                );
361            }
362            if let Some(flow) = flows.get_mut(&call_id) {
363                if flow.items.len() >= self.inner.max_items {
364                    flow.dropped += 1;
365                    overflow = true;
366                } else {
367                    let seq = flow.next_seq;
368                    flow.next_seq += 1;
369                    flow.items.push(SipFlowItem {
370                        timestamp,
371                        seq,
372                        leg: None,
373                        msg_type: "Sip",
374                        call_id,
375                        src_addr,
376                        dst_addr,
377                        payload,
378                    });
379                }
380            }
381        }
382        if overflow {
383            let previous = self.inner.dropped.fetch_add(1, Ordering::Relaxed);
384            if previous % 1000 == 0 {
385                tracing::warn!(
386                    total_dropped = previous + 1,
387                    "sipflow per-call message cap reached, dropping messages"
388                );
389            }
390        }
391    }
392}
393
394impl MessageInspector for SipFlow {
395    fn before_send(&self, msg: SipMessage, dest: Option<&SipAddr>) -> SipMessage {
396        self.record_sip(true, &msg, dest);
397        let next = self.inner.next.lock().ok();
398        match next.as_deref() {
399            Some(Some(n)) => n.before_send(msg, dest),
400            _ => msg,
401        }
402    }
403
404    fn after_received(&self, msg: SipMessage, from: Option<&SipAddr>) -> SipMessage {
405        self.record_sip(false, &msg, from);
406        let next = self.inner.next.lock().ok();
407        match next.as_deref() {
408            Some(Some(n)) => n.after_received(msg, from),
409            _ => msg,
410        }
411    }
412}
413
414fn sip_addr_to_string(addr: &SipAddr) -> String {
415    addr.addr.to_string()
416}
417
418/// Falls back to the top Via sent-by ("host:port") when the transport did
419/// not provide the peer address.
420fn via_sent_by(msg: &SipMessage) -> Option<String> {
421    use rsipstack::rsip::ToTypedHeader;
422    match msg {
423        SipMessage::Request(req) => req
424            .via_header()
425            .ok()
426            .and_then(|v| v.typed().ok())
427            .map(|v| v.sent_by().to_string()),
428        SipMessage::Response(resp) => resp
429            .via_header()
430            .ok()
431            .and_then(|v| v.typed().ok())
432            .map(|v| v.sent_by().to_string()),
433    }
434}
435
436#[cfg(test)]
437mod tests {
438    use super::*;
439    use rsipstack::rsip::{Header, Headers, Method, Request, Response, Uri, Version};
440    use std::sync::atomic::AtomicUsize;
441
442    fn invite_request(call_id: &str) -> SipMessage {
443        SipMessage::Request(Request {
444            method: Method::Invite,
445            uri: Uri::try_from("sip:bot@example.com").unwrap(),
446            headers: Headers::from(vec![
447                Header::CallId(call_id.into()),
448                Header::CSeq("1 INVITE".into()),
449                Header::Via("SIP/2.0/UDP 10.0.0.5:5060;branch=z9hG4bK-test".into()),
450            ]),
451            version: Version::V2,
452            body: vec![],
453        })
454    }
455
456    fn ok_response(call_id: &str) -> SipMessage {
457        SipMessage::Response(Response {
458            headers: Headers::from(vec![
459                Header::CallId(call_id.into()),
460                Header::CSeq("1 INVITE".into()),
461                Header::Via("SIP/2.0/UDP 10.0.0.5:5060;branch=z9hG4bK-test".into()),
462            ]),
463            ..Default::default()
464        })
465    }
466
467    fn test_flow(max_calls: usize, max_items: usize) -> SipFlow {
468        SipFlow::new(
469            SipFlowConfig {
470                max_calls: Some(max_calls),
471                max_items_per_call: Some(max_items),
472                ..Default::default()
473            },
474            "192.168.1.10:5060".to_string(),
475            None,
476        )
477    }
478
479    fn udp_addr(ip: &str) -> SipAddr {
480        SipAddr {
481            addr: rsipstack::rsip::HostWithPort::try_from(format!("{ip}:5060")).unwrap(),
482            r#type: Some(rsipstack::sip::Transport::Udp),
483        }
484    }
485
486    #[test]
487    fn records_both_directions_with_addrs() {
488        let flow = test_flow(16, 100);
489
490        flow.record_sip(false, &invite_request("c1"), Some(&udp_addr("10.0.0.5")));
491        flow.record_sip(true, &ok_response("c1"), Some(&udp_addr("10.0.0.5")));
492
493        let items = flow.query_flow("c1", 0, u64::MAX);
494        assert_eq!(items.len(), 2);
495        // Incoming: remote is src, local is dst.
496        assert_eq!(items[0].src_addr, "10.0.0.5:5060");
497        assert_eq!(items[0].dst_addr, "192.168.1.10:5060");
498        // Outgoing: the other way around.
499        assert_eq!(items[1].src_addr, "192.168.1.10:5060");
500        assert_eq!(items[1].dst_addr, "10.0.0.5:5060");
501        assert_eq!(items[0].call_id, "c1");
502        assert_eq!(items[0].msg_type, "Sip");
503        assert_eq!(items[0].leg, None);
504        assert_eq!(items[0].seq, 0);
505        assert_eq!(items[1].seq, 1);
506        assert!(items[0].payload.starts_with("INVITE "));
507        assert!(items[0].timestamp > 0);
508    }
509
510    #[test]
511    fn falls_back_to_via_sent_by_without_transport_addr() {
512        let flow = test_flow(16, 100);
513        flow.record_sip(false, &invite_request("c1"), None);
514        let items = flow.query_flow("c1", 0, u64::MAX);
515        assert_eq!(items.len(), 1);
516        assert_eq!(items[0].src_addr, "10.0.0.5:5060");
517    }
518
519    #[test]
520    fn per_call_cap_drops_and_counts() {
521        let flow = test_flow(16, 3);
522        for _ in 0..5 {
523            flow.record_sip(true, &ok_response("c1"), None);
524        }
525        let items = flow.query_flow("c1", 0, u64::MAX);
526        assert_eq!(items.len(), 3);
527        assert_eq!(flow.dropped_count(), 2);
528    }
529
530    #[test]
531    fn lru_evicts_inactive_calls() {
532        let flow = test_flow(2, 100);
533        flow.record_sip(true, &ok_response("c1"), None);
534        flow.record_sip(true, &ok_response("c2"), None);
535        flow.record_sip(true, &ok_response("c1"), None); // promote c1
536        flow.record_sip(true, &ok_response("c3"), None); // evicts c2
537
538        assert_eq!(flow.tracked_calls(), 2);
539        assert!(flow.query_flow("c2", 0, u64::MAX).is_empty());
540        assert_eq!(flow.query_flow("c1", 0, u64::MAX).len(), 2);
541        assert_eq!(flow.query_flow("c3", 0, u64::MAX).len(), 1);
542    }
543
544    #[test]
545    fn query_filters_by_time_window() {
546        let flow = test_flow(16, 100);
547        flow.record_sip(true, &ok_response("c1"), None);
548        let items = flow.query_flow("c1", 0, u64::MAX);
549        let ts = items[0].timestamp;
550        assert_eq!(flow.query_flow("c1", ts, ts).len(), 1);
551        assert_eq!(flow.query_flow("c1", ts + 1, u64::MAX).len(), 0);
552        assert_eq!(flow.query_flow("unknown", 0, u64::MAX).len(), 0);
553    }
554
555    #[test]
556    fn session_association_and_eviction() {
557        let flow = test_flow(16, 100);
558        flow.associate("s.abc", "c1");
559        flow.associate("s.abc", "c2");
560        flow.associate("s.abc", "c1"); // dedup
561        flow.associate("ref-1-s.abc", "c2"); // refer leg aliases the same dialog
562
563        let mut ids = flow.get_session_call_ids("s.abc");
564        ids.sort();
565        assert_eq!(ids, vec!["c1".to_string(), "c2".to_string()]);
566        assert_eq!(flow.get_session_call_ids("s.nope"), Vec::<String>::new());
567
568        flow.evict("s.abc", &["c1".to_string(), "c2".to_string()]);
569        assert!(flow.get_session_call_ids("s.abc").is_empty());
570        assert_eq!(flow.tracked_calls(), 0);
571    }
572
573    #[test]
574    fn jsonl_export_matches_rustpbx_shape() {
575        let flow = test_flow(16, 100);
576        flow.record_sip(false, &invite_request("c1"), Some(&udp_addr("10.0.0.5")));
577        let items = flow.query_flow("c1", 0, u64::MAX);
578        let jsonl = SipFlow::export_jsonl(&items);
579        let lines: Vec<&str> = jsonl.lines().collect();
580        assert_eq!(lines.len(), 1);
581        let obj: serde_json::Value = serde_json::from_str(lines[0]).unwrap();
582        for key in [
583            "timestamp",
584            "seq",
585            "leg",
586            "msg_type",
587            "call_id",
588            "src_addr",
589            "dst_addr",
590            "payload",
591        ] {
592            assert!(obj.get(key).is_some(), "missing key {key}");
593        }
594        assert_eq!(obj["msg_type"], "Sip");
595        assert!(obj["leg"].is_null());
596    }
597
598    #[test]
599    fn chained_inspector_sees_unmodified_message() {
600        struct CountingInspector {
601            seen: AtomicUsize,
602        }
603        impl MessageInspector for CountingInspector {
604            fn before_send(&self, msg: SipMessage, _dest: Option<&SipAddr>) -> SipMessage {
605                self.seen.fetch_add(1, Ordering::Relaxed);
606                msg
607            }
608            fn after_received(&self, msg: SipMessage, _from: Option<&SipAddr>) -> SipMessage {
609                self.seen.fetch_add(1, Ordering::Relaxed);
610                msg
611            }
612        }
613
614        let counter = Arc::new(CountingInspector {
615            seen: AtomicUsize::new(0),
616        });
617        struct CountingHolder(Arc<CountingInspector>);
618        impl MessageInspector for CountingHolder {
619            fn before_send(&self, msg: SipMessage, dest: Option<&SipAddr>) -> SipMessage {
620                self.0.before_send(msg, dest)
621            }
622            fn after_received(&self, msg: SipMessage, from: Option<&SipAddr>) -> SipMessage {
623                self.0.after_received(msg, from)
624            }
625        }
626
627        let flow = SipFlow::new(
628            SipFlowConfig::default(),
629            "192.168.1.10:5060".to_string(),
630            None,
631        );
632        flow.set_next(Some(Box::new(CountingHolder(counter.clone()))));
633
634        let dest = udp_addr("10.0.0.5");
635        let out = flow.before_send(ok_response("c1"), Some(&dest));
636        let inbound = flow.after_received(invite_request("c1"), Some(&dest));
637        assert_eq!(counter.seen.load(Ordering::Relaxed), 2);
638        // Messages pass through byte-identical.
639        assert_eq!(out.to_string(), ok_response("c1").to_string());
640        assert_eq!(inbound.to_string(), invite_request("c1").to_string());
641        // And were recorded.
642        assert_eq!(flow.query_flow("c1", 0, u64::MAX).len(), 2);
643    }
644}