Struct JsonFileStore 

pub struct JsonFileStore { /* private fields */ }

JSON-file-backed state store.

Each namespace is a single JSON file at {root}/{namespace}.json. Writes are atomic: the new state is written to a .tmp sibling and then renamed.

The root directory is provided at construction time; callers are expected to resolve it from the service-layer AppDir abstraction (typically ~/.algocline/state/).

Concurrency

Per-namespace locks (std::sync::Mutex) prevent lost updates under concurrent alc.state.* calls within the same process. The lock is acquired for the full load → mutate → atomic-rename cycle, so two tokio tasks operating on the same namespace are serialised.

Rationale for std::sync::Mutex over tokio::sync::Mutex: all I/O inside the lock uses std::fs (synchronous, no .await), so a standard mutex is sufficient and avoids holding a tokio mutex across potential scheduler context switches.

Multi-process safety is NOT provided. If multiple alc processes share the same state directory (uncommon), use a backend with native INCR (Redis) or transactions (SQLite).

Implementations

impl JsonFileStore

pub fn new(root: PathBuf) -> Self

Construct a store rooted at an explicit path.

The directory is not created eagerly; it is created lazily on the first set / set_nx / incr call via Self::state_path.

pub fn root(&self) -> &Path

Return the root directory this store writes under.

pub fn state_path(&self, ns: &str) -> Result<PathBuf, String>

Resolve the JSON file path for a namespace, validating the name and creating the root directory on demand.

pub fn list_dispatched( &self, namespace: &str, ) -> Result<Vec<String>, StateError>

List all keys in the dispatched layout for a namespace.

Enumerates {root}/{namespace}/*.json and returns the file names stripped of the .json extension, sorted lexicographically. Files with extensions other than .json, and .bak / .tmp siblings, are excluded. If the namespace directory does not exist the result is an empty Vec (namespace-absent ≡ zero keys).

Arguments

• namespace — the directory name under root; must pass [is_safe_segment] validation

Returns

A sorted list of key strings, or a StateError on I/O / validation failure.

Errors

• StateError::UnsafeSegment if namespace fails path-safety check
• StateError::IoRead if reading the directory fails

pub fn show_dispatched( &self, namespace: &str, key: &str, ) -> Result<Value, StateError>

Read the full JSON value for a dispatched-layout key.

Reads {root}/{namespace}/{key}.json and deserializes it.

Arguments

• namespace — the subdirectory name; must pass [is_safe_segment]
• key — the file stem; must pass [is_safe_segment]

Returns

The deserialized serde_json::Value on success.

Errors

• StateError::UnsafeSegment if either segment fails path-safety check
• StateError::KeyNotFound if the file does not exist
• StateError::IoRead if the file cannot be read
• StateError::Serde if the content is not valid JSON

pub fn reset_dispatched_with_backup( &self, namespace: &str, key: &str, steps: &[String], fields: &[String], ) -> Result<ResetReport, StateError>

Atomically reset a dispatched-layout state file with a backup.

Performs the following sequence in order (Crux atomicity contract):

1. Validate namespace and key with [is_safe_segment].
2. Compute target path: {root}/{namespace}/{key}.json.
3. Return StateError::KeyNotFound if the file does not exist.
4. Acquire the per-path mutex via Self::ns_lock; hold until rename.
5. Copy the live file to {root}/{namespace}/{key}.json.bak — the live file is not touched before this point.
6. Load and parse the live file.
7. Apply in-memory mutations:
   • Remove each element of steps from data.completed_steps (if the array exists).
   • Delete each element of fields from the data top-level object.
   • If the top-level data field is absent or not an object, return StateError::ShapeInvalid.
8. Write the mutated value to {target}.tmp.
9. Rename .tmp → target (POSIX atomic on same filesystem).

A crash between steps 5 and 9 leaves the .bak intact and the live file unmodified (or only partially written to .tmp), so the original state is always recoverable.

Arguments

• namespace — subdirectory name; must pass [is_safe_segment]
• key — file stem; must pass [is_safe_segment]
• steps — step names to remove from data.completed_steps
• fields — field names to delete from the data top-level object

Returns

A ResetReport with the backup path and counts of removed items.

Errors

• StateError::UnsafeSegment if either segment fails path-safety check
• StateError::KeyNotFound if the file does not exist
• StateError::ShapeInvalid if the lock is poisoned or the JSON structure is not a {data: {...}} object
• StateError::IoBackup if the .bak copy fails
• StateError::IoRead if loading the live file fails
• StateError::IoWrite if the .tmp write or rename fails
• StateError::Serde if the file content is not valid JSON

Trait Implementations

impl StateStore for JsonFileStore

fn get(&self, ns: &str, key: &str) -> Result<Option<Value>, String>

Read a value. Returns None if the key does not exist.

fn set(&self, ns: &str, key: &str, value: Value) -> Result<(), String>

Write a value (upsert).

fn delete(&self, ns: &str, key: &str) -> Result<bool, String>

Remove a key. Returns true if it existed.

fn keys(&self, ns: &str) -> Result<Vec<String>, String>

List all keys in a namespace.

fn has(&self, ns: &str, key: &str) -> Result<bool, String>

Check whether a key exists.

fn set_nx(&self, ns: &str, key: &str, value: Value) -> Result<bool, String>

Set a value only if the key does not already exist. Returns true if the value was written, false if the key was already present.

fn incr( &self, ns: &str, key: &str, delta: f64, default: f64, ) -> Result<f64, String>

Counter increment, serialised per namespace within the same process.