Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

23.1 KB
Raw Blame
//! PathLockProvider trait and built-in implementations.
//!
//! The provider owns token storage. Backends with transactional storage may also
//! implement the optional atomic capabilities used by `PathLockManager`.

use std::collections::HashMap;
use std::sync::Arc;

use async_trait::async_trait;
use tokio::sync::RwLock;

use crate::core::internal_names::is_hidden_runtime_lock_name;
use crate::core::FileSystem;
use crate::crypto;

use super::codec::LockTokenCodec;
use super::types::{LockToken, PathLockError, PathLockRequest, PathLockResult};

/// Representation used for handles stored in a PathLock lease.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PathLockHandleMode {
    /// Handles are resolver-generated lock-file paths.
    LockPath,
    /// Handles are normalized logical paths.
    LogicalPath,
}

/// Token mutation made during one lock acquisition.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AcquisitionChange {
    /// A new token was created.
    Created {
        /// Token written by the provider.
        replacement: LockToken,
    },
    /// The same owner already held an equal or stronger token.
    Reentrant,
    /// A same-owner Exact token became Tree.
    Upgraded {
        /// Token restored if local lease publication fails.
        previous: LockToken,
        /// Tree token written by the provider.
        replacement: LockToken,
    },
}

/// One mutation made by an atomic provider acquisition.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AtomicAcquisition {
    /// Provider handle stored in the PathLock lease.
    pub handle: String,
    /// Token mutation used by rollback.
    pub change: AcquisitionChange,
}

/// Committed atomic acquisition mutations and storage-side recovery statistics.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AtomicAcquisitionResult {
    /// Mutations used to publish or roll back the local lease.
    pub acquisitions: Vec<AtomicAcquisition>,
    /// Stale tokens actually removed or replaced by this committed transaction.
    pub stale_tokens_removed: usize,
}

/// Storage abstraction for lock tokens. Only `PathLockManager` should call these methods.
#[async_trait]
pub trait PathLockProvider: Send + Sync {
    /// Add provider-owned observations to the manager's metrics snapshot.
    fn update_metrics(&self, _metrics: &mut super::metrics::LockMetrics) {}

    /// Human-readable provider name for config/logging/metrics.
    fn name(&self) -> &'static str;

    /// Return how this provider represents lease handles.
    fn handle_mode(&self) -> PathLockHandleMode {
        PathLockHandleMode::LockPath
    }

    /// Attempt one atomic batch acquisition when supported.
    async fn try_acquire_batch_atomic(
        &self,
        _requests: &[PathLockRequest],
        _owner_id: &str,
        _now_ns: u128,
        _stale_before_ns: u128,
    ) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {
        Ok(None)
    }

    /// Acquire with recovery statistics. Existing providers keep their atomic hook
    /// and report zero until they implement storage-side recovery accounting.
    async fn try_acquire_batch_atomic_with_stats(
        &self,
        requests: &[PathLockRequest],
        owner_id: &str,
        now_ns: u128,
        stale_before_ns: u128,
    ) -> PathLockResult<Option<AtomicAcquisitionResult>> {
        Ok(self
            .try_acquire_batch_atomic(requests, owner_id, now_ns, stale_before_ns)
            .await?
            .map(|acquisitions| AtomicAcquisitionResult {
                acquisitions,
                stale_tokens_removed: 0,
            }))
    }

    /// Roll back one completed atomic acquisition when supported.
    async fn rollback_acquisitions_atomic(
        &self,
        _acquisitions: &[AtomicAcquisition],
        _owner_id: &str,
    ) -> PathLockResult<Option<()>> {
        Ok(None)
    }

    /// Return whether one path is covered by a live token when supported.
    async fn is_path_locked_atomic(
        &self,
        _path: &str,
        _now_ns: u128,
        _stale_before_ns: u128,
        _ignore_stale: bool,
    ) -> PathLockResult<Option<bool>> {
        Ok(None)
    }

    /// Read the token at `lock_path`, returning `None` if no token exists.
    async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>>;

    /// Atomically create a token at `lock_path`. Must fail if a token already exists
    /// (unless it is stale and can be cleaned up by the manager).
    async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()>;

