Storage Backends

Purpose

Policy-aware strand vault with sessions, permissions, storage backends, WAL, fsck, snapshots, and replication.

This page follows the real source shape for Strand Vault and explains the workflow a developer is likely to use first.

Storage contract

Document persistence format, integrity checks, read/write ordering, idempotency, compaction or repair behavior, and how callers recover from partial failures. This section should answer what data is durable and what can be reconstructed.

Primary types to know

• AgentPermissions — libs/strand-vault/src/permissions.rs
• AppendGuard — libs/strand-vault/src/vault.rs
• Atom — libs/strand-vault/src/vault.rs
• CreateOptions — libs/strand-vault/src/config.rs
• DefaultPolicy — libs/strand-vault/src/policy.rs
• FileMetadataStorage — libs/strand-vault/src/storage/filesystem.rs
• FileSystemStorage — libs/strand-vault/src/storage/filesystem.rs
• FileSystemStorageFactory — libs/strand-vault/src/storage/filesystem.rs
• FileStrandStorage — libs/strand-vault/src/storage/filesystem.rs
• FsckReport — libs/strand-vault/src/fsck.rs
• IndexingConfig — libs/strand-vault/src/config.rs
• LruStoragePool — libs/strand-vault/src/storage/mod.rs

Example shape

use strand_vault::storage::filesystem::FileSystemStorageFactory;
use strand_vault::storage::memory::MemoryStorage;
use strand_vault::{StrandVault, VaultConfig};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // FileSystemStorageFactory mints durable Storage handles rooted at a path.
    // Swap it for an in-memory factory in tests by implementing StorageFactory
    // around `MemoryStorage::new()`.
    let dir = tempfile::tempdir()?;
    let mut cfg = VaultConfig::default();
    cfg.storage_factory = Box::new(FileSystemStorageFactory::new(dir.path()));
    cfg.cache_size = 32;
    cfg.compression = true;
    cfg.validate()?;

    let durable_vault = StrandVault::new(cfg).await?;

    // MemoryStorage is the ephemeral counterpart used by integration tests.
    let _memory: Arc<dyn strand_vault::Storage> = Arc::new(MemoryStorage::new());

    println!(
        "durable_root={} health={:?}",
        dir.path().display(),
        durable_vault.health(),
    );
    durable_vault.shutdown().await?;
    Ok(())
}