1use std::collections::BTreeMap;
44use std::fmt;
45
46use serde_json::{Map, Value};
47
48use crate::proto::udb::entity::v1::RecordSet;
49
50#[derive(Debug, Clone, PartialEq)]
52pub struct Record {
53 fields: Map<String, Value>,
54 revision: Option<String>,
55}
56
57impl Record {
58 pub fn fields(&self) -> &Map<String, Value> {
60 &self.fields
61 }
62
63 pub fn into_fields(self) -> Map<String, Value> {
65 self.fields
66 }
67
68 pub fn revision(&self) -> Option<&str> {
74 self.revision.as_deref()
75 }
76
77 pub fn get(&self, field: &str) -> Option<&Value> {
81 self.fields.get(field)
82 }
83
84 pub fn is_null(&self, field: &str) -> bool {
86 matches!(self.fields.get(field), Some(Value::Null))
87 }
88
89 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 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 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 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 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 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 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 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 pub fn timestamp(&self, field: &str) -> Result<&str, DecodeError> {
209 self.str(field)
210 }
211
212 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 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 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#[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 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 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 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 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 has_more: set.has_more,
326 exact_total: set.exact_total,
327 next_page_token: set.next_page_token.clone(),
328 })
329 }
330
331 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 pub fn has_more(&self) -> bool {
351 self.has_more
352 }
353
354 pub fn exact_total(&self) -> i64 {
358 self.exact_total
359 }
360
361 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#[derive(Debug, Clone, PartialEq, Eq)]
394pub enum DecodeError {
395 CanonicalRecordsMissing { rows: usize },
397 LengthMismatch {
399 what: &'static str,
400 expected: usize,
401 found: usize,
402 },
403 EmptyRecord { index: usize },
405 Malformed { index: usize, reason: String },
407 NotAnObject { index: usize, found: &'static str },
409 MissingField { field: String },
411 NullField { field: String },
413 UnexpectedType {
415 field: String,
416 expected: &'static str,
417 found: &'static str,
418 },
419 NotAnExactInteger { field: String, value: String },
422 IntegerOutOfRange {
424 field: String,
425 width: &'static str,
426 value: String,
427 },
428 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
502pub 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 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
547fn 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
559pub 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 rows: bodies.iter().map(|_| Row::default()).collect(),
585 ..RecordSet::default()
586 }
587 }
588
589 #[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 #[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 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 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 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 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}