    /// Atomically replace one exact token value.
    async fn compare_and_write_token(
        &self,
        lock_path: &str,
        expected: &LockToken,
        replacement: &LockToken,
    ) -> PathLockResult<bool>;

    /// Refresh the timestamp of an existing token owned by `owner_id`.
    /// Returns `true` if the token was refreshed, `false` if not found or wrong owner.
    async fn refresh_token(
        &self,
        lock_path: &str,
        owner_id: &str,
        time_ns: u128,
    ) -> PathLockResult<bool>;

    /// Refresh owned tokens, returning one result per input path in input order.
    /// A failed path must not prevent the remaining paths from being refreshed.
    /// Backends without batch support retain the single-token behavior.
    async fn refresh_tokens(
        &self,
        lock_paths: &[String],
        owner_id: &str,
        time_ns: u128,
    ) -> Vec<PathLockResult<bool>> {
        let mut results = Vec::with_capacity(lock_paths.len());
        for lock_path in lock_paths {
            results.push(self.refresh_token(lock_path, owner_id, time_ns).await);
        }
        results
    }

    /// Remove the token at `lock_path` if owned by `owner_id`.
    /// `force` bypasses storage CAS after the ownership check.
    /// Returns `true` if removed, `false` if not found or wrong owner.
    async fn remove_token(
        &self,
        lock_path: &str,
        owner_id: &str,
        force: bool,
    ) -> PathLockResult<bool>;

    /// Scan all descendant lock paths under `root`.
    async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>>;
}

// ── Memory provider ──

/// In-process lock table backed by a `HashMap`. Single-process only.
pub struct MemoryPathLockProvider {
    tokens: RwLock<HashMap<String, LockToken>>,
}

impl MemoryPathLockProvider {
    /// Create an empty in-memory provider.
    pub fn new() -> Self {
        Self {
            tokens: RwLock::new(HashMap::new()),
        }
    }
}

impl Default for MemoryPathLockProvider {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl PathLockProvider for MemoryPathLockProvider {
    fn name(&self) -> &'static str {
        "memory"
    }

    async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {
        Ok(self.tokens.read().await.get(lock_path).cloned())
    }

    async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {
        let mut tokens = self.tokens.write().await;
        if tokens.contains_key(lock_path) {
            return Err(PathLockError::Conflict {
                lock_path: lock_path.to_string(),
                owner: tokens[lock_path].owner_id.clone(),
                kind: tokens[lock_path].lock_type,
            });
        }
        tokens.insert(lock_path.to_string(), token.clone());
        Ok(())
    }

    async fn compare_and_write_token(
        &self,
        lock_path: &str,
        expected: &LockToken,
        replacement: &LockToken,
    ) -> PathLockResult<bool> {
        let mut tokens = self.tokens.write().await;
        match tokens.get(lock_path) {
            Some(token) if token == expected => {
                tokens.insert(lock_path.to_string(), replacement.clone());
                Ok(true)
            }
            _ => Ok(false),
        }
    }

    async fn refresh_token(
        &self,
        lock_path: &str,
        owner_id: &str,
        time_ns: u128,
    ) -> PathLockResult<bool> {
        let mut tokens = self.tokens.write().await;
        match tokens.get_mut(lock_path) {
            Some(token) if token.owner_id == owner_id => {
                token.time_ns = time_ns;
                Ok(true)
            }
            _ => Ok(false),
        }
    }

    async fn remove_token(
        &self,
        lock_path: &str,
        owner_id: &str,
        _force: bool,
    ) -> PathLockResult<bool> {
        let mut tokens = self.tokens.write().await;
        match tokens.get(lock_path) {
            Some(token) if token.owner_id == owner_id => {
                tokens.remove(lock_path);
                Ok(true)
            }
            _ => Ok(false),
        }
    }

    async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {
        let prefix = if root.ends_with('/') {
            root.to_string()
        } else {
            format!("{}/", root)
        };
        Ok(self
            .tokens
            .read()
            .await
            .keys()
            .filter(|k| k.starts_with(&prefix))
            .cloned()
            .collect())
    }
}

// ── Filesystem provider ──

/// Lock provider that stores tokens as files on the underlying filesystem.
pub struct FilesystemPathLockProvider {
    fs: Arc<dyn FileSystem>,
    empty_token_expire_secs: f64,
}

