freeswitch_sofia_trace_parser/
lib.rs

1//! Streaming parser for FreeSWITCH `mod_sofia` SIP trace dump files.
2//!
3//! FreeSWITCH logs SIP traffic to dump files at
4//! `/var/log/freeswitch/sip_traces/{profile}/{profile}.dump`, rotated as
5//! `.dump.1.xz`, `.dump.2.xz`, etc. This library provides a multi-level
6//! streaming parser that processes these files with constant memory.
7//!
8//! # Architecture
9//!
10//! Three parsing levels, each wrapping the previous:
11//!
12//! - **Level 1** ([`FrameIterator`]) — splits raw bytes on `\x0B\n` boundaries,
13//!   parses frame headers (direction, byte count, transport, address, timestamp).
14//! - **Level 2** ([`MessageIterator`]) — reassembles TCP segments by connection,
15//!   splits aggregated messages by Content-Length, passes UDP frames through.
16//! - **Level 3** ([`ParsedMessageIterator`]) — parses SIP request/status lines,
17//!   headers, and bodies. Supports multipart MIME splitting and JSON body unescaping.
18//!
19//! Every level accepts [`std::io::Read`], so they compose with files, pipes,
20//! `xzcat` subprocesses, [`std::io::Read::chain`] for file concatenation, and
21//! [`GrepFilter`] for grep-piped input.
22//!
23//! # Quick Start
24//!
25//! ```no_run
26//! use std::fs::File;
27//! use freeswitch_sofia_trace_parser::ParsedMessageIterator;
28//!
29//! let file = File::open("profile.dump").unwrap();
30//! for result in ParsedMessageIterator::new(file) {
31//!     let msg = result.unwrap();
32//!     println!("{} {} {} call-id={}",
33//!         msg.timestamp, msg.direction, msg.message_type,
34//!         msg.call_id().unwrap_or("-"));
35//! }
36//! ```
37//!
38//! # Input Coverage Tracking
39//!
40//! Every byte in the input is either parsed into a frame or classified with a
41//! [`SkipReason`]. Access parse statistics via the `stats()` / `parse_stats()`
42//! methods on each iterator. See [`ParseStats`] and [`SkipTracking`] for details.
43
44#![cfg_attr(
45    not(test),
46    deny(
47        clippy::unwrap_used,
48        clippy::expect_used,
49        clippy::panic,
50        clippy::unreachable
51    )
52)]
53
54mod finders;
55mod startline;
56
57/// Level 1: frame boundary detection and header parsing.
58pub mod frame;
59
60/// `Read` adapter that strips `grep -C` separator lines from piped input.
61pub mod grep;
62
63/// Level 2: TCP reassembly and Content-Length-based message splitting.
64pub mod message;
65
66/// On-demand pcap export: synthesize libpcap packets from parsed frames/messages.
67#[cfg(feature = "pcap")]
68pub mod pcap;
69
70/// Level 3: SIP message parsing, multipart MIME, and JSON body handling.
71pub mod sip;
72
73/// Core data types shared across all parsing levels.
74pub mod types;
75
76pub use frame::{FrameIterator, ParseError};
77pub use grep::GrepFilter;
78pub use message::MessageIterator;
79#[cfg(feature = "pcap")]
80pub use pcap::{PcapConfig, PcapError, PcapLayer, PcapWriter};
81pub use sip::{is_json_content_type, parse_sipfrag, ParsedMessageIterator};
82pub use types::{
83    Direction, Frame, FrameMeta, Headers, MimePart, ParseStats, ParsedSipMessage, SipFragment,
84    SipMessage, SipMessageType, SkipReason, SkipTracking, StaleClock, Timestamp, Transport,
85    UnknownKeyword, UnparsedRegion,
86};
freeswitch_sofia_trace_parser/lib.rs

freeswitch_sofia_trace_parser/
lib.rs
