Reference v0.16 state machine refactoring

v0.16: State Machine Refactoring (Planned)

Ziel

Vereinfachung der Deployment-Zustandsmaschine durch klare Trennung von:

• DeploymentStatus - Lebenszyklus des Deployments
• OperationMode - Laufzeitzustand (nur für Running Deployments)

Aktueller Zustand (v0.15)

DeploymentStatus (enum)

• Pending - Deployment initialisiert
• Running - Deployment läuft
• Stopped - Container gestoppt
• Failed - Terminal
• Removed - Terminal

OperationMode (value object)

• Normal - Normalbetrieb
• Migrating - Upgrade läuft
• Maintenance - Geplante Wartung
• Stopped - Gestoppt (redundant mit DeploymentStatus)
• Failed - Fehlgeschlagen (redundant)

Probleme

• Überlappung zwischen DeploymentStatus und OperationMode (Stopped, Failed)
• Unklar wann welcher Status verwendet wird
• Deployment wird erst am ENDE erstellt (nicht sichtbar während Installation)
• OperationMode.Migrating ist eigentlich ein Deployment-Lifecycle-Status

Neuer Zustand (v0.16)

DeploymentStatus (enum)

public enum DeploymentStatus
{
    Installing = 0,  // Neue Installation läuft
    Upgrading = 1,   // Upgrade/Rollback läuft
    Running = 2,     // Betriebsbereit
    Failed = 3,      // Letzte Operation fehlgeschlagen
    Removed = 4      // Gelöscht (terminal)
}

OperationMode (value object) - vereinfacht

// Nur gültig wenn DeploymentStatus == Running
public sealed class OperationMode
{
    public static readonly OperationMode Normal = new(0, "Normal");
    public static readonly OperationMode Maintenance = new(1, "Maintenance");
}

Design-Entscheidungen

1. Installing vs Upgrading getrennt - Ja, weil:

   • UI zeigt unterschiedliche Informationen
   • Rollback nur nach fehlgeschlagenem Upgrade sinnvoll
   • Unterschiedliche Phasen/Progress-Messages

2. Upgrade ist KEINE Maintenance - Unterschiedlicher Intent:

   • Maintenance = "Stack pausiert, wird später fortgesetzt"
   • Upgrade = "Stack wird aktiv transformiert zu neuer Version"

3. OperationMode nur bei Running - Klare Trennung:

   • DeploymentStatus = Lifecycle (was passiert gerade?)
   • OperationMode = Runtime (wie verhält sich der laufende Stack?)

4. Vorbereitung für Bounded Context Trennung:

   • Deployment BC (Installation/Upgrade/Rollback/Remove)
   • Operations BC (Health Monitoring, Maintenance Mode)

Zustandsübergänge

DeploymentStatus:

┌─────────────┐
│ Installing  │───success───►┌─────────┐
└─────────────┘              │ Running │◄──────┐
       │                     └─────────┘       │
       │ fail                    │   ▲         │
       ▼                upgrade/ │   │ success │
┌─────────────┐          rollback│   │         │
│   Failed    │◄─────────────────┘   │         │
└─────────────┘                      │         │
       │                     ┌───────────┐     │
       │ retry/rollback      │ Upgrading │─────┘
       └────────────────────►└───────────┘
                                   │
                                   │ fail
                                   ▼
                             ┌─────────┐
                             │ Failed  │
                             └─────────┘

Weitere Übergänge:
- Running → Removed (Deinstallation)
- Failed → Removed (Cleanup)

OperationMode (nur bei DeploymentStatus.Running):
- Normal ◄──► Maintenance

Implementierungsplan

Phase 1: Domain Model

1. DeploymentStatus.cs aktualisieren

   • Entfernen: Pending, Stopped
   • Hinzufügen: Installing, Upgrading

2. OperationMode.cs vereinfachen

   • Behalten: Normal, Maintenance
   • Entfernen: Migrating, Stopped, Failed
   • Validierung: OperationMode nur wenn Status == Running

3. Deployment.cs refactoren

   • Factory: StartInstallation() und StartUpgrade()
   • Deployment wird am START erstellt (sofort sichtbar in UI)
   • Neue Transitionen implementieren

Phase 2: Application Layer

4. DeploymentService.cs

   • Deployment am START erstellen
   • Installing bei neuer Installation
   • Upgrading bei Upgrade/Rollback
   • Bei Erfolg: MarkAsRunning()
   • Bei Fehler: MarkAsFailed()

5. ChangeOperationModeHandler.cs

   • Nur Normal ↔ Maintenance Übergänge
   • Validierung: Status muss Running sein

6. Health-Related Code

   • HealthSnapshot.cs anpassen
   • HealthSnapshotMapper.cs anpassen
   • MaintenanceObserverService.cs prüfen

Phase 3: API & Infrastructure

7. API Endpoints & DTOs

   • Response-Typen aktualisieren

8. EF Core Migration

   • Schema-Änderungen (keine Datenmigration nötig, pre-v1)

Phase 4: Tests

9. Unit Tests aktualisieren

   • DeploymentTests
   • OperationModeTests
   • Handler-Tests

10. Integration Tests aktualisieren

    • Deployment-Endpoints
    • Health-Endpoints

Abhängigkeiten

• v0.15 Rollback-Feature muss abgeschlossen sein