1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
use std::fmt::{self, Display};

use crate::uncased::UncasedStr;
use crate::uri::error::Error;
use crate::uri::{Absolute, Authority};

/// A domain and port identified by a client as the server being messaged.
///
/// For requests made via HTTP/1.1, a host is identified via the `HOST` header.
/// In HTTP/2 and HTTP/3, this information is instead communicated via the
/// `:authority` and `:port` pseudo-header request fields. It is a
/// client-controlled value via which the client communicates to the server the
/// domain name and port it is attempting to communicate with. The following
/// diagram illustrates the syntactic structure of a `Host`:
///
/// ```text
/// some.domain.foo:8088
/// |-------------| |--|
///      domain     port
/// ```
///
/// Only the domain part is required. Its value is case-insensitive.
///
/// # URI Construction
///
/// A `Host` is _not_ a [`Uri`](crate::uri::Uri), and none of Rocket's APIs will
/// accept a `Host` value as such. This is because doing so would facilitate the
/// construction of URIs to internal routes in a manner controllable by an
/// attacker, inevitably leading to "HTTP Host header attacks".
///
/// Instead, a `Host` must be checked before being converted to a [`Uri`]
/// value. The [`Host::to_authority`] and [`Host::to_absolute`] methods provide
/// these mechanisms:
///
/// ```rust
/// # #[macro_use] extern crate rocket;
/// # type Token = String;
/// use rocket::http::uri::Host;
///
/// // A sensitive URI we want to prefix with safe hosts.
/// #[get("/token?<secret>")]
/// fn token(secret: Token) { /* .. */ }
///
/// // Whitelist of known hosts. In a real setting, you might retrieve this
/// // list from config at ignite-time using tools like `AdHoc::config()`.
/// const WHITELIST: [Host<'static>; 4] = [
///     Host::new(uri!("rocket.rs")),
///     Host::new(uri!("rocket.rs:443")),
///     Host::new(uri!("guide.rocket.rs")),
///     Host::new(uri!("guide.rocket.rs:443")),
/// ];
///
/// // Use `Host::to_absolute()` to case-insensitively check a host against a
/// // whitelist, returning an `Absolute` usable as a `uri!()` prefix.
/// let host = Host::new(uri!("guide.ROCKET.rs"));
/// let prefix = host.to_absolute("https", &WHITELIST);
///
/// // Since `guide.rocket.rs` is in the whitelist, `prefix` is `Some`.
/// assert!(prefix.is_some());
/// if let Some(prefix) = prefix {
///     // We can use this prefix to safely construct URIs.
///     let uri = uri!(prefix, token("some-secret-token"));
///     assert_eq!(uri, "https://guide.ROCKET.rs/token?secret=some-secret-token");
/// }
/// ```
///
/// # (De)serialization
///
/// `Host` is both `Serialize` and `Deserialize`:
///
/// ```rust
/// # #[cfg(feature = "serde")] mod serde {
/// # use serde_ as serde;
/// use serde::{Serialize, Deserialize};
/// use rocket::http::uri::Host;
///
/// #[derive(Deserialize, Serialize)]
/// # #[serde(crate = "serde_")]
/// struct UriOwned {
///     uri: Host<'static>,
/// }
///
/// #[derive(Deserialize, Serialize)]
/// # #[serde(crate = "serde_")]
/// struct UriBorrowed<'a> {
///     uri: Host<'a>,
/// }
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct Host<'a>(Authority<'a>);

impl<'a> Host<'a> {
    /// Create a new `Host` from an `Authority`. Only the `host` and `port`
    /// parts are preserved.
    ///
    /// ```rust
    /// # #[macro_use] extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// let host = Host::new(uri!("developer.mozilla.org"));
    /// assert_eq!(host.to_string(), "developer.mozilla.org");
    ///
    /// let host = Host::new(uri!("foo:bar@developer.mozilla.org:1234"));
    /// assert_eq!(host.to_string(), "developer.mozilla.org:1234");
    ///
    /// let host = Host::new(uri!("rocket.rs:443"));
    /// assert_eq!(host.to_string(), "rocket.rs:443");
    /// ```
    pub const fn new(authority: Authority<'a>) -> Self {
        Host(authority)
    }

    /// Parses the string `string` into a `Host`. Parsing will never allocate.
    /// Returns an `Error` if `string` is not a valid authority URI, meaning
    /// that this parser accepts a `user_info` part for compatibility but
    /// discards it.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[macro_use] extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// // Parse from a valid authority URI.
    /// let host = Host::parse("user:pass@domain").expect("valid host");
    /// assert_eq!(host.domain(), "domain");
    /// assert_eq!(host.port(), None);
    ///
    /// // Parse from a valid host.
    /// let host = Host::parse("domain:311").expect("valid host");
    /// assert_eq!(host.domain(), "doMaIN");
    /// assert_eq!(host.port(), Some(311));
    ///
    /// // Invalid hosts fail to parse.
    /// Host::parse("https://rocket.rs").expect_err("invalid host");
    ///
    /// // Prefer to use `uri!()` when the input is statically known:
    /// let host = Host::new(uri!("domain"));
    /// assert_eq!(host.domain(), "domain");
    /// assert_eq!(host.port(), None);
    /// ```
    pub fn parse(string: &'a str) -> Result<Host<'a>, Error<'a>> {
        Host::parse_bytes(string.as_bytes())
    }

    /// PRIVATE: Used by core.
    #[doc(hidden)]
    pub fn parse_bytes(bytes: &'a [u8]) -> Result<Host<'a>, Error<'a>> {
        crate::parse::uri::authority_from_bytes(bytes).map(Host::new)
    }

