agentics_storage/
backend.rs

1use std::path::Path;
2use std::time::SystemTime;
3
4use async_trait::async_trait;
5
6use crate::{Result, StorageError, StorageKey, StorageWriteIntent};
7
8/// Minimal object-storage interface used by services and workers.
9#[async_trait]
10pub trait Storage: std::fmt::Debug + Send + Sync {
11    /// Store content at a storage-relative key. Implementations must not overwrite.
12    async fn put(
13        &self,
14        key: &StorageKey,
15        content: &[u8],
16        intent: StorageWriteIntent,
17    ) -> Result<StorageKey>;
18
19    /// Store a local file at a storage-relative key. Implementations must not overwrite.
20    async fn put_file(
21        &self,
22        key: &StorageKey,
23        source: &Path,
24        intent: StorageWriteIntent,
25    ) -> Result<StorageKey>;
26
27    /// Promote a temporary object to a durable storage-relative key without overwriting.
28    async fn promote(
29        &self,
30        temporary_key: &StorageKey,
31        durable_key: &StorageKey,
32    ) -> Result<StorageKey>;
33
34    /// Read content from a storage-relative key with an object-size cap.
35    async fn get(&self, key: &StorageKey, intent: StorageWriteIntent) -> Result<Vec<u8>>;
36
37    /// Download an object into a local file with an object-size cap.
38    async fn get_to_file(
39        &self,
40        key: &StorageKey,
41        destination: &Path,
42        intent: StorageWriteIntent,
43    ) -> Result<()>;
44
45    /// Return whether a storage-relative key exists.
46    async fn exists(&self, key: &StorageKey) -> Result<bool>;
47
48    /// Delete a storage-relative key if it exists.
49    async fn delete(&self, key: &StorageKey) -> Result<()>;
50
51    /// List object keys below a storage-relative prefix.
52    async fn list_prefix(&self, prefix: &StorageKey) -> Result<Vec<StorageKey>>;
53
54    /// Delete every object below a storage-relative prefix older than the cutoff.
55    async fn delete_prefix_older_than(
56        &self,
57        prefix: &StorageKey,
58        older_than: SystemTime,
59    ) -> Result<u64>;
60
61    /// Delete every object below a storage-relative prefix.
62    async fn delete_prefix(&self, prefix: &StorageKey) -> Result<u64> {
63        let keys = self.list_prefix(prefix).await?;
64        let mut deleted = 0u64;
65        for key in keys {
66            self.delete(&key).await?;
67            deleted = deleted.checked_add(1).ok_or_else(|| {
68                StorageError::Internal("deleted object count overflow".to_string())
69            })?;
70        }
71        Ok(deleted)
72    }
73}
agentics_storage/backend.rs

agentics_storage/
backend.rs
