Nicht nur Dateien prüfen, sondern eine Lieferung sicher übernehmen

SFTP-Lieferungen automatisch testen: Dateien korrelieren, sicher übernehmen und archivieren

Die übergeordnete Idee steht im Hauptartikel zur automatischen Schnittstellenqualität. Die veröffentlichten Serienartikel zeigen den Weg über JSON Schema, CSV und Fixed-Width, HTTP-Verträge und den stabilen SFTP-Ein-Datei-Ablauf. Dieser Artikel erklärt, wie aus dem SFTP-Eingang ein nachvollziehbarer Delivery-Lifecycle wird.

Das v3-Profil als expliziter Vertrag

Version 3 baut auf der Verzeichnisauswahl von Version 2 auf. filePattern beschreibt die primäre Datei. companionPattern beschreibt eine Begleitdatei. Beide Muster werden nur gegen Basenames geprüft. deliveryIdPattern enthält eine benannte Gruppe deliveryId, die in beiden Dateinamen denselben Wert liefern muss.

{
  "format": "sftp",
  "version": 3,
  "host": "sftp.example.test",
  "port": 22,
  "username": "quality-reader",
  "remoteDirectory": "/incoming",
  "filePattern": "^delivery-[A-Z0-9-]+[.]json$",
  "companionPattern": "^delivery-[A-Z0-9-]+[.]meta[.]json$",
  "deliveryIdPattern": "^delivery-(?<deliveryId>[A-Z0-9-]+)(?:[.]meta)?[.]json$",
  "claimRemoteDirectory": "/claim",
  "archiveRemoteDirectory": "/archive",
  "knownHosts": "known_hosts",
  "privateKey": "id_ed25519",
  "contentFormat": "json",
  "contentProfile": "delivery.schema.json",
  "quarantineRemoteDirectory": "/quarantine",
  "stabilityChecks": 2,
  "stabilityDelaySeconds": 1,
  "maxAttempts": 2,
  "retryDelaySeconds": 1,
  "connectTimeoutSeconds": 10
}

Die beiden lokalen Dateien für Host-Key und Private Key bleiben unterhalb des Profilverzeichnisses. Das Profil enthält keine Passphrase. Falls der Schlüssel geschützt ist, kommt die Passphrase ausschließlich aus der dafür vorgesehenen Umgebungsvariable. Die Remote-Verzeichnisse sind bewusst getrennt: Der Produzent schreibt nach /incoming, der Validator besitzt /claim und /archive.

Mehrere Dateien, eine Liefer-ID

Eine Lieferung ist nicht automatisch vollständig, nur weil eine passende Datei vorhanden ist. Der v3-Selektor bildet Kandidaten nach ihrer Liefer-ID. Genau eine primäre Datei und genau eine Begleitdatei müssen dieselbe ID tragen. Die Auswahl bleibt dadurch deterministisch, ohne eine fachliche Entscheidung in „nimm die neueste Datei“ zu verstecken.

Claim und sicherer Wiederanlauf

Der Claim-Bereich ist die Besitzgrenze des Validators. Sobald genau eine vollständige Lieferung gefunden wurde, werden alle zugehörigen Dateien per Remote-Rename aus /incoming nach /claim verschoben. Erst danach beginnt der Download. Ein paralleler Lauf sieht die Lieferung im Eingangsverzeichnis nicht mehr und kann sie nicht noch einmal auswählen.

1. Den Claim-Bereich zuerst nach einer bereits übernommenen Lieferung durchsuchen.
2. Wenn dort nichts Passendes liegt, Eingang auf eine vollständige, eindeutige Lieferung prüfen.
3. Alle Dateien der Lieferung atomar in den Claim-Bereich umbenennen.
4. Bei einem Verbindungsabbruch den Claim beim nächsten Lauf aus dem Claim-Bereich wieder aufnehmen.

Damit wird aus „noch einmal prüfen“ ein definierter Wiederanlauf. Ein fehlgeschlagener Claim ist ein technischer Fehler mit Exit-Code 2. Wenn nur ein Teil des Claims gelingt, versucht der Adapter die bereits verschobenen Dateien zurückzusetzen; die ursprüngliche Transferstörung bleibt der maßgebliche Befund.

Stabilität, Integrität und Inhalt

