sip_header/
warning.rs

1//! SIP Warning header parser (RFC 3261 §20.43).
2
3use std::fmt;
4
5/// Error parsing a SIP Warning header.
6#[derive(Debug, Clone, PartialEq, Eq)]
7#[non_exhaustive]
8pub enum SipWarningError {
9    /// Empty input.
10    Empty,
11    /// Invalid format.
12    InvalidFormat(String),
13}
14
15impl fmt::Display for SipWarningError {
16    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
17        match self {
18            SipWarningError::Empty => write!(f, "empty Warning header"),
19            SipWarningError::InvalidFormat(msg) => write!(f, "invalid Warning format: {}", msg),
20        }
21    }
22}
23
24impl std::error::Error for SipWarningError {}
25
26/// A single Warning header entry.
27///
28/// RFC 3261 §20.43:
29/// ```text
30/// warning-value = warn-code SP warn-agent SP warn-text
31/// warn-code = 3DIGIT
32/// warn-agent = hostport / pseudonym
33/// warn-text = quoted-string
34/// ```
35#[derive(Debug, Clone, PartialEq, Eq)]
36#[non_exhaustive]
37pub struct SipWarningEntry {
38    code: u16,
39    agent: String,
40    text: String,
41}
42
43impl SipWarningEntry {
44    /// The 3-digit warning code.
45    pub fn code(&self) -> u16 {
46        self.code
47    }
48
49    /// The warn-agent (hostport or pseudonym).
50    pub fn agent(&self) -> &str {
51        &self.agent
52    }
53
54    /// The warn-text (unquoted).
55    pub fn text(&self) -> &str {
56        &self.text
57    }
58
59    fn parse(s: &str) -> Result<Self, SipWarningError> {
60        let s = s.trim();
61        if s.is_empty() {
62            return Err(SipWarningError::InvalidFormat(
63                "empty warning entry".to_string(),
64            ));
65        }
66
67        // Parse warn-code (3DIGIT)
68        let space_pos = s
69            .find(' ')
70            .ok_or_else(|| {
71                SipWarningError::InvalidFormat("missing space after warn-code".to_string())
72            })?;
73
74        let code_str = &s[..space_pos];
75        if code_str.len() != 3
76            || !code_str
77                .chars()
78                .all(|c| c.is_ascii_digit())
79        {
80            return Err(SipWarningError::InvalidFormat(format!(
81                "warn-code must be 3 digits, got '{}'",
82                code_str
83            )));
84        }
85
86        let code = code_str
87            .parse::<u16>()
88            .map_err(|_| {
89                SipWarningError::InvalidFormat(format!("invalid warn-code '{}'", code_str))
90            })?;
91
92        let rest = s[space_pos..].trim_start();
93
94        // Find the quoted warn-text
95        let quote_pos = rest
96            .find('"')
97            .ok_or_else(|| {
98                SipWarningError::InvalidFormat("missing quoted warn-text".to_string())
99            })?;
100
101        if quote_pos == 0 {
102            return Err(SipWarningError::InvalidFormat(
103                "missing warn-agent".to_string(),
104            ));
105        }
106
107        let agent = rest[..quote_pos]
108            .trim_end()
109            .to_string();
110        if agent.is_empty() {
111            return Err(SipWarningError::InvalidFormat(
112                "empty warn-agent".to_string(),
113            ));
114        }
115
116        // Parse quoted string
117        let text = parse_quoted_string(&rest[quote_pos..])?;
118
119        Ok(SipWarningEntry { code, agent, text })
120    }
121}
122
123impl fmt::Display for SipWarningEntry {
124    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
125        write!(
126            f,
127            "{:03} {} \"{}\"",
128            self.code,
129            self.agent,
130            crate::escape_quoted_pair(&self.text)
131        )
132    }
133}
134
135/// Parse a quoted string starting with `"`, returning the unescaped content.
136fn parse_quoted_string(s: &str) -> Result<String, SipWarningError> {
137    let s = s.trim_start();
138    if !s.starts_with('"') {
139        return Err(SipWarningError::InvalidFormat(
140            "quoted string must start with '\"'".to_string(),
141        ));
142    }
143
144    // Find the closing quote, respecting backslash escapes.
145    let content = &s[1..];
146    let mut escaped = false;
147    for (i, c) in content.char_indices() {
148        if escaped {
149            escaped = false;
150        } else if c == '\\' {
151            escaped = true;
152        } else if c == '"' {
153            return Ok(crate::unescape_quoted_pair(&content[..i]));
154        }
155    }
156
157    Err(SipWarningError::InvalidFormat(
158        "unterminated quoted string".to_string(),
159    ))
160}
161
162/// SIP Warning header.
163///
164/// RFC 3261 §20.43:
165/// ```text
166/// Warning = "Warning" HCOLON warning-value *(COMMA warning-value)
167/// ```
168#[derive(Debug, Clone, PartialEq, Eq)]
169#[non_exhaustive]
170pub struct SipWarning {
171    entries: Vec<SipWarningEntry>,
172}
173
174impl SipWarning {
175    /// Parse a Warning header value.
176    pub fn parse(raw: &str) -> Result<Self, SipWarningError> {
177        let raw = raw.trim();
178        if raw.is_empty() {
179            return Err(SipWarningError::Empty);
180        }
181
182        let entries = crate::split_comma_entries(raw)
183            .into_iter()
184            .map(SipWarningEntry::parse)
185            .collect::<Result<Vec<_>, _>>()?;
186
187        if entries.is_empty() {
188            return Err(SipWarningError::Empty);
189        }
190
191        Ok(SipWarning { entries })
192    }
193
194    /// All warning entries.
195    pub fn entries(&self) -> &[SipWarningEntry] {
196        &self.entries
197    }
198
199    /// Consume self and return entries as a `Vec`.
200    pub fn into_entries(self) -> Vec<SipWarningEntry> {
201        self.entries
202    }
203
204    /// Number of warning entries.
205    pub fn len(&self) -> usize {
206        self.entries
207            .len()
208    }
209
210    /// Whether there are no warning entries.
211    pub fn is_empty(&self) -> bool {
212        self.entries
213            .is_empty()
214    }
215}
216
217impl fmt::Display for SipWarning {
218    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
219        crate::fmt_joined(f, &self.entries, ", ")
220    }
221}
222
223impl_from_str_via_parse!(SipWarning, SipWarningError);
224
225impl IntoIterator for SipWarning {
226    type Item = SipWarningEntry;
227    type IntoIter = std::vec::IntoIter<SipWarningEntry>;
228
229    fn into_iter(self) -> Self::IntoIter {
230        self.entries
231            .into_iter()
232    }
233}
234
235impl<'a> IntoIterator for &'a SipWarning {
236    type Item = &'a SipWarningEntry;
237    type IntoIter = std::slice::Iter<'a, SipWarningEntry>;
238
239    fn into_iter(self) -> Self::IntoIter {
240        self.entries
241            .iter()
242    }
243}
244
245#[cfg(test)]
246mod tests {
247    use super::*;
248
249    #[test]
250    fn test_single_warning() {
251        let input = r#"301 example.com "Incompatible network protocol""#;
252        let warning = SipWarning::parse(input).unwrap();
253        assert_eq!(warning.len(), 1);
254        let entry = &warning.entries()[0];
255        assert_eq!(entry.code(), 301);
256        assert_eq!(entry.agent(), "example.com");
257        assert_eq!(entry.text(), "Incompatible network protocol");
258    }
259
260    #[test]
261    fn test_multiple_warnings() {
262        let input = r#"301 example.com "Incompatible network protocol", 399 198.51.100.1:5060 "Miscellaneous warning""#;
263        let warning = SipWarning::parse(input).unwrap();
264        assert_eq!(warning.len(), 2);
265
266        let entry1 = &warning.entries()[0];
267        assert_eq!(entry1.code(), 301);
268        assert_eq!(entry1.agent(), "example.com");
269        assert_eq!(entry1.text(), "Incompatible network protocol");
270
271        let entry2 = &warning.entries()[1];
272        assert_eq!(entry2.code(), 399);
273        assert_eq!(entry2.agent(), "198.51.100.1:5060");
274        assert_eq!(entry2.text(), "Miscellaneous warning");
275    }
276
277    #[test]
278    fn test_escaped_quotes_in_text() {
279        let input = r#"399 example.org "Warning with \"quoted\" text""#;
280        let warning = SipWarning::parse(input).unwrap();
281        assert_eq!(warning.len(), 1);
282        let entry = &warning.entries()[0];
283        assert_eq!(entry.code(), 399);
284        assert_eq!(entry.agent(), "example.org");
285        assert_eq!(entry.text(), r#"Warning with "quoted" text"#);
286    }
287
288    #[test]
289    fn test_common_warning_codes() {
290        let input1 = r#"301 example.com "Incompatible network protocol""#;
291        let warning1 = SipWarning::parse(input1).unwrap();
292        assert_eq!(warning1.entries()[0].code(), 301);
293
294        let input2 = r#"399 example.net "Miscellaneous warning""#;
295        let warning2 = SipWarning::parse(input2).unwrap();
296        assert_eq!(warning2.entries()[0].code(), 399);
297    }
298
299    #[test]
300    fn test_display_roundtrip() {
301        let input = r#"301 example.com "Incompatible network protocol", 399 198.51.100.1:5060 "Miscellaneous warning""#;
302        let warning = SipWarning::parse(input).unwrap();
303        let output = warning.to_string();
304        let reparsed = SipWarning::parse(&output).unwrap();
305        assert_eq!(warning, reparsed);
306    }
307
308    #[test]
309    fn test_display_roundtrip_with_escaped_quotes() {
310        let input = r#"399 example.org "Warning with \"quoted\" text""#;
311        let warning = SipWarning::parse(input).unwrap();
312        let output = warning.to_string();
313        let reparsed = SipWarning::parse(&output).unwrap();
314        assert_eq!(warning, reparsed);
315    }
316
317    #[test]
318    fn test_empty_input() {
319        let result = SipWarning::parse("");
320        assert!(matches!(result, Err(SipWarningError::Empty)));
321
322        let result = SipWarning::parse("   ");
323        assert!(matches!(result, Err(SipWarningError::Empty)));
324    }
325
326    #[test]
327    fn test_invalid_warn_code() {
328        let result = SipWarning::parse(r#"30 example.com "Short code""#);
329        assert!(matches!(result, Err(SipWarningError::InvalidFormat(_))));
330
331        let result = SipWarning::parse(r#"3001 example.com "Long code""#);
332        assert!(matches!(result, Err(SipWarningError::InvalidFormat(_))));
333
334        let result = SipWarning::parse(r#"abc example.com "Non-numeric""#);
335        assert!(matches!(result, Err(SipWarningError::InvalidFormat(_))));
336    }
337
338    #[test]
339    fn test_missing_warn_agent() {
340        let result = SipWarning::parse(r#"301 "Missing agent""#);
341        assert!(matches!(result, Err(SipWarningError::InvalidFormat(_))));
342    }
343
344    #[test]
345    fn test_missing_warn_text() {
346        let result = SipWarning::parse("301 example.com");
347        assert!(matches!(result, Err(SipWarningError::InvalidFormat(_))));
348    }
349
350    #[test]
351    fn test_unterminated_quoted_string() {
352        let result = SipWarning::parse(r#"301 example.com "Unterminated"#);
353        assert!(matches!(result, Err(SipWarningError::InvalidFormat(_))));
354    }
355
356    #[test]
357    fn test_into_iterator() {
358        let input = r#"301 example.com "First", 399 example.org "Second""#;
359        let warning = SipWarning::parse(input).unwrap();
360
361        let codes: Vec<u16> = warning
362            .into_iter()
363            .map(|e| e.code())
364            .collect();
365        assert_eq!(codes, vec![301, 399]);
366    }
367
368    #[test]
369    fn test_into_iterator_ref() {
370        let input = r#"301 example.com "First", 399 example.org "Second""#;
371        let warning = SipWarning::parse(input).unwrap();
372
373        let codes: Vec<u16> = (&warning)
374            .into_iter()
375            .map(|e| e.code())
376            .collect();
377        assert_eq!(codes, vec![301, 399]);
378
379        assert_eq!(warning.len(), 2);
380    }
381
382    #[test]
383    fn test_is_empty() {
384        let input = r#"301 example.com "Warning""#;
385        let warning = SipWarning::parse(input).unwrap();
386        assert!(!warning.is_empty());
387    }
388
389    #[test]
390    fn test_into_entries() {
391        let input = r#"301 example.com "First", 399 example.org "Second""#;
392        let warning = SipWarning::parse(input).unwrap();
393        let entries = warning.into_entries();
394        assert_eq!(entries.len(), 2);
395        assert_eq!(entries[0].code(), 301);
396        assert_eq!(entries[1].code(), 399);
397    }
398
399    #[test]
400    fn test_comma_in_warn_text() {
401        let input = r#"301 example.com "text, with comma", 399 example.org "fine""#;
402        let warning = SipWarning::parse(input).unwrap();
403        assert_eq!(warning.len(), 2);
404        assert_eq!(warning.entries()[0].text(), "text, with comma");
405        assert_eq!(warning.entries()[1].text(), "fine");
406    }
407
408    #[test]
409    fn test_from_str() {
410        let input = r#"301 example.com "warning""#;
411        let warning: SipWarning = input
412            .parse()
413            .unwrap();
414        assert_eq!(warning.len(), 1);
415    }
416
417    #[test]
418    fn test_ipv6_agent() {
419        let input = r#"301 [2001:db8::1]:5060 "IPv6 warning""#;
420        let warning = SipWarning::parse(input).unwrap();
421        assert_eq!(warning.entries()[0].agent(), "[2001:db8::1]:5060");
422    }
423
424    #[test]
425    fn test_escaped_backslash() {
426        let input = r#"399 example.com "Path: C:\\temp\\file""#;
427        let warning = SipWarning::parse(input).unwrap();
428        assert_eq!(warning.entries()[0].text(), r#"Path: C:\temp\file"#);
429    }
430}
sip_header/warning.rs

sip_header/
warning.rs
