From 03f4c2bd0abe0dd5a861e28c2041d4bcdf419b78 Mon Sep 17 00:00:00 2001
From: Isaiah Clifford Opoku <opokuisaiahclifford123@gmail.com>
Date: Thu, 21 May 2026 22:46:39 +0000
Subject: [PATCH] Add JsonSnapshotStateStore for durable state persistence

Introduce JsonSnapshotStateStore implementing IStateStore to
persist state to a JSON file on disk. The class uses an in-memory
ConcurrentDictionary for fast access and ensures state survives
process restarts by saving changes to a snapshot file. The default
file path is %TEMP%/azlocal/state.json, configurable via
AzLocal:SnapshotPath.

Implemented methods include GetAsync, SetAsync, DeleteAsync,
ListAsync, and ExistsAsync, with thread-safe file writes ensured
via SemaphoreSlim. Added private helpers for loading and saving
state. Includes XML documentation for clarity.
---
 src/AzLocal.State/JsonSnapshotStateStore.cs | 91 ++++++++++++++++++++-
 1 file changed, 89 insertions(+), 2 deletions(-)

diff --git a/src/AzLocal.State/JsonSnapshotStateStore.cs b/src/AzLocal.State/JsonSnapshotStateStore.cs
index 71dfcce..dd2f758 100644
--- a/src/AzLocal.State/JsonSnapshotStateStore.cs
+++ b/src/AzLocal.State/JsonSnapshotStateStore.cs
@@ -1,5 +1,92 @@
-namespace AzLocal.State;
+using AzLocal.Core.Interfaces;
+using Microsoft.Extensions.Configuration;
+using System.Collections.Concurrent;
+using System.Text.Json;
 
-public class JsonSnapshotStateStore
+namespace AzLocal.State;
+
+/// <summary>
+/// Same in-memory dictionary as <see cref="InMemoryStateStore"/>, but every write is also
+/// persisted to a JSON file on disk. State survives process restarts.
+/// Snapshot file defaults to <c>%TEMP%/azlocal/state.json</c> unless overridden via
+/// <c>AzLocal:SnapshotPath</c> in configuration.
+/// </summary>
+public class JsonSnapshotStateStore : IStateStore
 {
+    private readonly string _filePath;
+
+    // Limits concurrent file writes to one at a time so the snapshot is never half-written.
+    private readonly SemaphoreSlim _lock = new(1, 1);
+    private readonly ConcurrentDictionary<string, string> _store;
+
+    public JsonSnapshotStateStore(IConfiguration config)
+    {
+        var dir = config["AzLocal:SnapshotPath"]
+            ?? Path.Combine(Path.GetTempPath(), "azlocal");
+        Directory.CreateDirectory(dir);
+        _filePath = Path.Combine(dir, "state.json");
+        _store = Load();
+    }
+
+    /// <summary>Returns the entry deserialized as <typeparamref name="T"/>, or null if the key does not exist.</summary>
+    public Task<T?> GetAsync<T>(string key)
+    {
+        if (_store.TryGetValue(key, out var json))
+            return Task.FromResult(JsonSerializer.Deserialize<T>(json));
+        return Task.FromResult<T?>(default);
+    }
+
+    /// <summary>Serializes <paramref name="value"/> to JSON, stores it in memory, and flushes the snapshot to disk.</summary>
+    public async Task SetAsync<T>(string key, T value)
+    {
+        _store[key] = JsonSerializer.Serialize(value);
+        await SaveAsync();
+    }
+
+    /// <summary>Removes the entry with the given key and flushes the snapshot to disk. No-ops if the key does not exist.</summary>
+    public async Task DeleteAsync(string key)
+    {
+        _store.TryRemove(key, out _);
+        await SaveAsync();
+    }
+
+    /// <summary>Returns all entries whose keys start with <paramref name="prefix"/>, deserialized as <typeparamref name="T"/>.</summary>
+    public Task<IReadOnlyList<T>> ListAsync<T>(string prefix)
+    {
+        var results = _store
+            .Where(kv => kv.Key.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            .Select(kv => JsonSerializer.Deserialize<T>(kv.Value)!)
+            .ToList();
+        return Task.FromResult<IReadOnlyList<T>>(results);
+    }
+
+    /// <summary>Returns true if an entry with the given key exists.</summary>
+    public Task<bool> ExistsAsync(string key) =>
+        Task.FromResult(_store.ContainsKey(key));
+
+    #region private helpers
+
+    // Reads the snapshot file on startup. Returns an empty dictionary if the file does not exist yet.
+    private ConcurrentDictionary<string, string> Load()
+    {
+        if (!File.Exists(_filePath))
+            return new ConcurrentDictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        var json = File.ReadAllText(_filePath);
+        var dict = JsonSerializer.Deserialize<Dictionary<string, string>>(json) ?? new();
+        return new ConcurrentDictionary<string, string>(dict, StringComparer.OrdinalIgnoreCase);
+    }
+
+    // Writes the full dictionary to disk under the semaphore so concurrent writes don't race.
+    private async Task SaveAsync()
+    {
+        await _lock.WaitAsync();
+        try
+        {
+            await File.WriteAllTextAsync(_filePath,
+                JsonSerializer.Serialize(new Dictionary<string, string>(_store)));
+        }
+        finally { _lock.Release(); }
+    }
+
+    #endregion
 }