Der Claim ersetzt die fachliche Prüfung nicht. Er schützt nur den Übergang vom Produzentenbereich zur laufenden Validierung. Danach bleibt die bewährte SFTP-Pipeline erhalten:

1. Host-Key und Private-Key-Zugang strikt prüfen.
2. Typ, Größe und Änderungszeit für jede Datei als stabilen Snapshot beobachten.
3. Alle Bytes in ein temporäres lokales Verzeichnis laden.
4. Den optionalen SHA-256-Hash auf der primären Datei gegen das Profil prüfen.
5. Primär- und Begleitdatei mit dem konfigurierten JSON-, CSV- oder Fixed-Width-Vertrag validieren.

Der gemeinsame Inhaltspfad ist bewusst eine erste, begrenzte Korrelation: Beide Dateien verwenden dasselbe Content-Profil. Unterschiedliche Formate oder fachliche Regeln wie „Summe in Datei A muss Datei B entsprechen“ brauchen einen eigenen späteren Vertrag. Das macht die aktuelle Lösung kleiner und im Fehlerfall verständlich.

Archiv oder Quarantäne

Ein gültiges Ergebnis ist jetzt nicht mehr nur ein Status im Terminal. Wenn Claim und Archiv konfiguriert sind, werden alle geprüften Dateien erst nach erfolgreicher Validierung in das Archiv verschoben. Bei einem Hash- oder Inhaltsfehler geht die gesamte geclaimte Lieferung – sofern Quarantäne aktiviert ist – in den Quarantänebereich.

Die Zielnamen erhalten UTC-Zeitstempel und einen kurzen Kollisionsschutz. Das verhindert, dass ein späterer Lauf ein vorhandenes Ergebnis still überschreibt. Ein Fehler beim finalen Verschieben ist kein fachlicher Finding, sondern ein operativer Fehler mit Exit-Code 2.

Der operative Prüfbericht

Der gemeinsame Report behält status, valid und findings. Für einen v3-Lifecycle kann zusätzlich ein metadata-Objekt erscheinen. Es enthält keine Nutzdaten und keine Secrets, sondern nur die Informationen, die den Übergang nachvollziehbar machen:

{
  "status": "VALID",
  "valid": true,
  "findings": [],
  "metadata": {
    "deliveryId": "D-200",
    "filesValidated": 2,
    "lifecycle": "ARCHIVED",
    "archivedFiles": [
      "/archive/delivery-D-200.json.20260928180000-ab12cd34.validated",
      "/archive/delivery-D-200.meta.json.20260928180000-ef56ab78.validated"
    ]
  }
}

Ältere Adapter und v1/v2-SFTP-Läufe behalten die kompakte Report-Form, weil leere Metadaten nicht ausgegeben werden. Automatisierung kann weiterhin über Status und Findings entscheiden; die Lifecycle-Metadaten helfen zusätzlich bei Audit, Betrieb und manueller Nachverfolgung.

Der lokale Nachweis

Für ein Erfolgserlebnis braucht niemand einen öffentlichen SFTP-Dienst. Die Unit-Tests prüfen Korrelation, unvollständige Lieferungen, Claim-Wiederaufnahme und Zielbewegungen mit einem kontrollierten Transport-Fake. Der Integrationstest startet einen eingebetteten Apache-MINA-SSHD-Server und lässt den produktiven JSch-Transport damit arbeiten.

mvnw.cmd -B -Dtest=SftpValidatorTest,SftpValidatorIntegrationTest test

mvnw.cmd -B clean package

Bewusste Grenzen

• kein „neueste Datei gewinnt“ und keine Auswahl nach Serverreihenfolge;
• genau eine Primärdatei und optional genau eine Begleitdatei je korrelierter Lieferung;
• beide Dateien verwenden aktuell dasselbe Content-Profil;
• keine Passwort-Authentifizierung, kein SSH-Agent und keine automatische OpenSSH-Konfiguration;
• keine fachlichen Cross-File-Regeln und kein dauerhafter Directory-Watcher.

Diese Grenzen sind Teil des Vertrags. Sie verhindern, dass aus einem nachvollziehbaren Qualitätstest unbemerkt ein allgemeiner SFTP-Orchestrator wird. Die nächste fachliche Erweiterung kann deshalb gezielt entscheiden, wie unterschiedliche Formate und echte Cross-File-Regeln modelliert werden sollen.