Skip to main content

parsec_url/
punycode.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 James Conway
3
4//! RFC 3492 Punycode, one label at a time and without the `xn--` prefix.
5//!
6//! ```
7//! use parsec_url::punycode;
8//!
9//! assert_eq!(punycode::encode_str("bücher").unwrap(), "bcher-kva");
10//! assert_eq!(punycode::decode_to_string("bcher-kva").unwrap(), "bücher");
11//! ```
12
13const BASE: u32 = 36;
14const T_MIN: u32 = 1;
15const T_MAX: u32 = 26;
16const SKEW: u32 = 38;
17const DAMP: u32 = 700;
18const INITIAL_BIAS: u32 = 72;
19const INITIAL_N: u32 = 128;
20/// The longest label, in code points, that's encoded or decoded to. Both take time that grows with the square of a label's length;
21/// past this a label fails, as the arithmetic overflowing does. A label in
22/// DNS is at most 63 bytes, so no real one comes near it.
23pub const MAX_LABEL: usize = 4_000;
24
25fn adapt(mut delta: u32, points: u32, first: bool) -> u32 {
26    delta /= if first { DAMP } else { 2 };
27    delta += delta / points;
28    let mut k = 0;
29    while delta > ((BASE - T_MIN) * T_MAX) / 2 {
30        delta /= BASE - T_MIN;
31        k += BASE;
32    }
33    k + (BASE - T_MIN + 1) * delta / (delta + SKEW)
34}
35
36fn threshold(k: u32, bias: u32) -> u32 {
37    if k <= bias {
38        T_MIN
39    } else if k >= bias + T_MAX {
40        T_MAX
41    } else {
42        k - bias
43    }
44}
45
46fn digit_value(b: u8) -> Option<u32> {
47    match b {
48        b'a'..=b'z' => Some((b - b'a') as u32),
49        b'A'..=b'Z' => Some((b - b'A') as u32),
50        b'0'..=b'9' => Some((b - b'0') as u32 + 26),
51        _ => None,
52    }
53}
54
55/// Decodes a Punycode label into code points, or `None` if it isn't
56/// valid Punycode or decodes to something that isn't a scalar value.
57pub(crate) fn decode(input: &str) -> Option<Vec<char>> {
58    let bytes = input.as_bytes();
59    let (basic, extended) = match bytes.iter().rposition(|&b| b == b'-') {
60        Some(at) => (&bytes[..at], &bytes[at + 1..]),
61        None => (&bytes[..0], bytes),
62    };
63    if !basic.is_ascii() {
64        return None;
65    }
66    let mut out: Vec<char> = basic.iter().map(|&b| b as char).collect();
67    let (mut n, mut i, mut bias) = (INITIAL_N, 0u32, INITIAL_BIAS);
68    let mut digits = extended.iter();
69    while digits.len() > 0 {
70        let old_i = i;
71        let mut w = 1u32;
72        let mut k = BASE;
73        loop {
74            let digit = digit_value(*digits.next()?)?;
75            i = i.checked_add(digit.checked_mul(w)?)?;
76            let t = threshold(k, bias);
77            if digit < t {
78                break;
79            }
80            w = w.checked_mul(BASE - t)?;
81            k += BASE;
82        }
83        let len = out.len() as u32 + 1;
84        bias = adapt(i - old_i, len, old_i == 0);
85        n = n.checked_add(i / len)?;
86        i %= len;
87        if out.len() >= MAX_LABEL {
88            return None;
89        }
90        out.insert(i as usize, char::from_u32(n)?);
91        i += 1;
92    }
93    Some(out)
94}
95
96/// Encodes code points as Punycode, or `None` on overflow or past
97/// [`MAX_LABEL`].
98pub(crate) fn encode(input: &[char], out: &mut String) -> Option<()> {
99    if input.len() > MAX_LABEL {
100        return None;
101    }
102    let start = out.len();
103    out.extend(input.iter().filter(|c| c.is_ascii()));
104    let basic = (out.len() - start) as u32;
105    if basic > 0 {
106        out.push('-');
107    }
108    let (mut n, mut delta, mut bias) = (INITIAL_N, 0u32, INITIAL_BIAS);
109    let mut handled = basic;
110    let total = input.len() as u32;
111    while handled < total {
112        let m = input.iter().map(|&c| c as u32).filter(|&c| c >= n).min()?;
113        delta = delta.checked_add((m - n).checked_mul(handled + 1)?)?;
114        n = m;
115        for &c in input {
116            let c = c as u32;
117            if c < n {
118                delta = delta.checked_add(1)?;
119            }
120            if c == n {
121                let mut q = delta;
122                let mut k = BASE;
123                loop {
124                    let t = threshold(k, bias);
125                    if q < t {
126                        break;
127                    }
128                    let d = t + (q - t) % (BASE - t);
129                    out.push(digit(d));
130                    q = (q - t) / (BASE - t);
131                    k += BASE;
132                }
133                out.push(digit(q));
134                bias = adapt(delta, handled + 1, handled == basic);
135                delta = 0;
136                handled += 1;
137            }
138        }
139        delta = delta.checked_add(1)?;
140        n = n.checked_add(1)?;
141    }
142    Some(())
143}
144
145fn digit(d: u32) -> char {
146    (if d < 26 {
147        b'a' + d as u8
148    } else {
149        b'0' + (d - 26) as u8
150    }) as char
151}
152
153/// Encodes a label as Punycode: `"bücher"` becomes `"bcher-kva"`. `None`
154/// means the arithmetic overflowed, or the label is over [`MAX_LABEL`].
155pub fn encode_str(input: &str) -> Option<String> {
156    let chars: Vec<char> = input.chars().collect();
157    let mut out = String::with_capacity(input.len());
158    encode(&chars, &mut out)?;
159    Some(out)
160}
161
162/// Decodes a Punycode label: `"bcher-kva"` becomes `"bücher"`. `None` if
163/// it isn't valid Punycode, or decodes to over [`MAX_LABEL`] code points.
164pub fn decode_to_string(input: &str) -> Option<String> {
165    decode(input).map(|chars| chars.into_iter().collect())
166}