Retry restore-test downloads safely and expose bounded diagnostics

RESTORE_TEST.md

@@ -6,6 +6,82 @@ entschlüsselt, validiert und in ein privates Testverzeichnis entpackt. SQL-Dump
 werden zusätzlich in eine isolierte MariaDB importiert und mit `mariadb-check`
 geprüft. Produktive Anwendungen werden dabei nicht angehalten oder überschrieben.
 
+## Downloadfehler bei der Abnahme am 15.09.2026
+
+Das Update `4f220dbc6447` erzeugte den Satz
+`appbackup_2026-09-15_09-03-06_20b0f7a6`. Sein Upload und der vollständige
+Bytevergleich aller 15 Dateien bestanden, auch für die rund 5 GiB große
+`nextcloud-data.tar.zst`. Der Abschlussmarker wurde bestätigt. Anschließend
+bestand der separate Restore-Test Metadaten, drei Datenbanken, WordPress und
+Nextcloud; beim erneuten Abruf der Nextcloud-Daten folgte `Command failed: bash`.
+Der Test meldete `FAIL; cleanup OK`, das gesamte Update deshalb `FAILED`.
+
+Der Fehler ist dem Shell-Aufruf für den Komponentendownload einschließlich
+Remote-Vorprüfung zuzuordnen: Tar-Prüfung und Entpacken würden einen anderen
+Programmnamen melden; Fehler der separaten Platzbeschaffung werden bereits
+mit einer eigenen Meldung versehen. Der Supervisor verwarf jedoch stderr
+und nannte weder Exit-Code noch genaue Phase. Ob diesmal Crypt-Header, Timeout,
+HTTP-Fehler oder eine andere Bridge-Ursache vorlag, ist damit **nicht mehr aus
+diesem Log rekonstruierbar**. Ein erneuter `bad magic string` ist nicht belegt.
+
+Die erste Korrektur erfasste `rclone check`, aber nicht diesen eigenen
+`rclone cat`-Pfad. Auch `cat` wiederholt den gesamten Befehl in rclone 1.74.3
+nicht automatisch über `--retries`.
+Quelle: [rclone-1.74.3-cat-Aufruf](https://github.com/rclone/rclone/blob/v1.74.3/cmd/cat/cat.go).
+
+### Korrigierter Ablauf
+
+Der Restore-Test verwendet für seine lesenden Remote-Aufrufe jetzt dieselben
+Konfigurationswerte wie die Backup-Rückleseprüfung:
+
+- `RCLONE_CHECK_ATTEMPTS=3`: höchstens drei Versuche je Metadatenabruf/Download.
+- `RCLONE_CHECK_DEADLINE=3600`: maximal eine Stunde je Versuch einschließlich
+  Remote-Vorprüfung. Der Python-Supervisor beendet die eigene Prozessgruppe bei
+  Überschreitung mit TERM, nötigenfalls nach fünf Sekunden mit KILL.
+- `RCLONE_CHECK_TIMEOUT=300` und `RCLONE_CHECK_LOW_LEVEL_RETRIES=3`: kürzere
+  rclone-Leerlauffrist und begrenzte interne Versuche, auch bei der Vorprüfung.
+- `RCLONE_CHECK_RETRY_DELAY=30`: Pause zwischen fehlgeschlagenen Versuchen.
+  Die Gesamtfrist `RESTORE_TEST_TIMEOUT` und die Speicherüberwachung bleiben
+  während Downloads und Wartepausen wirksam. Die Fristen addieren sich nicht
+  zu einer unbegrenzten Verlängerung des gesamten Restore-Tests.
+
+Bei einer Wiederholung wird die angefangene Archivdatei auf null gekürzt und
+vollständig neu geladen; es wird niemals an Teilbytes angehängt. Metadaten
+werden je Versuch in einem neuen begrenzten Puffer gelesen. Erst ein erfolgreich
+beendeter Download mit passender Größe und SHA-256 darf zur Archivprüfung und
+zum Entpacken gelangen. Größenüberschreitungen, Prüfsummenfehler, Speichergrenzen,
+Gesamtfrist und Signalabbrüche lösen keine Download-Wiederholung aus.
+Die Platzbereinigung wird nicht als Remote-Leseoperation wiederholt.
+
+Jede Komponente meldet und speichert nun ihre konkrete Phase: Download,
+Prüfsumme, Archivprüfung, Platzabschätzung, Entpacken, DB-Import/-Prüfung und
+Bereinigung. Während eines Remote-Aufrufs erscheint etwa jede Minute
+ein Fortschrittsbericht mit gelesenen Bytes und verstrichener Zeit, auch bei
+Stillstand. Nicht erfolgreiche Prozesse nennen Exit-Code oder Fristablauf.
+
+Remote-stderr wird parallel zum Archivstrom gelesen und ausschließlich in feste
+Fehlerklassen übersetzt, etwa `crypt-header`, `io-timeout`, `tls`, `dns`,
+`connection`, `http-429` oder `http-503`. Die Auswertung hat einen begrenzten
+Textpuffer; große stderr-Ausgaben können die Download-Pipe nicht blockieren.
+Es werden keine rohen URLs, Tokens, Header, Dateiinhalte oder Providertexte
+übernommen. Unbekannte Meldungen erscheinen als `unclassified remote error`.
+Diese Klassifizierung ist ein Diagnosehinweis, kein Beweis der Providerursache.
+DB- und sonstige Tool-stderr-Ausgaben bleiben vollständig unterdrückt, da sie
+SQL-Inhalte enthalten können. Phase und Exit-Code bleiben trotzdem sichtbar.
+
+Ein bleibender Fehler erhält den bereits verifizierten Backup-Satz und den
+vorherigen Restore-Erfolgsnachweis, meldet die betroffene Komponente als `FAIL`
+und bereinigt die Testdaten. Nach fehlgeschlagener Update-Abnahme bleiben
+Backup- und Restore-Test-Timer gestoppt. Das neue Paket erneut im Wartungsfenster
+installieren; es führt ein neues Backup samt vollständiger Restore-Abnahme aus.
+Erst die neue `result.txt` mit `SUCCESS` bestätigt die gesamte Abnahme.
+[Installationsschritte](UPDATE_ANLEITUNG.md).
+
+Der vorhandene erfolgreiche Backup-Satz darf alternativ nach Installation des
+Fixes mit `app-restore-test.sh --remote-run` erneut geprüft werden. Dabei bleibt
+die Altersgrenze aktiv. Ein solcher Einzeltest setzt nicht nachträglich das
+alte Update-Ergebnis auf SUCCESS und aktiviert keine Update-Timer.
+
 ## Speicherbedarf und Bereinigung
 
 Wegen des knappen Speichers auf Gemini läuft immer nur **eine Komponente**:
@@ -221,6 +297,22 @@ Technische Referenzen: [Docker run](https://docs.docker.com/reference/cli/docker
 
 ## Entwicklung und lokale Verifikation
 
+Der Folgefix vom 15.09.2026 bestand alle **33 Restore-Test-Fälle** mit der von
+Gemini kopierten rclone-1.74.3-Binärdatei und dem echten lokalen
+`mariadb:10.11`-Image. Geprüft wurden auch Teil-Downloads/Metadaten mit erneutem
+Erfolg, dauerhaft fehlgeschlagene Downloads, Fristablauf, Signalabbruch,
+Gesamtfrist während einer Retry-Pause und zu große Antworten. Große stderr-
+Ausgaben blockierten nicht; synthetische Tokens und SQL-Inhalte erschienen
+weder im Log noch im Status oder Bericht. Die Testcontainer und Testdaten waren
+anschließend entfernt. Diese lokalen Tests ersetzen nicht die erneute
+OneDrive-/Rocky-Abnahme auf Gemini.
+
+Die vollständige Basissuite `tests/run.sh` bestand ebenfalls: Bash-Syntax,
+ShellCheck und 111 erfolgreiche Tests; fünf optionale Docker-Fälle waren in
+diesem netzlosen Basistest ausgelassen und wurden im oben genannten echten
+MariaDB-Lauf bestanden. Insgesamt sind damit alle **116 unterschiedlichen
+Tests** erfolgreich abgedeckt, einschließlich Paketinstallation und Rollback.
+
 Am 12.09.2026 bestanden **100 unterschiedliche Tests**: 71 Backup-/Restore-/
 Installer-Regressionstests, 23 Restore-Test-Fälle mit dem offiziellen lokalen
 MariaDB-10.11-Image und 6 gezielte Scratch-/Recovery-Schutzprüfungen. ShellCheck