Skip to main content

udb_client/
record.rs

1//! Decoding relational reads.
2//!
3//! # Why this module exists
4//!
5//! [`RecordSet`] carries a returned page in TWO parallel representations, and
6//! only one of them is canonical:
7//!
8//! - **`records_json`** — one JSON object per record. This is the data. Every
9//!   other UDB SDK (Go, TypeScript, Python, Java, C#, PHP) reads it.
10//! - **`rows`** — a `map<string, google.protobuf.Value>` per record, kept for
11//!   wire compatibility. The broker emits it EMPTY on the relational read path.
12//!
13//! The proto declares both without a discriminator, so the generated struct
14//! gives no hint which one to read. Reading `rows` compiles, type-checks, and
15//! returns the correct RECORD COUNT with every field map empty — a populated
16//! table reads back as a page of empty entities, with no error anywhere. That is
17//! the failure this module exists to make impossible.
18//!
19//! [`Records::decode`] reads the canonical representation, fails closed on a
20//! structurally inconsistent page, and preserves integer values exactly.
21//!
22//! ```no_run
23//! # use udb_client::{Records, UdbClient};
24//! # async fn example(udb: &mut UdbClient, req: udb_client::proto::udb::entity::v1::SelectRequest)
25//! # -> Result<(), Box<dyn std::error::Error>> {
26//! let records = Records::decode(&udb.select(req).await?)?;
27//! for record in records.iter() {
28//!     println!("{} — {}", record.str("id")?, record.i64("amount_minor")?);
29//! }
30//! # Ok(())
31//! # }
32//! ```
33//!
34//! # Integer exactness
35//!
36//! Values are decoded with `serde_json`, whose `Number` holds `i64`/`u64`
37//! natively, so `9007199254740993` survives. They are deliberately NOT routed
38//! through `prost_types::Value`, whose only numeric kind is `NumberValue(f64)` —
39//! that representation cannot hold a 64-bit integer, and rounds silently.
40//! [`Record::i64`] and [`Record::u64`] reject a value that is not an exact
41//! integer of that width rather than truncating it.
42
43use std::collections::BTreeMap;
44use std::fmt;
45
46use serde_json::{Map, Value};
47
48use crate::proto::udb::entity::v1::RecordSet;
49
50/// One decoded record: the broker's canonical JSON object for a single row.
51#[derive(Debug, Clone, PartialEq)]
52pub struct Record {
53    fields: Map<String, Value>,
54    revision: Option<String>,
55}
56
57impl Record {
58    /// The record's fields, exactly as the broker serialized them.
59    pub fn fields(&self) -> &Map<String, Value> {
60        &self.fields
61    }
62
63    /// Consume the record and take its fields.
64    pub fn into_fields(self) -> Map<String, Value> {
65        self.fields
66    }
67
68    /// The opaque revision token for this record, when the read asked for one
69    /// (`SelectRequest::include_revision`).
70    ///
71    /// Feed it back as `UpdateRequest::expected_revision` /
72    /// `DeleteRequest::expected_revision` for optimistic concurrency.
73    pub fn revision(&self) -> Option<&str> {
74        self.revision.as_deref()
75    }
76
77    /// Raw access to one field. `None` when the column is absent from the
78    /// projection — distinct from present-and-SQL-NULL, which is
79    /// `Some(Value::Null)`.
80    pub fn get(&self, field: &str) -> Option<&Value> {
81        self.fields.get(field)
82    }
83
84    /// Whether the field is present and SQL NULL.
85    pub fn is_null(&self, field: &str) -> bool {
86        matches!(self.fields.get(field), Some(Value::Null))
87    }
88
89    /// A present, non-NULL field, or a typed error naming which of the two it
90    /// was. Absent and NULL are separate errors on purpose: a caller reading a
91    /// column that was never selected has a different bug from one reading a
92    /// column that is legitimately empty.
93    fn required(&self, field: &str) -> Result<&Value, DecodeError> {
94        match self.fields.get(field) {
95            None => Err(DecodeError::MissingField {
96                field: field.to_string(),
97            }),
98            Some(Value::Null) => Err(DecodeError::NullField {
99                field: field.to_string(),
100            }),
101            Some(value) => Ok(value),
102        }
103    }
104
105    fn wrong_type(field: &str, expected: &'static str, found: &Value) -> DecodeError {
106        DecodeError::UnexpectedType {
107            field: field.to_string(),
108            expected,
109            found: json_kind(found),
110        }
111    }
112
113    /// A required string field.
114    pub fn str(&self, field: &str) -> Result<&str, DecodeError> {
115        match self.required(field)? {
116            Value::String(text) => Ok(text),
117            other => Err(Self::wrong_type(field, "string", other)),
118        }
119    }
120
121    /// A required boolean field.
122    pub fn bool(&self, field: &str) -> Result<bool, DecodeError> {
123        match self.required(field)? {
124            Value::Bool(value) => Ok(*value),
125            other => Err(Self::wrong_type(field, "bool", other)),
126        }
127    }
128
129    /// A required signed 64-bit integer.
130    ///
131    /// Fails rather than truncating when the value is fractional, out of `i64`
132    /// range, or lost precision before it reached us.
133    pub fn i64(&self, field: &str) -> Result<i64, DecodeError> {
134        let value = self.required(field)?;
135        let Value::Number(number) = value else {
136            return Err(Self::wrong_type(field, "integer", value));
137        };
138        number
139            .as_i64()
140            .ok_or_else(|| inexact_integer(field, number))
141    }
142
143    /// A required unsigned 64-bit integer.
144    pub fn u64(&self, field: &str) -> Result<u64, DecodeError> {
145        let value = self.required(field)?;
146        let Value::Number(number) = value else {
147            return Err(Self::wrong_type(field, "integer", value));
148        };
149        number
150            .as_u64()
151            .ok_or_else(|| inexact_integer(field, number))
152    }
153
154    /// A required signed 32-bit integer. Rejects anything outside `i32` rather
155    /// than wrapping — a narrowing cast is how an out-of-range BIGINT becomes a
156    /// plausible small number.
157    pub fn i32(&self, field: &str) -> Result<i32, DecodeError> {
158        let wide = self.i64(field)?;
159        i32::try_from(wide).map_err(|_| DecodeError::IntegerOutOfRange {
160            field: field.to_string(),
161            width: "i32",
162            value: wide.to_string(),
163        })
164    }
165
166    /// A required floating-point field. Accepts an integer-valued number too,
167    /// since JSON does not distinguish `1` from `1.0`.
168    pub fn f64(&self, field: &str) -> Result<f64, DecodeError> {
169        let value = self.required(field)?;
170        match value {
171            Value::Number(number) => number.as_f64().ok_or_else(|| DecodeError::UnexpectedType {
172                field: field.to_string(),
173                expected: "float",
174                found: "number out of f64 range",
175            }),
176            other => Err(Self::wrong_type(field, "float", other)),
177        }
178    }
179
180    /// A required `BYTEA` field.
181    ///
182    /// The broker base64-encodes binary columns so they survive JSON. Some
183    /// executor paths additionally tag the cell with a `base64:` prefix; both
184    /// spellings decode here so a caller does not have to know which path served
185    /// the read.
186    pub fn bytes(&self, field: &str) -> Result<Vec<u8>, DecodeError> {
187        use base64::Engine as _;
188
189        let value = self.required(field)?;
190        let Value::String(text) = value else {
191            return Err(Self::wrong_type(field, "base64 string", value));
192        };
193        let body = text.strip_prefix("base64:").unwrap_or(text);
194        base64::engine::general_purpose::STANDARD
195            .decode(body)
196            .map_err(|err| DecodeError::InvalidBase64 {
197                field: field.to_string(),
198                reason: err.to_string(),
199            })
200    }
201
202    /// A required timestamp, as the RFC 3339 text the broker emitted.
203    ///
204    /// Returned as `&str` rather than a parsed instant so this crate does not
205    /// force a date-time library on its callers; hand it to whichever one the
206    /// consumer already uses. `TIMESTAMPTZ` is emitted in the canonical `Z`
207    /// form.
208    pub fn timestamp(&self, field: &str) -> Result<&str, DecodeError> {
209        self.str(field)
210    }
211
212    /// A required JSON/JSONB object field.
213    pub fn object(&self, field: &str) -> Result<&Map<String, Value>, DecodeError> {
214        match self.required(field)? {
215            Value::Object(map) => Ok(map),
216            other => Err(Self::wrong_type(field, "object", other)),
217        }
218    }
219
220    /// A required array field.
221    pub fn array(&self, field: &str) -> Result<&[Value], DecodeError> {
222        match self.required(field)? {
223            Value::Array(items) => Ok(items),
224            other => Err(Self::wrong_type(field, "array", other)),
225        }
226    }
227
228    /// `Ok(None)` when the field is absent or NULL, otherwise the decoded value.
229    ///
230    /// Wraps any accessor above:
231    /// `record.optional("closed_at", Record::timestamp)?`.
232    pub fn optional<'a, T, F>(&'a self, field: &str, read: F) -> Result<Option<T>, DecodeError>
233    where
234        F: FnOnce(&'a Self, &str) -> Result<T, DecodeError>,
235    {
236        match self.fields.get(field) {
237            None | Some(Value::Null) => Ok(None),
238            Some(_) => read(self, field).map(Some),
239        }
240    }
241}
242
243/// A decoded page of records, plus the page metadata that came with it.
244#[derive(Debug, Clone, PartialEq)]
245pub struct Records {
246    records: Vec<Record>,
247    has_more: bool,
248    exact_total: i64,
249    next_page_token: String,
250}
251
252impl Records {
253    /// Decode a [`RecordSet`] into its canonical records.
254    ///
255    /// Fails closed rather than returning a plausible-but-wrong page. In
256    /// particular a set whose `rows` are populated while `records_json` is empty
257    /// is rejected instead of being reported as zero records — that shape is the
258    /// signature of reading the compatibility representation, and silently
259    /// turning it into an empty result is precisely the data-loss this decoder
260    /// exists to prevent.
261    pub fn decode(set: &RecordSet) -> Result<Self, DecodeError> {
262        if set.records_json.is_empty() && !set.rows.is_empty() {
263            return Err(DecodeError::CanonicalRecordsMissing {
264                rows: set.rows.len(),
265            });
266        }
267        // `rows` is index-aligned with `records_json` when present at all. The
268        // broker emits one empty entry per record on the relational path, so a
269        // DIFFERENT non-zero length means the two representations disagree about
270        // how many records this page holds, and neither can be trusted.
271        if !set.rows.is_empty() && set.rows.len() != set.records_json.len() {
272            return Err(DecodeError::LengthMismatch {
273                what: "rows",
274                expected: set.records_json.len(),
275                found: set.rows.len(),
276            });
277        }
278        // Revisions are absent unless the read asked for them; when present they
279        // are index-aligned, and a misalignment would attach a record's revision
280        // token to a DIFFERENT record — an optimistic-concurrency write against
281        // the wrong row.
282        if !set.record_revisions.is_empty() && set.record_revisions.len() != set.records_json.len()
283        {
284            return Err(DecodeError::LengthMismatch {
285                what: "record_revisions",
286                expected: set.records_json.len(),
287                found: set.record_revisions.len(),
288            });
289        }
290
291        let mut records = Vec::with_capacity(set.records_json.len());
292        for (index, blob) in set.records_json.iter().enumerate() {
293            if blob.is_empty() {
294                return Err(DecodeError::EmptyRecord { index });
295            }
296            let value: Value =
297                serde_json::from_slice(blob).map_err(|err| DecodeError::Malformed {
298                    index,
299                    reason: err.to_string(),
300                })?;
301            let Value::Object(fields) = value else {
302                return Err(DecodeError::NotAnObject {
303                    index,
304                    found: json_kind(&value),
305                });
306            };
307            records.push(Record {
308                fields,
309                // An empty slot means "no tracked revision yet", which is not the
310                // same as "revisions were not requested" — keep only a non-empty
311                // token.
312                revision: set
313                    .record_revisions
314                    .get(index)
315                    .filter(|token| !token.is_empty())
316                    .cloned(),
317            });
318        }
319
320        Ok(Self {
321            records,
322            // Reported, not enforced: `records.len()` is authoritative for what
323            // is in hand. `has_more` says whether to keep paging; `exact_total`
324            // is the match count, set only when the read asked for it.
325            has_more: set.has_more,
326            exact_total: set.exact_total,
327            next_page_token: set.next_page_token.clone(),
328        })
329    }
330
331    /// Number of records on this page.
332    pub fn len(&self) -> usize {
333        self.records.len()
334    }
335
336    pub fn is_empty(&self) -> bool {
337        self.records.is_empty()
338    }
339
340    pub fn iter(&self) -> std::slice::Iter<'_, Record> {
341        self.records.iter()
342    }
343
344    pub fn get(&self, index: usize) -> Option<&Record> {
345        self.records.get(index)
346    }
347
348    /// True when the page is full and more rows may match: keep paging with
349    /// [`Records::next_page_token`].
350    pub fn has_more(&self) -> bool {
351        self.has_more
352    }
353
354    /// Every row the filter matches, ignoring the limit and page position. Set
355    /// only when the read asked for it (`SelectRequest.include_total`); 0
356    /// otherwise. Use [`Records::len`] for how many records are in this page.
357    pub fn exact_total(&self) -> i64 {
358        self.exact_total
359    }
360
361    /// Token for the next page, empty when this is the last one.
362    pub fn next_page_token(&self) -> &str {
363        &self.next_page_token
364    }
365
366    pub fn into_records(self) -> Vec<Record> {
367        self.records
368    }
369}
370
371impl<'a> IntoIterator for &'a Records {
372    type Item = &'a Record;
373    type IntoIter = std::slice::Iter<'a, Record>;
374
375    fn into_iter(self) -> Self::IntoIter {
376        self.records.iter()
377    }
378}
379
380impl IntoIterator for Records {
381    type Item = Record;
382    type IntoIter = std::vec::IntoIter<Record>;
383
384    fn into_iter(self) -> Self::IntoIter {
385        self.records.into_iter()
386    }
387}
388
389/// Why a [`RecordSet`] or one of its fields could not be decoded.
390///
391/// Every variant names the record index or field, so a failure points at the
392/// data rather than at this module.
393#[derive(Debug, Clone, PartialEq, Eq)]
394pub enum DecodeError {
395    /// The set carries compatibility `rows` but no canonical `records_json`.
396    CanonicalRecordsMissing { rows: usize },
397    /// A parallel array disagreed with `records_json` about the record count.
398    LengthMismatch {
399        what: &'static str,
400        expected: usize,
401        found: usize,
402    },
403    /// A record body was zero bytes.
404    EmptyRecord { index: usize },
405    /// A record body was not valid JSON.
406    Malformed { index: usize, reason: String },
407    /// A record body was valid JSON but not a JSON object.
408    NotAnObject { index: usize, found: &'static str },
409    /// The field was not in the returned projection.
410    MissingField { field: String },
411    /// The field was present and SQL NULL.
412    NullField { field: String },
413    /// The field held a different JSON kind than the accessor asked for.
414    UnexpectedType {
415        field: String,
416        expected: &'static str,
417        found: &'static str,
418    },
419    /// A numeric field was not an exact integer of the requested width —
420    /// fractional, or beyond what the type can hold.
421    NotAnExactInteger { field: String, value: String },
422    /// An integer was exact but outside the narrower requested width.
423    IntegerOutOfRange {
424        field: String,
425        width: &'static str,
426        value: String,
427    },
428    /// A binary field was not decodable base64.
429    InvalidBase64 { field: String, reason: String },
430}
431
432impl fmt::Display for DecodeError {
433    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
434        match self {
435            Self::CanonicalRecordsMissing { rows } => write!(
436                f,
437                "record set carries {rows} compatibility row(s) but no records_json: the canonical \
438                 records are missing, so this is not an empty result"
439            ),
440            Self::LengthMismatch {
441                what,
442                expected,
443                found,
444            } => write!(
445                f,
446                "record set is inconsistent: {found} {what} against {expected} record(s)"
447            ),
448            Self::EmptyRecord { index } => {
449                write!(f, "record {index} has an empty body")
450            }
451            Self::Malformed { index, reason } => {
452                write!(f, "record {index} is not valid JSON: {reason}")
453            }
454            Self::NotAnObject { index, found } => {
455                write!(f, "record {index} is a JSON {found}, expected an object")
456            }
457            Self::MissingField { field } => {
458                write!(f, "field `{field}` is not in the returned projection")
459            }
460            Self::NullField { field } => write!(f, "field `{field}` is NULL"),
461            Self::UnexpectedType {
462                field,
463                expected,
464                found,
465            } => write!(f, "field `{field}` is a {found}, expected {expected}"),
466            Self::NotAnExactInteger { field, value } => write!(
467                f,
468                "field `{field}` holds {value}, which is not an exact integer of the requested width"
469            ),
470            Self::IntegerOutOfRange {
471                field,
472                width,
473                value,
474            } => write!(f, "field `{field}` holds {value}, out of range for {width}"),
475            Self::InvalidBase64 { field, reason } => {
476                write!(f, "field `{field}` is not valid base64: {reason}")
477            }
478        }
479    }
480}
481
482impl std::error::Error for DecodeError {}
483
484fn inexact_integer(field: &str, number: &serde_json::Number) -> DecodeError {
485    DecodeError::NotAnExactInteger {
486        field: field.to_string(),
487        value: number.to_string(),
488    }
489}
490
491fn json_kind(value: &Value) -> &'static str {
492    match value {
493        Value::Null => "null",
494        Value::Bool(_) => "bool",
495        Value::Number(_) => "number",
496        Value::String(_) => "string",
497        Value::Array(_) => "array",
498        Value::Object(_) => "object",
499    }
500}
501
502/// Build the `rows`-shaped map a caller might expect, from the canonical
503/// records, for the narrow case of code that already speaks
504/// `google.protobuf.Value`.
505///
506/// Provided so such a caller does not hand-roll the conversion and reintroduce
507/// the f64 rounding this module avoids: integers beyond 2^53 CANNOT be
508/// represented in `google.protobuf.Value`, so they are rendered as their exact
509/// decimal string rather than silently rounded.
510pub fn record_to_prost_struct(record: &Record) -> prost_types::Struct {
511    prost_types::Struct {
512        fields: record
513            .fields()
514            .iter()
515            .map(|(key, value)| (key.clone(), json_to_prost_value(value)))
516            .collect(),
517    }
518}
519
520fn json_to_prost_value(value: &Value) -> prost_types::Value {
521    use prost_types::value::Kind;
522
523    let kind = match value {
524        Value::Null => Kind::NullValue(0),
525        Value::Bool(value) => Kind::BoolValue(*value),
526        Value::Number(number) => match exact_f64(number) {
527            Some(value) => Kind::NumberValue(value),
528            // Out of f64's exact-integer range. A rounded number would be a
529            // silent corruption; the decimal spelling is lossless and the
530            // caller can see what happened.
531            None => Kind::StringValue(number.to_string()),
532        },
533        Value::String(text) => Kind::StringValue(text.clone()),
534        Value::Array(items) => Kind::ListValue(prost_types::ListValue {
535            values: items.iter().map(json_to_prost_value).collect(),
536        }),
537        Value::Object(map) => Kind::StructValue(prost_types::Struct {
538            fields: map
539                .iter()
540                .map(|(key, value)| (key.clone(), json_to_prost_value(value)))
541                .collect(),
542        }),
543    };
544    prost_types::Value { kind: Some(kind) }
545}
546
547/// `Some(f64)` only when the conversion is exact.
548fn exact_f64(number: &serde_json::Number) -> Option<f64> {
549    const EXACT: i64 = 1 << 53;
550    if let Some(value) = number.as_i64() {
551        return (-EXACT..=EXACT).contains(&value).then_some(value as f64);
552    }
553    if let Some(value) = number.as_u64() {
554        return (value <= EXACT as u64).then_some(value as f64);
555    }
556    number.as_f64()
557}
558
559/// Group records by a string field, preserving order within each group.
560///
561/// A small convenience for the common "read a page, bucket it by owner" shape,
562/// kept here so it uses the checked accessors rather than raw map indexing.
563pub fn group_by_str<'a>(
564    records: &'a Records,
565    field: &str,
566) -> Result<BTreeMap<&'a str, Vec<&'a Record>>, DecodeError> {
567    let mut grouped: BTreeMap<&'a str, Vec<&'a Record>> = BTreeMap::new();
568    for record in records.iter() {
569        grouped.entry(record.str(field)?).or_default().push(record);
570    }
571    Ok(grouped)
572}
573
574#[cfg(test)]
575mod tests {
576    use super::*;
577    use crate::proto::udb::entity::v1::Row;
578
579    fn set(bodies: &[&str]) -> RecordSet {
580        RecordSet {
581            records_json: bodies.iter().map(|b| b.as_bytes().to_vec()).collect(),
582            // Exactly what the broker sends on the relational path: one EMPTY
583            // compatibility row per record.
584            rows: bodies.iter().map(|_| Row::default()).collect(),
585            ..RecordSet::default()
586        }
587    }
588
589    /// The precise v0.5.21 wire shape: populated `records_json`, aligned empty
590    /// `rows`. This is the fixture that must decode.
591    #[test]
592    fn decodes_the_shape_the_broker_actually_sends() {
593        let decoded = Records::decode(&set(&[r#"{"id":"a","n":1}"#])).unwrap();
594        assert_eq!(decoded.len(), 1);
595        assert_eq!(decoded.get(0).unwrap().str("id").unwrap(), "a");
596        assert_eq!(decoded.get(0).unwrap().i64("n").unwrap(), 1);
597    }
598
599    /// The defect's signature must NOT decode as an empty result.
600    #[test]
601    fn rows_without_canonical_records_is_an_error_not_an_empty_page() {
602        let broken = RecordSet {
603            records_json: Vec::new(),
604            rows: vec![Row::default(), Row::default()],
605            ..RecordSet::default()
606        };
607        assert_eq!(
608            Records::decode(&broken),
609            Err(DecodeError::CanonicalRecordsMissing { rows: 2 })
610        );
611    }
612
613    #[test]
614    fn a_genuinely_empty_page_is_fine() {
615        let decoded = Records::decode(&RecordSet::default()).unwrap();
616        assert!(decoded.is_empty());
617    }
618
619    #[test]
620    fn integers_beyond_f64_survive() {
621        let decoded = Records::decode(&set(&[r#"{"big":9007199254740993}"#])).unwrap();
622        assert_eq!(
623            decoded.get(0).unwrap().i64("big").unwrap(),
624            9007199254740993
625        );
626    }
627
628    #[test]
629    fn u64_above_i64_max_survives() {
630        let decoded = Records::decode(&set(&[r#"{"big":18446744073709551615}"#])).unwrap();
631        assert_eq!(decoded.get(0).unwrap().u64("big").unwrap(), u64::MAX);
632        // The same value is NOT a valid i64, and must say so rather than wrap.
633        assert!(matches!(
634            decoded.get(0).unwrap().i64("big"),
635            Err(DecodeError::NotAnExactInteger { .. })
636        ));
637    }
638
639    #[test]
640    fn fractional_is_not_an_integer() {
641        let decoded = Records::decode(&set(&[r#"{"n":1.5}"#])).unwrap();
642        assert!(matches!(
643            decoded.get(0).unwrap().i64("n"),
644            Err(DecodeError::NotAnExactInteger { .. })
645        ));
646    }
647
648    #[test]
649    fn i32_rejects_overflow_instead_of_wrapping() {
650        let decoded = Records::decode(&set(&[r#"{"n":2147483648}"#])).unwrap();
651        assert!(matches!(
652            decoded.get(0).unwrap().i32("n"),
653            Err(DecodeError::IntegerOutOfRange { .. })
654        ));
655    }
656
657    #[test]
658    fn negative_is_not_unsigned() {
659        let decoded = Records::decode(&set(&[r#"{"n":-1}"#])).unwrap();
660        assert!(matches!(
661            decoded.get(0).unwrap().u64("n"),
662            Err(DecodeError::NotAnExactInteger { .. })
663        ));
664    }
665
666    #[test]
667    fn absent_and_null_are_different_errors() {
668        let decoded = Records::decode(&set(&[r#"{"present":null}"#])).unwrap();
669        let record = decoded.get(0).unwrap();
670        assert!(matches!(
671            record.str("present"),
672            Err(DecodeError::NullField { .. })
673        ));
674        assert!(matches!(
675            record.str("absent"),
676            Err(DecodeError::MissingField { .. })
677        ));
678        assert!(record.is_null("present"));
679        assert!(!record.is_null("absent"));
680        assert_eq!(record.optional("present", Record::str).unwrap(), None);
681        assert_eq!(record.optional("absent", Record::str).unwrap(), None);
682    }
683
684    #[test]
685    fn bytes_decode_with_and_without_the_prefix() {
686        let decoded = Records::decode(&set(&[r#"{"a":"aGk=","b":"base64:aGk="}"#])).unwrap();
687        let record = decoded.get(0).unwrap();
688        assert_eq!(record.bytes("a").unwrap(), b"hi");
689        assert_eq!(record.bytes("b").unwrap(), b"hi");
690    }
691
692    #[test]
693    fn bad_base64_is_a_typed_error() {
694        let decoded = Records::decode(&set(&[r#"{"a":"!!!!"}"#])).unwrap();
695        assert!(matches!(
696            decoded.get(0).unwrap().bytes("a"),
697            Err(DecodeError::InvalidBase64 { .. })
698        ));
699    }
700
701    #[test]
702    fn malformed_json_names_the_record() {
703        let broken = RecordSet {
704            records_json: vec![b"{".to_vec()],
705            rows: vec![Row::default()],
706            ..RecordSet::default()
707        };
708        assert!(matches!(
709            Records::decode(&broken),
710            Err(DecodeError::Malformed { index: 0, .. })
711        ));
712    }
713
714    #[test]
715    fn a_non_object_record_is_rejected() {
716        let broken = RecordSet {
717            records_json: vec![b"[1,2]".to_vec()],
718            ..RecordSet::default()
719        };
720        assert!(matches!(
721            Records::decode(&broken),
722            Err(DecodeError::NotAnObject { index: 0, .. })
723        ));
724    }
725
726    #[test]
727    fn an_empty_record_body_is_rejected() {
728        let broken = RecordSet {
729            records_json: vec![Vec::new()],
730            ..RecordSet::default()
731        };
732        assert_eq!(
733            Records::decode(&broken),
734            Err(DecodeError::EmptyRecord { index: 0 })
735        );
736    }
737
738    #[test]
739    fn misaligned_revisions_are_rejected() {
740        let mut broken = set(&[r#"{"id":"a"}"#, r#"{"id":"b"}"#]);
741        broken.record_revisions = vec!["r1".into()];
742        assert!(matches!(
743            Records::decode(&broken),
744            Err(DecodeError::LengthMismatch {
745                what: "record_revisions",
746                ..
747            })
748        ));
749    }
750
751    #[test]
752    fn misaligned_rows_are_rejected() {
753        let mut broken = set(&[r#"{"id":"a"}"#, r#"{"id":"b"}"#]);
754        broken.rows = vec![Row::default()];
755        assert!(matches!(
756            Records::decode(&broken),
757            Err(DecodeError::LengthMismatch { what: "rows", .. })
758        ));
759    }
760
761    #[test]
762    fn revisions_attach_to_their_own_record() {
763        let mut with_revisions = set(&[r#"{"id":"a"}"#, r#"{"id":"b"}"#]);
764        with_revisions.record_revisions = vec![String::new(), "r2".into()];
765        let decoded = Records::decode(&with_revisions).unwrap();
766        // An empty slot means "not tracked yet", not "revision is the empty
767        // string".
768        assert_eq!(decoded.get(0).unwrap().revision(), None);
769        assert_eq!(decoded.get(1).unwrap().revision(), Some("r2"));
770    }
771
772    #[test]
773    fn page_metadata_is_carried_through() {
774        let mut page = set(&[r#"{"id":"a"}"#]);
775        page.next_page_token = "next".into();
776        page.has_more = true;
777        page.exact_total = 97;
778        let decoded = Records::decode(&page).unwrap();
779        assert_eq!(decoded.next_page_token(), "next");
780        // Reported as sent; `len` stays authoritative for what is in hand.
781        assert!(decoded.has_more());
782        assert_eq!(decoded.exact_total(), 97);
783        assert_eq!(decoded.len(), 1);
784    }
785
786    #[test]
787    fn prost_conversion_refuses_to_round_a_big_integer() {
788        use prost_types::value::Kind;
789
790        let decoded = Records::decode(&set(&[r#"{"small":42,"big":9007199254740993}"#])).unwrap();
791        let converted = record_to_prost_struct(decoded.get(0).unwrap());
792        assert_eq!(
793            converted.fields["small"].kind,
794            Some(Kind::NumberValue(42.0))
795        );
796        // f64 cannot hold this. Exact decimal text beats a silently wrong number.
797        assert_eq!(
798            converted.fields["big"].kind,
799            Some(Kind::StringValue("9007199254740993".into()))
800        );
801    }
802
803    #[test]
804    fn typed_accessors_reject_the_wrong_kind() {
805        let decoded = Records::decode(&set(&[r#"{"s":"text","n":1}"#])).unwrap();
806        let record = decoded.get(0).unwrap();
807        assert!(matches!(
808            record.i64("s"),
809            Err(DecodeError::UnexpectedType {
810                expected: "integer",
811                found: "string",
812                ..
813            })
814        ));
815        assert!(matches!(
816            record.str("n"),
817            Err(DecodeError::UnexpectedType {
818                expected: "string",
819                found: "number",
820                ..
821            })
822        ));
823    }
824
825    #[test]
826    fn objects_and_arrays_round_trip() {
827        let decoded = Records::decode(&set(&[r#"{"meta":{"k":"v"},"tags":["a","b"]}"#])).unwrap();
828        let record = decoded.get(0).unwrap();
829        assert_eq!(
830            record.object("meta").unwrap()["k"],
831            Value::String("v".into())
832        );
833        assert_eq!(record.array("tags").unwrap().len(), 2);
834    }
835
836    #[test]
837    fn grouping_uses_checked_accessors() {
838        let decoded = Records::decode(&set(&[
839            r#"{"owner":"a","id":1}"#,
840            r#"{"owner":"b","id":2}"#,
841            r#"{"owner":"a","id":3}"#,
842        ]))
843        .unwrap();
844        let grouped = group_by_str(&decoded, "owner").unwrap();
845        assert_eq!(grouped["a"].len(), 2);
846        assert_eq!(grouped["b"].len(), 1);
847        assert!(matches!(
848            group_by_str(&decoded, "missing"),
849            Err(DecodeError::MissingField { .. })
850        ));
851    }
852}