@feltdb/core 0.9.0 → 0.10.0

package/dist/create/server-source/crates/feltdb/src/state_model.rs

@@ -109,6 +109,142 @@ pub struct StateRevision {
     pub metadata: BTreeMap<String, Value>,
 }
 
+/// A content object addressed by its content identity.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct StateObject {
+    pub id: StateId,
+    pub content: String,
+    #[serde(default)]
+    pub metadata: BTreeMap<String, Value>,
+}
+
+impl StateObject {
+    pub fn new(content: String) -> Self {
+        let id = StateId::compute(&content);
+        Self {
+            id,
+            content,
+            metadata: BTreeMap::new(),
+        }
+    }
+
+    pub fn verify_integrity(&self) -> bool {
+        self.id == StateId::compute(&self.content)
+    }
+}
+
+/// A mutable named reference to an immutable revision.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+pub struct StateRef {
+    pub namespace: String,
+    pub name: String,
+    pub target: StateId,
+    pub version: u64,
+    pub authority: String,
+    pub updated_at_ms: u64,
+    #[serde(default)]
+    pub metadata: BTreeMap<String, Value>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum RefError {
+    InvalidIdentifier,
+    NotFound,
+    AlreadyExists,
+    UnknownTarget(StateId),
+    VersionConflict { expected: u64, current: u64 },
+    Storage(String),
+}
+
+impl std::fmt::Display for RefError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            RefError::InvalidIdentifier => write!(f, "invalid ref identifier"),
+            RefError::NotFound => write!(f, "ref not found"),
+            RefError::AlreadyExists => write!(f, "ref already exists"),
+            RefError::UnknownTarget(id) => write!(f, "ref target {id} does not exist"),
+            RefError::VersionConflict { expected, current } => {
+                write!(f, "stale ref version: expected {expected}, current {current}")
+            }
+            RefError::Storage(message) => write!(f, "{message}"),
+        }
+    }
+}
+
+impl std::error::Error for RefError {}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+pub struct MaterializationProjection {
+    #[serde(default)]
+    pub paths: Vec<Vec<PathComponent>>,
+}
+
+impl MaterializationProjection {
+    pub fn full() -> Self {
+        Self { paths: Vec::new() }
+    }
+
+    pub fn select(paths: Vec<Vec<PathComponent>>) -> Self {
+        Self { paths }
+    }
+
+    pub fn is_full(&self) -> bool {
+        self.paths.is_empty() || self.paths.iter().any(|path| path.is_empty())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum MaterializationError {
+    RevisionNotFound(StateId),
+    ContentUnparseable(String),
+    MissingPath(Vec<PathComponent>),
+    NonDeterministicProjection,
+}
+
+impl std::fmt::Display for MaterializationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            MaterializationError::RevisionNotFound(id) => write!(f, "revision {id} not found"),
+            MaterializationError::ContentUnparseable(error) => {
+                write!(f, "revision content is not parseable JSON: {error}")
+            }
+            MaterializationError::MissingPath(path) => {
+                write!(f, "projection path does not resolve: {path:?}")
+            }
+            MaterializationError::NonDeterministicProjection => write!(
+                f,
+                "projection contains overlapping paths and does not deterministically resolve"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for MaterializationError {}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+pub struct GarbageCollectionReport {
+    pub roots: Vec<StateRef>,
+    pub reachable_revisions: Vec<StateId>,
+    pub reachable_objects: Vec<StateId>,
+    pub collected_revisions: Vec<StateId>,
+    pub collected_objects: Vec<StateId>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum GarbageCollectionError {
+    Storage(String),
+}
+
+impl std::fmt::Display for GarbageCollectionError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            GarbageCollectionError::Storage(message) => write!(f, "{message}"),
+        }
+    }
+}
+
+impl std::error::Error for GarbageCollectionError {}
+
 /// Compute a revision identity.
 ///
 /// Every component participates: the same content is a different revision on a
@@ -1011,6 +1147,70 @@ fn assign_path(state: &mut Value, path: &[PathComponent], value: Value) -> Resul
     }
 }
 
