gradatum-storage

Storage trait abstraction with OpenDAL backends (filesystem, S3, Azure Blob) and NFS rejection guard.

Status : Alpha — placeholder v0.0.2. Phase 2.0c-bis Auth Path 2 LIVE 2026-05-07 (git tag v0.1.0-alpha.5). Source code private until v1.0 public release per D5 criterion. See gradatum.org.

Part of gradatum — Memory backbone for AI agents.

Public API

Trait

/// Storage abstraction — async read/write/list/delete/stat primitives.
#[async_trait]
pub trait Storage: Send + Sync {
    async fn read(&self, path: &str) -> Result<Bytes, StorageError>;
    async fn write(&self, path: &str, data: Bytes) -> Result<(), StorageError>;
    async fn delete(&self, path: &str) -> Result<(), StorageError>;
    async fn list(&self, prefix: &str) -> Result<Vec<StorageEntry>, StorageError>;
    async fn exists(&self, path: &str) -> Result<bool, StorageError>;
    async fn stat(&self, path: &str) -> Result<StorageEntry, StorageError>;
}

Implementations

/// Filesystem backend via OpenDAL (feature = "fs", enabled by default).
pub struct FileStorage { ... }

impl FileStorage {
    /// Create a new FileStorage rooted at `root`.
    /// Returns Err if root is on an NFS mount (caveat C11).
    pub fn new(root: &Path) -> Result<Self, StorageError>
}

Functions

/// Verify via statfs(2) that `path` is not on an NFS mount.
/// Called automatically by FileStorage::new().
pub fn ensure_local_filesystem(path: &Path) -> Result<(), StorageError>

Types

pub struct StorageEntry {
    pub path: String,
    pub size: u64,
    pub last_modified: Option<DateTime<Utc>>,
}

#[derive(Debug, thiserror::Error)]
pub enum StorageError {
    Io(std::io::Error),
    Core(GradatumError),
    NfsMountDetected { path: PathBuf },
    Backend(String),
}

Feature flags

Documentation

• Project : https://gradatum.org
• Source : private until v1.0
• Roadmap : Phase 2.0c-bis (alpha.5 LIVE) → Phase 2.1 v0.1.0-rc.1 → v0.1.0 public
• License : Apache-2.0