icydb_core/db/codec/
cursor.rs

1///
2/// Cursor codec helpers.
3///
4/// This module owns the opaque wire-token format used for continuation cursors.
5/// It intentionally contains only token encoding/decoding logic and no query semantics.
6///
7
8// Defensive decode bound for untrusted cursor token input.
9const MAX_CURSOR_TOKEN_HEX_LEN: usize = 8 * 1024;
10
11///
12/// CursorDecodeError
13///
14
15#[derive(Debug, Eq, thiserror::Error, PartialEq)]
16pub enum CursorDecodeError {
17    #[error("cursor token is empty")]
18    Empty,
19
20    #[error("cursor token exceeds max length: {len} hex chars (max {max})")]
21    TooLong { len: usize, max: usize },
22
23    #[error("cursor token must have an even number of hex characters")]
24    OddLength,
25
26    #[error("invalid hex character at position {position}")]
27    InvalidHex { position: usize },
28}
29
30/// Encode raw cursor bytes as a lowercase hex token.
31#[must_use]
32pub fn encode_cursor(bytes: &[u8]) -> String {
33    let mut out = String::with_capacity(bytes.len() * 2);
34    for byte in bytes {
35        use std::fmt::Write as _;
36        let _ = write!(out, "{byte:02x}");
37    }
38    out
39}
40
41/// Decode a lowercase/uppercase hex cursor token into raw bytes.
42///
43/// The token may include surrounding whitespace, which is trimmed.
44pub fn decode_cursor(token: &str) -> Result<Vec<u8>, CursorDecodeError> {
45    let token = token.trim();
46
47    if token.is_empty() {
48        return Err(CursorDecodeError::Empty);
49    }
50
51    if token.len() > MAX_CURSOR_TOKEN_HEX_LEN {
52        return Err(CursorDecodeError::TooLong {
53            len: token.len(),
54            max: MAX_CURSOR_TOKEN_HEX_LEN,
55        });
56    }
57
58    if !token.len().is_multiple_of(2) {
59        return Err(CursorDecodeError::OddLength);
60    }
61
62    let mut out = Vec::with_capacity(token.len() / 2);
63    let bytes = token.as_bytes();
64
65    for idx in (0..bytes.len()).step_by(2) {
66        let hi = decode_hex_nibble(bytes[idx])
67            .ok_or(CursorDecodeError::InvalidHex { position: idx + 1 })?;
68
69        let lo = decode_hex_nibble(bytes[idx + 1])
70            .ok_or(CursorDecodeError::InvalidHex { position: idx + 2 })?;
71
72        out.push((hi << 4) | lo);
73    }
74
75    Ok(out)
76}
77
78const fn decode_hex_nibble(byte: u8) -> Option<u8> {
79    match byte {
80        b'0'..=b'9' => Some(byte - b'0'),
81        b'a'..=b'f' => Some(byte - b'a' + 10),
82        b'A'..=b'F' => Some(byte - b'A' + 10),
83        _ => None,
84    }
85}
86
87///
88/// TESTS
89///
90
91#[cfg(test)]
92mod tests {
93    use super::{CursorDecodeError, MAX_CURSOR_TOKEN_HEX_LEN, decode_cursor, encode_cursor};
94
95    #[test]
96    fn decode_cursor_rejects_empty_and_whitespace_tokens() {
97        let err = decode_cursor("").expect_err("empty token should be rejected");
98        assert_eq!(err, CursorDecodeError::Empty);
99
100        let err = decode_cursor("   \n\t").expect_err("whitespace token should be rejected");
101        assert_eq!(err, CursorDecodeError::Empty);
102    }
103
104    #[test]
105    fn decode_cursor_rejects_odd_length_tokens() {
106        let err = decode_cursor("abc").expect_err("odd-length token should be rejected");
107        assert_eq!(err, CursorDecodeError::OddLength);
108    }
109
110    #[test]
111    fn decode_cursor_enforces_max_token_length() {
112        let accepted = "aa".repeat(MAX_CURSOR_TOKEN_HEX_LEN / 2);
113        let accepted_bytes = decode_cursor(&accepted).expect("max-sized token should decode");
114        assert_eq!(accepted_bytes.len(), MAX_CURSOR_TOKEN_HEX_LEN / 2);
115
116        let rejected = format!("{accepted}aa");
117        let err = decode_cursor(&rejected).expect_err("oversized token should be rejected");
118        assert_eq!(
119            err,
120            CursorDecodeError::TooLong {
121                len: MAX_CURSOR_TOKEN_HEX_LEN + 2,
122                max: MAX_CURSOR_TOKEN_HEX_LEN
123            }
124        );
125    }
126
127    #[test]
128    fn decode_cursor_rejects_invalid_hex_with_position() {
129        let err = decode_cursor("0x").expect_err("invalid hex nibble should be rejected");
130        assert_eq!(err, CursorDecodeError::InvalidHex { position: 2 });
131    }
132
133    #[test]
134    fn decode_cursor_accepts_mixed_case_and_surrounding_whitespace() {
135        let bytes = decode_cursor("  0aFf10  ").expect("mixed-case hex token should decode");
136        assert_eq!(bytes, vec![0x0a, 0xff, 0x10]);
137    }
138
139    #[test]
140    fn encode_decode_cursor_round_trip_is_stable() {
141        let raw = vec![0x00, 0x01, 0x0a, 0xff];
142        let encoded = encode_cursor(&raw);
143        assert_eq!(encoded, "00010aff");
144
145        let decoded = decode_cursor(&encoded).expect("encoded token should decode");
146        assert_eq!(decoded, raw);
147    }
148}
icydb_core/db/codec/cursor.rs

icydb_core/db/codec/
cursor.rs