+fn assign_projection(
+    state: &mut Value,
+    path: &[PathComponent],
+    value: Value,
+) -> Result<(), MaterializationError> {
+    let Some((last, prefix)) = path.split_last() else {
+        *state = value;
+        return Ok(());
+    };
+
+    let mut current = state;
+    for component in prefix {
+        match component {
+            PathComponent::Key(key) => {
+                if current.is_null() {
+                    *current = Value::Object(serde_json::Map::new());
+                }
+                let Some(object) = current.as_object_mut() else {
+                    return Err(MaterializationError::MissingPath(path.to_vec()));
+                };
+                current = object.entry(key.clone()).or_insert(Value::Null);
+            }
+            PathComponent::Index(index) => {
+                if current.is_null() {
+                    *current = Value::Array(Vec::new());
+                }
+                let Some(array) = current.as_array_mut() else {
+                    return Err(MaterializationError::MissingPath(path.to_vec()));
+                };
+                while array.len() <= *index {
+                    array.push(Value::Null);
+                }
+                current = &mut array[*index];
+            }
+        }
+    }
+
+    match last {
+        PathComponent::Key(key) => {
+            if current.is_null() {
+                *current = Value::Object(serde_json::Map::new());
+            }
+            let Some(object) = current.as_object_mut() else {
+                return Err(MaterializationError::MissingPath(path.to_vec()));
+            };
+            object.insert(key.clone(), value);
+            Ok(())
+        }
+        PathComponent::Index(index) => {
+            if current.is_null() {
+                *current = Value::Array(Vec::new());
+            }
+            let Some(array) = current.as_array_mut() else {
+                return Err(MaterializationError::MissingPath(path.to_vec()));
+            };
+            while array.len() <= *index {
+                array.push(Value::Null);
+            }
+            array[*index] = value;
+            Ok(())
+        }
+    }
+}
+
 /// Applies a plan and materializes the result as a new revision.
 ///
 /// The revision is built with the existing [`StateRevision::child`] constructor,
