Skip to main content

realm_codec/
lib.rs

1//! # realm-codec
2//!
3//! Parser and writer for [Realm](https://github.com/realm/realm-core) binary database
4//! files (format version 9).
5//!
6//! - **Read** an existing `.realm` file with [`RealmFile::open`] — no Realm SDK required.
7//! - **Write** a new `.realm` file from scratch with [`RealmBuilder`].
8//!
9//! ## Reading
10//!
11//! ```no_run
12//! use realm_codec::{RealmFile, Value};
13//!
14//! let realm = RealmFile::open("/path/to/file.realm")?;
15//!
16//! if let Some(table) = realm.table("class_BlockDataModel") {
17//!     for row in &table.rows {
18//!         println!("{}", table.get(row, "content").as_str());
19//!     }
20//! }
21//! # Ok::<(), realm_codec::RealmError>(())
22//! ```
23//!
24//! ## Writing
25//!
26//! ```no_run
27//! use realm_codec::{RealmBuilder, ColumnType, Value};
28//!
29//! let mut builder = RealmBuilder::new();
30//! builder
31//!     .table("class_Note")
32//!     .column("id",   ColumnType::String)
33//!     .column("body", ColumnType::String)
34//!     .row(vec![Value::String("1".into()), Value::String("Hello".into())]);
35//!
36//! builder.write("/path/to/out.realm")?;
37//! # Ok::<(), realm_codec::RealmError>(())
38//! ```
39
40#![forbid(unsafe_code)]
41#![warn(missing_docs)]
42
43pub(crate) mod format;
44mod reader;
45pub mod write;
46
47pub use write::{RealmBuilder, TableBuilder};
48
49use std::path::Path;
50
51// ── Error ─────────────────────────────────────────────────────────────────────
52
53/// Errors that can occur while opening or parsing a Realm file.
54#[derive(Debug)]
55#[non_exhaustive]
56pub enum RealmError {
57    /// An I/O error while reading the file from disk.
58    Io(std::io::Error),
59    /// The file does not conform to the expected Realm binary layout.
60    InvalidFormat(String),
61    /// The file uses a Realm format version other than 9.
62    UnsupportedVersion(u32),
63}
64
65impl std::fmt::Display for RealmError {
66    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
67        match self {
68            RealmError::Io(e) => write!(f, "I/O error: {e}"),
69            RealmError::InvalidFormat(msg) => write!(f, "invalid Realm format: {msg}"),
70            RealmError::UnsupportedVersion(v) => {
71                write!(f, "unsupported Realm version {v} (only v9 is supported)")
72            }
73        }
74    }
75}
76
77impl std::error::Error for RealmError {
78    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
79        if let RealmError::Io(e) = self { Some(e) } else { None }
80    }
81}
82
83impl From<std::io::Error> for RealmError {
84    fn from(e: std::io::Error) -> Self {
85        RealmError::Io(e)
86    }
87}
88
89/// Convenience `Result` alias for this crate.
90pub type Result<T> = std::result::Result<T, RealmError>;
91
92// ── Column type ───────────────────────────────────────────────────────────────
93
94/// The declared type of a Realm column.
95///
96/// Decoded from the 4-bit type codes stored in the table spec array.
97#[derive(Debug, Clone, Copy, PartialEq, Eq)]
98#[non_exhaustive]
99pub enum ColumnType {
100    /// 64-bit signed integer.
101    Int,
102    /// Boolean (1-bit).
103    Bool,
104    /// UTF-8 string.
105    String,
106    /// Arbitrary binary data.
107    Data,
108    /// 32-bit IEEE 754 float.
109    Float,
110    /// 64-bit IEEE 754 double.
111    Double,
112    /// Unix timestamp (seconds).
113    Timestamp,
114    /// Reference to a row in another table.
115    Link,
116    /// List of references to rows in another table.
117    LinkList,
118    /// Inverse link (back-link).
119    BackLink,
120    /// A type code not recognised by this parser version.
121    Unknown(u8),
122}
123
124impl ColumnType {
125    /// Decode a raw 4-bit type code from the Realm spec array.
126    pub fn from_u8(v: u8) -> Self {
127        match v {
128            0 => ColumnType::Int,
129            1 => ColumnType::Bool,
130            2 => ColumnType::String,
131            3 => ColumnType::Data,
132            4 => ColumnType::Float,
133            5 => ColumnType::Double,
134            7 => ColumnType::Timestamp,
135            8 | 12 => ColumnType::Link,
136            9 | 13 => ColumnType::LinkList,
137            14 => ColumnType::BackLink,
138            other => ColumnType::Unknown(other),
139        }
140    }
141}
142
143// ── Value ─────────────────────────────────────────────────────────────────────
144
145/// A single parsed cell value.
146#[derive(Debug, Clone, PartialEq)]
147#[non_exhaustive]
148pub enum Value {
149    /// The cell is absent or could not be decoded.
150    Null,
151    /// Boolean cell.
152    Bool(bool),
153    /// Integer cell (i64).
154    Int(i64),
155    /// Float or double cell (stored as f64).
156    Float(f64),
157    /// Unix timestamp in seconds.
158    Timestamp(i64),
159    /// UTF-8 string or binary data column.
160    String(String),
161    /// Row index in a linked table.
162    Link(usize),
163}
164
165impl Value {
166    /// Returns `true` if the value is [`Value::Null`].
167    pub fn is_null(&self) -> bool {
168        matches!(self, Value::Null)
169    }
170
171    /// Returns the inner `&str` if this is a [`Value::String`], otherwise `""`.
172    pub fn as_str(&self) -> &str {
173        if let Value::String(s) = self { s } else { "" }
174    }
175
176    /// Returns the inner `i64` if this is a [`Value::Int`], otherwise `0`.
177    pub fn as_int(&self) -> i64 {
178        if let Value::Int(i) = self { *i } else { 0 }
179    }
180
181    /// Returns the inner `bool` if this is a [`Value::Bool`], otherwise `false`.
182    pub fn as_bool(&self) -> bool {
183        if let Value::Bool(b) = self { *b } else { false }
184    }
185
186    /// Returns the inner Unix timestamp if this is a [`Value::Timestamp`], otherwise `0`.
187    pub fn as_timestamp(&self) -> i64 {
188        if let Value::Timestamp(t) = self { *t } else { 0 }
189    }
190
191    /// Returns the inner `f64` if this is a [`Value::Float`], otherwise `0.0`.
192    pub fn as_float(&self) -> f64 {
193        if let Value::Float(f) = self { *f } else { 0.0 }
194    }
195}
196
197// ── Row ───────────────────────────────────────────────────────────────────────
198
199/// A single row of cell values in a table.
200///
201/// Column order matches [`RealmTable::columns`].
202#[derive(Debug, Clone)]
203pub struct Row {
204    /// Cell values in column-declaration order.
205    pub values: Vec<Value>,
206}
207
208impl Row {
209    /// Get the value at column index `col_idx`, or [`Value::Null`] if out of range.
210    pub fn get(&self, col_idx: usize) -> &Value {
211        self.values.get(col_idx).unwrap_or(&Value::Null)
212    }
213}
214
215// ── Table ─────────────────────────────────────────────────────────────────────
216
217/// A parsed Realm table: schema + rows.
218#[derive(Debug, Clone)]
219pub struct RealmTable {
220    /// Table name as stored in the Realm file (e.g. `"class_BlockDataModel"`).
221    pub name: String,
222    /// Column definitions in declaration order: `(column_name, column_type)`.
223    pub columns: Vec<(String, ColumnType)>,
224    /// All rows in the table.
225    pub rows: Vec<Row>,
226}
227
228impl RealmTable {
229    /// Return the column index for `name`, or `None` if not found.
230    pub fn column_index(&self, name: &str) -> Option<usize> {
231        self.columns.iter().position(|(n, _)| n == name)
232    }
233
234    /// Return the value in `row` for the column named `col_name`.
235    ///
236    /// Returns [`Value::Null`] if the column does not exist.
237    pub fn get<'a>(&self, row: &'a Row, col_name: &str) -> &'a Value {
238        match self.column_index(col_name) {
239            Some(i) => row.get(i),
240            None => &Value::Null,
241        }
242    }
243}
244
245// ── RealmFile ─────────────────────────────────────────────────────────────────
246
247/// An opened and fully-parsed Realm database file.
248///
249/// Constructed via [`RealmFile::open`] or [`RealmFile::from_bytes`].
250pub struct RealmFile {
251    tables: Vec<RealmTable>,
252}
253
254impl RealmFile {
255    /// Read and parse a `.realm` file from disk.
256    ///
257    /// # Errors
258    ///
259    /// Returns [`RealmError::Io`] if the file cannot be read, [`RealmError::InvalidFormat`]
260    /// if the binary layout is unexpected, or [`RealmError::UnsupportedVersion`] if the
261    /// format version is not 9.
262    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
263        let data = std::fs::read(path)?;
264        Self::from_bytes(&data)
265    }
266
267    /// Parse a Realm database from an in-memory byte slice.
268    ///
269    /// Useful for testing or when the file is already loaded in memory.
270    pub fn from_bytes(data: &[u8]) -> Result<Self> {
271        let tables = reader::read_tables(data)?;
272        Ok(RealmFile { tables })
273    }
274
275    /// All tables in the file, in the order they appear in the Group.
276    pub fn tables(&self) -> &[RealmTable] {
277        &self.tables
278    }
279
280    /// Find a table by exact name (e.g. `"class_BlockDataModel"`).
281    ///
282    /// Returns `None` if no table with that name exists.
283    pub fn table(&self, name: &str) -> Option<&RealmTable> {
284        self.tables.iter().find(|t| t.name == name)
285    }
286}
287
288// ── Tests ─────────────────────────────────────────────────────────────────────
289
290#[cfg(test)]
291mod tests {
292    use super::format::*;
293    use super::*;
294
295    // ── NodeHeader ────────────────────────────────────────────────────────────
296
297    #[test]
298    fn node_header_bits_width8() {
299        let mut h = [0u8; 8];
300        // wtype=0 (bits), width_enc=4 → width=8, size=5
301        h[4] = 4;
302        h[7] = 5;
303        let hdr = NodeHeader::parse(&h);
304        assert_eq!(hdr.width, 8);
305        assert_eq!(hdr.wtype, WTYPE_BITS);
306        assert_eq!(hdr.size, 5);
307        assert!(!hdr.is_inner);
308    }
309
310    #[test]
311    fn node_header_multiply_width64() {
312        let mut h = [0u8; 8];
313        // wtype=1 (multiply), width_enc=7 → width=64
314        h[4] = (WTYPE_MULTIPLY << 3) | 7;
315        h[7] = 3;
316        let hdr = NodeHeader::parse(&h);
317        assert_eq!(hdr.wtype, WTYPE_MULTIPLY);
318        assert_eq!(hdr.width, 64);
319        assert_eq!(hdr.size, 3);
320    }
321
322    #[test]
323    fn node_header_width_encoding_all_values() {
324        // width_enc 0..=7 → 0, 1, 2, 4, 8, 16, 32, 64
325        let expected = [0u8, 1, 2, 4, 8, 16, 32, 64];
326        for (enc, &exp) in expected.iter().enumerate() {
327            let mut h = [0u8; 8];
328            h[4] = enc as u8;
329            assert_eq!(NodeHeader::parse(&h).width, exp, "enc={enc}");
330        }
331    }
332
333    #[test]
334    fn node_header_size_three_bytes() {
335        // size is packed in h[5..7]: (h[5]<<16)|(h[6]<<8)|h[7]
336        let mut h = [0u8; 8];
337        h[5] = 0x01;
338        h[6] = 0x02;
339        h[7] = 0x03;
340        assert_eq!(NodeHeader::parse(&h).size, 0x010203);
341    }
342
343    #[test]
344    fn node_header_inner_flag() {
345        let mut h = [0u8; 8];
346        h[4] = 0x80;
347        assert!(NodeHeader::parse(&h).is_inner);
348    }
349
350    // ── String decoding ───────────────────────────────────────────────────────
351
352    #[test]
353    fn decode_short_string_normal() {
354        let mut slot = [0u8; 32];
355        slot[..5].copy_from_slice(b"hello");
356        slot[31] = 26; // tail = 32 - 5 - 1
357        assert_eq!(decode_short_string(&slot), "hello");
358    }
359
360    #[test]
361    fn decode_short_string_empty() {
362        let mut slot = [0u8; 8];
363        slot[7] = 7; // tail = 8 - 0 - 1
364        assert_eq!(decode_short_string(&slot), "");
365    }
366
367    #[test]
368    fn decode_short_string_full_slot() {
369        // All 7 payload bytes used, tail=0
370        let mut slot = [b'x'; 8];
371        slot[7] = 0;
372        let s = decode_short_string(&slot);
373        assert_eq!(s.len(), 7);
374    }
375
376    #[test]
377    fn decode_short_string_empty_slice() {
378        assert_eq!(decode_short_string(&[]), "");
379    }
380
381    // ── Bit-width element reading ─────────────────────────────────────────────
382
383    #[test]
384    fn read_bits_elem_8bit() {
385        let data = [10u8, 20, 30];
386        assert_eq!(read_bits_elem(&data, 0, 8), 10);
387        assert_eq!(read_bits_elem(&data, 2, 8), 30);
388    }
389
390    #[test]
391    fn read_bits_elem_4bit() {
392        // byte 0xAB: lower nibble = 0xB (elem 0), upper nibble = 0xA (elem 1)
393        let data = [0xABu8];
394        assert_eq!(read_bits_elem(&data, 0, 4), 0xB);
395        assert_eq!(read_bits_elem(&data, 1, 4), 0xA);
396    }
397
398    #[test]
399    fn read_bits_elem_1bit() {
400        let data = [0b1010_1010u8];
401        assert_eq!(read_bits_elem(&data, 0, 1), 0);
402        assert_eq!(read_bits_elem(&data, 1, 1), 1);
403        assert_eq!(read_bits_elem(&data, 7, 1), 1);
404    }
405
406    #[test]
407    fn read_bits_elem_64bit() {
408        let val: u64 = 0xDEAD_BEEF_1234_5678;
409        let data = val.to_le_bytes();
410        assert_eq!(read_bits_elem(&data, 0, 64), val);
411    }
412
413    #[test]
414    fn read_bits_elem_zero_width() {
415        assert_eq!(read_bits_elem(&[0xFF], 0, 0), 0);
416    }
417
418    // ── ColumnType ────────────────────────────────────────────────────────────
419
420    #[test]
421    fn column_type_known_codes() {
422        assert_eq!(ColumnType::from_u8(0), ColumnType::Int);
423        assert_eq!(ColumnType::from_u8(1), ColumnType::Bool);
424        assert_eq!(ColumnType::from_u8(2), ColumnType::String);
425        assert_eq!(ColumnType::from_u8(3), ColumnType::Data);
426        assert_eq!(ColumnType::from_u8(4), ColumnType::Float);
427        assert_eq!(ColumnType::from_u8(5), ColumnType::Double);
428        assert_eq!(ColumnType::from_u8(7), ColumnType::Timestamp);
429        assert_eq!(ColumnType::from_u8(8), ColumnType::Link);
430        assert_eq!(ColumnType::from_u8(12), ColumnType::Link);
431        assert_eq!(ColumnType::from_u8(9), ColumnType::LinkList);
432        assert_eq!(ColumnType::from_u8(14), ColumnType::BackLink);
433    }
434
435    #[test]
436    fn column_type_unknown() {
437        assert!(matches!(ColumnType::from_u8(99), ColumnType::Unknown(99)));
438    }
439
440    // ── Value accessors ───────────────────────────────────────────────────────
441
442    #[test]
443    fn value_accessors_hit() {
444        assert_eq!(Value::String("hi".into()).as_str(), "hi");
445        assert_eq!(Value::Int(42).as_int(), 42);
446        assert_eq!(Value::Bool(true).as_bool(), true);
447        assert_eq!(Value::Timestamp(100).as_timestamp(), 100);
448        assert!((Value::Float(3.14).as_float() - 3.14).abs() < 1e-9);
449    }
450
451    #[test]
452    fn value_accessors_miss() {
453        assert_eq!(Value::Null.as_str(), "");
454        assert_eq!(Value::Null.as_int(), 0);
455        assert_eq!(Value::Null.as_bool(), false);
456        assert_eq!(Value::Null.as_timestamp(), 0);
457        assert_eq!(Value::Null.as_float(), 0.0);
458    }
459
460    #[test]
461    fn value_is_null() {
462        assert!(Value::Null.is_null());
463        assert!(!Value::Int(1).is_null());
464        assert!(!Value::String("x".into()).is_null());
465    }
466
467    // ── Row / RealmTable ──────────────────────────────────────────────────────
468
469    #[test]
470    fn row_get_in_bounds() {
471        let row = Row { values: vec![Value::Int(1), Value::Bool(true)] };
472        assert_eq!(row.get(0), &Value::Int(1));
473        assert_eq!(row.get(1), &Value::Bool(true));
474    }
475
476    #[test]
477    fn row_get_out_of_bounds() {
478        let row = Row { values: vec![Value::Int(1)] };
479        assert_eq!(row.get(99), &Value::Null);
480    }
481
482    #[test]
483    fn realm_table_column_index() {
484        let table = RealmTable {
485            name: "t".into(),
486            columns: vec![
487                ("id".into(), ColumnType::String),
488                ("age".into(), ColumnType::Int),
489            ],
490            rows: vec![],
491        };
492        assert_eq!(table.column_index("id"), Some(0));
493        assert_eq!(table.column_index("age"), Some(1));
494        assert_eq!(table.column_index("missing"), None);
495    }
496
497    #[test]
498    fn realm_table_get_by_name() {
499        let row = Row { values: vec![Value::String("abc".into()), Value::Int(7)] };
500        let table = RealmTable {
501            name: "t".into(),
502            columns: vec![
503                ("id".into(), ColumnType::String),
504                ("count".into(), ColumnType::Int),
505            ],
506            rows: vec![],
507        };
508        assert_eq!(table.get(&row, "id").as_str(), "abc");
509        assert_eq!(table.get(&row, "count").as_int(), 7);
510        assert_eq!(table.get(&row, "missing"), &Value::Null);
511    }
512
513    // ── File-level validation ─────────────────────────────────────────────────
514
515    #[test]
516    fn file_too_small_rejected() {
517        let result = RealmFile::from_bytes(&[0u8; 10]);
518        assert!(matches!(result, Err(RealmError::InvalidFormat(_))));
519    }
520
521    #[test]
522    fn bad_magic_rejected() {
523        let mut data = vec![0u8; 24];
524        data[16..20].copy_from_slice(b"XXXX");
525        data[20..24].copy_from_slice(&9u32.to_le_bytes());
526        assert!(matches!(
527            RealmFile::from_bytes(&data),
528            Err(RealmError::InvalidFormat(_))
529        ));
530    }
531
532    #[test]
533    fn unsupported_version_rejected() {
534        let mut data = vec![0u8; 24];
535        data[16..20].copy_from_slice(b"T-DB");
536        data[20..24].copy_from_slice(&5u32.to_le_bytes());
537        assert!(matches!(
538            RealmFile::from_bytes(&data),
539            Err(RealmError::UnsupportedVersion(5))
540        ));
541    }
542
543    #[test]
544    fn realm_error_display() {
545        let e = RealmError::UnsupportedVersion(5);
546        assert!(e.to_string().contains("v9"));
547        let e = RealmError::InvalidFormat("bad".into());
548        assert!(e.to_string().contains("bad"));
549    }
550
551    #[test]
552    fn realm_error_source_io() {
553        use std::error::Error;
554        let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "missing");
555        let e = RealmError::from(io_err);
556        assert!(e.source().is_some());
557    }
558
559    #[test]
560    fn realm_error_source_non_io() {
561        use std::error::Error;
562        let e = RealmError::InvalidFormat("x".into());
563        assert!(e.source().is_none());
564    }
565}