Skip to main content

turnloop_postgres/
types.rs

1//! Common PostgreSQL codecs. `Int8` and `Numeric` remain exact: pg's default
2//! JS parsers use strings. JSON parsing and local-time JS Date construction
3//! belong to the host; neither reads a clock here.
4use crate::{Error, Result, wire::Cursor};
5use std::{borrow::Cow, fmt::Write};
6
7#[derive(Debug, Clone, PartialEq)]
8pub enum Value<'a> {
9    Null,
10    Bool(bool),
11    Int(i32),
12    Int8(i64),
13    Float(f64),
14    Text(Cow<'a, str>),
15    Numeric(Cow<'a, str>),
16    Bytes(Cow<'a, [u8]>),
17    Json(Cow<'a, str>),
18    Uuid(Cow<'a, str>),
19    /// ISO DateStyle text; preserves infinity and local-time timestamp meaning.
20    TemporalText {
21        oid: u32,
22        text: Cow<'a, str>,
23    },
24    /// PostgreSQL epoch: days after 2000-01-01. i32 extrema are infinities.
25    Date(i32),
26    /// Microseconds after 2000-01-01; timestamptz=true means UTC.
27    Timestamp {
28        microseconds: i64,
29        timestamptz: bool,
30    },
31    Array(Vec<Value<'a>>),
32    /// Unknown binary types are deliberately not interpreted as UTF-8.
33    Raw {
34        oid: u32,
35        bytes: Cow<'a, [u8]>,
36    },
37    /// Text-format value of an OID with no codec here (time, interval, inet,
38    /// oid, xml, enums, ...). Distinct from `Text`, which only text, varchar,
39    /// bpchar and name produce, so a host can apply its own parser.
40    Unknown {
41        oid: u32,
42        text: Cow<'a, str>,
43    },
44}
45impl Value<'_> {
46    pub fn into_owned(self) -> Value<'static> {
47        match self {
48            Self::Null => Value::Null,
49            Self::Bool(v) => Value::Bool(v),
50            Self::Int(v) => Value::Int(v),
51            Self::Int8(v) => Value::Int8(v),
52            Self::Float(v) => Value::Float(v),
53            Self::Text(v) => Value::Text(Cow::Owned(v.into_owned())),
54            Self::Numeric(v) => Value::Numeric(Cow::Owned(v.into_owned())),
55            Self::Bytes(v) => Value::Bytes(Cow::Owned(v.into_owned())),
56            Self::Json(v) => Value::Json(Cow::Owned(v.into_owned())),
57            Self::Uuid(v) => Value::Uuid(Cow::Owned(v.into_owned())),
58            Self::TemporalText { oid, text } => Value::TemporalText {
59                oid,
60                text: Cow::Owned(text.into_owned()),
61            },
62            Self::Date(v) => Value::Date(v),
63            Self::Timestamp {
64                microseconds,
65                timestamptz,
66            } => Value::Timestamp {
67                microseconds,
68                timestamptz,
69            },
70            Self::Array(v) => Value::Array(v.into_iter().map(Value::into_owned).collect()),
71            Self::Raw { oid, bytes } => Value::Raw {
72                oid,
73                bytes: Cow::Owned(bytes.into_owned()),
74            },
75            Self::Unknown { oid, text } => Value::Unknown {
76                oid,
77                text: Cow::Owned(text.into_owned()),
78            },
79        }
80    }
81}
82fn text(b: &[u8]) -> Result<&str> {
83    std::str::from_utf8(b).map_err(|_| Error::Protocol("invalid UTF-8 value"))
84}
85fn number<T: std::str::FromStr>(s: &str) -> Result<T> {
86    s.parse()
87        .map_err(|_| Error::Protocol("invalid numeric value"))
88}
89fn array_element(oid: u32) -> Option<u32> {
90    Some(match oid {
91        1000 => 16,
92        1001 => 17,
93        1005 => 21,
94        1007 => 23,
95        1009 => 25,
96        1014 => 1042,
97        1015 => 1043,
98        1016 => 20,
99        1021 => 700,
100        1022 => 701,
101        1115 => 1114,
102        1182 => 1082,
103        1185 => 1184,
104        1231 => 1700,
105        199 => 114,
106        2951 => 2950,
107        3807 => 3802,
108        _ => return None,
109    })
110}
111/// Decode one field. Borrowed text/binary rows remain allocation-free; arrays,
112/// bytea unescaping, binary numeric and binary UUID allocate their result only.
113pub fn decode(oid: u32, format: i16, bytes: Option<&[u8]>) -> Result<Value<'_>> {
114    let Some(b) = bytes else {
115        return Ok(Value::Null);
116    };
117    if !matches!(format, 0 | 1) {
118        return Err(Error::Protocol("invalid value format"));
119    }
120    if let Some(element) = array_element(oid) {
121        return if format == 0 {
122            text_array(element, text(b)?)
123        } else {
124            binary_array(element, b)
125        };
126    }
127    if format == 0 {
128        let s = text(b)?;
129        return Ok(match oid {
130            16 => Value::Bool(match s {
131                "t" => true,
132                "f" => false,
133                _ => return Err(Error::Protocol("invalid boolean")),
134            }),
135            21 | 23 => Value::Int(number(s)?),
136            20 => Value::Int8(number(s)?),
137            700 | 701 => Value::Float(number(s)?),
138            1700 => Value::Numeric(s.into()),
139            17 => Value::Bytes(Cow::Owned(bytea(s)?)),
140            114 | 3802 => Value::Json(s.into()),
141            2950 => Value::Uuid(s.into()),
142            1082 | 1114 | 1184 => Value::TemporalText {
143                oid,
144                text: s.into(),
145            },
146            // The same text OIDs the binary codec accepts.
147            19 | 25 | 1042 | 1043 => Value::Text(s.into()),
148            _ => Value::Unknown {
149                oid,
150                text: s.into(),
151            },
152        });
153    }
154    let mut c = Cursor(b);
155    let value = match oid {
156        16 => Value::Bool(match c.u8()? {
157            0 => false,
158            1 => true,
159            _ => return Err(Error::Protocol("invalid boolean")),
160        }),
161        21 => Value::Int(c.i16()? as i32),
162        23 => Value::Int(c.i32()?),
163        20 => Value::Int8(i64::from_be_bytes(c.take(8)?.try_into().unwrap())),
164        700 => Value::Float(f32::from_be_bytes(c.take(4)?.try_into().unwrap()) as f64),
165        701 => Value::Float(f64::from_be_bytes(c.take(8)?.try_into().unwrap())),
166        17 => {
167            c.take(b.len())?;
168            Value::Bytes(b.into())
169        }
170        25 | 1042 | 1043 | 19 => {
171            c.take(b.len())?;
172            Value::Text(text(b)?.into())
173        }
174        114 => {
175            c.take(b.len())?;
176            Value::Json(text(b)?.into())
177        }
178        3802 => {
179            if c.u8()? != 1 {
180                return Err(Error::Protocol("unsupported jsonb version"));
181            }
182            let s = text(c.0)?;
183            c.take(c.0.len())?;
184            Value::Json(s.into())
185        }
186        1082 => Value::Date(c.i32()?),
187        1114 | 1184 => Value::Timestamp {
188            microseconds: i64::from_be_bytes(c.take(8)?.try_into().unwrap()),
189            timestamptz: oid == 1184,
190        },
191        2950 => {
192            let bytes = c.take(16)?;
193            let mut s = String::with_capacity(36);
194            for (i, b) in bytes.iter().enumerate() {
195                if matches!(i, 4 | 6 | 8 | 10) {
196                    s.push('-');
197                }
198                write!(s, "{b:02x}").unwrap();
199            }
200            Value::Uuid(s.into())
201        }
202        1700 => {
203            c.take(b.len())?;
204            Value::Numeric(numeric(b)?.into())
205        }
206        _ => {
207            c.take(b.len())?;
208            Value::Raw {
209                oid,
210                bytes: b.into(),
211            }
212        }
213    };
214    c.end()?;
215    Ok(value)
216}
217fn bytea(s: &str) -> Result<Vec<u8>> {
218    let mut out = Vec::with_capacity(s.len() / 2);
219    if let Some(hex) = s.strip_prefix("\\x") {
220        if hex.len() % 2 != 0 {
221            return Err(Error::Protocol("odd bytea hex length"));
222        }
223        for pair in hex.as_bytes().as_chunks::<2>().0 {
224            let h = |b: u8| {
225                (b as char)
226                    .to_digit(16)
227                    .map(|v| v as u8)
228                    .ok_or(Error::Protocol("invalid bytea hex"))
229            };
230            out.push(h(pair[0])? * 16 + h(pair[1])?);
231        }
232    } else {
233        let mut c = Cursor(s.as_bytes());
234        while !c.0.is_empty() {
235            let b = c.u8()?;
236            if b != b'\\' {
237                out.push(b);
238            } else if c.0.first() == Some(&b'\\') {
239                c.u8()?;
240                out.push(b'\\');
241            } else {
242                let b = c.take(3)?;
243                if b[0] > b'3' || b.iter().any(|v| !(b'0'..=b'7').contains(v)) {
244                    return Err(Error::Protocol("invalid bytea escape"));
245                }
246                out.push((b[0] - b'0') * 64 + (b[1] - b'0') * 8 + b[2] - b'0');
247            }
248        }
249    }
250    Ok(out)
251}
252fn numeric(b: &[u8]) -> Result<String> {
253    let mut c = Cursor(b);
254    let count = c.u16()? as usize;
255    let weight = c.i16()? as i32;
256    let sign = c.u16()?;
257    let scale = c.u16()? as usize;
258    let digits = c.take(count.checked_mul(2).ok_or(Error::Limit)?)?;
259    c.end()?;
260    if count > 32767 || scale > 16383 {
261        return Err(Error::Protocol("invalid numeric scale"));
262    }
263    for d in digits.as_chunks::<2>().0 {
264        if u16::from_be_bytes(*d) >= 10000 {
265            return Err(Error::Protocol("invalid numeric digit"));
266        }
267    }
268    if let Some(s) = match sign {
269        0xc000 => Some("NaN"),
270        0xd000 => Some("Infinity"),
271        0xf000 => Some("-Infinity"),
272        0 | 0x4000 => None,
273        _ => return Err(Error::Protocol("invalid numeric sign")),
274    } {
275        return Ok(s.into());
276    }
277    let digit = |power: i32| {
278        let i = weight - power;
279        if i < 0 || i as usize >= count {
280            0
281        } else {
282            u16::from_be_bytes(
283                digits[i as usize * 2..i as usize * 2 + 2]
284                    .try_into()
285                    .unwrap(),
286            )
287        }
288    };
289    let mut s = String::new();
290    if sign == 0x4000 {
291        s.push('-');
292    }
293    if weight < 0 {
294        s.push('0');
295    } else {
296        for power in (0..=weight).rev() {
297            if power == weight {
298                write!(s, "{}", digit(power)).unwrap();
299            } else {
300                write!(s, "{:04}", digit(power)).unwrap();
301            }
302        }
303    }
304    if scale > 0 {
305        s.push('.');
306        let start = s.len();
307        for i in 1..=scale.div_ceil(4) {
308            write!(s, "{:04}", digit(-(i as i32))).unwrap();
309        }
310        s.truncate(start + scale);
311    }
312    Ok(s)
313}
314fn binary_array(element: u32, b: &[u8]) -> Result<Value<'_>> {
315    let mut c = Cursor(b);
316    let dimensions = c.i32()?;
317    let nulls = c.i32()?;
318    let actual = c.u32()?;
319    if !(0..=6).contains(&dimensions) || !matches!(nulls, 0 | 1) || actual != element {
320        return Err(Error::Protocol("invalid array header"));
321    }
322    let mut shape = [0usize; 6];
323    let mut count = if dimensions == 0 { 0 } else { 1usize };
324    for n in &mut shape[..dimensions as usize] {
325        let len = c.i32()?;
326        c.i32()?;
327        if len < 0 {
328            return Err(Error::Protocol("negative array length"));
329        }
330        *n = len as usize;
331        count = count.checked_mul(*n).ok_or(Error::Limit)?;
332    }
333    if count > c.0.len() / 4 {
334        return Err(Error::Protocol("truncated array elements"));
335    }
336    fn values<'a>(c: &mut Cursor<'a>, shape: &[usize], element: u32) -> Result<Value<'a>> {
337        let mut out = Vec::with_capacity(shape.first().copied().unwrap_or(0));
338        if let Some(&n) = shape.first() {
339            for _ in 0..n {
340                out.push(if shape.len() > 1 {
341                    values(c, &shape[1..], element)?
342                } else {
343                    let len = c.i32()?;
344                    let bytes = match len {
345                        -1 => None,
346                        0.. => Some(c.take(len as usize)?),
347                        _ => return Err(Error::Protocol("invalid array element length")),
348                    };
349                    decode(element, 1, bytes)?
350                });
351            }
352        }
353        Ok(Value::Array(out))
354    }
355    let v = values(&mut c, &shape[..dimensions as usize], element)?;
356    c.end()?;
357    Ok(v)
358}
359fn text_array(element: u32, s: &str) -> Result<Value<'_>> {
360    let mut c = Cursor(s.as_bytes());
361    let has_bounds = c.0.first() == Some(&b'[');
362    // pg drops custom lower bounds in the JS array. Validate the prefix grammar.
363    while c.0.first() == Some(&b'[') {
364        c.u8()?;
365        let end =
366            c.0.iter()
367                .position(|b| *b == b']')
368                .ok_or(Error::Protocol("invalid array bounds"))?;
369        let bounds = text(c.take(end)?)?;
370        let (low, high) = bounds
371            .split_once(':')
372            .ok_or(Error::Protocol("invalid array bounds"))?;
373        let _: i32 = number(low)?;
374        let _: i32 = number(high)?;
375        c.u8()?;
376    }
377    if has_bounds && c.u8()? != b'=' {
378        return Err(Error::Protocol("array bounds require equals"));
379    }
380    fn array<'a>(c: &mut Cursor<'a>, element: u32, depth: usize) -> Result<Value<'a>> {
381        if depth > 6 || c.u8()? != b'{' {
382            return Err(Error::Protocol("invalid array nesting"));
383        }
384        let mut values = Vec::new();
385        if c.0.first() == Some(&b'}') {
386            c.u8()?;
387            return Ok(Value::Array(values));
388        }
389        loop {
390            if c.0.first() == Some(&b'{') {
391                values.push(array(c, element, depth + 1)?);
392            } else {
393                let quoted = c.0.first() == Some(&b'"');
394                if quoted {
395                    c.u8()?;
396                }
397                let start = c.0;
398                let mut end = 0;
399                let mut escaped = false;
400                loop {
401                    let b = *c.0.get(end).ok_or(Error::Protocol("unterminated array"))?;
402                    if b == b'\\' {
403                        escaped = true;
404                        end += 2;
405                        if end > c.0.len() {
406                            return Err(Error::Protocol("truncated array escape"));
407                        }
408                        continue;
409                    }
410                    if (quoted && b == b'"') || (!quoted && matches!(b, b',' | b'}')) {
411                        break;
412                    }
413                    end += 1;
414                }
415                c.take(end)?;
416                if quoted {
417                    c.u8()?;
418                }
419                let raw = &start[..end];
420                if !quoted && raw.is_empty() {
421                    return Err(Error::Protocol("empty unquoted array element"));
422                }
423                if !quoted && raw == b"NULL" {
424                    values.push(Value::Null);
425                } else if escaped {
426                    let mut buf = Vec::with_capacity(raw.len());
427                    let mut i = 0;
428                    while i < raw.len() {
429                        if raw[i] == b'\\' {
430                            i += 1;
431                        }
432                        buf.push(raw[i]);
433                        i += 1;
434                    }
435                    values.push(decode(element, 0, Some(&buf))?.into_owned());
436                } else {
437                    values.push(decode(element, 0, Some(raw))?);
438                }
439            }
440            match c.u8()? {
441                b',' => {}
442                b'}' => break,
443                _ => return Err(Error::Protocol("invalid array separator")),
444            }
445        }
446        Ok(Value::Array(values))
447    }
448    let v = array(&mut c, element, 1)?;
449    c.end()?;
450    Ok(v)
451}
452
453#[cfg(test)]
454mod tests {
455    use super::*;
456    #[test]
457    fn common_types_and_arrays() {
458        assert_eq!(
459            decode(20, 0, Some(b"9223372036854775807")).unwrap(),
460            Value::Int8(i64::MAX)
461        );
462        assert_eq!(
463            decode(1700, 0, Some(b"1.2300")).unwrap(),
464            Value::Numeric("1.2300".into())
465        );
466        assert_eq!(
467            decode(17, 0, Some(b"\\x00ff")).unwrap(),
468            Value::Bytes(vec![0, 255].into())
469        );
470        assert_eq!(
471            decode(1009, 0, Some(br#"{"hello, world","NULL",NULL,"a\\b"}"#)).unwrap(),
472            Value::Array(vec![
473                Value::Text("hello, world".into()),
474                Value::Text("NULL".into()),
475                Value::Null,
476                Value::Text("a\\b".into())
477            ])
478        );
479        assert_eq!(
480            decode(1007, 0, Some(b"[2:3]={1,2}")).unwrap(),
481            Value::Array(vec![Value::Int(1), Value::Int(2)])
482        );
483        assert!(decode(1007, 0, Some(b"{1,}")).is_err());
484        let numeric = [0, 2, 0, 0, 0, 0, 0, 4, 0, 1, 8, 252];
485        assert_eq!(
486            decode(1700, 1, Some(&numeric)).unwrap(),
487            Value::Numeric("1.2300".into())
488        );
489        assert_eq!(
490            decode(3802, 1, Some(b"\x01{\"x\":1}")).unwrap(),
491            Value::Json("{\"x\":1}".into())
492        );
493        assert!(decode(23, 1, Some(&[1])).is_err());
494        assert_eq!(
495            decode(2950, 1, Some(&[0; 16])).unwrap(),
496            Value::Uuid("00000000-0000-0000-0000-000000000000".into())
497        );
498        let mut array = Vec::new();
499        for n in [1i32, 1, 23, 2, 1, 4, 42, -1] {
500            array.extend_from_slice(&n.to_be_bytes());
501        }
502        assert_eq!(
503            decode(1007, 1, Some(&array)).unwrap(),
504            Value::Array(vec![Value::Int(42), Value::Null])
505        );
506    }
507    #[test]
508    fn unknown_text_oids_are_not_reported_as_text() {
509        for oid in [19, 25, 1042, 1043] {
510            assert_eq!(
511                decode(oid, 0, Some(b"hello")).unwrap(),
512                Value::Text("hello".into()),
513                "OID {oid}"
514            );
515        }
516        // time, interval, inet, oid and an arbitrary enum/extension OID.
517        for (oid, text) in [
518            (1083, "12:34:56"),
519            (1186, "1 day"),
520            (869, "127.0.0.1"),
521            (26, "16384"),
522            (91_234, "happy"),
523        ] {
524            let value = decode(oid, 0, Some(text.as_bytes())).unwrap();
525            assert_eq!(
526                value,
527                Value::Unknown {
528                    oid,
529                    text: text.into()
530                }
531            );
532            assert!(matches!(
533                value.into_owned(),
534                Value::Unknown { oid: o, text: Cow::Owned(t) } if o == oid && t == text
535            ));
536        }
537        // Binary unknowns stay uninterpreted bytes.
538        assert_eq!(
539            decode(1083, 1, Some(&[0; 8])).unwrap(),
540            Value::Raw {
541                oid: 1083,
542                bytes: Cow::Borrowed(&[0; 8])
543            }
544        );
545        assert!(decode(1083, 0, Some(&[0xff])).is_err());
546    }
547}