grafos_store/

bucket.rs

//! Bucket management for organizing objects into logical containers.

extern crate alloc;
use alloc::string::String;
use alloc::vec::Vec;

use grafos_std::error::{FabricError, Result};
use grafos_std::host;

use serde::{Deserialize, Serialize};

use crate::bucket_config::{BucketConfig, BucketTier};
use crate::bucket_handle::BucketHandle;
use crate::bucket_locator::BucketLocator;

/// Metadata for a bucket.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct BucketInfo {
    /// Bucket name.
    pub name: String,
    /// Pool the bucket belongs to.
    pub pool: String,
    /// Creation timestamp (unix seconds).
    pub created_at: u64,
}

/// Manages creation and lifecycle of object store buckets.
///
/// Buckets are logical containers within a pool. The bucket manager
/// tracks which buckets exist and their metadata.
///
/// # Example
///
/// ```rust
/// use grafos_store::BucketManager;
///
/// let mut mgr = BucketManager::new("default");
/// mgr.create("images").unwrap();
/// mgr.create("logs").unwrap();
///
/// assert!(mgr.exists("images"));
/// assert_eq!(mgr.list().len(), 2);
/// ```
pub struct BucketManager {
    pool: String,
    buckets: Vec<BucketInfo>,
    generation_counter: u64,
    published: Vec<BucketLocator>,
}

impl BucketManager {
    /// Create a new bucket manager for the given pool.
    pub fn new(pool: &str) -> Self {
        BucketManager {
            pool: String::from(pool),
            buckets: Vec::new(),
            generation_counter: 0,
            published: Vec::new(),
        }
    }

    /// Create a new bucket. Returns an error if the bucket already exists.
    pub fn create(&mut self, name: &str) -> Result<&BucketInfo> {
        if self.exists(name) {
            return Err(FabricError::IoError(-11));
        }
        let now = host::unix_time_secs();
        let info = BucketInfo {
            name: String::from(name),
            pool: self.pool.clone(),
            created_at: now,
        };
        self.buckets.push(info);

        #[cfg(feature = "observe")]
        crate::observe_hooks::on_bucket_created(name);

        Ok(self.buckets.last().unwrap())
    }

    /// Check if a bucket exists.
    pub fn exists(&self, name: &str) -> bool {
        self.buckets.iter().any(|b| b.name == name)
    }

    /// Get bucket info by name.
    pub fn get(&self, name: &str) -> Option<&BucketInfo> {
        self.buckets.iter().find(|b| b.name == name)
    }

    /// Drop (delete) a bucket by name. Returns `true` if it existed.
    pub fn drop_bucket(&mut self, name: &str) -> bool {
        let len_before = self.buckets.len();
        self.buckets.retain(|b| b.name != name);
        self.buckets.len() < len_before
    }

    /// List all bucket names.
    pub fn list(&self) -> Vec<&str> {
        self.buckets.iter().map(|b| b.name.as_str()).collect()
    }

    /// The pool this manager belongs to.
    pub fn pool(&self) -> &str {
        &self.pool
    }

    /// Create a bucket from a configuration, returning a typed handle.
    pub fn create_bucket(&mut self, config: BucketConfig) -> Result<BucketHandle> {
        if self.exists(&config.name) {
            return Err(FabricError::IoError(-11));
        }
        let now = host::unix_time_secs();
        self.generation_counter += 1;
        let info = BucketInfo {
            name: config.name.clone(),
            pool: self.pool.clone(),
            created_at: now,
        };
        self.buckets.push(info);
        Ok(BucketHandle {
            name: config.name,
            pool: self.pool.clone(),
            tier: config.tier,
            created_at: now,
            generation: self.generation_counter,
        })
    }

    /// Open an existing bucket by name, returning a typed handle.
    pub fn open_bucket(&self, name: &str) -> Result<BucketHandle> {
        let info = self.get(name).ok_or(FabricError::IoError(-4))?;
        Ok(BucketHandle {
            name: info.name.clone(),
            pool: info.pool.clone(),
            tier: BucketTier::Memory, // default; tier info not stored in BucketInfo
            created_at: info.created_at,
            generation: self.generation_counter,
        })
    }

    /// Publish a bucket handle as a locator for cross-app discovery.
    pub fn publish(&mut self, handle: &BucketHandle) -> BucketLocator {
        let locator = BucketLocator {
            version: 1,
            name: handle.name.clone(),
            pool: handle.pool.clone(),
            tier: handle.tier.clone(),
            generation: handle.generation,
            created_at: handle.created_at,
        };
        // Replace existing locator for same name, or push new
        if let Some(pos) = self.published.iter().position(|l| l.name == locator.name) {
            self.published[pos] = locator.clone();
        } else {
            self.published.push(locator.clone());
        }
        locator
    }