    /// Parses the string `string` into an `Host`. Parsing never allocates
    /// on success. May allocate on error.
    ///
    /// This method should be used instead of [`Host::parse()`] when the source
    /// is already a `String`. Returns an `Error` if `string` is not a valid
    /// authority URI, meaning that this parser accepts a `user_info` part for
    /// compatibility but discards it.
    ///
    /// # Example
    ///
    /// ```rust
    /// # extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// let source = format!("rocket.rs:8000");
    /// let host = Host::parse_owned(source).expect("valid host");
    /// assert_eq!(host.domain(), "rocket.rs");
    /// assert_eq!(host.port(), Some(8000));
    /// ```
    pub fn parse_owned(string: String) -> Result<Host<'static>, Error<'static>> {
        Authority::parse_owned(string).map(Host::new)
    }

    /// Returns the case-insensitive domain part of the host.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[macro_use] extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// let host = Host::new(uri!("domain.com:123"));
    /// assert_eq!(host.domain(), "domain.com");
    ///
    /// let host = Host::new(uri!("username:password@domain:123"));
    /// assert_eq!(host.domain(), "domain");
    ///
    /// let host = Host::new(uri!("[1::2]:123"));
    /// assert_eq!(host.domain(), "[1::2]");
    /// ```
    #[inline]
    pub fn domain(&self) -> &UncasedStr {
        self.0.host().into()
    }

    /// Returns the port part of the host, if there is one.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[macro_use] extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// // With a port.
    /// let host = Host::new(uri!("domain:123"));
    /// assert_eq!(host.port(), Some(123));
    ///
    /// let host = Host::new(uri!("domain.com:8181"));
    /// assert_eq!(host.port(), Some(8181));
    ///
    /// // Without a port.
    /// let host = Host::new(uri!("domain.foo.bar.tld"));
    /// assert_eq!(host.port(), None);
    /// ```
    #[inline(always)]
    pub fn port(&self) -> Option<u16> {
        self.0.port()
    }

    /// Checks `self` against `whitelist`. If `self` is in `whitelist`, returns
    /// an [`Authority`] URI representing self. Otherwise, returns `None`.
    /// Domain comparison is case-insensitive.
    ///
    /// See [URI construction](Self#uri-construction) for more.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[macro_use] extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// let whitelist = &[Host::new(uri!("domain.tld"))];
    ///
    /// // A host in the whitelist returns `Some`.
    /// let host = Host::new(uri!("domain.tld"));
    /// let uri = host.to_authority(whitelist);
    /// assert!(uri.is_some());
    /// assert_eq!(uri.unwrap().to_string(), "domain.tld");
    ///
    /// let host = Host::new(uri!("foo:bar@doMaIN.tLd"));
    /// let uri = host.to_authority(whitelist);
    /// assert!(uri.is_some());
    /// assert_eq!(uri.unwrap().to_string(), "doMaIN.tLd");
    ///
    /// // A host _not_ in the whitelist returns `None`.
    /// let host = Host::new(uri!("domain.tld:1234"));
    /// let uri = host.to_authority(whitelist);
    /// assert!(uri.is_none());
    /// ```
    pub fn to_authority<'h, W>(&self, whitelist: W) -> Option<Authority<'a>>
        where W: IntoIterator<Item = &'h Host<'h>>
    {
        let mut auth = whitelist.into_iter().any(|h| h == self).then(|| self.0.clone())?;
        auth.user_info = None;
        Some(auth)
    }

    /// Checks `self` against `whitelist`. If `self` is in `whitelist`, returns
    /// an [`Absolute`] URI representing `self` with scheme `scheme`. Otherwise,
    /// returns `None`. Domain comparison is case-insensitive.
    ///
    /// See [URI construction](Self#uri-construction) for more.
    ///
    /// # Example
    ///
    /// ```rust
    /// # #[macro_use] extern crate rocket;
    /// use rocket::http::uri::Host;
    ///
    /// let whitelist = &[Host::new(uri!("domain.tld:443"))];
    ///
    /// // A host in the whitelist returns `Some`.
    /// let host = Host::new(uri!("user@domain.tld:443"));
    /// let uri = host.to_absolute("http", whitelist);
    /// assert!(uri.is_some());
    /// assert_eq!(uri.unwrap().to_string(), "http://domain.tld:443");
    ///
    /// let host = Host::new(uri!("domain.TLD:443"));
    /// let uri = host.to_absolute("https", whitelist);
    /// assert!(uri.is_some());
    /// assert_eq!(uri.unwrap().to_string(), "https://domain.TLD:443");
    ///
    /// // A host _not_ in the whitelist returns `None`.
    /// let host = Host::new(uri!("domain.tld"));
    /// let uri = host.to_absolute("http", whitelist);
    /// assert!(uri.is_none());
    /// ```
    pub fn to_absolute<'h, W>(&self, scheme: &'a str, whitelist: W) -> Option<Absolute<'a>>
        where W: IntoIterator<Item = &'h Host<'h>>
    {
        let scheme = crate::parse::uri::scheme_from_str(scheme).ok()?;
        let authority = self.to_authority(whitelist)?;
        Some(Absolute::const_new(scheme, Some(authority), "", None))
    }
}

impl_serde!(Host<'a>, "an HTTP host");

impl_base_traits!(Host, domain, port);

impl crate::ext::IntoOwned for Host<'_> {
    type Owned = Host<'static>;

    fn into_owned(self) -> Host<'static> {
        Host(self.0.into_owned())
    }
}

impl<'a> From<Authority<'a>> for Host<'a> {
    fn from(auth: Authority<'a>) -> Self {
        Host::new(auth)
    }
}

impl Display for Host<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.domain().fmt(f)?;
        if let Some(port) = self.port() {
            write!(f, ":{}", port)?;
        }

        Ok(())
    }
}