reddb_server/
document_body.rs

1//! Native binary document-body container wiring (PRD-1398, ADR-0063).
2//!
3//! DOCUMENT collections keep the canonical document under a `body` field.
4//! Behind the `storage.binary_document_body` flag, writes serialise that body into the
5//! native binary container ([`reddb_types::document_body_codec`]) instead of
6//! plain UTF-8 JSON. The container is self-describing — it starts with the
7//! `RDOC` magic — so every read path decodes it back to JSON transparently,
8//! regardless of the flag, keeping the wire/clients on JSON (no driver change).
9//!
10//! The binary form lives only inside the stored `Value::Json` bytes; the rest
11//! of the engine continues to see a JSON body in memory. This is the
12//! binary write + binary-to-JSON read path; bare field filters/projections
13//! offset-read from the body after the production cutover.
14
15use reddb_types::document_body_codec;
16
17use crate::application::entity::json_to_storage_value;
18use crate::json::{to_vec as json_to_vec, Map, Value as JsonValue};
19use crate::presentation::entity_json::storage_value_to_json;
20use crate::storage::schema::Value;
21use crate::{RedDBError, RedDBResult};
22
23/// True when `bytes` begin with the document-body container magic.
24///
25/// A legacy UTF-8 JSON document body is an object and starts with `{`, so this
26/// magic check never collides with a JSON body.
27pub(crate) fn is_binary_container(bytes: &[u8]) -> bool {
28    bytes.starts_with(document_body_codec::MAGIC)
29}
30
31/// Decode a binary document-body container back to its JSON object.
32///
33/// Returns `None` when `bytes` is not a container — so callers fall back to
34/// their existing JSON parse — or when a container fails to decode.
35pub(crate) fn decode_container_to_json(bytes: &[u8]) -> Option<JsonValue> {
36    if !is_binary_container(bytes) {
37        return None;
38    }
39    let fields = document_body_codec::decode(bytes).ok()?;
40    let mut map = Map::new();
41    for (key, value) in fields {
42        map.insert(key, storage_value_to_json(&value));
43    }
44    Some(JsonValue::Object(map))
45}
46
47/// Offset-read a single top-level field from a stored document body.
48///
49/// Returns the field's storage [`Value`] decoded directly from the binary
50/// container by offset ([`document_body_codec::read_field_by_name`]) — no
51/// other field is touched. Returns `None` when `bytes` is not a binary
52/// container or the field is absent.
53///
54/// This is the read seam that makes the body the single source of truth: a
55/// `WHERE`/projection on a top-level field routes here to read it straight
56/// from the body.
57pub(crate) fn read_body_field(bytes: &[u8], name: &str) -> Option<Value> {
58    if !is_binary_container(bytes) {
59        return None;
60    }
61    document_body_codec::read_field_by_name(bytes, name)
62        .ok()
63        .flatten()
64}
65
66/// Decode every top-level field of a binary document body as storage values.
67///
68/// Returns `None` when `bytes` is not a binary container. Used to expand a
69/// `SELECT *` over a single-source document back into its top-level fields.
70pub(crate) fn body_fields(bytes: &[u8]) -> Option<Vec<(String, Value)>> {
71    if !is_binary_container(bytes) {
72        return None;
73    }
74    document_body_codec::decode(bytes).ok()
75}
76
77/// List the top-level field names of a binary document body (offset-read of
78/// the keys section only). Returns `None` for non-container bytes.
79pub(crate) fn container_field_names(bytes: &[u8]) -> Option<Vec<String>> {
80    if !is_binary_container(bytes) {
81        return None;
82    }
83    document_body_codec::field_names(bytes).ok()
84}
85
86/// Serialise a document body for storage in the `body` field.
87///
88/// With `binary` set and an object body, produce the native binary container;
89/// otherwise (or for a non-object body, which the container cannot represent)
90/// fall back to UTF-8 JSON bytes. The caller wraps the result in `Value::Json`.
91pub(crate) fn serialize_document_body(body: &JsonValue, binary: bool) -> RedDBResult<Vec<u8>> {
92    if binary {
93        if let JsonValue::Object(map) = body {
94            let typed: Vec<(String, Value)> = map
95                .iter()
96                .map(|(key, value)| Ok((key.clone(), json_to_storage_value(value)?)))
97                .collect::<RedDBResult<_>>()?;
98            let refs: Vec<(&str, &Value)> = typed
99                .iter()
100                .map(|(key, value)| (key.as_str(), value))
101                .collect();
102            let mut out = Vec::new();
103            document_body_codec::encode(&refs, &mut out).map_err(|err| {
104                RedDBError::Query(format!("failed to encode binary document body: {err}"))
105            })?;
106            return Ok(out);
107        }
108    }
109    json_to_vec(body)
110        .map_err(|err| RedDBError::Query(format!("failed to serialize document body: {err}")))
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116
117    fn parse(text: &str) -> JsonValue {
118        crate::json::from_str(text).expect("valid JSON fixture")
119    }
120
121    fn body() -> JsonValue {
122        parse(
123            r#"{"name":"Alice","age":30,"email":"alice@example.com",
124               "tags":["admin","ops"],"profile":{"city":"SP","active":true}}"#,
125        )
126    }
127
128    #[test]
129    fn binary_off_emits_plain_json_bytes() {
130        let bytes = serialize_document_body(&body(), false).expect("serialize");
131        assert!(!is_binary_container(&bytes), "flag off must stay JSON");
132        assert_eq!(bytes.first(), Some(&b'{'));
133        assert!(decode_container_to_json(&bytes).is_none());
134    }
135
136    #[test]
137    fn binary_on_emits_container_that_decodes_to_equal_json() {
138        let original = body();
139        let bytes = serialize_document_body(&original, true).expect("serialize");
140        assert!(is_binary_container(&bytes), "flag on must produce RDOC");
141        let decoded = decode_container_to_json(&bytes).expect("decode");
142        assert_eq!(
143            decoded, original,
144            "binary body must round-trip to equal JSON"
145        );
146    }
147
148    #[test]
149    fn non_object_body_falls_back_to_json_even_with_binary_on() {
150        let scalar = JsonValue::String("just-a-string".to_string());
151        let bytes = serialize_document_body(&scalar, true).expect("serialize");
152        assert!(!is_binary_container(&bytes));
153        assert_eq!(
154            json_to_vec(&scalar).unwrap(),
155            bytes,
156            "non-object body must serialise as plain JSON"
157        );
158    }
159
160    #[test]
161    fn rich_semantic_string_types_survive_round_trip() {
162        // On the JSON wire these are strings; the container must round-trip the
163        // exact JSON the client sent (Email/Ipv4/Subnet/Color string forms).
164        let original = parse(
165            r##"{"email":"user@example.com","ipv4":"127.0.0.1",
166               "subnet":"10.0.0.0/8","color":"#DEADBE","url":"https://reddb.io"}"##,
167        );
168        let bytes = serialize_document_body(&original, true).expect("serialize");
169        let decoded = decode_container_to_json(&bytes).expect("decode");
170        assert_eq!(decoded, original);
171    }
172
173    #[test]
174    fn read_body_field_offset_reads_from_binary_body() {
175        let bytes = serialize_document_body(&body(), true).expect("serialize");
176        assert_eq!(read_body_field(&bytes, "name"), Some(Value::text("Alice")));
177        assert_eq!(read_body_field(&bytes, "age"), Some(Value::Integer(30)));
178        assert_eq!(read_body_field(&bytes, "missing"), None);
179    }
180
181    #[test]
182    fn body_field_helpers_ignore_plain_json_bodies() {
183        let bytes = serialize_document_body(&body(), false).expect("serialize");
184        assert_eq!(read_body_field(&bytes, "name"), None);
185        assert_eq!(body_fields(&bytes), None);
186        assert_eq!(container_field_names(&bytes), None);
187    }
188
189    #[test]
190    fn body_fields_and_names_cover_top_level_keys() {
191        let bytes = serialize_document_body(&body(), true).expect("serialize");
192        let names = container_field_names(&bytes).expect("names");
193        for key in ["name", "age", "email", "tags", "profile"] {
194            assert!(names.contains(&key.to_string()), "missing {key}");
195        }
196        let fields = body_fields(&bytes).expect("fields");
197        assert_eq!(fields.len(), names.len());
198    }
199
200    #[test]
201    fn empty_object_round_trips() {
202        let original = parse("{}");
203        let bytes = serialize_document_body(&original, true).expect("serialize");
204        assert!(is_binary_container(&bytes));
205        assert_eq!(decode_container_to_json(&bytes), Some(original));
206    }
207}
reddb_server/document_body.rs

reddb_server/
document_body.rs
