ClawdDotNet/src/ClawdDotNet.Manager/InstanceState.cs

using System.Text.Json;
using System.Text.Json.Serialization;
using ClawdDotNet.Core.Storage;

namespace ClawdDotNet.Manager;

/// <summary>
/// Was der Manager über einen laufenden Instanzprozess auf die Platte schreibt.
///
/// <para><b>Warum es diese Datei gibt (E-M6).</b> Fällt der Manager aus, laufen die
/// Instanzen weiter — er darf nicht der Einzelpunkt sein, gegen den dieses ganze Vorhaben
/// gebaut wird. Der neu gestartete Manager muss sie also wiederfinden, und zwar ohne
/// Datenbank: Alles, was er dafür braucht, liegt als JSON im Instanzverzeichnis.</para>
///
/// <para><b>Die Prozesskennung allein taugt dafür nicht.</b> Nach einem Neustart der
/// Maschine ist 4711 mit einiger Wahrscheinlichkeit irgendein anderer Prozess — und den
/// dann für die eigene Instanz zu halten, wäre schlimmer als sie gar nicht zu finden. Der
/// verlässliche Beweis ist der Socket: Antwortet er mit derselben Instanzkennung, ist es
/// dieselbe Instanz. Deshalb steht sie hier mit drin. <see cref="StartedAt"/> und
/// <see cref="ProcessId"/> sind das Zweitmerkmal — sie sagen, welchen Prozess man
/// anfassen muss, sobald die Identität feststeht.</para>
/// </summary>
public sealed class InstanceState
{
    /// <summary>Der Dateiname im Instanzverzeichnis.</summary>
    public const string FileName = "instance-state.json";

    [JsonPropertyName("instanceId")]
    public string InstanceId { get; set; } = "";

    [JsonPropertyName("instanceName")]
    public string InstanceName { get; set; } = "";

    [JsonPropertyName("processId")]
    public int ProcessId { get; set; }

    /// <summary>
    /// Startzeit des Prozesses, nicht der Instanz.
    ///
    /// <para>Zusammen mit <see cref="ProcessId"/> ergibt sie ein Paar, das eine
    /// wiederverwendete Kennung entlarvt: Ein Prozess, der später gestartet wurde als
    /// hier steht, ist nicht der, den wir gestartet haben.</para>
    /// </summary>
    [JsonPropertyName("startedAt")]
    public DateTimeOffset StartedAt { get; set; }

    /// <summary>Socket oder Named Pipe — wie man mit dieser Instanz spricht.</summary>
    [JsonPropertyName("endpoint")]
    public string Endpoint { get; set; } = "";

    /// <summary>Welcher Managerprozess sie gestartet hat. Nur zur Diagnose.</summary>
    [JsonPropertyName("managerProcessId")]
    public int ManagerProcessId { get; set; }
}

/// <summary>
/// Liest und schreibt die Zustandsdatei einer Instanz.
///
/// <para>Bewusst nachsichtig beim Lesen: Eine kaputte oder halb geschriebene Datei heißt
/// „ich weiß nichts über diese Instanz" und nicht „Ausnahme". Der Manager kann damit
/// umgehen — er fragt dann eben den Socket, und wenn der schweigt, läuft sie nicht.
/// Geschrieben wird über <see cref="AtomicFile"/>, damit ein Absturz mitten im Schreiben
/// keine halbe Datei hinterlässt.</para>
/// </summary>
public static class InstanceStateStore
{
    private static readonly JsonSerializerOptions JsonOpts = new()
    {
        WriteIndented = true,
        PropertyNameCaseInsensitive = true
    };

    public static string PathFor(string instanceDirectory)
        => Path.Combine(Path.GetFullPath(instanceDirectory), InstanceState.FileName);

    /// <summary>Der hinterlegte Zustand, oder <c>null</c>: keine Datei, keine lesbare.</summary>
    public static InstanceState? Read(string instanceDirectory)
    {
        var path = PathFor(instanceDirectory);

        try
        {
            if (!File.Exists(path)) return null;

            return JsonSerializer.Deserialize<InstanceState>(
                AtomicFile.ReadAllText(path), JsonOpts);
        }
        catch (Exception ex) when (ex is JsonException or IOException or UnauthorizedAccessException)
        {
            return null;
        }
    }

    public static void Write(string instanceDirectory, InstanceState state)
        => AtomicFile.WriteAllText(
            PathFor(instanceDirectory), JsonSerializer.Serialize(state, JsonOpts));

    /// <summary>
    /// Räumt die Zustandsdatei weg — nach einem geordneten Ende und nachdem festgestellt
    /// wurde, dass ein Eintrag ins Leere zeigt.
    ///
    /// <para>Eine liegengebliebene Datei ist kein Drama: Der Manager prüft ohnehin den
    /// Socket, bevor er ihr glaubt. Sie wegzuräumen erspart aber die Frage, warum eine
    /// Instanz „laut Datei läuft" und trotzdem nicht antwortet.</para>
    /// </summary>
    public static void Clear(string instanceDirectory)
    {
        try
        {
            var path = PathFor(instanceDirectory);
            if (File.Exists(path)) File.Delete(path);
        }
        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
        {
            // Nicht der Rede wert - siehe oben.
        }
    }
}