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, PackInclude,
10    PackLimits, 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
462/// `include?: [{ path: string, excludeTables?: string[] }]` of a `pack()` options document.
463fn parse_pack_includes(object: &serde_json::Map<String, Value>) -> Result<Vec<PackInclude>, OptionsError> {
464    let Some(raw) = object.get("include").filter(|value| !value.is_null()) else {
465        return Ok(Vec::new());
466    };
467    let Some(items) = raw.as_array() else {
468        return shape("\"include\" must be an array of { path, excludeTables? }");
469    };
470    let mut includes = Vec::new();
471    for item in items {
472        let entry = as_object(item, "include[]")?;
473        let Some(path) = optional_string(entry, "path")? else {
474            return shape("every \"include\" entry needs a \"path\"");
475        };
476        includes.push(PackInclude {
477            path,
478            exclude_tables: parse_exclude_tables(entry)?,
479        });
480    }
481    Ok(includes)
482}
483
484fn parse_pack_limits(object: &serde_json::Map<String, Value>) -> Result<PackLimits, OptionsError> {
485    let mut limits = PackLimits::default();
486    let Some(raw) = object.get("limits").filter(|value| !value.is_null()) else {
487        return Ok(limits);
488    };
489    let raw = as_object(raw, "limits")?;
490    let number = |key: &str| -> Result<Option<u64>, OptionsError> {
491        match raw.get(key).filter(|value| !value.is_null()) {
492            None => Ok(None),
493            Some(value) => match value.as_u64() {
494                Some(number) => Ok(Some(number)),
495                None => shape(format!("\"limits.{key}\" must be a non-negative integer")),
496            },
497        }
498    };
499    if let Some(value) = number("maxArchiveBytes")? {
500        limits.max_archive_bytes = value;
501    }
502    if let Some(value) = number("maxTotalBytes")? {
503        limits.max_total_bytes = value;
504    }
505    if let Some(value) = number("maxEntryBytes")? {
506        limits.max_entry_bytes = value;
507    }
508    if let Some(value) = number("maxEntries")? {
509        limits.max_entries = value as usize;
510    }
511    Ok(limits)
512}
513
514/// Builds [`PackLimits`] from `{ limits?: { maxArchiveBytes?, maxTotalBytes?, maxEntryBytes?, maxEntries? } }`.
515pub fn parse_pack_limits_options(value: &Value) -> Result<PackLimits, OptionsError> {
516    if value.is_null() {
517        return Ok(PackLimits::default());
518    }
519    parse_pack_limits(as_object(value, "options")?)
520}
521
522/// Builds [`PackOptions`] from the JSON document `pack()` takes:
523/// `{ indexes?: boolean, excludeTables?: string[], extra?: { [entryName]: string }, limits?, lock? }`.
524pub fn parse_pack_options(value: &Value) -> Result<PackOptions, OptionsError> {
525    let mut options = PackOptions::default();
526    if value.is_null() {
527        return Ok(options);
528    }
529    let object = as_object(value, "options")?;
530    options.indexes = optional_bool(object, "indexes")?.unwrap_or(false);
531    options.exclude_tables = parse_exclude_tables(object)?;
532    options.include = parse_pack_includes(object)?;
533    if let Some(extra) = object.get("extra").filter(|value| !value.is_null()) {
534        for (name, content) in as_object(extra, "extra")? {
535            match content.as_str() {
536                Some(text) => options.extra.push((name.clone(), text.as_bytes().to_vec())),
537                None => return shape(format!("\"extra.{name}\" must be a string")),
538            }
539        }
540    }
541    options.limits = parse_pack_limits(object)?;
542    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
543        options.lock = parse_lock(lock)?;
544    }
545    Ok(options)
546}
547
548/// Builds [`UnpackOptions`] from the JSON document `unpack()` takes: `{ limits?, maxImageBytes?, lock? }`.
549pub fn parse_unpack_options(value: &Value) -> Result<UnpackOptions, OptionsError> {
550    let mut options = UnpackOptions::default();
551    if value.is_null() {
552        return Ok(options);
553    }
554    let object = as_object(value, "options")?;
555    options.max_image_bytes = optional_u64(object, "maxImageBytes")?;
556    options.limits = parse_pack_limits(object)?;
557    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
558        options.lock = parse_lock(lock)?;
559    }
560    Ok(options)
561}
562
563fn parse_migration_target(raw: &str) -> Result<LayoutKind, OptionsError> {
564    match raw {
565        "flat" => Ok(LayoutKind::Flat),
566        "nested" => Ok(LayoutKind::Nested),
567        other => shape(format!("\"to\" must be \"flat\" or \"nested\" — got \"{other}\"")),
568    }
569}
570
571#[cfg(test)]
572mod tests {
573    use serde_json::json;
574
575    use super::*;
576
577    #[test]
578    fn an_absent_document_keeps_every_engine_default() {
579        let options = parse_open_options(&Value::Null).unwrap();
580
581        assert!(!options.readonly);
582        assert_eq!(options.snapshot_every, OpenOptions::default().snapshot_every);
583        assert!(options.cypher.is_none());
584    }
585
586    #[test]
587    fn readonly_snapshot_every_and_lock_reach_the_engine_options() {
588        let options = parse_open_options(&json!({
589            "readonly": true,
590            "snapshotEvery": 5,
591            "lock": { "timeoutMs": 0, "retryIntervalMs": 10 },
592        }))
593        .unwrap();
594
595        assert!(options.readonly);
596        assert_eq!(options.snapshot_every, 5);
597        let lock = options
598            .lock
599            .options()
600            .expect("an object shape asks for a lock, not for skipping");
601        assert_eq!(lock.timeout_ms, Some(0));
602        assert_eq!(lock.retry_interval_ms, Some(10));
603        assert_eq!(lock.heartbeat_ms, None);
604    }
605
606    #[test]
607    fn compaction_reaches_the_engine_in_both_the_thresholds_and_the_false_shape() {
608        let named = parse_open_options(&json!({
609            "compaction": { "deadBytesRatio": 0.5, "minDeadBytes": 200 },
610        }))
611        .unwrap();
612        assert_eq!(
613            named.compaction,
614            Some(CatalogCompaction::Enabled {
615                dead_bytes_ratio: 0.5,
616                min_dead_bytes: 200
617            })
618        );
619
620        let off = parse_open_options(&json!({ "compaction": false })).unwrap();
621        assert_eq!(off.compaction, Some(CatalogCompaction::Disabled));
622
623        // NOTE: absent and null both mean "leave it to the catalog", which is not the same as false.
624        for document in [json!({}), json!({ "compaction": null })] {
625            assert_eq!(parse_open_options(&document).unwrap().compaction, None, "{document}");
626        }
627    }
628
629    #[test]
630    fn a_compaction_ratio_outside_zero_to_one_is_refused_before_the_engine_is_touched() {
631        for ratio in [json!(0), json!(1.5), json!("half")] {
632            let document = json!({ "compaction": { "deadBytesRatio": ratio, "minDeadBytes": 1 } });
633            assert!(parse_open_options(&document).is_err(), "{document}");
634        }
635        assert!(parse_open_options(&json!({ "compaction": true })).is_err());
636    }
637
638    #[test]
639    fn lock_false_asks_the_engine_to_skip_the_writer_lock_and_true_asks_for_the_defaults() {
640        assert!(matches!(
641            parse_open_options(&json!({ "lock": false })).unwrap().lock,
642            LockMode::Skip
643        ));
644
645        // NOTE: absent and null must stay the locked default — skipping is opt-in only.
646        for document in [
647            json!({}),
648            json!({ "lock": null }),
649            json!({ "lock": true }),
650            json!({ "lock": {} }),
651        ] {
652            let lock = parse_open_options(&document).unwrap().lock;
653            assert!(matches!(lock, LockMode::Enabled(_)), "{document} must keep the lock");
654            assert_eq!(lock.options().unwrap().timeout_ms, None);
655        }
656    }
657
658    #[test]
659    fn a_lock_that_is_neither_a_flag_nor_an_options_object_is_refused_as_a_shape_error() {
660        assert_eq!(
661            parse_open_options(&json!({ "lock": "off" })).unwrap_err(),
662            OptionsError::Shape("\"lock\" must be a boolean or an object of lock options".to_string())
663        );
664        assert_eq!(
665            parse_open_options(&json!({ "lock": { "timeoutMs": -1 } })).unwrap_err(),
666            OptionsError::Shape("\"timeoutMs\" must be a non-negative whole number".to_string())
667        );
668    }
669
670    #[test]
671    fn a_base64_keyring_decodes_to_the_exact_bytes_and_keeps_its_write_key() {
672        let options = parse_open_options(&json!({
673            "cypher": {
674                "keys": { "k1": "AAECAw==" },
675                "keyId": "k1",
676                "onMissingKey": "omit",
677            },
678        }))
679        .unwrap();
680
681        let cypher = options.cypher.unwrap();
682        assert_eq!(cypher.keys["k1"], vec![0, 1, 2, 3]);
683        assert_eq!(cypher.key_id.as_deref(), Some("k1"));
684        assert_eq!(cypher.on_missing_key, Some(MissingKeyPolicy::Omit));
685    }
686
687    #[test]
688    fn a_hex_keyring_decodes_only_when_key_encoding_says_so() {
689        let hex = json!({ "cypher": { "keys": { "k1": "00010203" }, "keyEncoding": "hex" } });
690        let options = parse_open_options(&hex).unwrap();
691        assert_eq!(options.cypher.unwrap().keys["k1"], vec![0, 1, 2, 3]);
692
693        // NOTE: "00010203" is also valid base64 — the same text decodes to different bytes.
694        let as_base64 = json!({ "cypher": { "keys": { "k1": "00010203" } } });
695        assert_ne!(
696            parse_open_options(&as_base64).unwrap().cypher.unwrap().keys["k1"],
697            vec![0, 1, 2, 3]
698        );
699    }
700
701    #[test]
702    fn unusable_key_material_is_reported_as_a_key_error_naming_the_key() {
703        let error = parse_open_options(&json!({ "cypher": { "keys": { "k1": "!!!!" } } })).unwrap_err();
704
705        assert_eq!(error, OptionsError::Key("key \"k1\" is not valid base64".to_string()));
706    }
707
708    #[test]
709    fn a_wrong_typed_option_is_refused_as_a_shape_error_naming_the_member() {
710        assert_eq!(
711            parse_open_options(&json!({ "readonly": "yes" })).unwrap_err(),
712            OptionsError::Shape("\"readonly\" must be a boolean".to_string())
713        );
714        assert_eq!(
715            parse_open_options(&json!({ "snapshotEvery": -1 })).unwrap_err(),
716            OptionsError::Shape("\"snapshotEvery\" must be a non-negative whole number".to_string())
717        );
718        assert!(matches!(
719            parse_open_options(&json!({ "cypher": { "keys": {}, "onMissingKey": "shrug" } })).unwrap_err(),
720            OptionsError::Shape(_)
721        ));
722    }
723
724    #[test]
725    fn follow_reaches_the_engine_in_all_three_shapes_the_option_takes() {
726        assert_eq!(parse_open_options(&json!({})).unwrap().follow, FollowOption::Default);
727        assert_eq!(
728            parse_open_options(&json!({ "follow": null })).unwrap().follow,
729            FollowOption::Default
730        );
731        assert_eq!(
732            parse_open_options(&json!({ "follow": false })).unwrap().follow,
733            FollowOption::Off
734        );
735        assert_eq!(
736            parse_open_options(&json!({ "follow": true })).unwrap().follow,
737            FollowOption::Every(Duration::ZERO)
738        );
739        assert_eq!(
740            parse_open_options(&json!({ "follow": { "intervalMs": 250 } }))
741                .unwrap()
742                .follow,
743            FollowOption::Every(Duration::from_millis(250))
744        );
745        assert_eq!(
746            parse_open_options(&json!({ "follow": {} })).unwrap().follow,
747            FollowOption::Every(Duration::ZERO)
748        );
749    }
750
751    #[test]
752    fn a_follow_that_is_neither_a_flag_nor_an_interval_is_refused_as_a_shape_error() {
753        assert!(matches!(
754            parse_open_options(&json!({ "follow": "always" })).unwrap_err(),
755            OptionsError::Shape(_)
756        ));
757        assert!(matches!(
758            parse_open_options(&json!({ "follow": { "intervalMs": -1 } })).unwrap_err(),
759            OptionsError::Shape(_)
760        ));
761    }
762
763    #[test]
764    fn the_layout_triple_reaches_the_engine_unresolved() {
765        assert_eq!(parse_open_options(&json!({})).unwrap().layout, LayoutOptions::default());
766
767        let named = parse_open_options(&json!({
768            "layout": "nested",
769            "metadataFile": "cerebro.json",
770        }))
771        .unwrap();
772        assert_eq!(named.layout.kind, Some(LayoutKind::Nested));
773        assert_eq!(named.layout.metadata_file.as_deref(), Some("cerebro.json"));
774        assert_eq!(named.layout.manifest, None);
775
776        // NOTE: the two names are passed on as given — the engine, not this, decides they conflict.
777        let both = parse_open_options(&json!({ "manifest": "a.json", "metadataFile": "b.json" })).unwrap();
778        assert_eq!(both.layout.manifest.as_deref(), Some("a.json"));
779        assert_eq!(both.layout.metadata_file.as_deref(), Some("b.json"));
780    }
781
782    #[test]
783    fn an_unknown_layout_kind_and_a_non_string_file_name_are_refused_as_shape_errors() {
784        assert_eq!(
785            parse_open_options(&json!({ "layout": "sideways" })).unwrap_err(),
786            OptionsError::Shape("\"layout\" must be \"flat\" or \"nested\" — got \"sideways\"".to_string())
787        );
788        assert_eq!(
789            parse_open_options(&json!({ "metadataFile": 7 })).unwrap_err(),
790            OptionsError::Shape("\"metadataFile\" must be a string".to_string())
791        );
792    }
793
794    #[test]
795    fn a_migration_with_no_document_moves_into_the_nested_arrangement_under_the_engine_lock() {
796        let options = parse_migrate_layout_options(&Value::Null).unwrap();
797
798        assert_eq!(options.to, None, "absent is the engine's own default, not a second one");
799        assert!(!options.dry_run);
800        assert!(options.metadata_file.is_none() && options.from_metadata_file.is_none());
801        assert!(matches!(options.lock, LockMode::Enabled(_)));
802    }
803
804    #[test]
805    fn both_document_name_pairs_reach_the_engine_unresolved_so_it_makes_the_refusal() {
806        let options = parse_migrate_layout_options(&json!({
807            "to": "flat",
808            "fromMetadataFile": "cerebro.json",
809            "fromManifest": "legacy.json",
810            "metadataFile": "hayson.json",
811            "manifestFile": "old.json",
812            "dryRun": true,
813        }))
814        .unwrap();
815
816        assert_eq!(options.to, Some(LayoutKind::Flat));
817        assert_eq!(options.from_metadata_file.as_deref(), Some("cerebro.json"));
818        assert_eq!(options.from_manifest.as_deref(), Some("legacy.json"));
819        assert_eq!(options.metadata_file.as_deref(), Some("hayson.json"));
820        assert_eq!(options.manifest_file.as_deref(), Some("old.json"));
821        assert!(options.dry_run);
822    }
823
824    #[test]
825    fn a_migration_takes_the_same_lock_document_an_open_takes() {
826        let options = parse_migrate_layout_options(&json!({ "lock": { "timeoutMs": 0 } })).unwrap();
827
828        assert_eq!(
829            options.lock.options().and_then(|lock| lock.timeout_ms),
830            Some(0),
831            "a host that owns the wait has to be able to ask for a fail-fast attempt"
832        );
833        let skipped = parse_migrate_layout_options(&json!({ "lock": false })).unwrap();
834        assert!(matches!(skipped.lock, LockMode::Skip));
835    }
836
837    #[test]
838    fn an_unknown_migration_target_is_refused_as_a_shape_error() {
839        assert_eq!(
840            parse_migrate_layout_options(&json!({ "to": "sideways" })).unwrap_err(),
841            OptionsError::Shape("\"to\" must be \"flat\" or \"nested\" — got \"sideways\"".to_string())
842        );
843        assert_eq!(
844            parse_migrate_layout_options(&json!({ "dryRun": "yes" })).unwrap_err(),
845            OptionsError::Shape("\"dryRun\" must be a boolean".to_string())
846        );
847    }
848
849    #[test]
850    fn base64_accepts_the_url_safe_alphabet_and_optional_padding() {
851        assert_eq!(decode_base64("+/8="), decode_base64("-_8"));
852        assert_eq!(decode_base64(""), Some(Vec::new()));
853        assert_eq!(decode_base64("QQ"), Some(vec![b'A']));
854        assert_eq!(decode_base64("QQ=="), Some(vec![b'A']));
855    }
856
857    #[test]
858    fn base64_refuses_a_length_and_a_symbol_that_cannot_be_base64() {
859        assert_eq!(decode_base64("A"), None);
860        assert_eq!(decode_base64("QQ*="), None);
861    }
862
863    #[test]
864    fn hex_round_trips_both_cases_and_refuses_odd_or_non_hex_input() {
865        assert_eq!(decode_hex("DEADbeef"), Some(vec![0xde, 0xad, 0xbe, 0xef]));
866        assert_eq!(decode_hex("abc"), None);
867        assert_eq!(decode_hex("zz"), None);
868    }
869
870    #[test]
871    fn pack_options_carry_extra_entries_limits_and_the_lock() {
872        let options = parse_pack_options(&json!({
873            "indexes": true,
874            "excludeTables": ["users"],
875            "extra": { "gly.json": "{}" },
876            "limits": { "maxEntries": 5, "maxEntryBytes": 10 },
877        }))
878        .unwrap();
879
880        assert!(options.indexes);
881        assert_eq!(options.exclude_tables, vec!["users".to_string()]);
882        assert_eq!(options.extra, vec![("gly.json".to_string(), b"{}".to_vec())]);
883        assert_eq!(options.limits.max_entries, 5);
884        assert_eq!(options.limits.max_entry_bytes, 10);
885        assert_eq!(
886            options.limits.max_archive_bytes,
887            PackLimits::default().max_archive_bytes
888        );
889        assert!(parse_pack_options(&json!({ "extra": { "a": 1 } })).is_err());
890        assert!(parse_unpack_options(&json!({ "limits": { "maxEntries": -1 } })).is_err());
891        assert_eq!(
892            parse_unpack_options(&Value::Null).unwrap().limits,
893            PackLimits::default()
894        );
895    }
896}
hayson_binding_shared/options.rs

hayson_binding_shared/
options.rs
