Struct FilePersistenceBackend 

pub struct FilePersistenceBackend { /* private fields */ }

Persists data as files in a directory on disk.

Each key maps to a file named <key>.bin inside the base directory. The base directory must exist before calling any methods.

Key Sanitization

Characters that are invalid in file names on common operating systems (/, \, :, *, ?, ", <, >, |) are replaced with _ before the path is constructed. This prevents path-traversal attacks and ensures portability across Linux, macOS, and Windows.

Concurrency

FilePersistenceBackend is Clone and Send + Sync. Each clone shares the same base_dir via Arc and can be used from multiple async tasks simultaneously.

Writes are atomic at the OS level: data is written to a uniquely-named temporary file in the same directory and then renamed into place, so a reader never observes a half-written file even if the process crashes. Concurrent writes to the same key from multiple tasks are safe but are not serialized — the final file content is determined by whichever rename completes last.

Implementations

impl FilePersistenceBackend

pub fn new(base_dir: impl Into<PathBuf>) -> Self

Create a new backend that stores files in base_dir.

The directory is not created automatically — it must already exist.

pub fn base_dir(&self) -> &Path

Return the base directory that this backend stores files in.

impl FilePersistenceBackend

pub async fn list_keys(&self) -> Result<Vec<String>, AgentRuntimeError>

List all keys currently stored in the backend.

Returns the readable prefix portion of stored filenames (the part before the hash suffix). Useful for backup/restore tooling and debugging.

pub async fn exists(&self, key: &str) -> Result<bool, AgentRuntimeError>

Check whether a key exists in the backend without loading its value.

Returns Ok(true) if the file for key is present in the store.

pub async fn key_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of keys currently stored in the backend.

More efficient than list_keys().await?.len() for callers that only need the count, as it avoids building the string list.

Trait Implementations

impl Clone for FilePersistenceBackend

fn clone(&self) -> FilePersistenceBackend

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FilePersistenceBackend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PersistenceBackend for FilePersistenceBackend

fn batch_save<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, items: &'life1 [(&'life2 str, &'life3 [u8])], ) -> Pin<Box<dyn Future<Output = Result<(), AgentRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Save multiple key-value pairs concurrently.

All writes are issued simultaneously using try_join_all instead of the default sequential loop, so throughput scales with disk/OS concurrency.

fn batch_load<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, keys: &'life1 [&'life2 str], ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<Vec<u8>>>, AgentRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Load multiple keys concurrently.

All reads are issued simultaneously using try_join_all. Returns results in the same order as keys.

fn save<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, value: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), AgentRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Persist raw bytes under the given key.

fn load<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, AgentRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load raw bytes for the given key.

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), AgentRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete the entry for the given key. No-op if the key does not exist.