sdp-types: late spring cleaning

kbalt · Jun 24, 2024 · d51444f · d51444f
1 parent 9dfb439
commit d51444f
Show file tree

Hide file tree

Showing 16 changed files with 660 additions and 765 deletions.
diff --git a/crates/sdp-types/src/attributes/candidate.rs b/crates/sdp-types/src/attributes/candidate.rs
@@ -13,10 +13,12 @@ use std::fmt;
 use std::net::IpAddr;
 use std::str::FromStr;
 
+/// Encountered invalid values for key-value params when parsing an [`IceCandidate`]
 #[derive(Debug, thiserror::Error)]
 #[error("failed to parse candidate")]
-pub struct InvalidCandidateParam;
+pub struct InvalidCandidateParamError;
 
+/// Used by [`IceCandidate`]
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum UntaggedAddress {
     Fqdn(BytesStr),
@@ -46,11 +48,11 @@ impl fmt::Display for UntaggedAddress {
     }
 }
 
-/// SDP ICE Candidate
+/// ICE Candidate (`a=candidate`)
 ///
 /// [RFC5245](https://tools.ietf.org/html/rfc5245#section-15.1)
 #[derive(Debug, Clone)]
-pub struct Candidate {
+pub struct IceCandidate {
     /// Session unique ID assigned to the candidate
     pub foundation: BytesStr,
 
@@ -97,7 +99,7 @@ pub struct Candidate {
     pub unknown: Vec<(BytesStr, BytesStr)>,
 }
 
-impl Candidate {
+impl IceCandidate {
     pub fn parse<'i>(src: &Bytes, i: &'i str) -> IResult<&'i str, Self> {
         map_res(
                 preceded(
@@ -128,24 +130,24 @@ impl Candidate {
                         ))),
                     )),
                 ),
