nodedb 0.4.0

Local-first, real-time, edge-to-cloud hybrid database for multi-modal workloads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

// SPDX-License-Identifier: BUSL-1.1

//! Key layout for the versioned document and index tables.

/// 20-digit zero-pad for i64 lexicographic ordering under reverse-scan.
pub fn format_sys_from(sys_from_ms: i64) -> String {
    format!("{sys_from_ms:020}")
}

/// Build a versioned document key. Returns an error if `doc_id` contains
/// a NUL byte — NUL is reserved as the version separator.
pub fn versioned_doc_key(
    database_id: u64,
    tenant: u64,
    coll: &str,
    doc_id: &str,
    sys_from_ms: i64,
) -> crate::Result<String> {
    if doc_id.as_bytes().contains(&0) {
        return Err(crate::Error::BadRequest {
            detail: "document id may not contain NUL byte".into(),
        });
    }
    Ok(format!(
        "{database_id}:{tenant}:{coll}:{doc_id}\x00{}",
        format_sys_from(sys_from_ms)
    ))
}

/// Prefix matching every version of a single doc_id — used by reverse-scan.
pub fn doc_prefix(database_id: u64, tenant: u64, coll: &str, doc_id: &str) -> String {
    format!("{database_id}:{tenant}:{coll}:{doc_id}\x00")
}

/// Upper-bound exclusive companion of [`doc_prefix`]: because `\x00` is
/// the minimum byte, `\x01` is the next-greater separator and bounds all
/// suffixes for this doc_id cleanly.
pub fn doc_prefix_end(database_id: u64, tenant: u64, coll: &str, doc_id: &str) -> String {
    format!("{database_id}:{tenant}:{coll}:{doc_id}\x01")
}

/// Prefix matching every version of every doc_id in a collection.
pub fn coll_prefix(database_id: u64, tenant: u64, coll: &str) -> String {
    format!("{database_id}:{tenant}:{coll}:")
}

/// Upper-bound exclusive companion of [`coll_prefix`]. `:` = 0x3A; `;` =
/// 0x3B is the next byte, giving a clean exclusive upper bound that still
/// holds after the leading `{database_id}:` is prepended.
pub fn coll_prefix_end(database_id: u64, tenant: u64, coll: &str) -> String {
    format!("{database_id}:{tenant}:{coll};")
}

/// Prefix matching every version of every doc_id in every collection of a
/// single `(database_id, tenant)` — used by the whole-tenant hard drop.
pub fn tenant_prefix(database_id: u64, tenant: u64) -> String {
    format!("{database_id}:{tenant}:")
}

/// Upper-bound exclusive companion of [`tenant_prefix`]. The tenant field is
/// terminated by `:` (0x3A); `;` (0x3B) is the next byte, giving a clean
/// exclusive upper bound over every collection under this tenant.
pub fn tenant_prefix_end(database_id: u64, tenant: u64) -> String {
    format!("{database_id}:{tenant};")
}

/// Extract `sys_from_ms` from a versioned key. Returns `None` if the key
/// has no NUL separator (defensive — should not happen for keys produced
/// by [`versioned_doc_key`]).
pub fn parse_sys_from(key: &str) -> Option<i64> {
    let (_, suffix) = key.rsplit_once('\x00')?;
    suffix.parse().ok()
}

/// Extract `doc_id` slice from a versioned key (between the
/// `{database_id}:{tenant}:{coll}:` and `\x00` boundaries). Returns the whole
/// remainder when parsing fails.
pub fn parse_doc_id<'a>(
    key: &'a str,
    database_id: u64,
    tenant: u64,
    coll: &str,
) -> Option<&'a str> {
    let prefix = format!("{database_id}:{tenant}:{coll}:");
    let rest = key.strip_prefix(&prefix)?;
    let (id, _) = rest.rsplit_once('\x00')?;
    Some(id)
}