impl FilesystemPathLockProvider {
    /// Create a filesystem-backed provider with an explicit empty-token expiry.
    ///
    /// `fs` stores lock files, and `lock_expire_secs` controls empty-token recovery.
    /// Returns a configured filesystem provider.
    pub fn new(fs: Arc<dyn FileSystem>, lock_expire_secs: f64) -> Self {
        Self {
            fs,
            empty_token_expire_secs: lock_expire_secs,
        }
    }

    /// Read raw token bytes from `lock_path`, returning `None` if no token exists.
    async fn read_token_raw(&self, lock_path: &str) -> PathLockResult<Option<Vec<u8>>> {
        let mut result = self.fs.read(lock_path, 0, 0).await;
        if result
            .as_ref()
            .is_ok_and(|data| LockTokenCodec::decode(String::from_utf8_lossy(data).trim()).is_err())
        {
            // A concurrent in-place CAS write can expose a transient partial token.
            tokio::task::yield_now().await;
            result = self.fs.read(lock_path, 0, 0).await;
        }
        match result {
            Ok(data) => Ok(Some(data)),
            Err(e) => {
                if matches!(
                    e,
                    crate::core::Error::NotFound(_) | crate::core::Error::MountPointNotFound(_)
                ) {
                    Ok(None)
                } else {
                    Err(PathLockError::Io(format!(
                        "failed to read lock token at '{lock_path}': {e}"
                    )))
                }
            }
        }
    }

    /// Map filesystem CAS failures into pathlock busy vs. fatal I/O outcomes.
    fn map_cas_error(operation: &str, lock_path: &str, error: crate::core::Error) -> PathLockError {
        match error {
            crate::core::Error::WouldBlock(message) => PathLockError::Busy {
                lock_path: lock_path.to_string(),
                operation: format!("{operation} CAS ({message})"),
            },
            other => PathLockError::Io(format!("{operation} CAS failed: {other}")),
        }
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use crate::core::{Error, FileSystem, WriteFlag};
    use crate::plugins::memfs::MemFileSystem;

    use super::*;

    /// Verify the fallback reports each path and continues after a token error.
    #[tokio::test]
    async fn batch_refresh_fallback_preserves_per_path_results() {
        let fs = Arc::new(MemFileSystem::new());
        fs.mkdir("/data", 0o755).await.unwrap();
        for (path, raw) in [
            ("/data/bad", "not-a-token"),
            ("/data/good", "owner:100:T"),
            ("/data/foreign", "other:100:E"),
        ] {
            fs.write(path, raw.as_bytes(), 0, WriteFlag::Create)
                .await
                .unwrap();
        }
        let provider = FilesystemPathLockProvider::new(fs, 30.0);
        let paths = ["bad", "good", "foreign", "missing"].map(|name| format!("/data/{name}"));
        let results = provider.refresh_tokens(&paths, "owner", 200).await;
        assert_eq!(results.len(), paths.len());
        assert!(matches!(results[0], Err(PathLockError::InvalidToken(_))));
        assert!(matches!(results[1], Ok(true)));
        assert!(matches!(results[2], Ok(false)));
        assert!(matches!(results[3], Ok(false)));
        let token = provider.read_token(&paths[1]).await.unwrap().unwrap();
        assert_eq!(token.time_ns, 200);
        assert_eq!(token.lock_type, crate::lock::PathLockKind::Tree);
        assert!(provider.refresh_tokens(&[], "owner", 200).await.is_empty());
    }

    /// Verify legacy encrypted lock files are treated as removable upgrade leftovers.
    #[tokio::test]
    async fn read_token_cleans_up_legacy_encrypted_lock() {
        let fs = Arc::new(MemFileSystem::new());
        fs.mkdir("/data", 0o755).await.unwrap();
        fs.write(
            "/data/.path.ovlock",
            b"OVE1legacy-ciphertext",
            0,
            WriteFlag::Create,
        )
        .await
        .unwrap();
        let provider = FilesystemPathLockProvider::new(fs.clone(), 30.0);

        let token = provider.read_token("/data/.path.ovlock").await.unwrap();

        assert!(token.is_none());
        assert!(matches!(
            fs.read("/data/.path.ovlock", 0, 0).await,
            Err(Error::NotFound(_))
        ));
    }

    /// Verify malformed non-legacy lock files still surface as invalid tokens.
    #[tokio::test]
    async fn read_token_rejects_non_legacy_invalid_lock() {
        let fs = Arc::new(MemFileSystem::new());
        fs.mkdir("/data", 0o755).await.unwrap();
        fs.write("/data/.path.ovlock", b"not-a-token", 0, WriteFlag::Create)
            .await
            .unwrap();
        let provider = FilesystemPathLockProvider::new(fs.clone(), 30.0);

        let err = provider.read_token("/data/.path.ovlock").await.unwrap_err();

        assert!(matches!(err, PathLockError::InvalidToken(_)));
        assert_eq!(
            fs.read("/data/.path.ovlock", 0, 0).await.unwrap(),
            b"not-a-token"
        );
    }

    /// Verify valid plaintext lock files continue to decode unchanged.
    #[tokio::test]
    async fn read_token_accepts_plaintext_lock() {
        let fs = Arc::new(MemFileSystem::new());
        fs.mkdir("/data", 0o755).await.unwrap();
        fs.write("/data/.path.ovlock", b"owner:123:E", 0, WriteFlag::Create)
            .await
            .unwrap();
        let provider = FilesystemPathLockProvider::new(fs, 30.0);

        let token = provider
            .read_token("/data/.path.ovlock")
            .await
            .unwrap()
            .unwrap();

        assert_eq!(token.owner_id, "owner");
        assert_eq!(token.time_ns, 123);
        assert_eq!(token.lock_type, crate::lock::PathLockKind::Exact);
    }

    #[test]
    fn compare_and_remove_would_block_maps_to_busy() {
        let err = FilesystemPathLockProvider::map_cas_error(
            "remove",
            "/data/.path.ovlock",
            Error::WouldBlock("lock would block".to_string()),
        );
        assert!(matches!(err, PathLockError::Busy { .. }));
    }
}

#[async_trait]
impl PathLockProvider for FilesystemPathLockProvider {
    fn name(&self) -> &'static str {
        "filesystem"
    }

