Skip to main content

parsec_url/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 James Conway
3
4//! The WHATWG URL Standard: URLs with every getter and setter the `URL`
5//! interface has, `URLSearchParams`, and the host, IDNA and Punycode
6//! algorithms under them.
7//!
8//! It's written from the standard's current text, IDNA (UTS #46) and NFC
9//! included, with the Unicode 18.0 tables in `src/tables.rs`. The API has
10//! the shape the standard's JavaScript one has, so `url.pathname()` here is
11//! `url.pathname` there. `tests/wpt.rs` runs the web-platform-tests URL
12//! suite against it, every case of which passes.
13//!
14//! ```
15//! use parsec_url::Url;
16//!
17//! let base = Url::parse("https://example.com/a/b?x=1").unwrap();
18//! let mut url = Url::parse_with_base("../c?q=two words#top", &base).unwrap();
19//! assert_eq!(url.href(), "https://example.com/c?q=two%20words#top");
20//!
21//! let mut params = url.search_params();
22//! params.append("page", "2");
23//! url.set_search_params(&params);
24//! assert_eq!(url.search(), "?q=two+words&page=2");
25//! ```
26
27use std::cmp::Ordering;
28use std::fmt;
29use std::hash::{Hash, Hasher};
30use std::str::FromStr;
31
32mod form;
33mod host;
34mod idna;
35pub mod normalize;
36mod parser;
37mod percent;
38pub mod punycode;
39mod tables;
40
41pub use host::Host;
42use host::HostKind;
43use parser::Scheme;
44
45/// Why a URL didn't parse.
46#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
47#[non_exhaustive]
48pub enum ParseError {
49    EmptyHost,
50    IdnaError,
51    InvalidPort,
52    InvalidIpv4Address,
53    InvalidIpv6Address,
54    InvalidDomainCharacter,
55    RelativeUrlWithoutBase,
56    RelativeUrlWithCannotBeABaseBase,
57    /// The URL would be 4 GiB or more.
58    Overflow,
59}
60
61impl fmt::Display for ParseError {
62    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
63        f.write_str(match self {
64            ParseError::EmptyHost => "empty host",
65            ParseError::IdnaError => "invalid international domain name",
66            ParseError::InvalidPort => "invalid port number",
67            ParseError::InvalidIpv4Address => "invalid IPv4 address",
68            ParseError::InvalidIpv6Address => "invalid IPv6 address",
69            ParseError::InvalidDomainCharacter => "invalid domain character",
70            ParseError::RelativeUrlWithoutBase => "relative URL without a base",
71            ParseError::RelativeUrlWithCannotBeABaseBase => {
72                "relative URL with a cannot-be-a-base base"
73            }
74            ParseError::Overflow => "URLs of 4 GiB or more are not supported",
75        })
76    }
77}
78
79impl std::error::Error for ParseError {}
80
81/// A parsed URL. Getters and setters are named after the `URL` interface's
82/// attributes and behave as they do: a setter given a value the spec
83/// rejects leaves the URL as it was.
84///
85/// It's the serialization, in one string, and where each component of it
86/// starts. Two URLs are equal, and ordered, by their serializations.
87#[derive(Clone, Debug)]
88pub struct Url {
89    s: String,
90    /// The `:` after the scheme.
91    scheme_end: u32,
92    /// Where the username ends; with no host, all of these up to
93    /// `host_end` are `scheme_end + 1`.
94    username_end: u32,
95    host_start: u32,
96    host_end: u32,
97    /// After the host and port; with no host, after "scheme:" and the
98    /// "/." that can follow it.
99    path_start: u32,
100    /// The `?` and the `#`, if there are a query and a fragment.
101    query_start: Option<u32>,
102    fragment_start: Option<u32>,
103    port: Option<u16>,
104    host: HostKind,
105    scheme: Scheme,
106    opaque_path: bool,
107}
108
109impl Url {
110    /// Parses an absolute URL, as `new URL(input)` does.
111    pub fn parse(input: &str) -> Result<Url, ParseError> {
112        parser::parse(input, None)
113    }
114
115    /// Parses `input` against `base`, as `new URL(input, base)` does.
116    pub fn parse_with_base(input: &str, base: &Url) -> Result<Url, ParseError> {
117        parser::parse(input, Some(base))
118    }
119
120    /// Whether `input` parses, against `base` if there is one: `URL.canParse`.
121    pub fn can_parse(input: &str, base: Option<&Url>) -> bool {
122        parser::parse(input, base).is_ok()
123    }
124
125    /// The whole serialized URL.
126    pub fn href(&self) -> &str {
127        &self.s
128    }
129
130    /// Replaces the whole URL; unlike the other setters, this one fails
131    /// when the new value doesn't parse, as the `href` setter throws.
132    pub fn set_href(&mut self, value: &str) -> Result<(), ParseError> {
133        *self = Url::parse(value)?;
134        Ok(())
135    }
136
137    /// The serialized origin, `"null"` for an opaque one. A `blob:` URL's
138    /// is its inner URL's, when that's http, https or file.
139    pub fn origin(&self) -> String {
140        match self.scheme {
141            Scheme::Http | Scheme::Https | Scheme::Ws | Scheme::Wss | Scheme::Ftp => {
142                format!("{}//{}", self.protocol(), self.host())
143            }
144            Scheme::Other if self.scheme_str() == "blob" => match Url::parse(self.pathname()) {
145                Ok(inner) if matches!(inner.scheme, Scheme::Http | Scheme::Https) => inner.origin(),
146                _ => "null".into(),
147            },
148            _ => "null".into(),
149        }
150    }
151
152    /// The scheme with its colon, like `"https:"`.
153    pub fn protocol(&self) -> &str {
154        &self.s[..=self.scheme_end as usize]
155    }
156
157    pub fn set_protocol(&mut self, value: &str) {
158        self.set_scheme(value);
159    }
160
161    pub fn username(&self) -> &str {
162        if self.host == HostKind::None {
163            return "";
164        }
165        &self.s[self.scheme_end as usize + 3..self.username_end as usize]
166    }
167
168    pub fn set_username(&mut self, value: &str) {
169        self.set_userinfo(value, |p| &mut p.username);
170    }
171
172    pub fn password(&self) -> &str {
173        let (end, start) = (self.username_end as usize, self.host_start as usize);
174        if end < start && self.s.as_bytes()[end] == b':' {
175            &self.s[end + 1..start - 1]
176        } else {
177            ""
178        }
179    }
180
181    pub fn set_password(&mut self, value: &str) {
182        self.set_userinfo(value, |p| &mut p.password);
183    }
184
185    /// The host and, if there is one, the port.
186    pub fn host(&self) -> &str {
187        if self.host == HostKind::None {
188            return "";
189        }
190        &self.s[self.host_start as usize..self.path_start as usize]
191    }
192
193    pub fn set_host(&mut self, value: &str) {
194        self.set_host_with(value, false);
195    }
196
197    /// The host without the port.
198    pub fn hostname(&self) -> &str {
199        &self.s[self.host_start as usize..self.host_end as usize]
200    }
201
202    pub fn set_hostname(&mut self, value: &str) {
203        self.set_host_with(value, true);
204    }
205
206    /// The port, empty when it's absent or the scheme's default.
207    pub fn port(&self) -> &str {
208        match self.port {
209            Some(_) => &self.s[self.host_end as usize + 1..self.path_start as usize],
210            None => "",
211        }
212    }
213
214    pub fn set_port(&mut self, value: &str) {
215        self.set_port_value(value);
216    }
217
218    pub fn pathname(&self) -> &str {
219        let end = self
220            .query_start
221            .or(self.fragment_start)
222            .map_or(self.s.len(), |e| e as usize);
223        &self.s[self.path_start as usize..end]
224    }
225
226    pub fn set_pathname(&mut self, value: &str) {
227        self.set_path(value);
228    }
229
230    /// The query with its `?`, or empty when it's absent or empty.
231    pub fn search(&self) -> &str {
232        match self.query() {
233            Some(q) if !q.is_empty() => {
234                let start = self.query_start.unwrap_or(0) as usize;
235                &self.s[start..start + 1 + q.len()]
236            }
237            _ => "",
238        }
239    }
240
241    pub fn set_search(&mut self, value: &str) {
242        self.set_query_value(value);
243    }
244
245    /// The fragment with its `#`, or empty when it's absent or empty.
246    pub fn hash(&self) -> &str {
247        match self.fragment_start {
248            Some(f) if (f as usize) + 1 < self.s.len() => &self.s[f as usize..],
249            _ => "",
250        }
251    }
252
253    pub fn set_hash(&mut self, value: &str) {
254        self.set_fragment_value(value);
255    }
256
257    /// The query parsed as `application/x-www-form-urlencoded`, the list
258    /// `url.searchParams` starts from.
259    pub fn search_params(&self) -> SearchParams {
260        // Not `SearchParams::parse`, which drops a leading `?`: the query of
261        // `??a` is `?a`, and its first name is `?a`.
262        SearchParams {
263            list: form::parse(self.query().unwrap_or("")),
264        }
265    }
266
267    /// Writes `params` back as the query, as changing `url.searchParams`
268    /// does: an empty list removes the query, `?` and all.
269    pub fn set_search_params(&mut self, params: &SearchParams) {
270        if params.is_empty() {
271            self.set_raw_query(None);
272        } else {
273            self.set_raw_query(Some(&params.to_string()));
274        }
275    }
276}
277
278impl PartialEq for Url {
279    fn eq(&self, other: &Url) -> bool {
280        self.s == other.s
281    }
282}
283
284impl Eq for Url {}
285
286impl PartialOrd for Url {
287    fn partial_cmp(&self, other: &Url) -> Option<Ordering> {
288        Some(self.cmp(other))
289    }
290}
291
292impl Ord for Url {
293    fn cmp(&self, other: &Url) -> Ordering {
294        self.s.cmp(&other.s)
295    }
296}
297
298impl Hash for Url {
299    fn hash<H: Hasher>(&self, state: &mut H) {
300        self.s.hash(state);
301    }
302}
303
304impl fmt::Display for Url {
305    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
306        f.write_str(self.href())
307    }
308}
309
310impl FromStr for Url {
311    type Err = ParseError;
312
313    fn from_str(s: &str) -> Result<Url, ParseError> {
314        Url::parse(s)
315    }
316}
317
318impl AsRef<str> for Url {
319    fn as_ref(&self) -> &str {
320        self.href()
321    }
322}
323
324/// `URLSearchParams`: an ordered list of name-value pairs, read from and
325/// written as `application/x-www-form-urlencoded`.
326#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
327pub struct SearchParams {
328    list: Vec<(String, String)>,
329}
330
331impl SearchParams {
332    pub fn new() -> SearchParams {
333        SearchParams::default()
334    }
335
336    /// Parses a query string, `new URLSearchParams(init)`; one leading `?`
337    /// is dropped. Bytes that aren't UTF-8 once percent-decoded become
338    /// U+FFFD, as the spec says.
339    pub fn parse(init: &str) -> SearchParams {
340        SearchParams {
341            list: form::parse(init.strip_prefix('?').unwrap_or(init)),
342        }
343    }
344
345    /// How many pairs there are: `size`.
346    pub fn len(&self) -> usize {
347        self.list.len()
348    }
349
350    pub fn is_empty(&self) -> bool {
351        self.list.is_empty()
352    }
353
354    pub fn append(&mut self, name: &str, value: &str) {
355        self.list.push((name.to_owned(), value.to_owned()));
356    }
357
358    /// Removes every pair named `name`, or only those whose value is also
359    /// `value` when one is given.
360    pub fn delete(&mut self, name: &str, value: Option<&str>) {
361        self.list
362            .retain(|(n, v)| n != name || value.is_some_and(|value| v != value));
363    }
364
365    /// The first value named `name`.
366    pub fn get(&self, name: &str) -> Option<&str> {
367        self.list
368            .iter()
369            .find(|(n, _)| n == name)
370            .map(|(_, v)| v.as_str())
371    }
372
373    /// Every value named `name`, in order.
374    pub fn get_all(&self, name: &str) -> Vec<&str> {
375        self.list
376            .iter()
377            .filter(|(n, _)| n == name)
378            .map(|(_, v)| v.as_str())
379            .collect()
380    }
381
382    /// Whether a pair is named `name`, and has `value` if one is given.
383    pub fn has(&self, name: &str, value: Option<&str>) -> bool {
384        self.list
385            .iter()
386            .any(|(n, v)| n == name && value.is_none_or(|value| v == value))
387    }
388
389    /// Gives the first pair named `name` this value and removes the rest,
390    /// or appends the pair if there's none.
391    pub fn set(&mut self, name: &str, value: &str) {
392        let mut found = false;
393        self.list.retain_mut(|(n, v)| {
394            if n != name {
395                return true;
396            }
397            if found {
398                return false;
399            }
400            found = true;
401            value.clone_into(v);
402            true
403        });
404        if !found {
405            self.append(name, value);
406        }
407    }
408
409    /// Sorts by name, keeping pairs with the same name in their order. The
410    /// spec compares UTF-16 code units, which puts U+1F308 before U+FB03.
411    pub fn sort(&mut self) {
412        self.list
413            .sort_by(|(a, _), (b, _)| a.encode_utf16().cmp(b.encode_utf16()));
414    }
415
416    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
417        self.list.iter().map(|(n, v)| (n.as_str(), v.as_str()))
418    }
419}
420
421/// The `application/x-www-form-urlencoded` serialization: `toString()`.
422impl fmt::Display for SearchParams {
423    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
424        f.write_str(&form::serialize(self.iter()))
425    }
426}
427
428impl<K: Into<String>, V: Into<String>> FromIterator<(K, V)> for SearchParams {
429    fn from_iter<I: IntoIterator<Item = (K, V)>>(pairs: I) -> SearchParams {
430        SearchParams {
431            list: pairs
432                .into_iter()
433                .map(|(k, v)| (k.into(), v.into()))
434                .collect(),
435        }
436    }
437}
438
439/// A domain the URL Standard's domain to ASCII rejects.
440#[derive(Clone, Copy, Debug, PartialEq, Eq)]
441pub struct InvalidDomain;
442
443impl fmt::Display for InvalidDomain {
444    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
445        f.write_str("invalid domain")
446    }
447}
448
449impl std::error::Error for InvalidDomain {}
450
451/// The URL Standard's [domain parser], which the host parser runs:
452/// `"Bücher.example"` becomes `"xn--bcher-kva.example"`. An ASCII domain
453/// is only lowercased; any other goes through UTS #46 ToASCII. Either way
454/// the result can't be empty or hold a forbidden domain code point.
455///
456/// [domain parser]: https://url.spec.whatwg.org/#concept-domain-to-ascii
457pub fn domain_to_ascii(domain: &str) -> Result<String, InvalidDomain> {
458    let ascii = if domain.is_ascii() {
459        domain.to_ascii_lowercase()
460    } else {
461        idna::to_ascii(domain).ok_or(InvalidDomain)?
462    };
463    if ascii.is_empty() || ascii.bytes().any(host::forbidden_domain) {
464        return Err(InvalidDomain);
465    }
466    Ok(ascii)
467}
468
469/// The URL Standard's [domain to Unicode], for showing a host to a person:
470/// `"xn--bcher-kva.example"` becomes `"bücher.example"`. A domain that
471/// UTS #46 ToUnicode records an error for comes back as it was.
472///
473/// [domain to Unicode]: https://url.spec.whatwg.org/#concept-domain-to-unicode
474pub fn domain_to_unicode(domain: &str) -> String {
475    match idna::to_unicode(domain) {
476        (unicode, false) => unicode,
477        (_, true) => domain.to_owned(),
478    }
479}