Skip to main content

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}