sip_uri_types/lib.rs
1//! SIP/SIPS, tel: and URN URI values, each component held in canonical form.
2//!
3//! Parse text into these types with [sip-uri](https://docs.rs/sip-uri).
4//!
5//! These types were sip-uri's own until 0.2; code written against them there
6//! migrates with sip-uri's
7//! [guide](https://docs.rs/sip-uri/0.3/sip_uri/migrating_from_0_2/index.html).
8//!
9//! The `serde` feature serializes each value as its parts, and deserializes
10//! them through the same canonizing constructor as [`From`] a parts struct.
11//! A [`Host`] reads a hostname through [`Host::from_hostname`]. The shape is
12//! under the same semver as the fields: a field added to a parts struct is a
13//! minor release, missing fields take their defaults, unknown ones are
14//! ignored, and a SIP URI read without `scheme` has none. That compatibility
15//! needs a self-describing format such as JSON, YAML or CBOR: in a
16//! positional one such as bincode or postcard, an added field changes the
17//! encoding, so data stored that way does not survive a minor release.
18//!
19//! ```
20//! use sip_uri_types::{Host, SipUri, TelUri};
21//!
22//! let uri = SipUri::new(Host::Hostname("example.com".into()))
23//! .with_user("+15551234567")
24//! .with_param("user", Some("phone"));
25//! assert_eq!(uri.to_string(), "sip:+15551234567@example.com;user=phone");
26//!
27//! let tel = TelUri::new("+1555 123");
28//! assert_eq!(tel.number(), Some("+1555%20123"));
29//! ```
30//!
31//! # Canonical form
32//!
33//! Each component keeps its conformant characters literal, decodes escapes
34//! of unreserved characters only, and holds every other byte as an uppercase
35//! `%XX`, whichever path built the value. A tel: number, a fragment and a
36//! URN component decode no escape at all. An escaped reserved character
37//! stays escaped, so `%2B1` and `+1` are distinct users.
38//!
39//! Builders and parts structs take URI text, not logical values: a well-formed
40//! `%XX` in it is read as an escape, never re-encoded. `with_user("%2B1")`
41//! holds `%2B1`. [`encoding`] has one encoder and one decoder per component
42//! a builder takes as text, between logical bytes and that text.
43//!
44//! Hostnames are lowercased as ASCII only, with no IDNA and no non-ASCII case
45//! folding. An IPv6 address renders as [`std::net::Ipv6Addr`] displays it,
46//! and an IPv6 zone ID is not representable.
47//!
48//! # Equality
49//!
50//! `Eq` and `Hash` compare the canonical form component by component. That
51//! is identity, never RFC 3261 §19.1.4, RFC 3966 §4 or RFC 8141 §3
52//! equivalence: param order, param and header name case, a tel: number's
53//! visual separators, a hostname's trailing dot and a URN's r-, q- and
54//! f-components all count. RFC equivalence is sip-uri's `UriEquivalence`.
55//!
56//! [`UriHeaderEquivalence`] is the interface by which that comparison
57//! matches two [`Headers`] sets, which a SIP header parser implements with
58//! each field's own rules; [`ordered_headers_equivalent`] is the default.
59//!
60//! # Stability
61//!
62//! The URI kinds with their own type are fixed: a URI with any other scheme
63//! is [`Uri::Other`]. [`Uri`] and [`Scheme`] are therefore exhaustive.
64//!
65//! The minimum supported Rust version is 1.70, 1.71 with the `serde`
66//! feature. Raising it is a minor release.
67
68#![deny(unsafe_code)]
69#![warn(clippy::undocumented_unsafe_blocks)]
70
71mod canon;
72mod equivalence;
73mod host;
74mod params;
75#[cfg(feature = "serde")]
76mod serde_impls;
77mod sip_uri;
78mod tel_uri;
79mod uri;
80mod urn_uri;
81
82pub use canon::encoding;
83pub use equivalence::{ordered_headers_equivalent, UriHeaderEquivalence};
84pub use host::{Bare, Host, Hostname};
85pub use params::{CapacityError, Headers, Pairs, Params, UserParams};
86pub use sip_uri::{Scheme, SipUri, SipUriParts, UserHost};
87pub use tel_uri::{TelUri, TelUriParts};
88pub use uri::{KindMismatchError, OtherUri, OtherUriError, Uri};
89pub use urn_uri::{AssignedName, UrnUri, UrnUriParts};
90
91#[cfg(doctest)]
92#[doc = include_str!("../README.md")]
93struct ReadmeDoctests;
94
95#[cfg(test)]
96mod tests {
97 use super::*;
98
99 fn is_send_sync_unpin<T: Send + Sync + Unpin>() {}
100
101 #[test]
102 fn data_types_are_send_sync_unpin() {
103 is_send_sync_unpin::<Uri>();
104 is_send_sync_unpin::<SipUri>();
105 is_send_sync_unpin::<SipUriParts>();
106 is_send_sync_unpin::<TelUri>();
107 is_send_sync_unpin::<TelUriParts>();
108 is_send_sync_unpin::<UrnUri>();
109 is_send_sync_unpin::<UrnUriParts>();
110 is_send_sync_unpin::<OtherUri>();
111 is_send_sync_unpin::<OtherUriError>();
112 is_send_sync_unpin::<CapacityError>();
113 is_send_sync_unpin::<KindMismatchError>();
114 is_send_sync_unpin::<Host>();
115 is_send_sync_unpin::<Hostname>();
116 is_send_sync_unpin::<Bare<'static>>();
117 is_send_sync_unpin::<Scheme>();
118 is_send_sync_unpin::<Params>();
119 is_send_sync_unpin::<UserParams>();
120 is_send_sync_unpin::<Headers>();
121 is_send_sync_unpin::<Pairs<'static>>();
122 is_send_sync_unpin::<UserHost<'static>>();
123 is_send_sync_unpin::<AssignedName<'static>>();
124 }
125}