Struct SystemSidecar 

pub struct SystemSidecar<T> { /* private fields */ }

Atomic JSON persistence for one _system/ document of type T.

T is the whole document — callers parameterize with the collection they store (SystemSidecar<Vec<Row>>). Persisting T rather than a hardwired Vec leaves room for a future versioned envelope without changing this IO layer.

Implementations

impl<T> SystemSidecar<T>

pub fn new(data_path: impl AsRef<Path>, file_name: &str) -> Self

Construct a sidecar rooted at <data_path>/_system/<file_name>.

file_name must match the on-disk name the subsystem has always used — changing it would orphan existing state across an upgrade.

pub fn at_path(path: impl Into<PathBuf>) -> Self

Construct a sidecar at an exact path, bypassing the _system/ convention.

For callers that already own the full target path (e.g. an embedder that supplies it directly) and must keep that exact location for on-disk compatibility.

pub fn path(&self) -> &Path

Borrow the resolved sidecar path (for diagnostics).

pub fn load(&self) -> Result<T, SidecarIoError>

where T: DeserializeOwned + Default,

Load the persisted document, or T::default() if absent or empty.

A missing file and a zero-byte file both mean “nothing persisted yet” and yield the default — first-boot callers rely on this.

Errors

Returns SidecarIoError::Read on IO failure or SidecarIoError::Decode when the file is present but not valid JSON.

pub fn store(&self, value: &T) -> Result<(), SidecarIoError>

where T: Serialize,

Atomically replace the persisted document with value.

Writes a temp file, fsyncs it, renames it over the target, then fsyncs the parent directory so the rename itself is crash-durable.

Errors

Returns SidecarIoError::Encode if serialization fails, SidecarIoError::CreateDir if the _system/ directory cannot be created, or SidecarIoError::Write on any write / fsync / rename failure.

pub fn store_value<S>(&self, value: &S) -> Result<(), SidecarIoError>

where S: Serialize + ?Sized,

Atomically replace the persisted document with any value that serializes to the same JSON as T.

Identical to Self::store but accepts a borrowed view (e.g. a &[Row] for a SystemSidecar<Vec<Row>>) so callers that already own a slice can persist it without cloning into an owned T first. S must serialize to the same shape T deserializes from — the caller guarantees this.

Errors

Same as Self::store.

Trait Implementations

impl<T> Clone for SystemSidecar<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for SystemSidecar<T>

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

Formats the value using the given formatter.