XState-Persistenz nach fünf Jahren: So löst StateKeep das Problem

Die Idee klingt simpel: Ein Zustandssystem wie XState sollte Zustände zwischen Server-Neustarts speichern können. Doch was in Theorie einfach erscheint, entpuppt sich in der Praxis als komplexe Herausforderung. Bereits 2019 wurde im offiziellen XState-Repository eine Frage gestellt, die bis heute ungelöst bleibt: Wie persistiert man den Zustand eines XState-Aktors zwischen Server-Neustarts? Die Antwort des Kernteams war ehrlich, aber unbefriedigend: XState selbst bietet keine native Persistenz. Entwickler müssten den Zustand manuell serialisieren, speichern und bei Bedarf wiederherstellen. Diese Lösung mag für kleine Projekte funktionieren, doch für skalierbare Anwendungen mit tausenden laufenden Prozessen wird sie schnell zum Albtraum.

Warum selbstgebaute Lösungen scheitern

Die manuelle Persistenz von XState-Zuständen scheint auf den ersten Blick trivial. Ein Entwickler könnte etwa den Befehl actor.getSnapshot() nutzen, den Zustand als JSON serialisieren und in Redis oder PostgreSQL speichern. Bei einem Neustart würde der Zustand dann rehydriert. Doch genau hier beginnen die Probleme. XState v5 brachte 2023 ein neues Snapshot-Format mit, das ältere Versionen inkompatibel machte. Teams, die ihre Zustände in der alten Version gespeichert hatten, standen plötzlich vor einem Datenverlust oder korrumpierten Kontexten. Der Grund: Das Snapshot-Format war nie als öffentliche API gedacht. Als Bibliothek ist XState nicht für die Nutzung seiner Ausgaben verantwortlich — ein klassisches Infrastrukturproblem.

Doch die Herausforderungen gehen tiefer. Selbst wenn das Format stabil bleibt, stoßen Entwickler auf ein weiteres Hindernis: Migrationen. Stellen Sie sich vor, Ihr Bestellsystem nutzt einen XState-basierten Workflow mit 40.000 aktiven Aufträgen. Ihr Team beschließt, einen zusätzlichen Qualitätssicherungsschritt einzuführen. Sie schreiben ein Migrationsskript, testen es in der Staging-Umgebung und starten es um Mitternacht in Produktion. Plötzlich stellen Sie fest, dass 847 Aufträge in einem Edge-Zustand feststecken, den Sie nicht berücksichtigt haben. Drei Stunden später ist das Problem behoben — aber die manuelle Nacharbeit hätte vermieden werden können. Dies ist kein Problem von XState oder mangelnder Kompetenz der Entwickler. Es ist ein strukturelles Defizit: Es fehlt eine Schicht, die zwischen der XState-Bibliothek und der Anwendungsebene vermittelt und Verantwortung für die Konsistenz der Zustände über Codeänderungen hinweg übernimmt.

Stately Cloud: Eine Teillösung mit Grenzen

Stately hat dieses Problem erkannt und mit Stately Cloud eine gehostete Lösung entwickelt. Die Plattform persistiert XState-Aktoren, hält sie zwischen Neustarts am Leben und bietet eine API für das Senden von Events sowie das Abfragen von Zuständen. Für kleine Projekte oder Teams, die in JavaScript arbeiten und bereit sind, ihre Daten in der Cloud zu hosten, mag dies eine valide Option sein. Doch für viele Unternehmen ist Stately Cloud keine Lösung:

• Datenhoheit: In Branchen wie Finanzen, Gesundheitswesen oder Versicherungen unterliegen Kundendaten strengen Compliance-Vorgaben. Die Speicherung dieser Daten auf externen Servern ist oft nicht zulässig. Stately Cloud bietet keine Self-Hosting-Option.

• Sprachabhängigkeit: Stately Cloud erfordert die Nutzung von XState in TypeScript. Teams, deren Backend in Python, Go oder Java läuft, sind ausgeschlossen.

• Migrationen ohne Unterstützung: Selbst bei Stately Cloud müssen Entwickler selbst entscheiden, welche der 40.000 laufenden Aktoren auf die neue Version migriert werden sollen. Die Plattform bietet keine automatisierte Logik, um komplexe Migrationen basierend auf der Ereignishistorie zu steuern.

Das Migration-Problem: Warum es komplexer ist als gedacht

Betrachten wir ein scheinbar einfaches Szenario, das jedoch jedes Migrationswerkzeug vor unlösbare Probleme stellt. Nehmen wir ein Kreditantrags-Workflow mit 50.000 aktiven Anträgen. Ihr Team muss einen zusätzlichen Compliance-Check-Schritt einführen — allerdings nur für Anträge, die den kostenpflichtigen Verifizierungsweg durchlaufen haben. Rechtlich ist dies erforderlich, um regulatorische Vorgaben zu erfüllen. Ihr Datenbank enthält 50.000 Aktoren, einige haben die Verifizierungsgebühr bezahlt, andere wurden davon befreit. Beide Gruppen befinden sich aktuell im Zustand awaiting_documents und sehen aus der Perspektive einer Abfrage nach dem aktuellen Zustand identisch aus. Jedes Migrationssystem, das sich ausschließlich am aktuellen Zustand orientiert, würde beide Gruppen gleich behandeln — was falsch wäre.

