syncova-backup/docs/agent-tasks.md

Auftragsübermittlung an Agenten (Phase 5)

Bis zu dieser Phase war der Agent ein angemeldeter Beobachter: Er meldete sich an und gab Lebenszeichen, aber der Server konnte ihm nichts zu tun geben. Zentral gesteuerte Sicherungen liefen nur für Quellen, die der Control-Server selbst erreicht.

Jetzt läuft die Kette durch:

Server stellt Auftrag ein
  → Agent holt ihn ab
  → Agent sichert über die Engine
  → Agent meldet Fortschritt und Ergebnis
  → Server trägt den Wiederherstellungspunkt ein

Der Agent holt ab, der Server drückt nicht

Das ist keine Bequemlichkeit, sondern die einzige Wahl, die in echten Netzen funktioniert. Ein Agent steht hinter einer Firewall, oft hinter NAT, und ist vom Server aus nicht erreichbar — jedenfalls nicht ohne eine eingehende Portfreigabe auf jedem gesicherten System. Die Verbindung geht deshalb immer vom Agenten aus, in genau der Richtung, die auch seine Lebendmeldung nimmt.

Drei Endpunkte, alle am Betriebstoken des Agenten:

POST /api/v1/agents/tasks/claim          # holt den nächsten Auftrag (204 = nichts zu tun)
POST /api/v1/agents/tasks/{id}/progress  # Fortschritt und Lebenszeichen
POST /api/v1/agents/tasks/{id}/result    # Ergebnis

Jeder prüft, dass der Auftrag dem anfragenden Agenten gehört. Ohne diese Prüfung könnte ein übernommener Agent die Aufträge aller anderen Systeme abholen — samt Quell- und Repositorypfaden, also einer Landkarte der gesamten Anlage.

Ein fremder und ein bereits abgeschlossener Auftrag ergeben dieselbe Antwort: Die Unterscheidung verriete, welche Auftragskennungen es gibt.

Der Fund: Der Server sperrte das Repository für seinen eigenen Agenten

Beim ersten Durchlauf meldete der Agent:

REPOSITORY_UNREACHABLE — Das Repository unter "…/p5/repo" ist von diesem
Agenten aus nicht erreichbar

Das Repository lag einwandfrei da. Gesperrt hatte es der Server: Phase 8 öffnet das Repository einmal je Lauf und hält dabei die Schreibsperre — eine richtige Entscheidung, solange der Server selbst sichert. Bei einer Delegation wartete er nun mit gehaltener Sperre darauf, dass der Agent in dasselbe Repository schreibt.

Der Server öffnet das Repository jetzt nur noch, wenn mindestens eine Quelle des Laufs serverseitig gesichert wird. Ein Lauf mit ausschließlich Agentenquellen löst den Datensatz auf — der Agent braucht den Pfad —, öffnet das Repository aber nicht.

Wie der Agent an das Repository kommt

Der Auftrag enthält den Repositorypfad; der Agent öffnet ihn unmittelbar. Daraus folgt eine Betriebsanforderung, die klar benannt sein muss:

Der Agent braucht Schreibzugriff auf das Repository. Auf einem gemeinsamen Server ist das der lokale Pfad. Bei getrennten Maschinen braucht es eine Freigabe (NFS, SMB) oder ein eingehängtes Verzeichnis. Erreicht der Agent das Ziel nicht, meldet er REPOSITORY_UNREACHABLE mit dem Hinweis auf die Freigabe — statt einen technischen Pfadfehler weiterzureichen oder eine leere Sicherung abzuliefern.

Ein Streaming-Protokoll, bei dem der Agent seine Blöcke an den Server schickt und dieser sie ablegt, wäre die Alternative. Es ist bewusst nicht gebaut: Es verdoppelt den Datenweg, macht den Control-Server zum Engpass jeder Sicherung und verlangt ein eigenes Übertragungsprotokoll samt Wiederaufnahme. Für einen ersten funktionierenden Weg ist die Freigabe die ehrlichere Lösung.

Regeln, die auch hier gelten

• Ein Auftrag je Agent. Ein Teilindex auf (agent_id) WHERE status IN ('claimed','running') erzwingt es. Zwei gleichzeitige Sicherungen desselben Systems konkurrierten um dieselben Dateien und dieselbe Schreibsperre.
• Ein Teilfehler bleibt ein Teilfehler. Der Agent meldet ihn als solchen, der Server berichtigt ein widersprüchliches Ergebnis, und die Datenbank lehnt „erfolgreich mit übergangenen Objekten" per CHECK ab. Drei Ebenen für dieselbe Regel — weil sie die wichtigste ist (verbindliche Regel 1).
• Ein Fehler ist eine Antwort. Der Agent meldet auch im Fehlerfall zurück. Ein Agent, der bei einem Fehler schweigt, lässt den Lauf bis zum Ablauf der Frist hängen.
• Verschlüsselung wird nie stillschweigend weggelassen. Verlangt der Auftrag sie und hat der Agent kein Schlüsselmaterial, wird der Auftrag abgelehnt. Ein Backup, das der Server für verschlüsselt hält und das es nicht ist, wäre eine Zusicherung ins Leere.
• Der Lauf wartet synchron auf den Agenten. Würde der Server den Auftrag nur einstellen und den Lauf als erfolgreich vermerken, stünde ein grüner Lauf in der Übersicht, während der Agent noch arbeitet — oder bereits gescheitert ist.
• Verwaiste Aufträge werden freigegeben, nicht wiederholt. Stirbt ein Agent mitten im Lauf, gilt sein Auftrag nach Fristablauf als gescheitert (AGENT_LOST, Klasse transient). Nicht erneut eingereiht: Er könnte bereits Blöcke geschrieben haben.
• Der Fortschritt ist zugleich die Lebendmeldung und wird gedrosselt (alle fünf Sekunden). Die Engine ruft ihren Rückruf sehr häufig auf; ungedrosselt erzeugte eine Sicherung mit einer Million Dateien eine Million HTTP-Anfragen.

Nachweis

Auf einer Maschine, auf der Server und Agent laufen:

Agent aufgenommen                      dev-agent
Auftrag mit agent_id angelegt          Quelle ist Agent zugewiesen ✓
Lauf angestoßen                        HTTP 202
Agent holt ab und führt aus            "auftrag wird ausgefuehrt"
Ergebnis                               succeeded, 3.500.014 Byte, 4 Objekte
Wiederherstellungspunkt in der DB      complete, 3.500.014 Byte
Quelle gelöscht, wiederhergestellt     ✓ alle Prüfsummen stimmen

Was noch fehlt

• Der Windows-Dienst ist weiterhin ungeprüft. service_windows.go ist geschrieben, aber auf macOS nicht ausführbar. Der Kommandozeilenweg und die Auftragsausführung sind plattformunabhängig; der Dienstwrapper ist der letzte ungeprüfte Teil von Phase 5.
• Wiederherstellung über den Agenten. Der Auftragstyp restore ist im Modell vorgesehen und nicht umgesetzt: Eine Wiederherstellung schreibt auf ein fremdes System und braucht dieselben drei Hürden wie die serverseitige (Phase 9). Sie wird als eigener Schritt gebaut, nicht nebenbei.
• Kein Streaming zum Server. Siehe oben — der Agent braucht Zugriff auf das Repository.
• Keine Abbruchmöglichkeit von außen. Ein laufender Agentenauftrag lässt sich derzeit nicht über die API abbrechen; er läuft zu Ende oder in die Frist.