Struct FileBackend 

pub struct FileBackend { /* private fields */ }

Filesystem-backed StorageBackend.

One file per key under dir. Concurrent writers are safe at the per-key granularity (atomic rename via tempfile); concurrent writers to the SAME key race in unspecified-but-atomic fashion (last commit wins).

Filesystem portability

Key→filename encoding preserves ASCII case: Foo and foo encode to Foo.bin and foo.bin. On case-insensitive filesystems (default macOS APFS, default Windows NTFS) these collide. graphrefly-internal keys (tier names, WAL frame paths) are case-consistent by construction, so the collision is only reachable with adversarial user-supplied keys. Lift documented in porting-deferred.md “M4.C FileBackend case-insensitive-filesystem key collision”.

Example

use std::sync::Arc;
use graphrefly_storage::{file_backend, snapshot_storage, SnapshotStorageOptions};

let backend = file_backend("./checkpoints");
let tier = snapshot_storage(backend, SnapshotStorageOptions::<MyState, _>::default());
tier.save(state).unwrap();

Implementations

impl FileBackend

pub fn new(dir: impl AsRef<Path>) -> Self

Construct a backend rooted at dir. The directory is created lazily on first write() — read / list / delete tolerate its absence.

pub fn with_include_hidden(self, include: bool) -> Self

Override whether list() includes filenames beginning with . (D161).

Default false: hidden filenames are skipped. This protects against in-flight tempfile::NamedTempFile temp files (which are created with a leading-. prefix) leaking into enumeration results during a concurrent flush.

Pass true if your application intentionally writes keys whose percent-encoding produces a leading-. filename and you need them visible in list().

pub fn dir(&self) -> &Path

Backend root directory.

pub fn include_hidden(&self) -> bool

Whether list() includes dot-prefixed filenames.

Trait Implementations

impl Debug for FileBackend

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

Formats the value using the given formatter.

impl StorageBackend for FileBackend

fn name(&self) -> &str

Diagnostic name (e.g. "memory", "file:./checkpoints"). Surfaces in error messages and tier Display impls.

fn read(&self, key: &str) -> Result<Option<Vec<u8>>, StorageError>

Read raw bytes; returns Ok(None) on miss.

fn write(&self, key: &str, bytes: &[u8]) -> Result<(), StorageError>

Write raw bytes.

fn delete(&self, key: &str) -> Result<(), StorageError>

Optional delete-by-key. Default is no-op so append-only or read-only backends can stay quiet.

fn list(&self, prefix: &str) -> Result<Vec<String>, StorageError>

Enumerate keys matching prefix (lex-ASC). Empty prefix enumerates all keys. Default returns BackendNoListSupport — backends that don’t support enumeration surface the diagnostic here at first call, NOT at attach (mirrors TS lazy-throw semantics for list_by_prefix).

fn flush(&self) -> Result<(), StorageError>

Optional drain hook — adapter authors implement when buffering writes. Default no-op; tier flush() does NOT cascade into this by default (the tier owns its own buffer; backend buffering is a separate concern the backend author opts into).