hayson_binding_shared/
options.rs

1use std::collections::HashMap;
2
3use std::time::Duration;
4
5use hayson_engine::catalog::CatalogCompaction;
6use hayson_engine::crypto::PasswordHashParams;
7use hayson_engine::crypto::{CipherOptions, MissingKeyPolicy};
8use hayson_engine::database::{
9    BackupOptions, FollowOption, LayoutKind, LayoutMigrationOptions, LayoutOptions, LockMode, OpenOptions, PackLimits,
10    PackOptions, RestoreOptions, UnpackOptions, VerifyOptions,
11};
12use hayson_engine::lock::{GraceServed, LockOptions};
13use serde_json::Value;
14
15/// Rejection of an `open()` options document, before the engine is ever touched.
16#[derive(Debug, PartialEq, Eq)]
17pub enum OptionsError {
18    /// A malformed option: wrong JSON type, unknown enum member, out-of-range number.
19    Shape(String),
20    /// Unusable key material — reported to JS as a cipher error, not a schema one.
21    Key(String),
22}
23
24fn shape<T>(message: impl Into<String>) -> Result<T, OptionsError> {
25    Err(OptionsError::Shape(message.into()))
26}
27
28fn as_object<'a>(value: &'a Value, what: &str) -> Result<&'a serde_json::Map<String, Value>, OptionsError> {
29    match value.as_object() {
30        Some(object) => Ok(object),
31        None => shape(format!("\"{what}\" must be a JSON object")),
32    }
33}
34
35fn optional_bool(object: &serde_json::Map<String, Value>, key: &str) -> Result<Option<bool>, OptionsError> {
36    match object.get(key) {
37        None | Some(Value::Null) => Ok(None),
38        Some(Value::Bool(value)) => Ok(Some(*value)),
39        Some(_) => shape(format!("\"{key}\" must be a boolean")),
40    }
41}
42
43fn optional_u64(object: &serde_json::Map<String, Value>, key: &str) -> Result<Option<u64>, OptionsError> {
44    match object.get(key) {
45        None | Some(Value::Null) => Ok(None),
46        Some(Value::Number(number)) => match number.as_u64() {
47            Some(value) => Ok(Some(value)),
48            None => shape(format!("\"{key}\" must be a non-negative whole number")),
49        },
50        Some(_) => shape(format!("\"{key}\" must be a number")),
51    }
52}
53
54fn optional_i64(object: &serde_json::Map<String, Value>, key: &str) -> Result<Option<i64>, OptionsError> {
55    match object.get(key) {
56        None | Some(Value::Null) => Ok(None),
57        Some(Value::Number(number)) => match number.as_i64() {
58            Some(value) => Ok(Some(value)),
59            None => shape(format!("\"{key}\" must be a whole number")),
60        },
61        Some(_) => shape(format!("\"{key}\" must be a number")),
62    }
63}
64
65fn optional_string(object: &serde_json::Map<String, Value>, key: &str) -> Result<Option<String>, OptionsError> {
66    match object.get(key) {
67        None | Some(Value::Null) => Ok(None),
68        Some(Value::String(value)) => Ok(Some(value.clone())),
69        Some(_) => shape(format!("\"{key}\" must be a string")),
70    }
71}
72
73/// `lock` in the shapes the TS `OpenOptions` takes (`boolean | LockOptions`): an object of lease
74/// tuning, or `false` to open without taking the writer lock at all — mutual exclusion between
75/// writers is then not enforced, which is the whole point and the whole danger of the option.
76/// `true` is TS's "lock the usual way" and resolves to the engine's defaults, not to skipping.
77fn parse_lock(value: &Value) -> Result<LockMode, OptionsError> {
78    match value {
79        Value::Bool(false) => Ok(LockMode::Skip),
80        Value::Bool(true) => Ok(LockMode::Enabled(LockOptions::default())),
81        Value::Object(object) => Ok(LockMode::Enabled(LockOptions {
82            stale_after_ms: optional_u64(object, "staleAfterMs")?,
83            heartbeat_ms: optional_u64(object, "heartbeatMs")?,
84            timeout_ms: optional_u64(object, "timeoutMs")?,
85            retry_interval_ms: optional_u64(object, "retryIntervalMs")?,
86            grace_served: parse_grace_served(object)?,
87        })),
88        _ => shape("\"lock\" must be a boolean or an object of lock options"),
89    }
90}
91
92/// `graceServed` — the lease a host has already challenged and waited the hand-over grace out on,
93/// so that the open it precedes reclaims that lease without the engine sleeping inside a call the
94/// host is waiting on. Not part of the public TS `LockOptions`: the binding layer synthesises it
95/// between two attempts of its own, off the `holder` its previous refusal named.
96///
97/// A token naming a lease that has since moved is not an error — it simply buys nothing, and the
98/// ordinary hand-over runs instead. Only its shape is judged here.
99fn parse_grace_served(object: &serde_json::Map<String, Value>) -> Result<Option<GraceServed>, OptionsError> {
100    let served = match object.get("graceServed") {
101        None | Some(Value::Null) => return Ok(None),
102        Some(value) => as_object(value, "graceServed")?,
103    };
104    let Some(owner) = optional_string(served, "owner")? else {
105        return shape("\"graceServed\" must name the \"owner\" whose grace it waited out");
106    };
107    let Some(heartbeat_at) = optional_i64(served, "heartbeatAt")? else {
108        return shape("\"graceServed\" must name the \"heartbeatAt\" whose grace it waited out");
109    };
110    Ok(GraceServed::parse(&owner, heartbeat_at))
111}
112
113/// `follow` in the three shapes the TS `OpenOptions` takes: `false` to never catch up unprompted,
114/// `true` for the engine's default interval, or `{ intervalMs }` for a custom one. Absent is not
115/// handled here — it means "resolve by `readonly`" and never reaches this function.
116fn parse_follow(value: &Value) -> Result<FollowOption, OptionsError> {
117    match value {
118        Value::Bool(false) => Ok(FollowOption::Off),
119        Value::Bool(true) => Ok(FollowOption::Every(Duration::ZERO)),
120        Value::Object(object) => match optional_u64(object, "intervalMs")? {
121            Some(interval_ms) => Ok(FollowOption::Every(Duration::from_millis(interval_ms))),
122            None => Ok(FollowOption::Every(Duration::ZERO)),
123        },
124        _ => shape("\"follow\" must be a boolean or an object with \"intervalMs\""),
125    }
126}
127
128/// `compaction` in the two shapes the TS `OpenOptions` takes: `false` to never rewrite a log
129/// unprompted, or `{ deadBytesRatio, minDeadBytes }` to set both thresholds. Absent is not handled
130/// here — it means "leave it to the catalog" and never reaches this function.
131fn parse_compaction(value: &Value) -> Result<CatalogCompaction, OptionsError> {
132    match value {
133        Value::Bool(false) => Ok(CatalogCompaction::Disabled),
134        Value::Object(object) => {
135            let ratio = match object.get("deadBytesRatio") {
136                None | Some(Value::Null) => None,
137                Some(Value::Number(number)) => number.as_f64(),
138                Some(_) => return shape("\"deadBytesRatio\" must be a number"),
139            };
140            let Some(dead_bytes_ratio) = ratio.filter(|ratio| *ratio > 0.0 && *ratio <= 1.0) else {
141                return shape("\"deadBytesRatio\" must be a number greater than 0 and at most 1");
142            };
143            let min_dead_bytes = optional_u64(object, "minDeadBytes")?.unwrap_or(0);
144            Ok(CatalogCompaction::Enabled {
145                dead_bytes_ratio,
146                min_dead_bytes,
147            })
148        }
149        _ => shape("\"compaction\" must be false or an object of compaction thresholds"),
150    }
151}
152
153fn parse_layout_kind(raw: &str) -> Result<LayoutKind, OptionsError> {
154    match raw {
155        "flat" => Ok(LayoutKind::Flat),
156        "nested" => Ok(LayoutKind::Nested),
157        other => shape(format!("\"layout\" must be \"flat\" or \"nested\" — got \"{other}\"")),
158    }
159}
160
161/// The `layout`/`metadataFile`/`manifest` triple, passed on unresolved: whether the two file names
162/// agree, and whether the requested arrangement matches the one on disk, is the engine's call, so
163/// both refusals read the same however a caller reaches them.
164fn parse_layout(object: &serde_json::Map<String, Value>) -> Result<LayoutOptions, OptionsError> {
165    Ok(LayoutOptions {
166        kind: match optional_string(object, "layout")? {
167            Some(raw) => Some(parse_layout_kind(&raw)?),
168            None => None,
169        },
170        metadata_file: optional_string(object, "metadataFile")?,
171        manifest: optional_string(object, "manifest")?,
172    })
173}
174
175fn parse_missing_key_policy(raw: &str) -> Result<MissingKeyPolicy, OptionsError> {
176    match raw {
177        "throw" => Ok(MissingKeyPolicy::Throw),
178        "omit" => Ok(MissingKeyPolicy::Omit),
179        "raw" => Ok(MissingKeyPolicy::Raw),
180        other => shape(format!(
181            "\"onMissingKey\" must be one of \"throw\", \"omit\", \"raw\" — got \"{other}\""
182        )),
183    }
184}
185
186/// Decodes one key of the `cypher.keys` map. `encoding` is the document-wide `keyEncoding`.
187fn decode_key(id: &str, raw: &str, encoding: KeyEncoding) -> Result<Vec<u8>, OptionsError> {
188    let decoded = match encoding {
189        KeyEncoding::Base64 => decode_base64(raw),
190        KeyEncoding::Hex => decode_hex(raw),
191    };
192    decoded.ok_or_else(|| OptionsError::Key(format!("key \"{id}\" is not valid {}", encoding.as_str())))
193}
194
195#[derive(Debug, Clone, Copy, PartialEq, Eq)]
196pub enum KeyEncoding {
197    Base64,
198    Hex,
199}
200
201impl KeyEncoding {
202    fn as_str(self) -> &'static str {
203        match self {
204            KeyEncoding::Base64 => "base64",
205            KeyEncoding::Hex => "hex",
206        }
207    }
208}
209
210fn base64_symbol(byte: u8) -> Option<u8> {
211    match byte {
212        b'A'..=b'Z' => Some(byte - b'A'),
213        b'a'..=b'z' => Some(byte - b'a' + 26),
214        b'0'..=b'9' => Some(byte - b'0' + 52),
215        // NOTE: accepts the URL-safe alphabet too — Node emits it for `base64url` encodings.
216        b'+' | b'-' => Some(62),
217        b'/' | b'_' => Some(63),
218        _ => None,
219    }
220}
221
222/// Standard and URL-safe base64, padding optional. `None` on any symbol outside the alphabet or a
223/// length that cannot be a whole number of bytes.
224pub fn decode_base64(raw: &str) -> Option<Vec<u8>> {
225    let symbols: &[u8] = raw.trim_end_matches('=').as_bytes();
226    if symbols.len() % 4 == 1 {
227        return None;
228    }
229    let mut out = Vec::with_capacity(symbols.len() * 3 / 4);
230    let mut accumulator: u32 = 0;
231    let mut bits = 0u32;
232    for byte in symbols {
233        accumulator = (accumulator << 6) | u32::from(base64_symbol(*byte)?);
234        bits += 6;
235        if bits >= 8 {
236            bits -= 8;
237            out.push((accumulator >> bits) as u8);
238        }
239    }
240    // Leftover bits of a truncated group must be zero, or the input was not base64 of these bytes.
241    if accumulator & ((1 << bits) - 1) != 0 {
242        return None;
243    }
244    Some(out)
245}
246
247/// Lowercase or uppercase hex, no separators. `None` on an odd length or a non-hex digit.
248pub fn decode_hex(raw: &str) -> Option<Vec<u8>> {
249    let digits = raw.as_bytes();
250    if !digits.len().is_multiple_of(2) {
251        return None;
252    }
253    let mut out = Vec::with_capacity(digits.len() / 2);
254    for pair in digits.chunks_exact(2) {
255        let high = (pair[0] as char).to_digit(16)?;
256        let low = (pair[1] as char).to_digit(16)?;
257        out.push((high * 16 + low) as u8);
258    }
259    Some(out)
260}
261
262/// The `cypher` sub-document of the `open()` options document, on its own — `{ keys, keyId,
263/// keyEncoding, onMissingKey }`. Public because a host that reads key material from a file or an
264/// environment variable (`crate::keys`) has such a document and no options document around it.
265pub fn parse_cypher(value: &Value) -> Result<CipherOptions, OptionsError> {
266    let object = as_object(value, "cypher")?;
267    let encoding = match optional_string(object, "keyEncoding")?.as_deref() {
268        None | Some("base64") => KeyEncoding::Base64,
269        Some("hex") => KeyEncoding::Hex,
270        Some(other) => {
271            return shape(format!(
272                "\"keyEncoding\" must be \"base64\" or \"hex\" — got \"{other}\""
273            ))
274        }
275    };
276
277    let raw_keys = match object.get("keys") {
278        Some(keys) => as_object(keys, "cypher.keys")?,
279        None => return shape("\"cypher\" needs a \"keys\" object"),
280    };
281
282    let mut keys = HashMap::with_capacity(raw_keys.len());
283    for (id, material) in raw_keys {
284        let Some(material) = material.as_str() else {
285            return shape(format!("key \"{id}\" must be a string"));
286        };
287        keys.insert(id.clone(), decode_key(id, material, encoding)?);
288    }
289
290    let on_missing_key = match optional_string(object, "onMissingKey")? {
291        Some(raw) => Some(parse_missing_key_policy(&raw)?),
292        None => None,
293    };
294
295    Ok(CipherOptions {
296        keys,
297        key_id: optional_string(object, "keyId")?,
298        on_missing_key,
299    })
300}
301
302/// Builds `OpenOptions` from the JSON document `open()` takes. Every member is optional; an absent
303/// one keeps the engine's own default, so `{}` and `null` both mean "open it the usual way".
304pub fn parse_open_options(value: &Value) -> Result<OpenOptions, OptionsError> {
305    let mut options = OpenOptions::default();
306    if value.is_null() {
307        return Ok(options);
308    }
309    let object = as_object(value, "options")?;
310
311    if let Some(readonly) = optional_bool(object, "readonly")? {
312        options.readonly = readonly;
313    }
314    if let Some(snapshot_every) = optional_u64(object, "snapshotEvery")? {
315        options.snapshot_every = snapshot_every;
316    }
317    if let Some(compaction) = object.get("compaction").filter(|value| !value.is_null()) {
318        options.compaction = Some(parse_compaction(compaction)?);
319    }
320    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
321        options.lock = parse_lock(lock)?;
322    }
323    if let Some(cypher) = object.get("cypher").filter(|value| !value.is_null()) {
324        options.cypher = Some(parse_cypher(cypher)?);
325    }
326    if let Some(follow) = object.get("follow").filter(|value| !value.is_null()) {
327        options.follow = parse_follow(follow)?;
328    }
329    if let Some(max) = optional_u64(object, "maxImageBytes")? {
330        options.max_image_bytes = Some(max);
331    }
332    if let Some(cost) = object.get("passwordHash").filter(|value| !value.is_null()) {
333        options.password_hash = parse_password_hash(cost)?;
334    }
335    options.layout = parse_layout(object)?;
336
337    Ok(options)
338}
339
340/// Builds [`LayoutMigrationOptions`] from the JSON document `migrateLayout()` takes — the TS
341/// `LayoutMigrationOptions`, member for member, plus the `lock` of `open()` so a host that has to
342/// wait differently for the writer lock can say so. Every member is optional; `{}` and `null` both
343/// mean "move it into the nested arrangement, keeping the document's name".
344///
345/// Neither pair of document names is resolved here, for the same reason `parse_layout` resolves
346/// nothing: whether the two names of a pair agree is the engine's refusal to make, so it reads the
347/// same however a caller reaches it.
348pub fn parse_migrate_layout_options(value: &Value) -> Result<LayoutMigrationOptions, OptionsError> {
349    let mut options = LayoutMigrationOptions::default();
350    if value.is_null() {
351        return Ok(options);
352    }
353    let object = as_object(value, "options")?;
354
355    options.to = match optional_string(object, "to")? {
356        Some(raw) => Some(parse_migration_target(&raw)?),
357        None => None,
358    };
359    options.from_metadata_file = optional_string(object, "fromMetadataFile")?;
360    options.from_manifest = optional_string(object, "fromManifest")?;
361    options.metadata_file = optional_string(object, "metadataFile")?;
362    options.manifest_file = optional_string(object, "manifestFile")?;
363    options.dry_run = optional_bool(object, "dryRun")?.unwrap_or(false);
364    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
365        options.lock = parse_lock(lock)?;
366    }
367
368    Ok(options)
369}
370
371/// Builds [`VerifyOptions`] from the JSON document `verify()` takes:
372/// `{ relations?: boolean, images?: boolean, maxImageBytes?: number }`.
373/// `null` and `{}` mean the defaults.
374pub fn parse_verify_options(value: &Value) -> Result<VerifyOptions, OptionsError> {
375    let mut options = VerifyOptions::default();
376    if value.is_null() {
377        return Ok(options);
378    }
379    let object = as_object(value, "options")?;
380    if let Some(relations) = optional_bool(object, "relations")? {
381        options.relations = relations;
382    }
383    if let Some(images) = optional_bool(object, "images")? {
384        options.images = images;
385    }
386    options.max_image_bytes = match object.get("maxImageBytes") {
387        None | Some(Value::Null) => None,
388        Some(value) => match value.as_u64() {
389            Some(bytes) => Some(bytes),
390            None => return shape("\"maxImageBytes\" must be a non-negative integer".to_string()),
391        },
392    };
393    Ok(options)
394}
395
396/// Builds [`BackupOptions`] from the JSON document `backup()` takes: `{ indexes?: boolean, excludeTables?: string[], lock? }`.
397pub fn parse_backup_options(value: &Value) -> Result<BackupOptions, OptionsError> {
398    let mut options = BackupOptions::default();
399    if value.is_null() {
400        return Ok(options);
401    }
402    let object = as_object(value, "options")?;
403    options.indexes = optional_bool(object, "indexes")?.unwrap_or(false);
404    options.exclude_tables = parse_exclude_tables(object)?;
405    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
406        options.lock = parse_lock(lock)?;
407    }
408    Ok(options)
409}
410
411/// Builds [`RestoreOptions`] from the JSON document `restore()` takes: `{ maxImageBytes?, lock? }`.
412pub fn parse_restore_options(value: &Value) -> Result<RestoreOptions, OptionsError> {
413    let mut options = RestoreOptions::default();
414    if value.is_null() {
415        return Ok(options);
416    }
417    let object = as_object(value, "options")?;
418    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
419        options.lock = parse_lock(lock)?;
420    }
421    Ok(options)
422}
423
424/// `{ memoryKiB?, iterations?, parallelism? }` — the Argon2id cost of new `passwordHash` values;
425/// whatever is left out keeps the engine's default.
426fn parse_password_hash(value: &Value) -> Result<PasswordHashParams, OptionsError> {
427    let object = as_object(value, "passwordHash")?;
428    let mut params = PasswordHashParams::default();
429    for (key, target) in [
430        ("memoryKiB", &mut params.memory_kib),
431        ("iterations", &mut params.iterations),
432        ("parallelism", &mut params.parallelism),
433    ] {
434        if let Some(number) = optional_u64(object, key)? {
435            *target = match u32::try_from(number) {
436                Ok(number) => number,
437                Err(_) => return shape(format!("\"passwordHash.{key}\" is too large")),
438            };
439        }
440    }
441    params.validate().map_err(|error| OptionsError::Shape(error.0))?;
442    Ok(params)
443}
444
445/// `excludeTables?: string[]` of a `backup()`/`pack()` options document.
446fn parse_exclude_tables(object: &serde_json::Map<String, Value>) -> Result<Vec<String>, OptionsError> {
447    let Some(raw) = object.get("excludeTables").filter(|value| !value.is_null()) else {
448        return Ok(Vec::new());
449    };
450    let Some(items) = raw.as_array() else {
451        return shape("\"excludeTables\" must be an array of table names");
452    };
453    items
454        .iter()
455        .map(|item| match item.as_str() {
456            Some(name) => Ok(name.to_string()),
457            None => shape("\"excludeTables\" must be an array of table names"),
458        })
459        .collect()
460}
461
462fn parse_pack_limits(object: &serde_json::Map<String, Value>) -> Result<PackLimits, OptionsError> {
463    let mut limits = PackLimits::default();
464    let Some(raw) = object.get("limits").filter(|value| !value.is_null()) else {
465        return Ok(limits);
466    };
467    let raw = as_object(raw, "limits")?;
468    let number = |key: &str| -> Result<Option<u64>, OptionsError> {
469        match raw.get(key).filter(|value| !value.is_null()) {
470            None => Ok(None),
471            Some(value) => match value.as_u64() {
472                Some(number) => Ok(Some(number)),
473                None => shape(format!("\"limits.{key}\" must be a non-negative integer")),
474            },
475        }
476    };
477    if let Some(value) = number("maxArchiveBytes")? {
478        limits.max_archive_bytes = value;
479    }
480    if let Some(value) = number("maxTotalBytes")? {
481        limits.max_total_bytes = value;
482    }
483    if let Some(value) = number("maxEntryBytes")? {
484        limits.max_entry_bytes = value;
485    }
486    if let Some(value) = number("maxEntries")? {
487        limits.max_entries = value as usize;
488    }
489    Ok(limits)
490}
491
492/// Builds [`PackLimits`] from `{ limits?: { maxArchiveBytes?, maxTotalBytes?, maxEntryBytes?, maxEntries? } }`.
493pub fn parse_pack_limits_options(value: &Value) -> Result<PackLimits, OptionsError> {
494    if value.is_null() {
495        return Ok(PackLimits::default());
496    }
497    parse_pack_limits(as_object(value, "options")?)
498}
499
500/// Builds [`PackOptions`] from the JSON document `pack()` takes:
501/// `{ indexes?: boolean, excludeTables?: string[], extra?: { [entryName]: string }, limits?, lock? }`.
502pub fn parse_pack_options(value: &Value) -> Result<PackOptions, OptionsError> {
503    let mut options = PackOptions::default();
504    if value.is_null() {
505        return Ok(options);
506    }
507    let object = as_object(value, "options")?;
508    options.indexes = optional_bool(object, "indexes")?.unwrap_or(false);
509    options.exclude_tables = parse_exclude_tables(object)?;
510    if let Some(extra) = object.get("extra").filter(|value| !value.is_null()) {
511        for (name, content) in as_object(extra, "extra")? {
512            match content.as_str() {
513                Some(text) => options.extra.push((name.clone(), text.as_bytes().to_vec())),
514                None => return shape(format!("\"extra.{name}\" must be a string")),
515            }
516        }
517    }
518    options.limits = parse_pack_limits(object)?;
519    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
520        options.lock = parse_lock(lock)?;
521    }
522    Ok(options)
523}
524
525/// Builds [`UnpackOptions`] from the JSON document `unpack()` takes: `{ limits?, maxImageBytes?, lock? }`.
526pub fn parse_unpack_options(value: &Value) -> Result<UnpackOptions, OptionsError> {
527    let mut options = UnpackOptions::default();
528    if value.is_null() {
529        return Ok(options);
530    }
531    let object = as_object(value, "options")?;
532    options.max_image_bytes = optional_u64(object, "maxImageBytes")?;
533    options.limits = parse_pack_limits(object)?;
534    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
535        options.lock = parse_lock(lock)?;
536    }
537    Ok(options)
538}
539
540fn parse_migration_target(raw: &str) -> Result<LayoutKind, OptionsError> {
541    match raw {
542        "flat" => Ok(LayoutKind::Flat),
543        "nested" => Ok(LayoutKind::Nested),
544        other => shape(format!("\"to\" must be \"flat\" or \"nested\" — got \"{other}\"")),
545    }
546}
547
548#[cfg(test)]
549mod tests {
550    use serde_json::json;
551
552    use super::*;
553
554    #[test]
555    fn an_absent_document_keeps_every_engine_default() {
556        let options = parse_open_options(&Value::Null).unwrap();
557
558        assert!(!options.readonly);
559        assert_eq!(options.snapshot_every, OpenOptions::default().snapshot_every);
560        assert!(options.cypher.is_none());
561    }
562
563    #[test]
564    fn readonly_snapshot_every_and_lock_reach_the_engine_options() {
565        let options = parse_open_options(&json!({
566            "readonly": true,
567            "snapshotEvery": 5,
568            "lock": { "timeoutMs": 0, "retryIntervalMs": 10 },
569        }))
570        .unwrap();
571
572        assert!(options.readonly);
573        assert_eq!(options.snapshot_every, 5);
574        let lock = options
575            .lock
576            .options()
577            .expect("an object shape asks for a lock, not for skipping");
578        assert_eq!(lock.timeout_ms, Some(0));
579        assert_eq!(lock.retry_interval_ms, Some(10));
580        assert_eq!(lock.heartbeat_ms, None);
581    }
582
583    #[test]
584    fn compaction_reaches_the_engine_in_both_the_thresholds_and_the_false_shape() {
585        let named = parse_open_options(&json!({
586            "compaction": { "deadBytesRatio": 0.5, "minDeadBytes": 200 },
587        }))
588        .unwrap();
589        assert_eq!(
590            named.compaction,
591            Some(CatalogCompaction::Enabled {
592                dead_bytes_ratio: 0.5,
593                min_dead_bytes: 200
594            })
595        );
596
597        let off = parse_open_options(&json!({ "compaction": false })).unwrap();
598        assert_eq!(off.compaction, Some(CatalogCompaction::Disabled));
599
600        // NOTE: absent and null both mean "leave it to the catalog", which is not the same as false.
601        for document in [json!({}), json!({ "compaction": null })] {
602            assert_eq!(parse_open_options(&document).unwrap().compaction, None, "{document}");
603        }
604    }
605
606    #[test]
607    fn a_compaction_ratio_outside_zero_to_one_is_refused_before_the_engine_is_touched() {
608        for ratio in [json!(0), json!(1.5), json!("half")] {
609            let document = json!({ "compaction": { "deadBytesRatio": ratio, "minDeadBytes": 1 } });
610            assert!(parse_open_options(&document).is_err(), "{document}");
611        }
612        assert!(parse_open_options(&json!({ "compaction": true })).is_err());
613    }
614
615    #[test]
616    fn lock_false_asks_the_engine_to_skip_the_writer_lock_and_true_asks_for_the_defaults() {
617        assert!(matches!(
618            parse_open_options(&json!({ "lock": false })).unwrap().lock,
619            LockMode::Skip
620        ));
621
622        // NOTE: absent and null must stay the locked default — skipping is opt-in only.
623        for document in [
624            json!({}),
625            json!({ "lock": null }),
626            json!({ "lock": true }),
627            json!({ "lock": {} }),
628        ] {
629            let lock = parse_open_options(&document).unwrap().lock;
630            assert!(matches!(lock, LockMode::Enabled(_)), "{document} must keep the lock");
631            assert_eq!(lock.options().unwrap().timeout_ms, None);
632        }
633    }
634
635    #[test]
636    fn a_lock_that_is_neither_a_flag_nor_an_options_object_is_refused_as_a_shape_error() {
637        assert_eq!(
638            parse_open_options(&json!({ "lock": "off" })).unwrap_err(),
639            OptionsError::Shape("\"lock\" must be a boolean or an object of lock options".to_string())
640        );
641        assert_eq!(
642            parse_open_options(&json!({ "lock": { "timeoutMs": -1 } })).unwrap_err(),
643            OptionsError::Shape("\"timeoutMs\" must be a non-negative whole number".to_string())
644        );
645    }
646
647    #[test]
648    fn a_base64_keyring_decodes_to_the_exact_bytes_and_keeps_its_write_key() {
649        let options = parse_open_options(&json!({
650            "cypher": {
651                "keys": { "k1": "AAECAw==" },
652                "keyId": "k1",
653                "onMissingKey": "omit",
654            },
655        }))
656        .unwrap();
657
658        let cypher = options.cypher.unwrap();
659        assert_eq!(cypher.keys["k1"], vec![0, 1, 2, 3]);
660        assert_eq!(cypher.key_id.as_deref(), Some("k1"));
661        assert_eq!(cypher.on_missing_key, Some(MissingKeyPolicy::Omit));
662    }
663
664    #[test]
665    fn a_hex_keyring_decodes_only_when_key_encoding_says_so() {
666        let hex = json!({ "cypher": { "keys": { "k1": "00010203" }, "keyEncoding": "hex" } });
667        let options = parse_open_options(&hex).unwrap();
668        assert_eq!(options.cypher.unwrap().keys["k1"], vec![0, 1, 2, 3]);
669
670        // NOTE: "00010203" is also valid base64 — the same text decodes to different bytes.
671        let as_base64 = json!({ "cypher": { "keys": { "k1": "00010203" } } });
672        assert_ne!(
673            parse_open_options(&as_base64).unwrap().cypher.unwrap().keys["k1"],
674            vec![0, 1, 2, 3]
675        );
676    }
677
678    #[test]
679    fn unusable_key_material_is_reported_as_a_key_error_naming_the_key() {
680        let error = parse_open_options(&json!({ "cypher": { "keys": { "k1": "!!!!" } } })).unwrap_err();
681
682        assert_eq!(error, OptionsError::Key("key \"k1\" is not valid base64".to_string()));
683    }
684
685    #[test]
686    fn a_wrong_typed_option_is_refused_as_a_shape_error_naming_the_member() {
687        assert_eq!(
688            parse_open_options(&json!({ "readonly": "yes" })).unwrap_err(),
689            OptionsError::Shape("\"readonly\" must be a boolean".to_string())
690        );
691        assert_eq!(
692            parse_open_options(&json!({ "snapshotEvery": -1 })).unwrap_err(),
693            OptionsError::Shape("\"snapshotEvery\" must be a non-negative whole number".to_string())
694        );
695        assert!(matches!(
696            parse_open_options(&json!({ "cypher": { "keys": {}, "onMissingKey": "shrug" } })).unwrap_err(),
697            OptionsError::Shape(_)
698        ));
699    }
700
701    #[test]
702    fn follow_reaches_the_engine_in_all_three_shapes_the_option_takes() {
703        assert_eq!(parse_open_options(&json!({})).unwrap().follow, FollowOption::Default);
704        assert_eq!(
705            parse_open_options(&json!({ "follow": null })).unwrap().follow,
706            FollowOption::Default
707        );
708        assert_eq!(
709            parse_open_options(&json!({ "follow": false })).unwrap().follow,
710            FollowOption::Off
711        );
712        assert_eq!(
713            parse_open_options(&json!({ "follow": true })).unwrap().follow,
714            FollowOption::Every(Duration::ZERO)
715        );
716        assert_eq!(
717            parse_open_options(&json!({ "follow": { "intervalMs": 250 } }))
718                .unwrap()
719                .follow,
720            FollowOption::Every(Duration::from_millis(250))
721        );
722        assert_eq!(
723            parse_open_options(&json!({ "follow": {} })).unwrap().follow,
724            FollowOption::Every(Duration::ZERO)
725        );
726    }
727
728    #[test]
729    fn a_follow_that_is_neither_a_flag_nor_an_interval_is_refused_as_a_shape_error() {
730        assert!(matches!(
731            parse_open_options(&json!({ "follow": "always" })).unwrap_err(),
732            OptionsError::Shape(_)
733        ));
734        assert!(matches!(
735            parse_open_options(&json!({ "follow": { "intervalMs": -1 } })).unwrap_err(),
736            OptionsError::Shape(_)
737        ));
738    }
739
740    #[test]
741    fn the_layout_triple_reaches_the_engine_unresolved() {
742        assert_eq!(parse_open_options(&json!({})).unwrap().layout, LayoutOptions::default());
743
744        let named = parse_open_options(&json!({
745            "layout": "nested",
746            "metadataFile": "cerebro.json",
747        }))
748        .unwrap();
749        assert_eq!(named.layout.kind, Some(LayoutKind::Nested));
750        assert_eq!(named.layout.metadata_file.as_deref(), Some("cerebro.json"));
751        assert_eq!(named.layout.manifest, None);
752
753        // NOTE: the two names are passed on as given — the engine, not this, decides they conflict.
754        let both = parse_open_options(&json!({ "manifest": "a.json", "metadataFile": "b.json" })).unwrap();
755        assert_eq!(both.layout.manifest.as_deref(), Some("a.json"));
756        assert_eq!(both.layout.metadata_file.as_deref(), Some("b.json"));
757    }
758
759    #[test]
760    fn an_unknown_layout_kind_and_a_non_string_file_name_are_refused_as_shape_errors() {
761        assert_eq!(
762            parse_open_options(&json!({ "layout": "sideways" })).unwrap_err(),
763            OptionsError::Shape("\"layout\" must be \"flat\" or \"nested\" — got \"sideways\"".to_string())
764        );
765        assert_eq!(
766            parse_open_options(&json!({ "metadataFile": 7 })).unwrap_err(),
767            OptionsError::Shape("\"metadataFile\" must be a string".to_string())
768        );
769    }
770
771    #[test]
772    fn a_migration_with_no_document_moves_into_the_nested_arrangement_under_the_engine_lock() {
773        let options = parse_migrate_layout_options(&Value::Null).unwrap();
774
775        assert_eq!(options.to, None, "absent is the engine's own default, not a second one");
776        assert!(!options.dry_run);
777        assert!(options.metadata_file.is_none() && options.from_metadata_file.is_none());
778        assert!(matches!(options.lock, LockMode::Enabled(_)));
779    }
780
781    #[test]
782    fn both_document_name_pairs_reach_the_engine_unresolved_so_it_makes_the_refusal() {
783        let options = parse_migrate_layout_options(&json!({
784            "to": "flat",
785            "fromMetadataFile": "cerebro.json",
786            "fromManifest": "legacy.json",
787            "metadataFile": "hayson.json",
788            "manifestFile": "old.json",
789            "dryRun": true,
790        }))
791        .unwrap();
792
793        assert_eq!(options.to, Some(LayoutKind::Flat));
794        assert_eq!(options.from_metadata_file.as_deref(), Some("cerebro.json"));
795        assert_eq!(options.from_manifest.as_deref(), Some("legacy.json"));
796        assert_eq!(options.metadata_file.as_deref(), Some("hayson.json"));
797        assert_eq!(options.manifest_file.as_deref(), Some("old.json"));
798        assert!(options.dry_run);
799    }
800
801    #[test]
802    fn a_migration_takes_the_same_lock_document_an_open_takes() {
803        let options = parse_migrate_layout_options(&json!({ "lock": { "timeoutMs": 0 } })).unwrap();
804
805        assert_eq!(
806            options.lock.options().and_then(|lock| lock.timeout_ms),
807            Some(0),
808            "a host that owns the wait has to be able to ask for a fail-fast attempt"
809        );
810        let skipped = parse_migrate_layout_options(&json!({ "lock": false })).unwrap();
811        assert!(matches!(skipped.lock, LockMode::Skip));
812    }
813
814    #[test]
815    fn an_unknown_migration_target_is_refused_as_a_shape_error() {
816        assert_eq!(
817            parse_migrate_layout_options(&json!({ "to": "sideways" })).unwrap_err(),
818            OptionsError::Shape("\"to\" must be \"flat\" or \"nested\" — got \"sideways\"".to_string())
819        );
820        assert_eq!(
821            parse_migrate_layout_options(&json!({ "dryRun": "yes" })).unwrap_err(),
822            OptionsError::Shape("\"dryRun\" must be a boolean".to_string())
823        );
824    }
825
826    #[test]
827    fn base64_accepts_the_url_safe_alphabet_and_optional_padding() {
828        assert_eq!(decode_base64("+/8="), decode_base64("-_8"));
829        assert_eq!(decode_base64(""), Some(Vec::new()));
830        assert_eq!(decode_base64("QQ"), Some(vec![b'A']));
831        assert_eq!(decode_base64("QQ=="), Some(vec![b'A']));
832    }
833
834    #[test]
835    fn base64_refuses_a_length_and_a_symbol_that_cannot_be_base64() {
836        assert_eq!(decode_base64("A"), None);
837        assert_eq!(decode_base64("QQ*="), None);
838    }
839
840    #[test]
841    fn hex_round_trips_both_cases_and_refuses_odd_or_non_hex_input() {
842        assert_eq!(decode_hex("DEADbeef"), Some(vec![0xde, 0xad, 0xbe, 0xef]));
843        assert_eq!(decode_hex("abc"), None);
844        assert_eq!(decode_hex("zz"), None);
845    }
846
847    #[test]
848    fn pack_options_carry_extra_entries_limits_and_the_lock() {
849        let options = parse_pack_options(&json!({
850            "indexes": true,
851            "excludeTables": ["users"],
852            "extra": { "gly.json": "{}" },
853            "limits": { "maxEntries": 5, "maxEntryBytes": 10 },
854        }))
855        .unwrap();
856
857        assert!(options.indexes);
858        assert_eq!(options.exclude_tables, vec!["users".to_string()]);
859        assert_eq!(options.extra, vec![("gly.json".to_string(), b"{}".to_vec())]);
860        assert_eq!(options.limits.max_entries, 5);
861        assert_eq!(options.limits.max_entry_bytes, 10);
862        assert_eq!(
863            options.limits.max_archive_bytes,
864            PackLimits::default().max_archive_bytes
865        );
866        assert!(parse_pack_options(&json!({ "extra": { "a": 1 } })).is_err());
867        assert!(parse_unpack_options(&json!({ "limits": { "maxEntries": -1 } })).is_err());
868        assert_eq!(
869            parse_unpack_options(&Value::Null).unwrap().limits,
870            PackLimits::default()
871        );
872    }
873}
hayson_binding_shared/options.rs

hayson_binding_shared/
options.rs
