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    parse_key_document(value, "cypher")
267}
268
269/// The keys document `encryption` takes: the same shape as `cypher`.
270pub fn parse_encryption(value: &Value) -> Result<CipherOptions, OptionsError> {
271    parse_key_document(value, "encryption")
272}
273
274fn parse_key_document(value: &Value, label: &str) -> Result<CipherOptions, OptionsError> {
275    let object = as_object(value, label)?;
276    let encoding = match optional_string(object, "keyEncoding")?.as_deref() {
277        None | Some("base64") => KeyEncoding::Base64,
278        Some("hex") => KeyEncoding::Hex,
279        Some(other) => {
280            return shape(format!(
281                "\"keyEncoding\" must be \"base64\" or \"hex\" — got \"{other}\""
282            ))
283        }
284    };
285
286    let raw_keys = match object.get("keys") {
287        Some(keys) => as_object(keys, &format!("{label}.keys"))?,
288        None => return shape(format!("\"{label}\" needs a \"keys\" object")),
289    };
290
291    let mut keys = HashMap::with_capacity(raw_keys.len());
292    for (id, material) in raw_keys {
293        let Some(material) = material.as_str() else {
294            return shape(format!("key \"{id}\" must be a string"));
295        };
296        keys.insert(id.clone(), decode_key(id, material, encoding)?);
297    }
298
299    let on_missing_key = match optional_string(object, "onMissingKey")? {
300        Some(raw) => Some(parse_missing_key_policy(&raw)?),
301        None => None,
302    };
303
304    Ok(CipherOptions {
305        keys,
306        key_id: optional_string(object, "keyId")?,
307        on_missing_key,
308    })
309}
310
311/// Builds `OpenOptions` from the JSON document `open()` takes. Every member is optional; an absent
312/// one keeps the engine's own default, so `{}` and `null` both mean "open it the usual way".
313pub fn parse_open_options(value: &Value) -> Result<OpenOptions, OptionsError> {
314    let mut options = OpenOptions::default();
315    if value.is_null() {
316        return Ok(options);
317    }
318    let object = as_object(value, "options")?;
319
320    if let Some(readonly) = optional_bool(object, "readonly")? {
321        options.readonly = readonly;
322    }
323    if let Some(snapshot_every) = optional_u64(object, "snapshotEvery")? {
324        options.snapshot_every = snapshot_every;
325    }
326    if let Some(compaction) = object.get("compaction").filter(|value| !value.is_null()) {
327        options.compaction = Some(parse_compaction(compaction)?);
328    }
329    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
330        options.lock = parse_lock(lock)?;
331    }
332    if let Some(cypher) = object.get("cypher").filter(|value| !value.is_null()) {
333        options.cypher = Some(parse_cypher(cypher)?);
334    }
335    if let Some(encryption) = object.get("encryption").filter(|value| !value.is_null()) {
336        options.encryption = Some(parse_encryption(encryption)?);
337    }
338    if let Some(follow) = object.get("follow").filter(|value| !value.is_null()) {
339        options.follow = parse_follow(follow)?;
340    }
341    if let Some(max) = optional_u64(object, "maxImageBytes")? {
342        options.max_image_bytes = Some(max);
343    }
344    if let Some(cost) = object.get("passwordHash").filter(|value| !value.is_null()) {
345        options.password_hash = parse_password_hash(cost)?;
346    }
347    options.layout = parse_layout(object)?;
348
349    Ok(options)
350}
351
352/// Builds [`LayoutMigrationOptions`] from the JSON document `migrateLayout()` takes — the TS
353/// `LayoutMigrationOptions`, member for member, plus the `lock` of `open()` so a host that has to
354/// wait differently for the writer lock can say so. Every member is optional; `{}` and `null` both
355/// mean "move it into the nested arrangement, keeping the document's name".
356///
357/// Neither pair of document names is resolved here, for the same reason `parse_layout` resolves
358/// nothing: whether the two names of a pair agree is the engine's refusal to make, so it reads the
359/// same however a caller reaches it.
360pub fn parse_migrate_layout_options(value: &Value) -> Result<LayoutMigrationOptions, OptionsError> {
361    let mut options = LayoutMigrationOptions::default();
362    if value.is_null() {
363        return Ok(options);
364    }
365    let object = as_object(value, "options")?;
366
367    options.to = match optional_string(object, "to")? {
368        Some(raw) => Some(parse_migration_target(&raw)?),
369        None => None,
370    };
371    options.from_metadata_file = optional_string(object, "fromMetadataFile")?;
372    options.from_manifest = optional_string(object, "fromManifest")?;
373    options.metadata_file = optional_string(object, "metadataFile")?;
374    options.manifest_file = optional_string(object, "manifestFile")?;
375    options.dry_run = optional_bool(object, "dryRun")?.unwrap_or(false);
376    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
377        options.lock = parse_lock(lock)?;
378    }
379
380    Ok(options)
381}
382
383/// Builds [`VerifyOptions`] from the JSON document `verify()` takes:
384/// `{ relations?: boolean, images?: boolean, maxImageBytes?: number }`.
385/// `null` and `{}` mean the defaults.
386pub fn parse_verify_options(value: &Value) -> Result<VerifyOptions, OptionsError> {
387    let mut options = VerifyOptions::default();
388    if value.is_null() {
389        return Ok(options);
390    }
391    let object = as_object(value, "options")?;
392    if let Some(relations) = optional_bool(object, "relations")? {
393        options.relations = relations;
394    }
395    if let Some(images) = optional_bool(object, "images")? {
396        options.images = images;
397    }
398    options.max_image_bytes = match object.get("maxImageBytes") {
399        None | Some(Value::Null) => None,
400        Some(value) => match value.as_u64() {
401            Some(bytes) => Some(bytes),
402            None => return shape("\"maxImageBytes\" must be a non-negative integer".to_string()),
403        },
404    };
405    options.encryption = parse_optional_encryption(object)?;
406    Ok(options)
407}
408
409/// Builds [`BackupOptions`] from the JSON document `backup()` takes: `{ indexes?: boolean, excludeTables?: string[], lock? }`.
410pub fn parse_backup_options(value: &Value) -> Result<BackupOptions, OptionsError> {
411    let mut options = BackupOptions::default();
412    if value.is_null() {
413        return Ok(options);
414    }
415    let object = as_object(value, "options")?;
416    options.indexes = optional_bool(object, "indexes")?.unwrap_or(false);
417    options.exclude_tables = parse_exclude_tables(object)?;
418    options.encryption = parse_optional_encryption(object)?;
419    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
420        options.lock = parse_lock(lock)?;
421    }
422    Ok(options)
423}
424
425/// Builds [`RestoreOptions`] from the JSON document `restore()` takes: `{ maxImageBytes?, lock? }`.
426pub fn parse_restore_options(value: &Value) -> Result<RestoreOptions, OptionsError> {
427    let mut options = RestoreOptions::default();
428    if value.is_null() {
429        return Ok(options);
430    }
431    let object = as_object(value, "options")?;
432    options.max_image_bytes = optional_u64(object, "maxImageBytes")?;
433    options.encryption = parse_optional_encryption(object)?;
434    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
435        options.lock = parse_lock(lock)?;
436    }
437    Ok(options)
438}
439
440/// `{ memoryKiB?, iterations?, parallelism? }` — the Argon2id cost of new `passwordHash` values;
441/// whatever is left out keeps the engine's default.
442fn parse_password_hash(value: &Value) -> Result<PasswordHashParams, OptionsError> {
443    let object = as_object(value, "passwordHash")?;
444    let mut params = PasswordHashParams::default();
445    for (key, target) in [
446        ("memoryKiB", &mut params.memory_kib),
447        ("iterations", &mut params.iterations),
448        ("parallelism", &mut params.parallelism),
449    ] {
450        if let Some(number) = optional_u64(object, key)? {
451            *target = match u32::try_from(number) {
452                Ok(number) => number,
453                Err(_) => return shape(format!("\"passwordHash.{key}\" is too large")),
454            };
455        }
456    }
457    params.validate().map_err(|error| OptionsError::Shape(error.0))?;
458    Ok(params)
459}
460
461/// `encryption?: { keys, keyId?, keyEncoding? }` of a backup/restore/pack/unpack/verify options document.
462fn parse_optional_encryption(object: &serde_json::Map<String, Value>) -> Result<Option<CipherOptions>, OptionsError> {
463    match object.get("encryption").filter(|value| !value.is_null()) {
464        Some(value) => Ok(Some(parse_encryption(value)?)),
465        None => Ok(None),
466    }
467}
468
469/// `excludeTables?: string[]` of a `backup()`/`pack()` options document.
470fn parse_exclude_tables(object: &serde_json::Map<String, Value>) -> Result<Vec<String>, OptionsError> {
471    let Some(raw) = object.get("excludeTables").filter(|value| !value.is_null()) else {
472        return Ok(Vec::new());
473    };
474    let Some(items) = raw.as_array() else {
475        return shape("\"excludeTables\" must be an array of table names");
476    };
477    items
478        .iter()
479        .map(|item| match item.as_str() {
480            Some(name) => Ok(name.to_string()),
481            None => shape("\"excludeTables\" must be an array of table names"),
482        })
483        .collect()
484}
485
486/// `include?: [{ path: string, excludeTables?: string[] }]` of a `pack()` options document.
487fn parse_pack_includes(object: &serde_json::Map<String, Value>) -> Result<Vec<PackInclude>, OptionsError> {
488    let Some(raw) = object.get("include").filter(|value| !value.is_null()) else {
489        return Ok(Vec::new());
490    };
491    let Some(items) = raw.as_array() else {
492        return shape("\"include\" must be an array of { path, excludeTables? }");
493    };
494    let mut includes = Vec::new();
495    for item in items {
496        let entry = as_object(item, "include[]")?;
497        let Some(path) = optional_string(entry, "path")? else {
498            return shape("every \"include\" entry needs a \"path\"");
499        };
500        includes.push(PackInclude {
501            path,
502            encryption: parse_optional_encryption(entry)?,
503            exclude_tables: parse_exclude_tables(entry)?,
504        });
505    }
506    Ok(includes)
507}
508
509fn parse_pack_limits(object: &serde_json::Map<String, Value>) -> Result<PackLimits, OptionsError> {
510    let mut limits = PackLimits::default();
511    let Some(raw) = object.get("limits").filter(|value| !value.is_null()) else {
512        return Ok(limits);
513    };
514    let raw = as_object(raw, "limits")?;
515    let number = |key: &str| -> Result<Option<u64>, OptionsError> {
516        match raw.get(key).filter(|value| !value.is_null()) {
517            None => Ok(None),
518            Some(value) => match value.as_u64() {
519                Some(number) => Ok(Some(number)),
520                None => shape(format!("\"limits.{key}\" must be a non-negative integer")),
521            },
522        }
523    };
524    if let Some(value) = number("maxArchiveBytes")? {
525        limits.max_archive_bytes = value;
526    }
527    if let Some(value) = number("maxTotalBytes")? {
528        limits.max_total_bytes = value;
529    }
530    if let Some(value) = number("maxEntryBytes")? {
531        limits.max_entry_bytes = value;
532    }
533    if let Some(value) = number("maxEntries")? {
534        limits.max_entries = value as usize;
535    }
536    Ok(limits)
537}
538
539/// Builds [`PackLimits`] from `{ limits?: { maxArchiveBytes?, maxTotalBytes?, maxEntryBytes?, maxEntries? } }`.
540pub fn parse_pack_limits_options(value: &Value) -> Result<PackLimits, OptionsError> {
541    if value.is_null() {
542        return Ok(PackLimits::default());
543    }
544    parse_pack_limits(as_object(value, "options")?)
545}
546
547/// Builds [`PackOptions`] from the JSON document `pack()` takes:
548/// `{ indexes?: boolean, excludeTables?: string[], extra?: { [entryName]: string }, limits?, lock? }`.
549pub fn parse_pack_options(value: &Value) -> Result<PackOptions, OptionsError> {
550    let mut options = PackOptions::default();
551    if value.is_null() {
552        return Ok(options);
553    }
554    let object = as_object(value, "options")?;
555    options.indexes = optional_bool(object, "indexes")?.unwrap_or(false);
556    options.exclude_tables = parse_exclude_tables(object)?;
557    options.include = parse_pack_includes(object)?;
558    options.encryption = parse_optional_encryption(object)?;
559    if let Some(extra) = object.get("extra").filter(|value| !value.is_null()) {
560        for (name, content) in as_object(extra, "extra")? {
561            match content.as_str() {
562                Some(text) => options.extra.push((name.clone(), text.as_bytes().to_vec())),
563                None => return shape(format!("\"extra.{name}\" must be a string")),
564            }
565        }
566    }
567    options.limits = parse_pack_limits(object)?;
568    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
569        options.lock = parse_lock(lock)?;
570    }
571    Ok(options)
572}
573
574/// Builds [`UnpackOptions`] from the JSON document `unpack()` takes: `{ limits?, maxImageBytes?, lock? }`.
575pub fn parse_unpack_options(value: &Value) -> Result<UnpackOptions, OptionsError> {
576    let mut options = UnpackOptions::default();
577    if value.is_null() {
578        return Ok(options);
579    }
580    let object = as_object(value, "options")?;
581    options.encryption = parse_optional_encryption(object)?;
582    if let Some(nested) = object.get("includeEncryption").filter(|value| !value.is_null()) {
583        for (folder, keys) in as_object(nested, "includeEncryption")? {
584            options
585                .include_encryption
586                .push((folder.clone(), parse_encryption(keys)?));
587        }
588    }
589    options.max_image_bytes = optional_u64(object, "maxImageBytes")?;
590    options.limits = parse_pack_limits(object)?;
591    if let Some(lock) = object.get("lock").filter(|value| !value.is_null()) {
592        options.lock = parse_lock(lock)?;
593    }
594    Ok(options)
595}
596
597fn parse_migration_target(raw: &str) -> Result<LayoutKind, OptionsError> {
598    match raw {
599        "flat" => Ok(LayoutKind::Flat),
600        "nested" => Ok(LayoutKind::Nested),
601        other => shape(format!("\"to\" must be \"flat\" or \"nested\" — got \"{other}\"")),
602    }
603}
604
605#[cfg(test)]
606mod tests {
607    use serde_json::json;
608
609    use super::*;
610
611    #[test]
612    fn an_absent_document_keeps_every_engine_default() {
613        let options = parse_open_options(&Value::Null).unwrap();
614
615        assert!(!options.readonly);
616        assert_eq!(options.snapshot_every, OpenOptions::default().snapshot_every);
617        assert!(options.cypher.is_none());
618    }
619
620    #[test]
621    fn readonly_snapshot_every_and_lock_reach_the_engine_options() {
622        let options = parse_open_options(&json!({
623            "readonly": true,
624            "snapshotEvery": 5,
625            "lock": { "timeoutMs": 0, "retryIntervalMs": 10 },
626        }))
627        .unwrap();
628
629        assert!(options.readonly);
630        assert_eq!(options.snapshot_every, 5);
631        let lock = options
632            .lock
633            .options()
634            .expect("an object shape asks for a lock, not for skipping");
635        assert_eq!(lock.timeout_ms, Some(0));
636        assert_eq!(lock.retry_interval_ms, Some(10));
637        assert_eq!(lock.heartbeat_ms, None);
638    }
639
640    #[test]
641    fn compaction_reaches_the_engine_in_both_the_thresholds_and_the_false_shape() {
642        let named = parse_open_options(&json!({
643            "compaction": { "deadBytesRatio": 0.5, "minDeadBytes": 200 },
644        }))
645        .unwrap();
646        assert_eq!(
647            named.compaction,
648            Some(CatalogCompaction::Enabled {
649                dead_bytes_ratio: 0.5,
650                min_dead_bytes: 200
651            })
652        );
653
654        let off = parse_open_options(&json!({ "compaction": false })).unwrap();
655        assert_eq!(off.compaction, Some(CatalogCompaction::Disabled));
656
657        // NOTE: absent and null both mean "leave it to the catalog", which is not the same as false.
658        for document in [json!({}), json!({ "compaction": null })] {
659            assert_eq!(parse_open_options(&document).unwrap().compaction, None, "{document}");
660        }
661    }
662
663    #[test]
664    fn a_compaction_ratio_outside_zero_to_one_is_refused_before_the_engine_is_touched() {
665        for ratio in [json!(0), json!(1.5), json!("half")] {
666            let document = json!({ "compaction": { "deadBytesRatio": ratio, "minDeadBytes": 1 } });
667            assert!(parse_open_options(&document).is_err(), "{document}");
668        }
669        assert!(parse_open_options(&json!({ "compaction": true })).is_err());
670    }
671
672    #[test]
673    fn lock_false_asks_the_engine_to_skip_the_writer_lock_and_true_asks_for_the_defaults() {
674        assert!(matches!(
675            parse_open_options(&json!({ "lock": false })).unwrap().lock,
676            LockMode::Skip
677        ));
678
679        // NOTE: absent and null must stay the locked default — skipping is opt-in only.
680        for document in [
681            json!({}),
682            json!({ "lock": null }),
683            json!({ "lock": true }),
684            json!({ "lock": {} }),
685        ] {
686            let lock = parse_open_options(&document).unwrap().lock;
687            assert!(matches!(lock, LockMode::Enabled(_)), "{document} must keep the lock");
688            assert_eq!(lock.options().unwrap().timeout_ms, None);
689        }
690    }
691
692    #[test]
693    fn a_lock_that_is_neither_a_flag_nor_an_options_object_is_refused_as_a_shape_error() {
694        assert_eq!(
695            parse_open_options(&json!({ "lock": "off" })).unwrap_err(),
696            OptionsError::Shape("\"lock\" must be a boolean or an object of lock options".to_string())
697        );
698        assert_eq!(
699            parse_open_options(&json!({ "lock": { "timeoutMs": -1 } })).unwrap_err(),
700            OptionsError::Shape("\"timeoutMs\" must be a non-negative whole number".to_string())
701        );
702    }
703
704    #[test]
705    fn a_base64_keyring_decodes_to_the_exact_bytes_and_keeps_its_write_key() {
706        let options = parse_open_options(&json!({
707            "cypher": {
708                "keys": { "k1": "AAECAw==" },
709                "keyId": "k1",
710                "onMissingKey": "omit",
711            },
712        }))
713        .unwrap();
714
715        let cypher = options.cypher.unwrap();
716        assert_eq!(cypher.keys["k1"], vec![0, 1, 2, 3]);
717        assert_eq!(cypher.key_id.as_deref(), Some("k1"));
718        assert_eq!(cypher.on_missing_key, Some(MissingKeyPolicy::Omit));
719    }
720
721    #[test]
722    fn a_hex_keyring_decodes_only_when_key_encoding_says_so() {
723        let hex = json!({ "cypher": { "keys": { "k1": "00010203" }, "keyEncoding": "hex" } });
724        let options = parse_open_options(&hex).unwrap();
725        assert_eq!(options.cypher.unwrap().keys["k1"], vec![0, 1, 2, 3]);
726
727        // NOTE: "00010203" is also valid base64 — the same text decodes to different bytes.
728        let as_base64 = json!({ "cypher": { "keys": { "k1": "00010203" } } });
729        assert_ne!(
730            parse_open_options(&as_base64).unwrap().cypher.unwrap().keys["k1"],
731            vec![0, 1, 2, 3]
732        );
733    }
734
735    #[test]
736    fn unusable_key_material_is_reported_as_a_key_error_naming_the_key() {
737        let error = parse_open_options(&json!({ "cypher": { "keys": { "k1": "!!!!" } } })).unwrap_err();
738
739        assert_eq!(error, OptionsError::Key("key \"k1\" is not valid base64".to_string()));
740    }
741
742    #[test]
743    fn a_wrong_typed_option_is_refused_as_a_shape_error_naming_the_member() {
744        assert_eq!(
745            parse_open_options(&json!({ "readonly": "yes" })).unwrap_err(),
746            OptionsError::Shape("\"readonly\" must be a boolean".to_string())
747        );
748        assert_eq!(
749            parse_open_options(&json!({ "snapshotEvery": -1 })).unwrap_err(),
750            OptionsError::Shape("\"snapshotEvery\" must be a non-negative whole number".to_string())
751        );
752        assert!(matches!(
753            parse_open_options(&json!({ "cypher": { "keys": {}, "onMissingKey": "shrug" } })).unwrap_err(),
754            OptionsError::Shape(_)
755        ));
756    }
757
758    #[test]
759    fn follow_reaches_the_engine_in_all_three_shapes_the_option_takes() {
760        assert_eq!(parse_open_options(&json!({})).unwrap().follow, FollowOption::Default);
761        assert_eq!(
762            parse_open_options(&json!({ "follow": null })).unwrap().follow,
763            FollowOption::Default
764        );
765        assert_eq!(
766            parse_open_options(&json!({ "follow": false })).unwrap().follow,
767            FollowOption::Off
768        );
769        assert_eq!(
770            parse_open_options(&json!({ "follow": true })).unwrap().follow,
771            FollowOption::Every(Duration::ZERO)
772        );
773        assert_eq!(
774            parse_open_options(&json!({ "follow": { "intervalMs": 250 } }))
775                .unwrap()
776                .follow,
777            FollowOption::Every(Duration::from_millis(250))
778        );
779        assert_eq!(
780            parse_open_options(&json!({ "follow": {} })).unwrap().follow,
781            FollowOption::Every(Duration::ZERO)
782        );
783    }
784
785    #[test]
786    fn a_follow_that_is_neither_a_flag_nor_an_interval_is_refused_as_a_shape_error() {
787        assert!(matches!(
788            parse_open_options(&json!({ "follow": "always" })).unwrap_err(),
789            OptionsError::Shape(_)
790        ));
791        assert!(matches!(
792            parse_open_options(&json!({ "follow": { "intervalMs": -1 } })).unwrap_err(),
793            OptionsError::Shape(_)
794        ));
795    }
796
797    #[test]
798    fn the_layout_triple_reaches_the_engine_unresolved() {
799        assert_eq!(parse_open_options(&json!({})).unwrap().layout, LayoutOptions::default());
800
801        let named = parse_open_options(&json!({
802            "layout": "nested",
803            "metadataFile": "cerebro.json",
804        }))
805        .unwrap();
806        assert_eq!(named.layout.kind, Some(LayoutKind::Nested));
807        assert_eq!(named.layout.metadata_file.as_deref(), Some("cerebro.json"));
808        assert_eq!(named.layout.manifest, None);
809
810        // NOTE: the two names are passed on as given — the engine, not this, decides they conflict.
811        let both = parse_open_options(&json!({ "manifest": "a.json", "metadataFile": "b.json" })).unwrap();
812        assert_eq!(both.layout.manifest.as_deref(), Some("a.json"));
813        assert_eq!(both.layout.metadata_file.as_deref(), Some("b.json"));
814    }
815
816    #[test]
817    fn an_unknown_layout_kind_and_a_non_string_file_name_are_refused_as_shape_errors() {
818        assert_eq!(
819            parse_open_options(&json!({ "layout": "sideways" })).unwrap_err(),
820            OptionsError::Shape("\"layout\" must be \"flat\" or \"nested\" — got \"sideways\"".to_string())
821        );
822        assert_eq!(
823            parse_open_options(&json!({ "metadataFile": 7 })).unwrap_err(),
824            OptionsError::Shape("\"metadataFile\" must be a string".to_string())
825        );
826    }
827
828    #[test]
829    fn a_migration_with_no_document_moves_into_the_nested_arrangement_under_the_engine_lock() {
830        let options = parse_migrate_layout_options(&Value::Null).unwrap();
831
832        assert_eq!(options.to, None, "absent is the engine's own default, not a second one");
833        assert!(!options.dry_run);
834        assert!(options.metadata_file.is_none() && options.from_metadata_file.is_none());
835        assert!(matches!(options.lock, LockMode::Enabled(_)));
836    }
837
838    #[test]
839    fn both_document_name_pairs_reach_the_engine_unresolved_so_it_makes_the_refusal() {
840        let options = parse_migrate_layout_options(&json!({
841            "to": "flat",
842            "fromMetadataFile": "cerebro.json",
843            "fromManifest": "legacy.json",
844            "metadataFile": "hayson.json",
845            "manifestFile": "old.json",
846            "dryRun": true,
847        }))
848        .unwrap();
849
850        assert_eq!(options.to, Some(LayoutKind::Flat));
851        assert_eq!(options.from_metadata_file.as_deref(), Some("cerebro.json"));
852        assert_eq!(options.from_manifest.as_deref(), Some("legacy.json"));
853        assert_eq!(options.metadata_file.as_deref(), Some("hayson.json"));
854        assert_eq!(options.manifest_file.as_deref(), Some("old.json"));
855        assert!(options.dry_run);
856    }
857
858    #[test]
859    fn a_migration_takes_the_same_lock_document_an_open_takes() {
860        let options = parse_migrate_layout_options(&json!({ "lock": { "timeoutMs": 0 } })).unwrap();
861
862        assert_eq!(
863            options.lock.options().and_then(|lock| lock.timeout_ms),
864            Some(0),
865            "a host that owns the wait has to be able to ask for a fail-fast attempt"
866        );
867        let skipped = parse_migrate_layout_options(&json!({ "lock": false })).unwrap();
868        assert!(matches!(skipped.lock, LockMode::Skip));
869    }
870
871    #[test]
872    fn an_unknown_migration_target_is_refused_as_a_shape_error() {
873        assert_eq!(
874            parse_migrate_layout_options(&json!({ "to": "sideways" })).unwrap_err(),
875            OptionsError::Shape("\"to\" must be \"flat\" or \"nested\" — got \"sideways\"".to_string())
876        );
877        assert_eq!(
878            parse_migrate_layout_options(&json!({ "dryRun": "yes" })).unwrap_err(),
879            OptionsError::Shape("\"dryRun\" must be a boolean".to_string())
880        );
881    }
882
883    #[test]
884    fn base64_accepts_the_url_safe_alphabet_and_optional_padding() {
885        assert_eq!(decode_base64("+/8="), decode_base64("-_8"));
886        assert_eq!(decode_base64(""), Some(Vec::new()));
887        assert_eq!(decode_base64("QQ"), Some(vec![b'A']));
888        assert_eq!(decode_base64("QQ=="), Some(vec![b'A']));
889    }
890
891    #[test]
892    fn base64_refuses_a_length_and_a_symbol_that_cannot_be_base64() {
893        assert_eq!(decode_base64("A"), None);
894        assert_eq!(decode_base64("QQ*="), None);
895    }
896
897    #[test]
898    fn hex_round_trips_both_cases_and_refuses_odd_or_non_hex_input() {
899        assert_eq!(decode_hex("DEADbeef"), Some(vec![0xde, 0xad, 0xbe, 0xef]));
900        assert_eq!(decode_hex("abc"), None);
901        assert_eq!(decode_hex("zz"), None);
902    }
903
904    #[test]
905    fn pack_options_carry_extra_entries_limits_and_the_lock() {
906        let options = parse_pack_options(&json!({
907            "indexes": true,
908            "excludeTables": ["users"],
909            "extra": { "gly.json": "{}" },
910            "limits": { "maxEntries": 5, "maxEntryBytes": 10 },
911        }))
912        .unwrap();
913
914        assert!(options.indexes);
915        assert_eq!(options.exclude_tables, vec!["users".to_string()]);
916        assert_eq!(options.extra, vec![("gly.json".to_string(), b"{}".to_vec())]);
917        assert_eq!(options.limits.max_entries, 5);
918        assert_eq!(options.limits.max_entry_bytes, 10);
919        assert_eq!(
920            options.limits.max_archive_bytes,
921            PackLimits::default().max_archive_bytes
922        );
923        assert!(parse_pack_options(&json!({ "extra": { "a": 1 } })).is_err());
924        assert!(parse_unpack_options(&json!({ "limits": { "maxEntries": -1 } })).is_err());
925        assert_eq!(
926            parse_unpack_options(&Value::Null).unwrap().limits,
927            PackLimits::default()
928        );
929    }
930
931    #[test]
932    fn restore_options_carry_the_image_limit_and_the_keys() {
933        let options = parse_restore_options(&json!({
934            "maxImageBytes": 7,
935            "encryption": { "keys": { "k1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" } },
936        }))
937        .unwrap();
938
939        assert_eq!(options.max_image_bytes, Some(7));
940        assert!(options.encryption.is_some());
941        assert!(parse_restore_options(&json!({ "maxImageBytes": -1 })).is_err());
942    }
943}
hayson_binding_shared/options.rs

hayson_binding_shared/
options.rs