-                |(foundation, (component, transport, priority, address, port, type_), p_ext)| -> Result<Candidate, InvalidCandidateParam> {
+                |(foundation, (component, transport, priority, address, port, type_), p_ext)| -> Result<IceCandidate, InvalidCandidateParamError> {
                     let mut unknown = vec![];
 
                     let mut rel_addr = None;
                     let mut rel_port = None;
 
                     for (key, value) in p_ext {
                         match key {
-                            "raddr" => rel_addr = Some(UntaggedAddress::parse(src)(value).map_err(|_| InvalidCandidateParam)?.1),
-                            "rport" => rel_port = Some(u16::from_str(value).map_err(|_| InvalidCandidateParam)?),
+                            "raddr" => rel_addr = Some(UntaggedAddress::parse(src)(value).map_err(|_| InvalidCandidateParamError)?.1),
+                            "rport" => rel_port = Some(u16::from_str(value).map_err(|_| InvalidCandidateParamError)?),
                             _ => unknown.push((
                                 BytesStr::from_parse(src, key),
                                 BytesStr::from_parse(src, value),
                             )),
                         }
                     }
 
-                    Ok(Candidate {
+                    Ok(IceCandidate {
                         foundation: BytesStr::from_parse(src, foundation),
                         component,
                         transport: BytesStr::from_parse(src, transport),
@@ -162,7 +164,7 @@ impl Candidate {
     }
 }
 
-impl fmt::Display for Candidate {
+impl fmt::Display for IceCandidate {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(
             f,
@@ -203,7 +205,7 @@ mod test {
             "candidate:12 2 TCP 2105458942 192.168.56.1 9 typ host raddr 192.168.1.22 rport 123 tcptype active",
         );
 
-        let (rem, candidate) = Candidate::parse(input.as_ref(), &input).unwrap();
+        let (rem, candidate) = IceCandidate::parse(input.as_ref(), &input).unwrap();
 
         assert_eq!(candidate.foundation, "12");
         assert_eq!(candidate.component, 2);
@@ -235,7 +237,7 @@ mod test {
 
     #[test]
     fn candidate_print() {
-        let candidate = Candidate {
+        let candidate = IceCandidate {
             foundation: "1".into(),
             component: 1,
             transport: "UDP".into(),

diff --git a/crates/sdp-types/src/attributes/direction.rs b/crates/sdp-types/src/attributes/direction.rs
@@ -2,7 +2,7 @@
 
 use std::fmt;
 
-/// Media direction attribute
+/// Media direction attribute e.g. (`a=sendrecv`)
 ///
 /// Session and Media Level attribute.  
 /// If the direction is specified at the session level but not as media level

diff --git a/crates/sdp-types/src/attributes/fmtp.rs b/crates/sdp-types/src/attributes/fmtp.rs
@@ -10,9 +10,9 @@ use nom::sequence::preceded;
 use std::fmt;
 use std::str::FromStr;
 
-/// Specify additional parameters for a format specified by a `rtpmap`
+/// Fmtp attribute (`a=fmtp`)
 ///
-/// Media-Level attribute
+/// Specify additional parameters for a format specified by a `rtpmap` in a media description
 ///
 /// [RFC8866](https://www.rfc-editor.org/rfc/rfc8866.html#section-6.15)
 #[derive(Debug, Clone)]

diff --git a/crates/sdp-types/src/attributes/ice.rs b/crates/sdp-types/src/attributes/ice.rs
@@ -9,18 +9,18 @@ use nom::combinator::map;
 use nom::multi::many1;
 use std::fmt;
 
-/// ice-options
+/// Ice options attribute (`a=ice-options`)
 ///
 /// Session Level attribute
 ///
 /// [RFC5245](https://datatracker.ietf.org/doc/html/rfc5245#section-15.5)
 #[derive(Default, Debug, Clone)]
-pub struct Options {
+pub struct IceOptions {
     /// Non empty list of options
     pub options: Vec<BytesStr>,
 }
 
-impl Options {
+impl IceOptions {
     pub fn parse<'i>(src: &Bytes, i: &'i str) -> IResult<&'i str, Self> {
         map(
             many1(map(take_while1(ice_char), |option| {
@@ -31,7 +31,7 @@ impl Options {
     }
 }
 
-impl fmt::Display for Options {
+impl fmt::Display for IceOptions {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         if self.options.is_empty() {
             return Ok(());
@@ -47,57 +47,57 @@ impl fmt::Display for Options {
     }
 }
 
-/// ice-ufrag attribute
+/// Ice username fragment attribute (`a=ice-ufrag`)
 ///
 /// Session and Media Level attribute  
 /// If not present at media level the attribute at session level is taken as default.
 ///
 /// [RFC5245](https://datatracker.ietf.org/doc/html/rfc5245#section-15.4)
 #[derive(Debug, Clone)]
-pub struct UsernameFragment {
+pub struct IceUsernameFragment {
     /// The username fragment.
     ///
     /// Must be between 4 and 256 bytes long
     pub ufrag: BytesStr,
 }
 
-impl UsernameFragment {
+impl IceUsernameFragment {
     pub fn parse<'i>(src: &Bytes, i: &'i str) -> IResult<&'i str, Self> {
         map(take_while_m_n(4, 256, ice_char), |ufrag| Self {
             ufrag: BytesStr::from_parse(src, ufrag),
         })(i)
     }
 }
 
-impl fmt::Display for UsernameFragment {
+impl fmt::Display for IceUsernameFragment {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "a=ice-ufrag:{}", self.ufrag)
     }
 }
 
-/// ice-pwd attribute
+/// Ice password attribute (`a=ice-pwd`)
 ///
 /// Session and Media Level attribute  
 /// If not present at media level the attribute at session level is taken as default.
 ///
 /// [RFC5245](https://datatracker.ietf.org/doc/html/rfc5245#section-15.4)
 #[derive(Debug, Clone)]
-pub struct Password {
+pub struct IcePassword {
     /// The password
     ///
     /// Must be between 22 and 256 bytes long
     pub pwd: BytesStr,
 }
 
-impl Password {
+impl IcePassword {
     pub fn parse<'i>(src: &Bytes, i: &'i str) -> IResult<&'i str, Self> {
         map(take_while_m_n(22, 256, ice_char), |pwd| Self {
             pwd: BytesStr::from_parse(src, pwd),
         })(i)
     }
 }
 
-impl fmt::Display for Password {
+impl fmt::Display for IcePassword {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "a=ice-pwd:{}", self.pwd)
     }

diff --git a/crates/sdp-types/src/attributes/mod.rs b/crates/sdp-types/src/attributes/mod.rs
@@ -2,12 +2,19 @@ use bytes::Bytes;
 use bytesstr::BytesStr;
 use std::fmt;
 
-pub mod candidate;
-pub mod direction;
-pub mod fmtp;
-pub mod ice;
-pub mod rtcp;
-pub mod rtpmap;
+mod candidate;
+mod direction;
+mod fmtp;
+mod ice;
+mod rtcp;
+mod rtpmap;
+
+pub use candidate::{IceCandidate, InvalidCandidateParamError, UntaggedAddress};
+pub use direction::Direction;
+pub use fmtp::Fmtp;
+pub use ice::{IceOptions, IcePassword, IceUsernameFragment};
+pub use rtcp::Rtcp;
+pub use rtpmap::RtpMap;
 
 /// `name:[value]` pair which contains an unparsed/unknown attribute
 #[derive(Debug, Clone)]

diff --git a/crates/sdp-types/src/attributes/rtcp.rs b/crates/sdp-types/src/attributes/rtcp.rs
@@ -10,22 +10,23 @@ use nom::sequence::{preceded, tuple};
 use std::fmt;
 use std::str::FromStr;
 
-/// Specify an alternative address/port for RTCP  
-/// Defined as a simple fix for NAT transversal with STUN
+/// Rtcp attribute (`a=rtcp`)
+///
+/// Specify an alternative address/port for RTCP
 ///
 /// Media Level attribute
 ///
 /// [RFC3605](https://datatracker.ietf.org/doc/html/rfc3605)
 #[derive(Debug, Clone)]
-pub struct RtcpAttr {
+pub struct Rtcp {
     /// Port to be used for RTCP
     pub port: u16,
 
     /// Optional address
     pub address: Option<TaggedAddress>,
 }
 
-impl RtcpAttr {
+impl Rtcp {
     pub fn parse<'i>(src: &Bytes, i: &'i str) -> IResult<&'i str, Self> {
         preceded(
             tag("rtcp:"),
@@ -36,7 +37,7 @@ impl RtcpAttr {
                     // optional tagged address
                     opt(ws((TaggedAddress::parse(src),))),
                 )),
-                |(port, address)| RtcpAttr {
+                |(port, address)| Rtcp {
                     port,
                     address: address.map(|t| t.0),
                 },
@@ -45,7 +46,7 @@ impl RtcpAttr {
     }
 }
 
-impl fmt::Display for RtcpAttr {
+impl fmt::Display for Rtcp {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "a=rtcp:{}", self.port)?;
 
@@ -67,7 +68,7 @@ mod test {
     fn rtcp() {
         let input = BytesStr::from_static("rtcp:4444");
 
-        let (rem, rtcp) = RtcpAttr::parse(input.as_ref(), &input).unwrap();
+        let (rem, rtcp) = Rtcp::parse(input.as_ref(), &input).unwrap();
 
         assert!(rem.is_empty());
 
@@ -79,7 +80,7 @@ mod test {
     fn rtcp_address() {
         let input = BytesStr::from_static("rtcp:4444 IN IP4 192.168.123.222");
 
-        let (rem, rtcp) = RtcpAttr::parse(input.as_ref(), &input).unwrap();
+        let (rem, rtcp) = Rtcp::parse(input.as_ref(), &input).unwrap();
 
         assert!(rem.is_empty());
 
@@ -91,7 +92,7 @@ mod test {
 
     #[test]
     fn rtcp_print() {
-        let rtcp = RtcpAttr {
+        let rtcp = Rtcp {
             port: 4444,
             address: None,
         };
@@ -101,7 +102,7 @@ mod test {
 
     #[test]
     fn rtcp_address_print() {
-        let rtcp = RtcpAttr {
+        let rtcp = Rtcp {
             port: 4444,
             address: Some(TaggedAddress::IP4(Ipv4Addr::new(192, 168, 123, 222))),
         };

diff --git a/crates/sdp-types/src/attributes/rtpmap.rs b/crates/sdp-types/src/attributes/rtpmap.rs
@@ -10,6 +10,8 @@ use nom::sequence::{preceded, terminated, tuple};
 use std::fmt;
 use std::str::FromStr;
 
+/// Rtpmap attribute (`a=rtpmap`)
+///
 /// Map a RTP payload number specified in the media description to a encoding.
 ///
 /// Media-Level attribute

diff --git a/crates/sdp-types/src/bandwidth.rs b/crates/sdp-types/src/bandwidth.rs
@@ -9,7 +9,7 @@ use nom::sequence::tuple;
 use std::fmt;
 use std::str::FromStr;
 
-/// Bandwidth Information
+/// Bandwidth field (`b=`)
 ///
 /// [RFC8866](https://www.rfc-editor.org/rfc/rfc8866.html#section-5.8)
 #[derive(Debug, Clone)]

diff --git a/crates/sdp-types/src/connection.rs b/crates/sdp-types/src/connection.rs
@@ -5,7 +5,7 @@ use nom::combinator::opt;
 use nom::sequence::pair;
 use std::fmt;
 
-/// Connection field
+/// Connection field (`c=`)
 ///
 /// [RFC8866](https://www.rfc-editor.org/rfc/rfc8866.html#section-5.7)
 #[derive(Debug, Clone)]