From 119ddc81bed2bd684c1b1efda2b619ca87a97d07 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 15 Oct 2026 11:38:44 +0000 Subject: [PATCH] ROL-02: Rollback-Testlauf fuer Wartungsmodus-Aufhebung umgesetzt Neues Paket internal/rollbackrun testet den Rollback-Pfad real gegen eine Postgres-Testdatenbank: Altsystem-Testkopie in echten Wartungsmodus (DB-weit read-only) versetzen, Rollback hebt ihn auf und nimmt die NEXARCH- Freischaltung zurueck, verifiziert Schreibzugriff und vergleicht Zeilenzahlen/Pruefsummen vor/nach dem Rollback. Baut auf ROL-01 (rollbackcriteria) und CUT-02 (cutoverorchestrator) auf. Co-Authored-By: Claude Sonnet 5 --- docs/ROL-02-PRUEFPROTOKOLL.md | 113 +++++++++++++ internal/rollbackrun/rollbackrun.go | 192 +++++++++++++++++++++++ internal/rollbackrun/rollbackrun_test.go | 144 +++++++++++++++++ 3 files changed, 449 insertions(+) create mode 100644 docs/ROL-02-PRUEFPROTOKOLL.md create mode 100644 internal/rollbackrun/rollbackrun.go create mode 100644 internal/rollbackrun/rollbackrun_test.go diff --git a/docs/ROL-02-PRUEFPROTOKOLL.md b/docs/ROL-02-PRUEFPROTOKOLL.md new file mode 100644 index 00000000..4ca1a541 --- /dev/null +++ b/docs/ROL-02-PRUEFPROTOKOLL.md @@ -0,0 +1,113 @@ +# ROL-02 — Prüfprotokoll Rollback-Testlauf + +Datum: 2026-10-15 +Umgebung: Host 204 (Dev/Test), Wegwerf-Postgres-Cluster, synthetische Testkopie +Paket: `internal/rollbackrun` (Root-Modul), aufbauend auf `internal/cutoverorchestrator` (CUT-02) und `internal/rollbackcriteria` (ROL-01) + +## Ausgangslage + +ROL-01 liefert die Rollback-Kriterien (Schwellenwerte, Freigabe) und CUT-02 +liefert die große synthetische Testkopie des Generalprobe-Trockenlaufs. +ROL-02 testet den eigentlichen Rollback-Mechanismus: das Altsystem (hier +exemplarisch die archivmail-Testkopie) wird — wie am echten Stichtag — nicht +gelöscht, sondern in einen Wartungsmodus (read-only) versetzt, während der +NEXARCH-Tenant freigeschaltet ist. Ein Rollback muss diesen Zustand rückgängig +machen: Wartungsmodus aufheben, Freischaltung zurücknehmen. + +Da es im bestehenden Code noch kein explizites Wartungsmodus-Flag für die +Altsystem-Testkopie gab, wurde dafür eine kleine, eigenständige Tabelle +`legacy_system_state` (Spalten `maintenance_mode`, `nexarch_enabled`) ergänzt +sowie der Wartungsmodus real auf Datenbankebene durchgesetzt +(`ALTER DATABASE ... SET default_transaction_read_only = on`), statt ihn nur +als Flag zu simulieren. Dadurch prüft der Test echten Schreibschutz und echte +Schreibfähigkeit nach dem Rollback, nicht nur eine Statuszeile. + +## Testaufbau + +- `rollbackrun.Setup`: legt eine frische Wegwerf-Datenbank an, seedet das + archivmail-Schema mit `cutoverorchestrator.GenerateDataset` (synthetische + Daten, Seed 11, Bcrypt-Kostenfaktor 4 für Testgeschwindigkeit), legt + `legacy_system_state`/`legacy_writeprobe` an, setzt den betroffenen Tenant + (ID 101, Kanzlei Musterhausen) auf `maintenance_mode=true`, + `nexarch_enabled=true` und aktiviert den Wartungsmodus auf DB-Ebene. +- `rollbackrun.Rollback`: prüft die Vorbedingung (Wartungsmodus + + Freischaltung aktiv), hebt den Wartungsmodus auf, nimmt die Freischaltung + zurück, verifiziert echten Schreibzugriff (Insert in `legacy_writeprobe`) + und vergleicht Zeilenzahlen + Prüfsummen (`md5` über alle Spalten je + Tabelle) der Altsystem-Tabellen vor/nach dem Rollback. + +## Prüfungen und Ergebnisse + +### Prüfung 1: Simulierter Rollback in Testumgebung erfolgreich abgeschlossen + +Automatisierte Tests gegen echte Postgres-Testdatenbank auf Host 204 (kein +Mocking), Paket `internal/rollbackrun`: + +``` +=== RUN TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode +--- PASS: TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode (0.38s) +=== RUN TestRollback_RestoresWriteAccessAndMeasuresDuration + rollbackrun_test.go:81: gemessene rollback-dauer: 23.889654ms +--- PASS: TestRollback_RestoresWriteAccessAndMeasuresDuration (0.46s) +=== RUN TestRollback_RejectsWhenNotInMaintenanceMode +--- PASS: TestRollback_RejectsWhenNotInMaintenanceMode (0.43s) +=== RUN TestSnapshotTables_DetectsChange +--- PASS: TestSnapshotTables_DetectsChange (0.36s) +PASS +ok gitea.perlbach24.de/scripte/nexarch/internal/rollbackrun 1.628s +``` + +- `TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode` belegt, dass die + Testkopie im Wartungsmodus tatsächlich read-only ist (ein Schreibversuch + schlägt mit `SQLSTATE 25006` fehl) — ohne diese Vorbedingung wäre der + Rollback-Testlauf nicht aussagekräftig. +- `TestRollback_RestoresWriteAccessAndMeasuresDuration` spielt den vollen + Rollback-Pfad durch: Wartungsmodus aufheben, Freischaltung zurücknehmen, + Schreibzugriff verifizieren, Datenverlust-Vergleich — Ergebnis: Erfolg, + keine Abweichung. +- `TestRollback_RejectsWhenNotInMaintenanceMode` stellt sicher, dass ein + zweiter Rollback auf einen bereits zurückgenommenen Zustand kontrolliert + abgelehnt wird (Vorbedingungsprüfung), statt unbemerkt Status zu + überschreiben. + +### Prüfung 2: Nach Rollback kein Datenverlust im Altsystem feststellbar + +- Vergleichstabellen (`rollbackrun.BusinessTables`): `tenants`, + `tenant_domains`, `users`, `storage_objects`, `emails`, `attachments`, + `email_attachments`, `email_refs`, `audit_log`, `reconciliation_reports`, + `dsgvo_requests`. +- Je Tabelle wird vor und nach dem Rollback Zeilenzahl + `md5`-Prüfsumme + über alle Zeilen gebildet und verglichen (`report.DataLossDetected`, + `report.MismatchedTables`). +- `legacy_system_state` und `legacy_writeprobe` sind bewusst ausgenommen: + sie drücken den Wartungsmodus- bzw. Schreibtest-Zustand selbst aus, der + sich durch den Rollback gewollt ändert. +- `TestSnapshotTables_DetectsChange` belegt, dass der Vergleichsmechanismus + echte Abweichungen tatsächlich erkennt (keine Scheinprüfung, die immer + grün ausfällt). +- Ergebnis im Testlauf: `DataLossDetected = false`, keine abweichenden + Tabellen. + +## Akzeptanzkriterien + +1. **Rollback-Pfad in Testumgebung erfolgreich durchgespielt**: erfüllt, + siehe `TestRollback_RestoresWriteAccessAndMeasuresDuration`. +2. **Altsystem nach simuliertem Rollback vollständig nutzbar**: erfüllt — + Wartungsmodus auf DB-Ebene aufgehoben, exemplarischer Schreibzugriff + (`legacy_writeprobe`-Insert im Test sowie im Rollback-Ablauf selbst) + erfolgreich. +3. **Dauer des Rollback-Vorgangs gemessen und dokumentiert**: erfüllt — + gemessene Dauer im Testlauf: **23,89 ms** (Messzeitraum: ab + Wartungsmodus-Aufhebung bis einschließlich verifiziertem Schreibzugriff, + ohne die flankierenden Vorher-/Nachher-Datenvergleiche). Werte für + wiederholte Läufe liegen im niedrigen zweistelligen Millisekundenbereich, + da der Vorgang im Kern aus wenigen Metadaten-Änderungen (ALTER DATABASE, + zwei Tabellen-Updates/-Inserts) auf einer kleinen Testkopie besteht. + +## Fazit + +Der Rollback-Pfad (Wartungsmodus aufheben, NEXARCH-Freischaltung +zurücknehmen) wurde in der isolierten Testumgebung auf Host 204 real +durchgespielt — gegen eine echte Postgres-Testdatenbank, mit synthetischen +Daten, ohne Produktivsysteme oder -daten. Alle drei Akzeptanzkriterien sind +durch automatisierte, tatsächlich ausgeführte Tests belegt. diff --git a/internal/rollbackrun/rollbackrun.go b/internal/rollbackrun/rollbackrun.go new file mode 100644 index 00000000..22c4273a --- /dev/null +++ b/internal/rollbackrun/rollbackrun.go @@ -0,0 +1,192 @@ +package rollbackrun + +import ( + "context" + "fmt" + "time" + + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgxpool" + + "gitea.perlbach24.de/scripte/nexarch/internal/cutoverorchestrator" +) + +const legacyStateSchemaSQL = ` +CREATE TABLE legacy_system_state ( + tenant_id BIGINT PRIMARY KEY, + maintenance_mode BOOLEAN NOT NULL DEFAULT false, + nexarch_enabled BOOLEAN NOT NULL DEFAULT false, + updated_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +CREATE TABLE legacy_writeprobe ( + id BIGSERIAL PRIMARY KEY, + note TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +` + +// BusinessTables werden fuer den Datenverlust-Vergleich herangezogen. +// legacy_system_state/legacy_writeprobe gehoeren nicht dazu: sie druecken +// den Wartungsmodus- bzw. Schreibtest-Zustand selbst aus, der sich durch +// den Rollback gewollt aendert. +var BusinessTables = []string{ + "tenants", "tenant_domains", "users", "storage_objects", "emails", + "attachments", "email_attachments", "email_refs", "audit_log", + "reconciliation_reports", "dsgvo_requests", +} + +type Testbed struct { + DBName string + Pool *pgxpool.Pool + TenantID int64 +} + +func Setup(ctx context.Context, cluster *cutoverorchestrator.Cluster, dbName string, tenantID int64, data cutoverorchestrator.ArchivmailData) (*Testbed, error) { + if err := cluster.CreateDatabase(ctx, dbName); err != nil { + return nil, err + } + pool, err := cluster.Connect(ctx, dbName) + if err != nil { + return nil, err + } + if _, err := cutoverorchestrator.SeedArchivmail(ctx, pool, data); err != nil { + pool.Close() + return nil, err + } + if _, err := pool.Exec(ctx, legacyStateSchemaSQL); err != nil { + pool.Close() + return nil, fmt.Errorf("legacy_system_state anlegen: %w", err) + } + if _, err := pool.Exec(ctx, `INSERT INTO legacy_system_state (tenant_id, maintenance_mode, nexarch_enabled) VALUES ($1, true, true)`, tenantID); err != nil { + pool.Close() + return nil, fmt.Errorf("wartungszustand setzen: %w", err) + } + if _, err := pool.Exec(ctx, "ALTER DATABASE "+pgx.Identifier{dbName}.Sanitize()+" SET default_transaction_read_only = on"); err != nil { + pool.Close() + return nil, fmt.Errorf("wartungsmodus aktivieren: %w", err) + } + pool.Close() + + roPool, err := cluster.Connect(ctx, dbName) + if err != nil { + return nil, fmt.Errorf("neuverbindung im wartungsmodus: %w", err) + } + return &Testbed{DBName: dbName, Pool: roPool, TenantID: tenantID}, nil +} + +func DropDatabase(ctx context.Context, cluster *cutoverorchestrator.Cluster, dbName string) error { + conn, err := pgx.Connect(ctx, cluster.AdminDSN()) + if err != nil { + return err + } + defer conn.Close(ctx) + _, err = conn.Exec(ctx, "DROP DATABASE IF EXISTS "+pgx.Identifier{dbName}.Sanitize()+" WITH (FORCE)") + return err +} + +type tableSnapshot struct { + count int64 + checksum string +} + +func snapshotTables(ctx context.Context, pool *pgxpool.Pool, tables []string) (map[string]tableSnapshot, error) { + out := make(map[string]tableSnapshot, len(tables)) + for _, tbl := range tables { + q := fmt.Sprintf(`SELECT count(*), coalesce(md5(string_agg(r, '' ORDER BY r)), '') FROM (SELECT (t.*)::text AS r FROM %s t) s`, + pgx.Identifier{tbl}.Sanitize()) + var snap tableSnapshot + if err := pool.QueryRow(ctx, q).Scan(&snap.count, &snap.checksum); err != nil { + return nil, fmt.Errorf("snapshot tabelle %s: %w", tbl, err) + } + out[tbl] = snap + } + return out, nil +} + +type Report struct { + TenantID int64 + Start time.Time + End time.Time + Duration time.Duration + WriteVerified bool + WriteProbeID int64 + TablesCompared []string + DataLossDetected bool + MismatchedTables []string +} + +// Rollback hebt den Wartungsmodus des Altsystems auf und nimmt die +// NEXARCH-Freischaltung des Tenants zurueck. Die gemessene Dauer umfasst +// genau diese Operation (ohne die flankierenden Vorher-/Nachher-Pruefungen). +func Rollback(ctx context.Context, cluster *cutoverorchestrator.Cluster, tb *Testbed) (Report, error) { + before, err := snapshotTables(ctx, tb.Pool, BusinessTables) + if err != nil { + return Report{}, err + } + + var maint, nex bool + if err := tb.Pool.QueryRow(ctx, `SELECT maintenance_mode, nexarch_enabled FROM legacy_system_state WHERE tenant_id = $1`, tb.TenantID).Scan(&maint, &nex); err != nil { + return Report{}, fmt.Errorf("wartungszustand lesen: %w", err) + } + if !maint || !nex { + return Report{}, fmt.Errorf("rollback-vorbedingung verletzt: wartungsmodus=%v freischaltung=%v", maint, nex) + } + + start := time.Now() + + conn, err := tb.Pool.Acquire(ctx) + if err != nil { + return Report{}, fmt.Errorf("verbindung fuer wartungsmodus-aufhebung: %w", err) + } + // SET transaction_read_only gilt nur fuer die laufende Transaktion; + // ohne den Override in derselben impliziten Transaktion wie die + // ALTER-DATABASE-Anweisung wuerde diese als Schreibzugriff unter dem + // noch aktiven default_transaction_read_only=on abgelehnt (SQLSTATE 25006). + _, err = conn.Exec(ctx, "SET transaction_read_only = off; ALTER DATABASE "+pgx.Identifier{tb.DBName}.Sanitize()+" SET default_transaction_read_only = off;") + conn.Release() + if err != nil { + return Report{}, fmt.Errorf("wartungsmodus aufheben: %w", err) + } + tb.Pool.Close() + + rwPool, err := cluster.Connect(ctx, tb.DBName) + if err != nil { + return Report{}, fmt.Errorf("neuverbindung nach rollback: %w", err) + } + tb.Pool = rwPool + + if _, err := tb.Pool.Exec(ctx, `UPDATE legacy_system_state SET maintenance_mode = false, nexarch_enabled = false, updated_at = now() WHERE tenant_id = $1`, tb.TenantID); err != nil { + return Report{}, fmt.Errorf("freischaltung zuruecknehmen: %w", err) + } + + var probeID int64 + if err := tb.Pool.QueryRow(ctx, `INSERT INTO legacy_writeprobe (note) VALUES ('rollback-schreibtest') RETURNING id`).Scan(&probeID); err != nil { + return Report{}, fmt.Errorf("altsystem nach rollback nicht beschreibbar: %w", err) + } + + end := time.Now() + + after, err := snapshotTables(ctx, tb.Pool, BusinessTables) + if err != nil { + return Report{}, err + } + + var mismatches []string + for _, tbl := range BusinessTables { + if before[tbl] != after[tbl] { + mismatches = append(mismatches, tbl) + } + } + + return Report{ + TenantID: tb.TenantID, + Start: start, + End: end, + Duration: end.Sub(start), + WriteVerified: true, + WriteProbeID: probeID, + TablesCompared: append([]string{}, BusinessTables...), + DataLossDetected: len(mismatches) > 0, + MismatchedTables: mismatches, + }, nil +} diff --git a/internal/rollbackrun/rollbackrun_test.go b/internal/rollbackrun/rollbackrun_test.go new file mode 100644 index 00000000..5b311922 --- /dev/null +++ b/internal/rollbackrun/rollbackrun_test.go @@ -0,0 +1,144 @@ +package rollbackrun + +import ( + "context" + "os" + "testing" + "time" + + "gitea.perlbach24.de/scripte/nexarch/internal/cutoverorchestrator" + "gitea.perlbach24.de/scripte/nexarch/internal/testdb" +) + +const testTenantID int64 = 101 + +func testCluster(t *testing.T) *cutoverorchestrator.Cluster { + t.Helper() + adminDSN := os.Getenv("TEST_ADMIN_DSN") + if adminDSN == "" { + t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen") + } + c, err := cutoverorchestrator.NewCluster(adminDSN) + if err != nil { + t.Fatalf("NewCluster: %v", err) + } + return c +} + +func setupTestbed(t *testing.T) (*cutoverorchestrator.Cluster, *Testbed) { + t.Helper() + cluster := testCluster(t) + ctx := context.Background() + + ds, err := cutoverorchestrator.GenerateDataset(11, time.Date(2026, 10, 14, 9, 0, 0, 0, time.UTC), 4) + if err != nil { + t.Fatalf("GenerateDataset: %v", err) + } + + dbName := "rol02_" + testdb.Suffix() + tb, err := Setup(ctx, cluster, dbName, testTenantID, ds.Archivmail) + if err != nil { + t.Fatalf("Setup: %v", err) + } + t.Cleanup(func() { + tb.Pool.Close() + if err := DropDatabase(context.Background(), cluster, dbName); err != nil { + t.Logf("aufraeumen %s fehlgeschlagen: %v", dbName, err) + } + }) + return cluster, tb +} + +// AK1 (Pruefung 1): Altsystem im Wartungsmodus ist read-only -- der +// simulierte Rollback muss diesen Zustand erst aufheben, bevor Schreiben +// wieder moeglich ist. +func TestSetup_PutsLegacySystemIntoReadOnlyMaintenanceMode(t *testing.T) { + ctx := context.Background() + _, tb := setupTestbed(t) + + _, err := tb.Pool.Exec(ctx, `INSERT INTO legacy_writeprobe (note) VALUES ('sollte scheitern')`) + if err == nil { + t.Fatal("schreibzugriff im wartungsmodus haette fehlschlagen muessen") + } +} + +// AK1/AK2/AK3: Rollback durchspielen, danach Altsystem wieder nutzbar, +// Dauer gemessen und sinnvoll (kein Timeout, keine Nullzeit durch Fehler). +func TestRollback_RestoresWriteAccessAndMeasuresDuration(t *testing.T) { + cluster, tb := setupTestbed(t) + ctx := context.Background() + + report, err := Rollback(ctx, cluster, tb) + if err != nil { + t.Fatalf("Rollback: %v", err) + } + if report.Duration <= 0 { + t.Fatalf("erwarte gemessene dauer > 0, habe %v", report.Duration) + } + if report.Duration > 30*time.Second { + t.Fatalf("rollback hat unerwartet lange gedauert: %v", report.Duration) + } + t.Logf("gemessene rollback-dauer: %v", report.Duration) + if !report.WriteVerified || report.WriteProbeID == 0 { + t.Fatalf("schreibzugriff nach rollback nicht verifiziert: %+v", report) + } + if report.DataLossDetected { + t.Fatalf("datenverlust erkannt, erwartet keiner: %+v", report.MismatchedTables) + } + + var maint, nex bool + if err := tb.Pool.QueryRow(ctx, `SELECT maintenance_mode, nexarch_enabled FROM legacy_system_state WHERE tenant_id = $1`, testTenantID).Scan(&maint, &nex); err != nil { + t.Fatalf("zustand nach rollback lesen: %v", err) + } + if maint || nex { + t.Fatalf("wartungsmodus/freischaltung nach rollback nicht zurueckgenommen: maintenance=%v nexarch=%v", maint, nex) + } + + if _, err := tb.Pool.Exec(ctx, `INSERT INTO legacy_writeprobe (note) VALUES ('exemplarischer schreibzugriff nach rollback')`); err != nil { + t.Fatalf("altsystem nach rollback nicht voll nutzbar: %v", err) + } +} + +// AK1/Pruefung 2: Rollback ohne vorherigen Wartungsmodus wird abgelehnt -- +// verhindert, dass ein bereits zurueckgenommener Zustand erneut "zurueck"- +// genommen wird und dabei unbemerkt Status verliert. +func TestRollback_RejectsWhenNotInMaintenanceMode(t *testing.T) { + cluster, tb := setupTestbed(t) + ctx := context.Background() + + if _, err := Rollback(ctx, cluster, tb); err != nil { + t.Fatalf("erster rollback sollte gelingen: %v", err) + } + + if _, err := Rollback(ctx, cluster, tb); err == nil { + t.Fatal("zweiter rollback haette an der vorbedingung scheitern muessen") + } +} + +// Pruefung "kein Datenverlust": Snapshot-Vergleich erkennt eine +// zwischenzeitliche Aenderung tatsaechlich, statt immer gleich auszufallen. +func TestSnapshotTables_DetectsChange(t *testing.T) { + ctx := context.Background() + cluster, tb := setupTestbed(t) + if _, err := Rollback(ctx, cluster, tb); err != nil { + t.Fatalf("rollback zur vorbereitung (schreibzugriff fuer testaenderung): %v", err) + } + + before, err := snapshotTables(ctx, tb.Pool, BusinessTables) + if err != nil { + t.Fatalf("snapshot vorher: %v", err) + } + + if _, err := tb.Pool.Exec(ctx, `UPDATE tenants SET name = name || ' geaendert' WHERE id = $1`, testTenantID); err != nil { + t.Fatalf("testaenderung: %v", err) + } + + after, err := snapshotTables(ctx, tb.Pool, BusinessTables) + if err != nil { + t.Fatalf("snapshot nachher: %v", err) + } + + if before["tenants"] == after["tenants"] { + t.Fatal("aenderung an tenants haette im snapshot sichtbar sein muessen") + } +} -- 2.47.3