    async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {
        let mut current = self.read_token_raw(lock_path).await?;
        loop {
            match current {
                Some(data) => {
                    if data.is_empty() {
                        let info = match self.fs.stat(lock_path).await {
                            Ok(info) => info,
                            Err(
                                crate::core::Error::NotFound(_)
                                | crate::core::Error::MountPointNotFound(_),
                            ) => return Ok(None),
                            Err(error) => {
                                return Err(PathLockError::Io(format!(
                                    "failed to stat empty lock token at '{lock_path}': {error}"
                                )));
                            }
                        };
                        let age = std::time::SystemTime::now()
                            .duration_since(info.mod_time)
                            .unwrap_or_default()
                            .as_secs_f64();
                        if age <= self.empty_token_expire_secs {
                            return Err(PathLockError::EmptyToken {
                                lock_path: lock_path.to_string(),
                            });
                        }
                        return Ok(None);
                    }
                    let raw = String::from_utf8_lossy(&data).trim().to_string();
                    match LockTokenCodec::decode(&raw) {
                        Ok(token) => return Ok(Some(token)),
                        Err(error) if crypto::is_encrypted(&data) => {
                            if self
                                .fs
                                .compare_and_remove(lock_path, &data)
                                .await
                                .map_err(|e| {
                                    Self::map_cas_error(
                                        "legacy encrypted lock cleanup",
                                        lock_path,
                                        e,
                                    )
                                })?
                            {
                                return Ok(None);
                            }
                            current = self.read_token_raw(lock_path).await?;
                        }
                        Err(error) => return Err(error),
                    }
                }
                None => return Ok(None),
            }
        }
    }