    /// Discover a previously published bucket locator by name.
    pub fn discover(&self, name: &str) -> Option<&BucketLocator> {
        self.published.iter().find(|l| l.name == name)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use grafos_std::host;

    fn setup() {
        host::reset_mock();
    }

    #[test]
    fn create_and_exists() {
        setup();
        let mut mgr = BucketManager::new("pool");
        assert!(!mgr.exists("b1"));

        mgr.create("b1").unwrap();
        assert!(mgr.exists("b1"));
    }

    #[test]
    fn create_duplicate_fails() {
        setup();
        let mut mgr = BucketManager::new("pool");
        mgr.create("b1").unwrap();
        assert!(mgr.create("b1").is_err());
    }

    #[test]
    fn drop_bucket() {
        setup();
        let mut mgr = BucketManager::new("pool");
        mgr.create("b1").unwrap();
        mgr.create("b2").unwrap();

        assert!(mgr.drop_bucket("b1"));
        assert!(!mgr.exists("b1"));
        assert!(mgr.exists("b2"));
        assert!(!mgr.drop_bucket("b1")); // already gone
    }

    #[test]
    fn list_buckets() {
        setup();
        let mut mgr = BucketManager::new("pool");
        mgr.create("alpha").unwrap();
        mgr.create("beta").unwrap();
        mgr.create("gamma").unwrap();

        let mut names = mgr.list();
        names.sort();
        assert_eq!(names, vec!["alpha", "beta", "gamma"]);
    }

    #[test]
    fn get_bucket_info() {
        setup();
        let mut mgr = BucketManager::new("mypool");
        mgr.create("data").unwrap();

        let info = mgr.get("data").unwrap();
        assert_eq!(info.name, "data");
        assert_eq!(info.pool, "mypool");
    }

    #[test]
    fn pool_name() {
        let mgr = BucketManager::new("test");
        assert_eq!(mgr.pool(), "test");
    }

    #[test]
    fn create_bucket_from_config() {
        setup();
        use crate::bucket_config::{BucketConfig, BucketTier};
        let mut mgr = BucketManager::new("pool");
        let config = BucketConfig::new("data").tier(BucketTier::Block);
        let handle = mgr.create_bucket(config).unwrap();
        assert_eq!(handle.name(), "data");
        assert_eq!(handle.pool(), "pool");
        assert_eq!(*handle.tier(), BucketTier::Block);
        assert_eq!(handle.generation(), 1);
        assert!(mgr.exists("data"));
    }

    #[test]
    fn create_bucket_duplicate_fails() {
        setup();
        use crate::bucket_config::BucketConfig;
        let mut mgr = BucketManager::new("pool");
        mgr.create_bucket(BucketConfig::new("dup")).unwrap();
        assert!(mgr.create_bucket(BucketConfig::new("dup")).is_err());
    }

    #[test]
    fn open_bucket() {
        setup();
        use crate::bucket_config::BucketConfig;
        let mut mgr = BucketManager::new("pool");
        mgr.create_bucket(BucketConfig::new("open-me")).unwrap();

        let handle = mgr.open_bucket("open-me").unwrap();
        assert_eq!(handle.name(), "open-me");
        assert_eq!(handle.pool(), "pool");
    }

    #[test]
    fn open_bucket_not_found() {
        let mgr = BucketManager::new("pool");
        assert!(mgr.open_bucket("nope").is_err());
    }

    #[test]
    fn publish_and_discover() {
        setup();
        use crate::bucket_config::{BucketConfig, BucketTier};
        let mut mgr = BucketManager::new("pool");
        let handle = mgr
            .create_bucket(BucketConfig::new("shared").tier(BucketTier::Memory))
            .unwrap();

        let locator = mgr.publish(&handle);
        assert_eq!(locator.version, 1);
        assert_eq!(locator.name, "shared");
        assert_eq!(locator.pool, "pool");
        assert_eq!(locator.tier, BucketTier::Memory);
        assert_eq!(locator.generation, 1);

        let found = mgr.discover("shared").unwrap();
        assert_eq!(found, &locator);
        assert!(mgr.discover("missing").is_none());
    }

    #[test]
    fn publish_replaces_existing() {
        setup();
        use crate::bucket_config::BucketConfig;
        let mut mgr = BucketManager::new("pool");
        let h1 = mgr.create_bucket(BucketConfig::new("b")).unwrap();
        mgr.publish(&h1);

        // Drop and recreate the bucket for a new generation
        mgr.drop_bucket("b");
        let h2 = mgr.create_bucket(BucketConfig::new("b")).unwrap();
        mgr.publish(&h2);

        let found = mgr.discover("b").unwrap();
        assert_eq!(found.generation, 2);
    }

    #[test]
    fn bucket_handle_uri() {
        setup();
        use crate::bucket_config::BucketConfig;
        let mut mgr = BucketManager::new("pool");
        let handle = mgr.create_bucket(BucketConfig::new("bkt")).unwrap();
        let uri = handle.uri("my-key").unwrap();
        assert_eq!(uri.pool(), "pool");
        assert_eq!(uri.bucket(), "bkt");
        assert_eq!(uri.key(), "my-key");
    }

    #[test]
    fn generation_increments() {
        setup();
        use crate::bucket_config::BucketConfig;
        let mut mgr = BucketManager::new("pool");
        let h1 = mgr.create_bucket(BucketConfig::new("a")).unwrap();
        let h2 = mgr.create_bucket(BucketConfig::new("b")).unwrap();
        assert_eq!(h1.generation(), 1);
        assert_eq!(h2.generation(), 2);
    }
}