@@ -1107,6 +1307,7 @@ pub fn reconcile(
 /// ref anything can move.
 pub struct StateStore {
     backing: Backing,
+    mutation_lock: Arc<Mutex<()>>,
 }
 
 /// Where revisions actually live.
@@ -1125,6 +1326,8 @@ enum Backing {
 struct VolatileState {
     revisions: HashMap<StateId, StateRevision>,
     retention: HashMap<String, RetentionState>,
+    refs: HashMap<(String, String), StateRef>,
+    objects: HashMap<StateId, StateObject>,
 }
 
 impl Clone for Backing {
@@ -1141,6 +1344,49 @@ fn revision_key(id: &StateId) -> String {
     format!("state:revision:{}", id.as_hex())
 }
 
+fn object_key(id: &StateId) -> String {
+    format!("state:object:{}", id.as_hex())
+}
+
+fn ref_key(namespace: &str, name: &str) -> String {
+    format!("state:ref:{}:{}", encode_ref_part(namespace), encode_ref_part(name))
+}
+
+fn encode_ref_part(value: &str) -> String {
+    value.replace('%', "%25").replace(':', "%3A")
+}
+
+fn valid_ref_component(value: &str) -> bool {
+    !value.trim().is_empty()
+}
+
+fn looks_like_state_id(value: &str) -> bool {
+    value.len() == 64 && value.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+fn current_time_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+fn collect_referenced_objects(revision: &StateRevision) -> BTreeSet<StateId> {
+    let mut ids = BTreeSet::from([revision.content_id.clone()]);
+    if let Some(values) = revision
+        .metadata
+        .get("object_refs")
+        .and_then(Value::as_array)
+    {
+        for value in values {
+            if let Some(hex) = value.as_str().filter(|value| looks_like_state_id(value)) {
+                ids.insert(StateId::from_hex(hex.to_string()));
+            }
+        }
+    }
+    ids
+}
+
 /// Where a resource's retention watermark lives.
 fn retention_key(resource: &str) -> String {
     format!("_retention:{resource}")
@@ -1311,6 +1557,7 @@ impl StateStore {
     pub fn new_volatile() -> Self {
         StateStore {
             backing: Backing::Volatile(Arc::new(Mutex::new(VolatileState::default()))),
+            mutation_lock: Arc::new(Mutex::new(())),
         }
     }
 
@@ -1326,6 +1573,7 @@ impl StateStore {
     pub fn with_feltdb(feltdb: Arc<crate::FeltDb>) -> Result<Self, String> {
         Ok(StateStore {
             backing: Backing::Durable(feltdb),
+            mutation_lock: Arc::new(Mutex::new(())),
         })
     }
 
@@ -1436,13 +1684,35 @@ impl StateStore {
         }
         match &self.backing {
             Backing::Volatile(state) => {
+                let mut state = state.lock().unwrap();
                 state
-                    .lock()
-                    .unwrap()
-                    .revisions
-                    .insert(revision.id.clone(), revision.clone());
+                    .objects
+                    .entry(revision.content_id.clone())
+                    .or_insert_with(|| StateObject::new(revision.content.clone()));
+                state.revisions.insert(revision.id.clone(), revision.clone());
             }
             Backing::Durable(feltdb) => {
+                let object = StateObject::new(revision.content.clone());
+                if let Some(existing) = feltdb
+                    .get::<StateObject>(&object_key(&object.id))
+                    .map_err(|error| {
+                        RevisionError::Storage(format!("Failed to read state object: {error}"))
+                    })?
+                {
+                    if !existing.verify_integrity() {
+                        return Err(RevisionError::Storage(
+                            "Stored state object failed integrity verification".to_string(),
+                        ));
+                    }
+                } else {
+                    feltdb
+                        .insert(&object_key(&object.id), object)
+                        .map_err(|error| {
+                            RevisionError::Storage(format!(
+                                "Failed to persist state object to FeltDB: {error}"
+                            ))
+                        })?;
+                }
                 feltdb
                     .insert(&revision_key(&revision.id), revision.clone())
                     .map_err(|error| {
@@ -1545,6 +1815,273 @@ impl StateStore {
         names
     }
 
+    /// Create a mutable reference in a namespace.
+    pub fn create_ref(
+        &self,
+        namespace: &str,
+        name: &str,
+        target: StateId,
+        authority: String,
+        metadata: BTreeMap<String, Value>,
+    ) -> Result<StateRef, RefError> {
+        if !valid_ref_component(namespace) || !valid_ref_component(name) {
+            return Err(RefError::InvalidIdentifier);
+        }
+        if !self.exists(&target) {
+            return Err(RefError::UnknownTarget(target));
+        }
+        let _guard = self.mutation_lock.lock().unwrap();
+        if self.get_ref(namespace, name).is_some() {
+            return Err(RefError::AlreadyExists);
+        }
+        let reference = StateRef {
+            namespace: namespace.to_string(),
+            name: name.to_string(),
+            target,
+            version: 1,
+            authority,
+            updated_at_ms: current_time_ms(),
+            metadata,
+        };
+        self.write_ref(&reference)?;
+        Ok(reference)
+    }
+
+    /// Read a reference.
+    pub fn get_ref(&self, namespace: &str, name: &str) -> Option<StateRef> {
+        if !valid_ref_component(namespace) || !valid_ref_component(name) {
+            return None;
+        }
+        match &self.backing {
+            Backing::Volatile(state) => state
+                .lock()
+                .unwrap()
+                .refs
+                .get(&(namespace.to_string(), name.to_string()))
+                .cloned(),
+            Backing::Durable(feltdb) => feltdb
+                .get::<StateRef>(&ref_key(namespace, name))
+                .ok()
+                .flatten(),
+        }
+    }
+
+    /// Move a reference with stale-version rejection.
+    pub fn move_ref(
+        &self,
+        namespace: &str,
+        name: &str,
+        target: StateId,
+        authority: String,
+    ) -> Result<StateRef, RefError> {
+        let current = self.get_ref(namespace, name).ok_or(RefError::NotFound)?;
+        self.compare_and_swap_ref(namespace, name, current.version, target, authority, None)
+    }
+
+    /// Compare-and-swap move for a reference.
+    pub fn compare_and_swap_ref(
+        &self,
+        namespace: &str,
+        name: &str,
+        expected_version: u64,
+        target: StateId,
+        authority: String,
+        metadata: Option<BTreeMap<String, Value>>,
+    ) -> Result<StateRef, RefError> {
+        if !valid_ref_component(namespace) || !valid_ref_component(name) {
+            return Err(RefError::InvalidIdentifier);
+        }
+        if !self.exists(&target) {
+            return Err(RefError::UnknownTarget(target));
+        }
+        let _guard = self.mutation_lock.lock().unwrap();
+        let mut current = self.get_ref(namespace, name).ok_or(RefError::NotFound)?;
+        if current.version != expected_version {
+            return Err(RefError::VersionConflict {
+                expected: expected_version,
+                current: current.version,
+            });
+        }
+        current.target = target;
+        current.version += 1;
+        current.authority = authority;
+        current.updated_at_ms = current_time_ms();
+        if let Some(metadata) = metadata {
+            current.metadata = metadata;
+        }
+        self.write_ref(&current)?;
+        Ok(current)
+    }
+
+    /// Delete a reference, optionally enforcing the current version.
+    pub fn delete_ref(
+        &self,
+        namespace: &str,
+        name: &str,
+        expected_version: Option<u64>,
+    ) -> Result<(), RefError> {
+        if !valid_ref_component(namespace) || !valid_ref_component(name) {
+            return Err(RefError::InvalidIdentifier);
+        }
+        let _guard = self.mutation_lock.lock().unwrap();
+        let current = self.get_ref(namespace, name).ok_or(RefError::NotFound)?;
+        if let Some(expected) = expected_version {
+            if current.version != expected {
+                return Err(RefError::VersionConflict {
+                    expected,
+                    current: current.version,
+                });
+            }
+        }
+        self.remove_ref(namespace, name)
+    }
+
+    /// Enumerate refs, optionally scoped to one namespace.
+    pub fn list_refs(&self, namespace: Option<&str>) -> Vec<StateRef> {
+        let mut refs: Vec<StateRef> = match &self.backing {
+            Backing::Volatile(state) => state.lock().unwrap().refs.values().cloned().collect(),
+            Backing::Durable(feltdb) => feltdb
+                .list_collection("state")
+                .unwrap_or_default()
+                .into_iter()
+                .filter(|row| row.key.starts_with("state:ref:") && !row.deleted)
+                .filter_map(|row| serde_json::from_value::<StateRef>(row.value).ok())
+                .collect(),
+        };
+        if let Some(namespace) = namespace {
+            refs.retain(|reference| reference.namespace == namespace);
+        }
+        refs.sort_by(|one, two| {
+            one.namespace
+                .cmp(&two.namespace)
+                .then_with(|| one.name.cmp(&two.name))
+        });
+        refs
+    }
+
+    /// Materialize a full revision value or a deterministic projection of it.
+    pub fn materialize(
+        &self,
+        revision_id: &StateId,
+        projection: &MaterializationProjection,
+    ) -> Result<Value, MaterializationError> {
+        let revision = self
+            .get(revision_id)
+            .ok_or_else(|| MaterializationError::RevisionNotFound(revision_id.clone()))?;
+        let source: Value = serde_json::from_str(&revision.content)
+            .map_err(|error| MaterializationError::ContentUnparseable(error.to_string()))?;
+        if projection.is_full() {
+            return Ok(source);
+        }
+        let mut paths = projection.paths.clone();
+        paths.sort();
+        paths.dedup();
+        for pair in paths.windows(2) {
+            if paths_overlap(&pair[0], &pair[1]) {
+                return Err(MaterializationError::NonDeterministicProjection);
+            }
+        }
+        let mut projected = Value::Object(serde_json::Map::new());
+        for path in paths {
+            let value = resolve_path(&source, &path)
+                .cloned()
+                .ok_or_else(|| MaterializationError::MissingPath(path.clone()))?;
+            assign_projection(&mut projected, &path, value)?;
+        }
+        Ok(projected)
+    }
+
+    /// Collect revisions and objects unreachable from current refs.
+    pub fn collect_unreachable(&self) -> Result<GarbageCollectionReport, GarbageCollectionError> {
+        let _guard = self.mutation_lock.lock().unwrap();
+        let roots = self.list_refs(None);
+        let mut reachable_revisions = BTreeSet::new();
+        let mut reachable_objects = BTreeSet::new();
+        let mut pending: Vec<StateId> = roots.iter().map(|reference| reference.target.clone()).collect();
+        while let Some(id) = pending.pop() {
+            if !reachable_revisions.insert(id.clone()) {
+                continue;
+            }
+            let Some(revision) = self.get(&id) else {
+                continue;
+            };
+            if let Some(parent_id) = revision.parent_id.clone() {
+                pending.push(parent_id);
+            }
+            for object_id in collect_referenced_objects(&revision) {
+                reachable_objects.insert(object_id);
+            }
+        }
+
+        let mut all_revisions: Vec<StateId> = self.all_revisions().into_iter().map(|r| r.id).collect();
+        all_revisions.sort();
+        let mut collected_revisions = Vec::new();
+        for revision_id in all_revisions {
+            if !reachable_revisions.contains(&revision_id) {
+                self.remove(&revision_id)
+                    .map_err(|error| GarbageCollectionError::Storage(error.to_string()))?;
+                collected_revisions.push(revision_id);
+            }
+        }
+
+        let mut all_objects: Vec<StateId> = self.all_objects().into_iter().map(|o| o.id).collect();
+        all_objects.sort();
+        let mut collected_objects = Vec::new();
+        for object_id in all_objects {
+            if !reachable_objects.contains(&object_id) {
+                self.remove_object(&object_id)?;
+                collected_objects.push(object_id);
+            }
+        }
+
+        let mut reachable_revisions_out: Vec<_> = reachable_revisions.into_iter().collect();
+        reachable_revisions_out.sort();
+        let mut reachable_objects_out: Vec<_> = reachable_objects.into_iter().collect();
+        reachable_objects_out.sort();
+        Ok(GarbageCollectionReport {
+            roots,
+            reachable_revisions: reachable_revisions_out,
+            reachable_objects: reachable_objects_out,
+            collected_revisions,
+            collected_objects,
+        })
+    }
+
+    fn write_ref(&self, reference: &StateRef) -> Result<(), RefError> {
+        match &self.backing {
+            Backing::Volatile(state) => {
+                state.lock().unwrap().refs.insert(
+                    (reference.namespace.clone(), reference.name.clone()),
+                    reference.clone(),
+                );
+            }
+            Backing::Durable(feltdb) => {
+                feltdb
+                    .insert(&ref_key(&reference.namespace, &reference.name), reference.clone())
+                    .map_err(|error| RefError::Storage(error.to_string()))?;
+            }
+        }
+        Ok(())
+    }
+
+    fn remove_ref(&self, namespace: &str, name: &str) -> Result<(), RefError> {
+        match &self.backing {
+            Backing::Volatile(state) => {
+                state
+                    .lock()
+                    .unwrap()
+                    .refs
+                    .remove(&(namespace.to_string(), name.to_string()));
+            }
+            Backing::Durable(feltdb) => {
+                feltdb
+                    .delete(&ref_key(namespace, name))
+                    .map_err(|error| RefError::Storage(error.to_string()))?;
+            }
+        }
+        Ok(())
+    }
+
     fn all_revisions(&self) -> Vec<StateRevision> {
         match &self.backing {
             Backing::Volatile(state) => state.lock().unwrap().revisions.values().cloned().collect(),
@@ -1558,6 +2095,19 @@ impl StateStore {
         }
     }
 
+    fn all_objects(&self) -> Vec<StateObject> {
+        match &self.backing {
+            Backing::Volatile(state) => state.lock().unwrap().objects.values().cloned().collect(),
+            Backing::Durable(feltdb) => feltdb
+                .list_collection("state")
+                .unwrap_or_default()
+                .into_iter()
+                .filter(|row| row.key.starts_with("state:object:") && !row.deleted)
+                .filter_map(|row| serde_json::from_value::<StateObject>(row.value).ok())
+                .collect(),
+        }
+    }
+
     /// A digest of this store's **history**: the revision graph and retention
     /// state, and nothing else.
     ///
@@ -1684,6 +2234,20 @@ impl StateStore {
         Ok(())
     }
 
+    fn remove_object(&self, id: &StateId) -> Result<(), GarbageCollectionError> {
+        match &self.backing {
+            Backing::Volatile(state) => {
+                state.lock().unwrap().objects.remove(id);
+            }
+            Backing::Durable(feltdb) => {
+                feltdb
+                    .delete(&object_key(id))
+                    .map_err(|error| GarbageCollectionError::Storage(error.to_string()))?;
+            }
+        }
+        Ok(())
+    }
+
     fn retention_state(&self, resource: &str) -> RetentionState {
         match &self.backing {
             Backing::Volatile(state) => state
@@ -1732,6 +2296,7 @@ impl Clone for StateStore {
     fn clone(&self) -> Self {
         StateStore {
             backing: self.backing.clone(),
+            mutation_lock: self.mutation_lock.clone(),
         }
     }
 }

package/dist/create/server-source/crates/feltdb/src/state_trigger.rs

@@ -288,6 +288,7 @@ fn create_workload(trigger: &StateTrigger, operation: &Operation, now: i64) -> C
             "record": operation.value,
         }),
         requested_by: trigger.requested_by.clone(),
+        session_id: None,
         authorization_snapshot: trigger.authorization_snapshot.clone(),
         capability_snapshot,
         connection_scopes: trigger.connection_scopes.clone(),