jmap_types/uri.rs
1//! RFC 3986 URI syntax checks (draft-atwood-jmap-updates-00 §7.1).
2//!
3//! "A property, argument, or Session member whose value is a URI or URL
4//! SHOULD hold a URI as defined in RFC 3986 Section 3. Unless its defining
5//! specification allows a relative reference, it SHOULD be a URI and not a
6//! relative reference." URIs in JMAP are ASCII: an IRI is mapped to a URI
7//! (RFC 3987 §3.1) before it is sent; `jmap-base-client` has the mapping.
8//!
9//! The workspace's `url` crate implements the WHATWG URL Standard, which
10//! normalizes and accepts input RFC 3986 rejects, so it is not used here
11//! (decision 29). Identifying URIs, such as capability URIs, compare as
12//! exact strings (RFC 3986 §6.2.1) unless their specification names
13//! another comparison.
14
15use std::fmt;
16
17/// Why a string is not an RFC 3986 URI or URI reference.
18#[non_exhaustive]
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub enum UriError {
21 /// The string does not match the RFC 3986 grammar, for example because
22 /// it has a space, a non-ASCII character or a bad percent-encoding.
23 Syntax,
24 /// The string is a relative reference where a URI with a scheme is
25 /// required (RFC 3986 §4.2).
26 Relative,
27}
28
29impl fmt::Display for UriError {
30 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
31 f.write_str(match self {
32 Self::Syntax => "not an RFC 3986 URI",
33 Self::Relative => "a relative reference where an RFC 3986 URI is required",
34 })
35 }
36}
37
38impl std::error::Error for UriError {}
39
40/// Check that `s` is an RFC 3986 §3 `URI`: a scheme, then hierarchical
41/// part, optional query and optional fragment. Fragments are allowed.
42///
43/// # Errors
44///
45/// [`UriError::Relative`] for a well-formed relative reference,
46/// [`UriError::Syntax`] for anything else that is not a URI.
47///
48/// ```rust
49/// use jmap_types::uri::{UriError, check_uri};
50///
51/// assert!(check_uri("https://example.com/a?b#c").is_ok());
52/// assert!(check_uri("urn:ietf:params:jmap:core").is_ok());
53/// assert_eq!(check_uri("/a/b"), Err(UriError::Relative));
54/// assert_eq!(check_uri("https://example.com/a b"), Err(UriError::Syntax));
55/// ```
56pub fn check_uri(s: &str) -> Result<(), UriError> {
57 if iri_string::types::UriStr::new(s).is_ok() {
58 return Ok(());
59 }
60 if iri_string::types::UriReferenceStr::new(s).is_ok() {
61 Err(UriError::Relative)
62 } else {
63 Err(UriError::Syntax)
64 }
65}
66
67/// Check that `s` is an RFC 3986 §4.1 `URI-reference`: a URI or a relative
68/// reference, for properties whose specification allows relative
69/// references.
70///
71/// # Errors
72///
73/// [`UriError::Syntax`] when it is neither.
74pub fn check_uri_reference(s: &str) -> Result<(), UriError> {
75 iri_string::types::UriReferenceStr::new(s)
76 .map(|_| ())
77 .map_err(|_| UriError::Syntax)
78}
79
80#[cfg(test)]
81mod tests {
82 use super::*;
83
84 /// RFC 3986 §1.1.2 examples are all URIs.
85 #[test]
86 fn rfc3986_examples_are_uris() {
87 for u in [
88 "ftp://ftp.is.co.za/rfc/rfc1808.txt",
89 "http://www.ietf.org/rfc/rfc2396.txt",
90 "ldap://[2001:db8::7]/c=GB?objectClass?one",
91 "mailto:John.Doe@example.com",
92 "news:comp.infosystems.www.servers.unix",
93 "tel:+1-816-555-1212",
94 "telnet://192.0.2.16:80/",
95 "urn:oasis:names:specification:docbook:dtd:xml:4.1.2",
96 ] {
97 assert_eq!(check_uri(u), Ok(()), "{u}");
98 }
99 }
100
101 /// RFC 3986 §5.4 relative references are references, not URIs.
102 #[test]
103 fn relative_references() {
104 for r in ["g", "./g", "g/", "/g", "//g", "?y", "g?y", "#s", "../g"] {
105 assert_eq!(check_uri(r), Err(UriError::Relative), "{r}");
106 assert_eq!(check_uri_reference(r), Ok(()), "{r}");
107 }
108 }
109
110 /// RFC 3986 §2: no spaces, no raw non-ASCII (that is an IRI, RFC 3987),
111 /// and `%` must start a percent-encoding.
112 #[test]
113 fn syntax_errors() {
114 for s in [
115 "https://example.com/a b",
116 "https://example.com/ü",
117 "https://example.com/%zz",
118 "",
119 ] {
120 assert_eq!(
121 check_uri(s),
122 if s.is_empty() {
123 Err(UriError::Relative)
124 } else {
125 Err(UriError::Syntax)
126 },
127 "{s:?}"
128 );
129 }
130 assert_eq!(
131 check_uri_reference("https://example.com/a b"),
132 Err(UriError::Syntax)
133 );
134 }
135}