Struct FileManager 

pub struct FileManager { /* private fields */ }

Re-export FileManager when files feature is enabled. File manager - main interface for file operations

Implementations

impl FileManager

pub async fn new(config: FileConfig) -> Result<FileManager, FileError>

Create a new file manager with default (empty) hooks.

For hooks integration, use FileManager::new_with_hooks instead.

pub async fn new_with_hooks( config: FileConfig, hooks: HookRegistry, ) -> Result<FileManager, FileError>

Create a new file manager with the given configuration and hooks.

Arguments

• config - File manager configuration
• hooks - Hook registry containing storage, read, metadata, and cleanup hooks

Example

use agent_diva_files::{FileManager, FileConfig, hooks::{HookRegistry, LoggingStorageHook}};

let mut hooks = HookRegistry::new();
hooks.register_storage_hook(Box::new(LoggingStorageHook));

let manager = FileManager::new_with_hooks(FileConfig::default(), hooks).await?;

pub async fn default() -> Result<FileManager, FileError>

Create with default configuration

pub async fn store( &self, data: &[u8], metadata: FileMetadata, ) -> Result<FileHandle, FileError>

Store file data and return a handle

If the file already exists (based on hash), returns an existing handle and increments the reference count.

Hook Integration

• Calls StorageHook::before_store hooks before storing
• Calls StorageHook::after_store hooks after successful storage
• Calls MetadataHook::extract_metadata for additional metadata

pub async fn store_from_path( &self, source_path: &PathBuf, metadata: Option<FileMetadata>, ) -> Result<FileHandle, FileError>

Store file from path

pub async fn get(&self, id: &str) -> Result<FileHandle, FileError>

Get a file handle by ID

Increments the reference count if found. Note: This only returns non-deleted files.

pub async fn clone_ref( &self, handle: &FileHandle, ) -> Result<FileHandle, FileError>

Clone a file handle (increment reference count)

pub async fn release(&self, handle: &FileHandle) -> Result<(), FileError>

Release a file handle (decrement reference count)

Does not actually delete the file - cleanup is done separately based on the cleanup strategy.

pub async fn soft_delete( &self, id: &str, deleted_by: Option<&str>, ) -> Result<bool, FileError>

Soft delete a file - marks it as deleted but doesn’t remove physically

The file enters a “deleted” state but can be recovered within the retention period. After retention_days expire, the file becomes eligible for permanent deletion via FileManager::purge_expired.

Arguments

• id - File ID to delete
• deleted_by - Optional identifier of who/what deleted the file

Example

// Soft delete a file
manager.soft_delete(&file_id, Some("user@example.com")).await?;

// List deleted files
let deleted = manager.list_deleted().await?;

// Restore if needed
manager.restore(&file_id).await?;

pub async fn restore(&self, id: &str) -> Result<bool, FileError>

Restore a soft-deleted file

Makes the file accessible again by clearing the deleted timestamp. Only works on files that were soft-deleted and haven’t expired yet.

Arguments

• id - File ID to restore

Returns

• Ok(true) - File was restored
• Ok(false) - File wasn’t found in deleted state

pub async fn list_deleted(&self) -> Result<Vec<FileIndexEntry>, FileError>

List all soft-deleted files

Returns files that have been soft-deleted but not yet purged. Files are sorted by deletion time (most recent first).

Returns

List of deleted file entries with deletion metadata

pub async fn hard_delete( &self, id: &str, ) -> Result<Option<FileIndexEntry>, FileError>

Permanently delete a specific file (bypass retention period)

WARNING: This immediately and permanently removes the file. Unlike soft delete, there is no way to recover a hard-deleted file.

Arguments

• id - File ID to permanently delete

Returns

The deleted entry (for logging/audit purposes), or None if not found

pub async fn purge_expired( &self, retention_days: u32, ) -> Result<usize, FileError>

Purge all soft-deleted files that have exceeded the retention period

This is the cleanup task for soft deletes. It finds all soft-deleted files where deleted_at is older than retention_days and permanently removes them.

Arguments

• retention_days - Files deleted more than this many days ago will be purged

Returns

Number of files permanently deleted

pub async fn is_deleted(&self, id: &str) -> Result<bool, FileError>

Check if a file is soft-deleted

Arguments

• id - File ID to check

Returns

true if the file is soft-deleted, false otherwise

pub async fn read(&self, handle: &FileHandle) -> Result<Vec<u8>, FileError>

Read file data by handle

Hook Integration

• Calls ReadHook::before_read hooks before reading (e.g., permission check)
• Calls ReadHook::after_read hooks after reading (e.g., decryption)

pub async fn read_string( &self, handle: &FileHandle, ) -> Result<String, FileError>

Read file as string (for text files)

pub fn full_path(&self, handle: &FileHandle) -> PathBuf

Get the full path for a handle

pub async fn exists(&self, id: &str) -> bool

Check if a file exists (non-deleted)

pub async fn metadata(&self, id: &str) -> Result<FileMetadata, FileError>

Get file metadata

Returns metadata for non-deleted files only.

pub async fn cleanup(&self) -> Result<usize, FileError>

Run cleanup - delete files with ref_count <= threshold

Returns the number of files deleted.

Hook Integration

• Calls CleanupHook::should_cleanup for each candidate
• Calls CleanupHook::after_cleanup after each file is deleted

pub async fn stats(&self) -> Result<StorageStats, FileError>

Get storage statistics

pub fn config(&self) -> &FileConfig

Get a reference to the config

pub fn hooks(&self) -> &HookRegistry

Get a reference to the hooks registry

Useful for inspecting registered hooks or adding hooks dynamically.

pub fn hooks_mut(&mut self) -> &mut HookRegistry

Get mutable reference to the hooks registry

Allows adding new hooks at runtime.

pub fn start_cleanup_task(self: Arc<FileManager>) -> JoinHandle<()>

Start background cleanup task

This spawns a task that periodically runs cleanup