Added the BeyondFacts Lab as a prototype (#1175)

app/MindWork AI Studio/Assistants/BeyondFactsLab/BeyondFactsLabStore.cs

@@ -0,0 +1,189 @@
+using System.Collections.Concurrent;
+using System.Text;
+using System.Text.Json;
+
+using AIStudio.Settings;
+
+namespace AIStudio.Assistants.BeyondFactsLab;
+
+/// <summary>
+/// Stores the preparations of the BeyondFacts Lab as files below the data directory.
+/// </summary>
+/// <remarks>
+/// Each preparation lives in a folder named by its ID. The store keeps no paths: it derives every path from
+/// IDs, so a backup works on another computer as well. It writes each file atomically, guards each preparation
+/// with a lock of its own, and never deletes anything on its own; only the person deletes a preparation.
+/// </remarks>
+/// <param name="logger">The logger.</param>
+/// <param name="storageOptions">Overrides the data directory, for tests.</param>
+public sealed partial class BeyondFactsLabStore(ILogger<BeyondFactsLabStore> logger, BflStorageOptions? storageOptions = null)
+{
+    /// <summary>
+    /// The name of the folder below the data directory.
+    /// </summary>
+    public const string ROOT_DIRECTORY_NAME = "beyondFactsLab";
+
+    /// <summary>
+    /// The longest name of a preparation the store keeps.
+    /// </summary>
+    public const int MAX_NAME_LENGTH = 200;
+
+    /// <summary>
+    /// The file of a preparation which holds its name and dates.
+    /// </summary>
+    private const string PROJECT_FILE_NAME = "project.json";
+
+    /// <summary>
+    /// The file which holds the preparation selected last.
+    /// </summary>
+    private const string SELECTION_FILE_NAME = "selection.json";
+
+    /// <summary>
+    /// The JSON options of all files of the lab.
+    /// </summary>
+    private static readonly JsonSerializerOptions JSON_OPTIONS = BeyondFactsLabJson.PERSISTENCE;
+
+    /// <summary>
+    /// The lock of each preparation.
+    /// </summary>
+    private readonly ConcurrentDictionary<Guid, SemaphoreSlim> projectLocks = [];
+
+    /// <summary>
+    /// Serializes the first start of the store.
+    /// </summary>
+    private readonly SemaphoreSlim initializationLock = new(1, 1);
+
+    /// <summary>
+    /// Serializes writing the selection.
+    /// </summary>
+    private readonly SemaphoreSlim selectionLock = new(1, 1);
+
+    /// <summary>
+    /// Whether the store cleaned up and read the selection already.
+    /// </summary>
+    private bool initialized;
+
+    /// <summary>
+    /// Gets the folder of the lab below the data directory.
+    /// </summary>
+    private string RootDirectory => Path.Combine(
+        storageOptions?.DataDirectory ??
+        SettingsManager.DataDirectory ??
+        throw new InvalidOperationException("The AI Studio data directory is not initialized."),
+        ROOT_DIRECTORY_NAME);
+
+    /// <summary>
+    /// Writes a text file so that readers see either the old or the new content, never a part of it.
+    /// </summary>
+    /// <param name="targetPath">The file to write.</param>
+    /// <param name="content">The new content.</param>
+    /// <param name="token">The cancellation token.</param>
+    private static async Task WriteTextAtomicAsync(string targetPath, string content, CancellationToken token)
+    {
+        Directory.CreateDirectory(Path.GetDirectoryName(targetPath)!);
+        var temporaryPath = $"{targetPath}.tmp-{Guid.NewGuid():N}";
+        try
+        {
+            await File.WriteAllTextAsync(temporaryPath, content, new UTF8Encoding(false), token);
+            await using (var stream = new FileStream(temporaryPath, FileMode.Open, FileAccess.ReadWrite, FileShare.None, 4_096, true))
+                await stream.FlushAsync(token);
+
+            File.Move(temporaryPath, targetPath, overwrite: true);
+        }
+        finally
+        {
+            TryDeleteFile(temporaryPath);
+        }
+    }
+
+    /// <summary>
+    /// Deletes a file when it exists, without failing.
+    /// </summary>
+    /// <param name="path">The file to delete.</param>
+    private static void TryDeleteFile(string path)
+    {
+        try
+        {
+            if (File.Exists(path))
+                File.Delete(path);
+        }
+        catch (Exception exception) when (exception is IOException or UnauthorizedAccessException)
+        {
+            // Cleaning up a temporary file is best effort; the next start tries again.
+        }
+    }
+
+    /// <summary>
+    /// Removes control characters from a name, trims it, and cuts it to the longest name the store keeps.
+    /// </summary>
+    /// <param name="name">The name as entered or as read from a file.</param>
+    /// <returns>The cleaned name, empty when nothing remains.</returns>
+    internal static string SanitizeName(string? name)
+    {
+        if (string.IsNullOrWhiteSpace(name))
+            return string.Empty;
+
+        var sanitized = new string(name.Where(character => !char.IsControl(character)).ToArray()).Trim();
+        return sanitized.Length <= MAX_NAME_LENGTH ? sanitized : sanitized[..MAX_NAME_LENGTH].TrimEnd();
+    }
+
+    /// <summary>
+    /// Gets the lock of a preparation.
+    /// </summary>
+    /// <param name="projectId">The ID of the preparation.</param>
+    private SemaphoreSlim GetLock(Guid projectId) => this.projectLocks.GetOrAdd(projectId, _ => new(1, 1));
+
+    /// <summary>
+    /// Drops the lock of a preparation which does not exist anymore.
+    /// </summary>
+    /// <remarks>
+    /// The semaphore is not disposed: another operation might still wait on it.
+    /// </remarks>
+    /// <param name="projectId">The ID of the preparation.</param>
+    private void ForgetLock(Guid projectId) => this.projectLocks.TryRemove(projectId, out _);
+
+    /// <summary>
+    /// Gets the folder of a preparation.
+    /// </summary>
+    /// <param name="projectId">The ID of the preparation.</param>
+    private string ProjectDirectory(Guid projectId) => Path.Combine(this.RootDirectory, projectId.ToString("D"));
+
+    /// <summary>
+    /// Gets the file which holds the name and the dates of a preparation.
+    /// </summary>
+    /// <param name="projectId">The ID of the preparation.</param>
+    private string ProjectPath(Guid projectId) => Path.Combine(this.ProjectDirectory(projectId), PROJECT_FILE_NAME);
+
+    /// <summary>
+    /// Gets the file which holds the preparation selected last.
+    /// </summary>
+    private string SelectionPath() => Path.Combine(this.RootDirectory, SELECTION_FILE_NAME);
+
+    /// <summary>
+    /// Creates the folder of the lab, removes temporary files a crash left behind, and reads the selection.
+    /// </summary>
+    /// <param name="token">The cancellation token.</param>
+    private async Task InitializeAsync(CancellationToken token)
+    {
+        if (this.initialized)
+            return;
+
+        await this.initializationLock.WaitAsync(token);
+        try
+        {
+            if (this.initialized)
+                return;
+
+            Directory.CreateDirectory(this.RootDirectory);
+            foreach (var temporaryPath in Directory.EnumerateFiles(this.RootDirectory, "*.tmp-*", SearchOption.AllDirectories))
+                TryDeleteFile(temporaryPath);
+
+            await this.LoadSelectionAsync(token);
+            this.initialized = true;
+        }
+        finally
+        {
+            this.initializationLock.Release();
+        }
+    }
+}