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/// Level 1: frame boundary detection and header parsing.
45pub mod frame;
46
47/// `Read` adapter that strips `grep -C` separator lines from piped input.
48pub mod grep;
49
50/// Level 2: TCP reassembly and Content-Length-based message splitting.
51pub mod message;
52
53/// Level 3: SIP message parsing, multipart MIME, and JSON body handling.
54pub mod sip;
55
56/// Core data types shared across all parsing levels.
57pub mod types;
58
59pub use frame::{FrameIterator, ParseError};
60pub use grep::GrepFilter;
61pub use message::MessageIterator;
62pub use sip::ParsedMessageIterator;
63pub use types::*;
freeswitch_sofia_trace_parser/lib.rs

freeswitch_sofia_trace_parser/
lib.rs
