Skip to content

Commit 9bb7c1a

Browse files
committed
feat(codec): add immutable namespace binding index updates
1 parent 2589413 commit 9bb7c1a

3 files changed

Lines changed: 719 additions & 0 deletions

File tree

‎src/namespace/radix.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
use super::{validate_absolute_path, PATH_MAX_BYTES};
99
use crate::{sha256, CodecError, CodecResult};
1010

11+
pub mod index;
12+
1113
pub const NODE_MAX_BYTES: usize = 16_384;
1214
pub const CHILD_MAX_COUNT: usize = 256;
1315
const NODE_DOMAIN: &[u8] = b"mega.namespace-radix.v1\0";

‎src/namespace/radix/index.rs‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
//! Iterative immutable binding-index operations over a caller-owned byte store.
2+
//!
3+
//! The fixed v1 node/key codecs determine identity. Only visited graph edges and
4+
//! value keys are checked; this does not validate a complete namespace graph,
5+
//! resolve binding/source membership or implement persistence/publication/GC.
6+
7+
use std::fmt;
8+
9+
use super::{decode_key, empty_root, encode_key, RadixChild, RadixNode, NODE_MAX_BYTES};
10+
use crate::{namespace::PATH_MAX_BYTES, sha256, CodecError};
11+
12+
#[derive(Debug, Clone, PartialEq, Eq)]
13+
pub enum IndexError {
14+
Codec(CodecError),
15+
Store(String),
16+
}
17+
18+
impl fmt::Display for IndexError {
19+
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
20+
match self {
21+
Self::Codec(error) => error.fmt(f),
22+
Self::Store(message) => write!(f, "binding index store unavailable: {message}"),
23+
}
24+
}
25+
}
26+
27+
impl std::error::Error for IndexError {}
28+
29+
impl From<CodecError> for IndexError {
30+
fn from(error: CodecError) -> Self {
31+
Self::Codec(error)
32+
}
33+
}
34+
35+
pub type IndexResult<T> = Result<T, IndexError>;
36+
37+
/// Implementations must insert immutable bytes, rejecting conflicting existing
38+
/// bytes for an ID. Durability, transactions and root publication are external.
39+
/// Missing/corrupt storage is an error, never an empty node or absent binding.
40+
pub trait NodeStore {
41+
fn read(&mut self, id: &[u8; 32]) -> IndexResult<Vec<u8>>;
42+
fn insert(&mut self, id: &[u8; 32], bytes: &[u8]) -> IndexResult<()>;
43+
}
44+
45+
pub struct RadixIndex<'a, S: NodeStore> {
46+
store: &'a mut S,
47+
}
48+
49+
impl<'a, S: NodeStore> RadixIndex<'a, S> {
50+
pub fn new(store: &'a mut S) -> Self {
51+
Self { store }
52+
}
53+
54+
fn load(&mut self, id: &[u8; 32], edge: Option<u8>, prefix: &[u8]) -> IndexResult<RadixNode> {
55+
let node = if *id == empty_root() {
56+
RadixNode::empty()
57+
} else {
58+
let bytes = self.store.read(id)?;
59+
if bytes.len() > NODE_MAX_BYTES {
60+
return Err(CodecError::BadLength("radix stored node").into());
61+
}
62+
if sha256(&[&bytes]) != *id {
63+
return Err(CodecError::DigestMismatch("radix stored node").into());
64+
}
65+
RadixNode::decode(&bytes)?
66+
};
67+
if edge.is_some_and(|edge| node.label.first() != Some(&edge)) {
68+
return Err(CodecError::BadOrdering("radix incoming child label").into());
69+
}
70+
validate_position(prefix, &node)?;
71+
Ok(node)
72+
}
73+
74+
/// A transient edit may need compression before it has canonical local shape.
75+
fn save(&mut self, mut node: RadixNode, prefix: &[u8]) -> IndexResult<Option<[u8; 32]>> {
76+
if node.binding.is_none() {
77+
if node.children.is_empty() {
78+
return Ok(None);
79+
}
80+
if node.children.len() == 1 {
81+
let child_ref = &node.children[0];
82+
let child_prefix = joined_key(prefix, &node.label)?;
83+
let child = self.load(&child_ref.digest, Some(child_ref.edge), &child_prefix)?;
84+
node.label.extend_from_slice(&child.label);
85+
node.binding = child.binding;
86+
node.children = child.children;
87+
}
88+
}
89+
validate_position(prefix, &node)?;
90+
let node = RadixNode::new(node.label, node.binding, node.children)?;
91+
let bytes = node.encode();
92+
let id = sha256(&[&bytes]);
93+
self.store.insert(&id, &bytes)?;
94+
Ok(Some(id))
95+
}
96+
97+
/// Copy only changed ancestors, retaining old roots. A no-op writes no nodes.
98+
/// On failure no new root is returned; inserted orphan nodes may remain and
99+
/// must be handled by the caller's transaction/retention policy.
100+
pub fn update(
101+
&mut self,
102+
root: &[u8; 32],
103+
path: &str,
104+
binding: Option<[u8; 32]>,
105+
) -> IndexResult<[u8; 32]> {
106+
let key = encode_key(path)?;
107+
let mut offset = 0;
108+
let mut id = *root;
109+
let mut edge = None;
110+
let mut ancestors = Vec::new();
111+
let mut replacement;
112+
loop {
113+
let mut node = self.load(&id, edge, &key[..offset])?;
114+
let remaining = &key[offset..];
115+
let common = remaining
116+
.iter()
117+
.zip(&node.label)
118+
.take_while(|(a, b)| a == b)
119+
.count();
120+
if common < node.label.len() {
121+
let Some(binding) = binding else {
122+
return Ok(*root);
123+
};
124+
let mut parent = RadixNode {
125+
label: node.label[..common].to_vec(),
126+
binding: None,
127+
children: Vec::new(),
128+
};
129+
node.label.drain(..common);
130+
let child_prefix = joined_key(&key[..offset], &parent.label)?;
131+
let child_edge = node.label[0];
132+
let child_id = required_id(self.save(node, &child_prefix)?)?;
133+
set_child(&mut parent.children, child_edge, Some(child_id));
134+
if common == remaining.len() {
135+
parent.binding = Some(binding);
136+
} else {
137+
let suffix = &remaining[common..];
138+
let leaf = RadixNode::new(suffix.to_vec(), Some(binding), Vec::new())?;
139+
let leaf_id = required_id(self.save(leaf, &child_prefix)?)?;
140+
set_child(&mut parent.children, suffix[0], Some(leaf_id));
141+
}
142+
replacement = self.save(parent, &key[..offset])?;
143+
break;
144+
}
145+
let parent_offset = offset;
146+
offset += common;
147+
if offset == key.len() {
148+
if node.binding == binding {
149+
return Ok(*root);
150+
}
151+
node.binding = binding;
152+
replacement = self.save(node, &key[..parent_offset])?;
153+
break;
154+
}
155+
let next_edge = key[offset];
156+
if let Some(child) = node.children.iter().find(|child| child.edge == next_edge) {
157+
id = child.digest;
158+
edge = Some(next_edge);
159+
ancestors.push((node, next_edge, parent_offset));
160+
} else {
161+
let Some(binding) = binding else {
162+
return Ok(*root);
163+
};
164+
let leaf = RadixNode::new(key[offset..].to_vec(), Some(binding), Vec::new())?;
165+
let leaf_id = required_id(self.save(leaf, &key[..offset])?)?;
166+
set_child(&mut node.children, next_edge, Some(leaf_id));
167+
replacement = self.save(node, &key[..parent_offset])?;
168+
break;
169+
}
170+
}
171+
while let Some((mut parent, edge, parent_offset)) = ancestors.pop() {
172+
set_child(&mut parent.children, edge, replacement);
173+
replacement = self.save(parent, &key[..parent_offset])?;
174+
}
175+
Ok(replacement.unwrap_or_else(empty_root))
176+
}
177+
178+
pub fn get(&mut self, root: &[u8; 32], path: &str) -> IndexResult<Option<[u8; 32]>> {
179+
Ok(self.walk(root, path, false)?.map(|(_, binding)| binding))
180+
}
181+
182+
pub fn longest_prefix(
183+
&mut self,
184+
root: &[u8; 32],
185+
path: &str,
186+
) -> IndexResult<Option<(String, [u8; 32])>> {
187+
self.walk(root, path, true)
188+
}
189+
190+
fn walk(
191+
&mut self,
192+
root: &[u8; 32],
193+
path: &str,
194+
ancestors: bool,
195+
) -> IndexResult<Option<(String, [u8; 32])>> {
196+
let key = encode_key(path)?;
197+
let mut id = *root;
198+
let mut edge = None;
199+
let mut offset = 0;
200+
let mut found = None;
201+
loop {
202+
let node = self.load(&id, edge, &key[..offset])?;
203+
if !key[offset..].starts_with(&node.label) {
204+
break;
205+
}
206+
offset += node.label.len();
207+
if let Some(binding) = node.binding {
208+
found = Some((decode_key(&key[..offset])?, binding));
209+
}
210+
if offset == key.len() {
211+
return Ok(found.filter(|(matched, _)| ancestors || matched == path));
212+
}
213+
let next_edge = key[offset];
214+
let Some(child) = node.children.iter().find(|child| child.edge == next_edge) else {
215+
break;
216+
};
217+
id = child.digest;
218+
edge = Some(next_edge);
219+
}
220+
Ok(if ancestors { found } else { None })
221+
}
222+
}
223+
224+
fn joined_key(prefix: &[u8], label: &[u8]) -> IndexResult<Vec<u8>> {
225+
if prefix.len() + label.len() > PATH_MAX_BYTES {
226+
return Err(CodecError::BadLength("radix assembled key").into());
227+
}
228+
Ok([prefix, label].concat())
229+
}
230+
231+
fn validate_position(prefix: &[u8], node: &RadixNode) -> IndexResult<()> {
232+
let assembled = joined_key(prefix, &node.label)?;
233+
if node.binding.is_some() {
234+
decode_key(&assembled)?;
235+
}
236+
Ok(())
237+
}
238+
239+
fn set_child(children: &mut Vec<RadixChild>, edge: u8, digest: Option<[u8; 32]>) {
240+
let position = children.binary_search_by_key(&edge, |child| child.edge);
241+
match (position, digest) {
242+
(Ok(index), Some(digest)) => children[index].digest = digest,
243+
(Ok(index), None) => {
244+
children.remove(index);
245+
}
246+
(Err(index), Some(digest)) => children.insert(index, RadixChild { edge, digest }),
247+
(Err(_), None) => {}
248+
}
249+
}
250+
251+
fn required_id(id: Option<[u8; 32]>) -> IndexResult<[u8; 32]> {
252+
id.ok_or_else(|| CodecError::BadOrdering("unexpected empty radix replacement").into())
253+
}
254+
255+
#[cfg(test)]
256+
mod tests;

0 commit comments

Comments
 (0)