    async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {
        use crate::core::WriteFlag;

        let encoded = LockTokenCodec::encode(token);
        let mut last_error = None;
        for _ in 0..2 {
            let error = match self
                .fs
                .write(lock_path, encoded.as_bytes(), 0, WriteFlag::CreateNew)
                .await
            {
                Ok(_) => return Ok(()),
                Err(error) => error,
            };
            match self.read_token(lock_path).await? {
                // Already exists — read and check if stale.
                Some(t) => {
                    return Err(PathLockError::Conflict {
                        lock_path: lock_path.to_string(),
                        owner: t.owner_id,
                        kind: t.lock_type,
                    });
                }
                None => {
                    last_error = Some(error);
                    if self
                        .fs
                        .compare_and_write(lock_path, b"", encoded.as_bytes())
                        .await
                        .map_err(|e| Self::map_cas_error("empty lock recovery", lock_path, e))?
                    {
                        return Ok(());
                    }
                }
            }
        }
        Err(PathLockError::Io(format!(
            "failed to create lock token at {lock_path}: {}",
            last_error.unwrap()
        )))
    }

    async fn compare_and_write_token(
        &self,
        lock_path: &str,
        expected: &LockToken,
        replacement: &LockToken,
    ) -> PathLockResult<bool> {
        let expected = LockTokenCodec::encode(expected);
        let replacement = LockTokenCodec::encode(replacement);
        self.fs
            .compare_and_write(lock_path, expected.as_bytes(), replacement.as_bytes())
            .await
            .map_err(|e| Self::map_cas_error("compare_and_write", lock_path, e))
    }

    async fn refresh_token(
        &self,
        lock_path: &str,
        owner_id: &str,
        time_ns: u128,
    ) -> PathLockResult<bool> {
        let Some(raw) = self.read_token_raw(lock_path).await? else {
            return Ok(false);
        };
        let token = LockTokenCodec::decode(&String::from_utf8_lossy(&raw).trim())?;
        if token.owner_id != owner_id {
            return Ok(false);
        }
        let new_token = LockToken {
            owner_id: owner_id.to_string(),
            time_ns,
            lock_type: token.lock_type,
        };
        let encoded = LockTokenCodec::encode(&new_token);
        self.fs
            .compare_and_write(lock_path, &raw, encoded.as_bytes())
            .await
            .map_err(|e| Self::map_cas_error("refresh", lock_path, e))
    }

    async fn remove_token(
        &self,
        lock_path: &str,
        owner_id: &str,
        force: bool,
    ) -> PathLockResult<bool> {
        let Some(raw) = self.read_token_raw(lock_path).await? else {
            return Ok(false);
        };
        let token = LockTokenCodec::decode(&String::from_utf8_lossy(&raw).trim())?;
        if token.owner_id != owner_id {
            return Ok(false);
        }
        if force {
            return match self.fs.remove(lock_path).await {
                Ok(()) => Ok(true),
                Err(
                    crate::core::Error::NotFound(_) | crate::core::Error::MountPointNotFound(_),
                ) => Ok(false),
                Err(error) => Err(PathLockError::Io(format!(
                    "failed to force remove lock token at '{lock_path}': {error}"
                ))),
            };
        }
        self.fs
            .compare_and_remove(lock_path, &raw)
            .await
            .map_err(|e| Self::map_cas_error("remove", lock_path, e))
    }

    async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {
        let mut result = Vec::new();
        self.scan_recursive(root, &mut result).await?;
        Ok(result)
    }
}

impl FilesystemPathLockProvider {
    /// Recursively scan a directory for `.path.ovlock` and `.exact.ovlock.*` files.
    fn is_lock_file(name: &str) -> bool {
        is_hidden_runtime_lock_name(name)
    }

    async fn scan_recursive(&self, dir: &str, result: &mut Vec<String>) -> PathLockResult<()> {
        let entries = match self.fs.read_internal_dir(dir).await {
            Ok(entries) => entries,
            Err(crate::core::Error::NotFound(_) | crate::core::Error::NotADirectory(_)) => {
                return Ok(());
            }
            Err(error) => {
                return Err(PathLockError::Io(format!(
                    "failed to scan lock directory '{dir}': {error}"
                )));
            }
        };

        for entry in entries {
            let child_path = if dir.ends_with('/') {
                format!("{}{}", dir, entry.name)
            } else {
                format!("{}/{}", dir, entry.name)
            };

            if Self::is_lock_file(&entry.name) {
                result.push(child_path);
            } else if entry.is_dir {
                Box::pin(self.scan_recursive(&child_path, result)).await?;
            }
        }
        Ok(())
    }
}