Der korrekte Ansatz erfordert einen Blick in die Ereignishistorie jedes Aktors. Ein Aktor, der das Event PAY_FEE verarbeitet hat, gehört in den neuen Compliance-Check-Workflow. Ein Aktor, der WAIVE_FEE verarbeitet hat, nicht. Die einzige Möglichkeit, die Zugehörigkeit zu bestimmen, liegt in der Analyse der bereits verarbeiteten Events. Genau dieses Problem adressiert StateKeep mit einem innovativen Ansatz.

StateKeep: Eine selbstgehostete Lösung für XState

StateKeep ist eine selbstgehostete Plattform, die XState-kompatible Zustandsmaschinen hostet und Migrationen auf Basis der Ereignishistorie steuert. Die Lösung funktioniert in jeder Backend-Sprache — von Python über Go bis hin zu Java oder Node.js — solange diese über einen HTTP-Client verfügt. Der Workflow gestaltet sich wie folgt:

• Bereitstellung: Ein Entwickler lädt eine XState-kompatible JSON-Definition über eine HTTP-Schnittstelle hoch.
• Aktor-Spawnen: Die Plattform startet neue Aktoren basierend auf der Definition.
• Migrationen: Bei einer neuen Version des Workflows gibt der Entwickler einen historyPath an, der definiert, welche Ereignissequenz zu einer Migration führt.

Ein Beispiel für eine Migration könnte wie folgt aussehen:

{
  "id": "loan-v2",
  "parentId": "loan-v1",
  "historyPath": ["SUBMIT_INFO", "PAY_FEE"],
  "definition": { 
    // Neue Zustandsdefinition
  }
}

StateKeep analysiert jeden Aktor und berechnet eine Art Fingerabdruck seiner Ereignishistorie — einen rollierenden Hash-Wert (FNV-1a), der die Abfolge aller verarbeiteten Event-Typen erfasst. Aktoren, deren Historie dem deklarierten Pfad entspricht, werden migriert. Andere bleiben auf der aktuellen Version. Alice hat die Verifizierungsgebühr bezahlt. Ihre Historie stimmt mit dem Pfad überein, daher wird sie in den neuen loan-v2-Workflow migriert, der einen zusätzlichen Einkommensverifizierungsschritt vor der Genehmigung vorsieht. Bob hat die Gebühr erlassen bekommen. Seine Historie passt nicht zum Pfad, daher bleibt er im alten Workflow. Beide Aktoren laufen weiter, ohne Neustart und ohne Verlust des Kontexts. Kein manuelles Migrationsskript. Keine nächtliche Anspannung.

Die Technologie hinter StateKeep basiert auf einem formalen mathematischen Beweis, der garantiert, dass jeder Aktor genau auf die richtige Version migriert wird — ohne dass ein Aktor doppelt evaluiert wird, unabhängig von der Reihenfolge oder Timing der Auswertung. Der Algorithmus läuft in nativem C mit einer durchschnittlichen Laufzeit von 1,26 Mikrosekunden pro Aktor. Für 50.000 Aktoren bedeutet das weniger als eine Sekunde Verarbeitungszeit auf Standard-Hardware.

Praktische Umsetzung mit StateKeep

Die Integration von StateKeep in eine bestehende Anwendung ist denkbar einfach. Hier ein Beispiel in TypeScript:

import { createClient } from '@statekeep/sdk';

const sk = createClient({
  baseUrl: '
  apiKey: 'sk_...'
});

// Bereitstellung einer Zustandsmaschine
await sk.deploy('loan-v1', {
  id: 'loan',
  initial: 'submitted',
  states: {
    submitted: {
      on: {
        SUBMIT_INFO: 'under_review'
      }
    },
    under_review: {
      on: {
        PAY_FEE: 'awaiting_documents',
        WAIVE_FEE: 'awaiting_documents'
      }
    },
    awaiting_documents: {
      // ... weitere Zustände
    }
  }
});

// Senden eines Events an einen Aktor
await sk.sendEvent('loan-123', 'PAY_FEE');

// Abfragen des aktuellen Zustands
const state = await sk.getState('loan-123');

StateKeep eliminiert nicht nur die Notwendigkeit, eigene Persistenzschichten zu entwickeln. Es bietet auch eine robuste Lösung für Migrationen, die auf der Ereignishistorie basiert und keine manuelle Nacharbeit erfordert. Für Teams, die Wert auf Datenhoheit, Sprachunabhängigkeit und zuverlässige Migrationen legen, ist StateKeep eine überzeugende Alternative zu bestehenden Lösungen. Die Zukunft der zustandsbasierten Anwendungen liegt nicht in der manuellen Arbeit der Entwickler, sondern in der Automatisierung der Infrastruktur — und StateKeep ist ein wichtiger Schritt in diese Richtung.