sck/gala-ki-spielwiese
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e7fb09069c76f854bdb5d37cb7b60f24788943fc
gala-ki-spielwiese/quarkus-automaton/docs/Plan.md

20 KiB
Raw Blame History

Plan: n8n Workflow → Quarkus Backend ersetzen

Stand: 2026-04-08
Basis: Avise-Tool Quarkus Backend (agent-backend/) — angepasst für SFTP → OCI Object Storage → DB-Workflow

Ziel

Ersetze den n8n-Workflow (derzeit: SFTP-Poll → ZIP-Entpacken → OCI-Upload → ORDS-Trigger) durch einen nativen Quarkus-Backend-Service.

Vorteil:

  • Keine externe Workflow-Engine-Abhängigkeit (n8n)
  • Single-Responsibility: Ein Service für eine Aufgabe (Dateieingang)
  • Bessere Observability (OTLP → Loki/Grafana)
  • Volle Kontrolle über Fehlerbehandlung und Retry-Logik
  • Einfacheres Deployment (JAR statt n8n-Instanz)

Architektur-Überblick

Das Scheduling übernimmt weiterhin die APEX Automation (stündlich). Sie ruft den Quarkus-Service per HTTP POST auf — wie bisher den n8n-Webhook. Der Service selbst hat keinen eigenen Scheduler.

APEX Automation (stündlich)
     │
     ▼ HTTP POST /api/process-incoming  (Header: X-Api-Key)
FileProcessingResource       [Quarkus REST Endpoint]
     │  gibt sofort 202 Accepted zurück (async, fire & forget)
     ▼
FileProcessingPipeline       [Hintergrund-Thread — für jede neue ZIP]
     │
     ├─→ SftpService                  [SSHJ — list, download, rename]
     │
     ├─→ ZipExtractionService         [Apache Commons Compress]
     │
     ├─→ OciUploadService             [OCI SDK — Instance Principal Auth]
     │
     └─→ OrdsNotificationService      [MicroProfile REST Client]
              │
              ▼
         Oracle DB (eingang/, zielordner)

Projektstruktur (Maven)

quarkus-automaton/
├── pom.xml                    (Java 25, Quarkus 3.x LTS)
│
├── src/main/java/de/galabau/
│   │
│   ├── api/
│   │   └── FileProcessingResource.java   (@Path("/api/process-incoming"), @POST, API-Key-Check)
│   │
│   ├── sftp/
│   │   ├── SftpConfig.java               (@ConfigMapping)
│   │   └── SftpService.java              (SSHJ — list, download, rename)
│   │
│   ├── zip/
│   │   └── ZipExtractionService.java     (Apache Commons Compress)
│   │
│   ├── oci/
│   │   ├── OciConfig.java
│   │   └── OciUploadService.java         (OCI SDK, Instance Principal, Marker-Handling)
│   │
│   ├── ords/
│   │   ├── OrdsClient.java               (MicroProfile REST Client)
│   │   └── OrdsNotificationService.java  (Retry via @Retry annotation)
│   │
│   ├── pipeline/
│   │   └── FileProcessingPipeline.java   (Extract → Upload → Notify → Cleanup)
│   │
│   ├── model/
│   │   ├── ProcessingContext.java        (runId, Dateien, Status)
│   │   └── OrdsRequest.java              (DTO)
│   │
│   ├── config/
│   │   └── ApplicationConfig.java        (zentrale @ConfigMapping)
│   │
│   └── exception/
│       ├── SftpException.java
│       ├── ZipException.java
│       ├── OciException.java
│       └── OrdsException.java
│
├── src/main/resources/
│   ├── application.properties
│   └── application-dev.properties
│
└── docs/
    ├── SETUP.md
    ├── Architecture.md
    ├── Configuration.md
    └── ErrorHandling.md

Pipeline-Steps

Step Komponente Bibliothek Beschreibung
api-trigger FileProcessingResource Quarkus REST Empfängt POST von APEX Automation, prüft API-Key, startet Pipeline async
sftp-list SftpService SSHJ Listet *.zip-Dateien im Remote-Verzeichnis
sftp-download SftpService SSHJ Lädt ZIP in lokales Arbeitsverzeichnis
zip-extract ZipExtractionService Apache Commons Compress Entpackt ZIP, preserviert Ordnerstruktur
oci-upload OciUploadService OCI SDK Lädt Dateien + Marker zu OCI Object Storage
sftp-rename SftpService SSHJ Remote-Rename zu .processed oder .error
ords-notify OrdsNotificationService MicroProfile REST Client Ruft ORDS-Endpunkt auf
cleanup FileProcessingPipeline pure Java Löscht lokale Arbeitsdateien (ZIP + entpackte Dateien)

Konfiguration (application.properties)

# API-Absicherung
galabau.api.key=${GALABAU_API_KEY}

# SFTP
galabau.sftp.host=sftp.lieferant.de
galabau.sftp.port=22
galabau.sftp.username=sftp_user
galabau.sftp.password=${GALABAU_SFTP_PASSWORD}
galabau.sftp.host-key-fingerprint=SHA256:AbCdEfGh...   # ssh-keyscan host | ssh-keygen -lf -
galabau.sftp.remote-path=/outgoing
galabau.sftp.local-work-dir=/tmp/sftp-work

# Alternative: Public-Key-Auth (empfohlen für Produktion)
# galabau.sftp.private-key-path=/etc/secrets/sftp-key
# galabau.sftp.private-key-passphrase=${SFTP_KEY_PASSPHRASE}

# OCI Object Storage — Auth via Credentials (Key als gemountetes Kubernetes Secret)
galabau.oci.namespace=mycompany
galabau.oci.region=eu-frankfurt-1
galabau.oci.bucket=my-bucket
galabau.oci.tenant-prefix=mandant_42/
galabau.oci.incoming-prefix=eingang/
# Scalar Credentials aus Env-Vars:
galabau.oci.tenancy-id=${OCI_TENANCY_ID}
galabau.oci.user-id=${OCI_USER_ID}
galabau.oci.fingerprint=${OCI_FINGERPRINT}
# Private Key als gemountetes Kubernetes Secret (Dateipfad, kein Env-Var-String):
galabau.oci.private-key-path=${OCI_PRIVATE_KEY_PATH}   # z.B. /etc/oci/private-key.pem

# ORDS
galabau.ords.base-url=http://ords:8080
galabau.ords.process-incoming-path=/ords/.../net_storage/process_incoming_ba_data
galabau.ords.api-key=${GALABAU_ORDS_API_KEY}

# Fehlerbehandlung
galabau.retry.max-attempts=3
galabau.retry.backoff-ms=1000

Credential-Strategie:

  • Alle Passwörter und API-Keys über ${ENV_VAR_NAME} — Quarkus liest Umgebungsvariablen nativ
  • OCI-Auth via SimpleAuthenticationDetailsProvider — Credentials aus Env-Vars, Private Key als gemountetes Kubernetes Secret (PEM-Datei); entspricht dem was apex_web_service mit OCI Web Credential intern tut (OCI HTTP Signature V1)
  • Deployment: Kubernetes Secrets → Environment Injection für Passwörter/API-Keys

REST Endpoint

@Path("/api/process-incoming")
@ApplicationScoped
public class FileProcessingResource {

    @Inject
    ApplicationConfig config;

    @Inject
    FileProcessingPipeline pipeline;

    @POST
    @Produces(MediaType.APPLICATION_JSON)
    public Response triggerProcessing(@HeaderParam("X-Api-Key") String apiKey) {
        if (!config.api().key().equals(apiKey)) {
            return Response.status(Response.Status.UNAUTHORIZED).build();
        }
        // Async: Pipeline im Hintergrund, APEX bekommt sofort 202
        pipeline.processAllAsync();
        return Response.accepted().build();
    }
}

Aufruf durch APEX Automation:

apex_web_service.make_rest_request(
    p_url         => 'http://backend:8080/api/process-incoming',
    p_http_method => 'POST',
    p_http_headers => apex_util.string_to_table('X-Api-Key:' || <secret>)
);

Concurrency Guard: FileProcessingPipeline hält ein AtomicBoolean isRunning-Flag. Kommt ein zweiter Trigger während eine Pipeline läuft → 409 Conflict zurückgeben, kein doppelter Lauf.

Async-Verhalten

@ApplicationScoped
public class FileProcessingPipeline {

    private final AtomicBoolean isRunning = new AtomicBoolean(false);

    @Inject
    ManagedExecutor executor;  // Quarkus Managed Executor

    public Response processAllAsync() {
        if (!isRunning.compareAndSet(false, true)) {
            return Response.status(409).entity("Pipeline already running").build();
        }
        executor.submit(() -> {
            try {
                processAll();
            } finally {
                isRunning.set(false);
            }
        });
        return Response.accepted().build();
    }

    void processAll() { ... }  // eigentliche Logik
}

Fehler im Hintergrund-Thread landen im Log (OTLP → Grafana) — APEX bekommt sie nicht als HTTP-Fehler, da die Antwort bereits weg ist. Das entspricht dem bisherigen n8n fire-and-forget-Verhalten.

Fehlerbehandlung & Retry

Fehlerklassen

Fehler Typ Retry Verhalten
SFTP-Verbindung fehlgeschlagen transient nein Nächster APEX-Lauf (1h) versucht es
ZIP beschädigt persistent nein ZIP auf SFTP umbenennen zu .error, Log
OCI-Verbindung fehlgeschlagen (z.B. 503) transient ja (exponential backoff) @Retry
OCI-Upload einer Datei schlägt fehl persistent nein SFTP-Rename zu .error, Log — bereits hochgeladene OCI-Dateien bleiben (idempotent)
ORDS-Aufruf schlägt fehl transient ja (2-3x) Marker liegt vor → APEX Automation schlägt beim nächsten Lauf ein
Allgemein technischer Fehler fallabhängig siehe SmallRye Fault Tolerance Exception-Log

Retry-Strategie (SmallRye Fault Tolerance)

@Retry(maxRetries = 3, delay = 1000, delayUnit = ChronoUnit.MILLIS)
@Timeout(value = 10, unit = ChronoUnit.SECONDS)
public void notifyOrds(ProcessingContext context) { ... }

Datenmodelle

ProcessingContext

public class ProcessingContext {
    public UUID runId;                      // eindeutige Lauf-ID
    public String zipFilename;              // z.B. "export_2026-04-08.zip"
    public String zipNameWithoutExt;        // z.B. "export_2026-04-08"
    public Path localZipPath;               // lokale ZIP-Datei (für Cleanup)
    public Path localExtractDir;            // lokales Entpack-Verzeichnis (für Cleanup)
    public List<FileEntry> extractedFiles;  // Verzeichnis + Datei-Namen
    public boolean markerUploaded;
    public LocalDateTime startTime;
    public ProcessingStatus status;
}

public enum ProcessingStatus {
    PENDING, PARTIALLY_UPLOADED, MARKER_UPLOADED, ORDS_NOTIFIED, FAILED
}

FileEntry

public class FileEntry {
    public String relativePath;   // "subdir/file.csv"
    public String ociKey;         // "eingang/export_2026-04-08/subdir/file.csv"
    public long fileSize;
    public boolean isMarker;      // true nur für "_READY_FOR_DB_PROCESSING_"
}

SFTP-Verarbeitung mit SSHJ

Siehe docs/SFTP-Integration.md für Details zur SSHJ-Integration (Host-Key-Verification, Credentials, Fehlerbehandlung).

Verarbeitungslogik

Pipeline.processAll():
    1. SftpService.listZipFiles()           → ["export_2026-04-08.zip", ...]
    2. für jede ZIP:
        a. SftpService.download(zip)         → lokale Datei
        b. ZipExtractionService.extract()    → ProcessingContext mit FileEntry-Liste
        c. OciUploadService.upload()         → Dateien + Marker in OCI
        d. SftpService.renameRemote(.processed oder .error)
        e. OrdsNotificationService.notify()
        f. cleanup: lokale ZIP + Entpack-Verzeichnis löschen  ← immer, auch bei Fehler

Cleanup (Schritt f) läuft immer — in einem finally-Block — damit kein Disk-Vollaufen bei Fehlern oder großen ZIPs.

OCI-Authentifizierung (SimpleAuthenticationDetailsProvider)

Credentials kommen aus Umgebungsvariablen (skalare Werte) und einem gemounteten Kubernetes Secret (Private Key als PEM-Datei).

@ApplicationScoped
public class OciUploadService {

    private final ObjectStorage client;

    @Inject
    OciConfig config;

    @PostConstruct
    void init() {
        SimpleAuthenticationDetailsProvider auth =
            SimpleAuthenticationDetailsProvider.builder()
                .tenantId(config.tenancyId())
                .userId(config.userId())
                .fingerprint(config.fingerprint())
                .region(Region.fromRegionId(config.region()))
                .privateKeySupplier(new FilePrivateKeySupplier(config.privateKeyPath()))
                .build();

        this.client = ObjectStorageClient.builder().build(auth);
    }
}

Kubernetes Deployment:

  • Skalare Werte (tenancyId, userId, fingerprint) → Kubernetes Secret → Env-Vars
  • Private Key PEM-Datei → Kubernetes Secret → Volume Mount unter /etc/oci/private-key.pem
  • OCI_PRIVATE_KEY_PATH=/etc/oci/private-key.pem als Env-Var

ORDS-Integration

REST-Client

@RegisterRestClient(configKey = "ords-client")
public interface OrdsClient {

    @POST
    @Path("${galabau.ords.process-incoming-path}")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    Response processIncoming(ProcessIncomingRequest request);
}

// application.properties:
// quarkus.rest-client.ords-client.url=${galabau.ords.base-url}

public class ProcessIncomingRequest {
    public String zipName;        // "export_2026-04-08"
    public String runId;          // für Logging-Korrelation
    public LocalDateTime uploadedAt;
}

Fehlerbehandlung

  • Schlägt der ORDS-Aufruf fehl → Marker liegt trotzdem vor
  • APEX Automation findet beim nächsten Stundenlauf den Marker und verarbeitet
  • Keine Versuche, den Fehler lokal zu beheben

Abhängigkeiten (pom.xml)

<properties>
    <java.version>25</java.version>
    <quarkus.platform.version><!-- aktuelle LTS auf code.quarkus.io prüfen --></quarkus.platform.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Quarkus Core -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>

    <!-- REST Endpoint (eingehend von APEX) -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest</artifactId>
    </dependency>

    <!-- REST Client (ausgehend zu ORDS) -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest-client-jackson</artifactId>
    </dependency>

    <!-- Managed Executor (für Async-Pipeline) -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-smallrye-context-propagation</artifactId>
    </dependency>

    <!-- SFTP: SSHJ — moderner Java SFTP/SSH Client -->
    <!-- Aktuelle Version prüfen: https://mvnrepository.com/artifact/com.hierynomus/sshj -->
    <dependency>
        <groupId>com.hierynomus</groupId>
        <artifactId>sshj</artifactId>
        <version>0.38.0</version>
    </dependency>

    <!-- OCI Object Storage SDK -->
    <!-- Aktuelle Version prüfen: https://mvnrepository.com/artifact/com.oracle.oci.sdk/oci-java-sdk-objectstorage -->
    <dependency>
        <groupId>com.oracle.oci.sdk</groupId>
        <artifactId>oci-java-sdk-objectstorage</artifactId>
        <version>3.44.0</version>
    </dependency>

    <!-- ZIP -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-compress</artifactId>
        <version>1.26.1</version>
    </dependency>

    <!-- Observability -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-opentelemetry</artifactId>
    </dependency>

    <!-- Fault Tolerance -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
    </dependency>

    <!-- Tests -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-junit5</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Hinweis: oci-java-sdk-objectstorage und sshj liegen nicht im Quarkus BOM — Versionen beim Projektstart auf Maven Central prüfen. Quarkus-eigene Artefakte (quarkus-*) brauchen keine <version>, da das BOM sie bereitstellt.

Observability & Logging

MDC-Hierarchie

runId        → ein ZIP-Verarbeitungslauf (gesetzt am Anfang jeder ZIP)
  step       → aktueller Pipeline-Step
    fileIdx  → welche Datei in diesem Schritt (optional)

MDC nach jeder ZIP mit MDC.clear() leeren — damit kein Kontext in die nächste ZIP sickert.

Log-Level

Schritt Level Beispiel
api-trigger INFO "Processing triggered by APEX, starting async pipeline"
sftp-list INFO "5 new ZIP files found on SFTP"
zip-extract INFO "ZIP 'export_2026-04-08.zip' extracted: 12 files, 5 directories"
oci-upload INFO "Uploaded 12 files + marker to OCI in 3.2s"
ords-notify INFO "ORDS endpoint called, HTTP 200"
cleanup DEBUG "Local files deleted: /tmp/sftp-work/export_2026-04-08.zip"
Fehler ERROR Mit vollem MDC-Context und Exception

Stack: OTLP → Loki/Grafana (Entwicklung: Dev Services, Produktion: externer Collector)

Migrations-Schritte

  1. Phase 1: Entwicklung

    • Projekt-Setup (Java 25, Quarkus 3.x, SSHJ)
    • REST Endpoint (FileProcessingResource) mit API-Key-Auth + Concurrency Guard
    • SFTP-Operationen (SSHJ: list, download, rename) mit Fingerprint-Verification
    • ZIP-Entpacken (Apache Commons Compress)
    • OCI-Upload (OCI SDK, Instance Principal, Marker-Handling)
    • ORDS-Benachrichtigung (REST Client + Retry)
    • Lokaler Cleanup (always in finally)
    • Fehlerbehandlung + OTLP-Logging
    • Package pck_auto_import mit p_process_incoming_files auf DB-Seite implementieren
    • Unit-Tests + Integration-Tests

  2. Phase 2: Testing & Deployment

    • E2E-Tests mit echtem SFTP / OCI / ORDS
    • Parallel-Run: n8n und Quarkus-Backend gleichzeitig aktiv
    • APEX Automation aktualisieren: URL von n8n-Webhook auf http://backend:8080/api/process-incoming ändern, X-Api-Key-Header ergänzen
    • Grafana Dashboards + Alerts aufsetzen

  3. Phase 3: Cutover

    • n8n deaktivieren / entfernen
    • Monitoring etablieren

Deployment-Constraints

  • Einzelinstanz: Der Service läuft als Einzelinstanz. Kein Clustering. Mehrere Instanzen würden dieselben SFTP-Dateien gleichzeitig verarbeiten. Der AtomicBoolean-Guard schützt nur innerhalb einer Instanz. Solange APEX Automation den Webhook nur einmal pro Lauf aufruft, kein Problem.

  • Idempotenz: OCI PUT ist idempotent. Bei abgebrochenem Lauf ohne Marker: nächster Trigger lädt ZIP erneut, Dateien werden überschrieben — kein korrupter Zustand.

  • Disk-Space: Lokales Arbeitsverzeichnis /tmp/sftp-work — Cleanup läuft immer im finally. Maximale gleichzeitige Belegung: eine ZIP + entpackte Dateien (sequenzielle Verarbeitung). Capacity Planning erforderlich (→ offene Frage).

Vorteile gegenüber n8n

Aspekt n8n Quarkus Backend
Abhängigkeiten Externe SaaS/self-hosted Ein JAR
Fehlerbehandlung UI-basiert konfigurieren Java Code, testbar
Observability n8n-Logs + externe Integrationen OTLP → Loki/Grafana nativ
Sicherheit Credentials in n8n-DB Env-Variablen / Secrets
Trigger n8n-Webhook REST Endpoint (identisches Muster)
Wartbarkeit Workflow-Änderungen in UI Code-Reviews, Git-History
Skalierung Horizontale Skalierung komplex Standard Quarkus/Kubernetes

Architektur-Entscheidungen ✅

  • Trigger: REST Endpoint (von APEX Automation aufgerufen, identisch zu bisherigem n8n-Webhook)
  • Scheduling: APEX Automation (bleibt unverändert — kein eigener Scheduler im Service)
  • Async: fire & forget (202 Accepted sofort, Pipeline im Hintergrund — wie n8n)
  • Endpoint-Auth: X-Api-Key Header (einfach, funktioniert mit APEX Web Service Calls)
  • Concurrency Guard: AtomicBoolean (kein Doppellauf bei schnellen APEX-Retries)
  • SFTP-Lösung: SSHJ (com.hierynomus:sshj) — leichtgewichtiger SFTP-Client
  • SFTP Host-Key: Fingerprint-basiert via galabau.sftp.host-key-fingerprint in Config
  • OCI Auth: SimpleAuthenticationDetailsProvider (Credentials via Env-Vars + gemountetes Kubernetes Secret für Private Key — entspricht apex_web_service mit OCI Credential)
  • OCI SDK: OCI Java SDK (HTTP Signature V1 automatisch)
  • ZIP: Apache Commons Compress
  • REST Clients: MicroProfile REST Client (configKey-basiert)
  • Credentials: ${ENV_VAR} in application.properties — Quarkus liest nativ aus Umgebungsvariablen
  • Java: 25
  • Cleanup: immer im finally nach jeder ZIP

Offene Fragen

  • Disk-Space: Wie groß dürfen ZIPs maximal sein? → Capacity Planning
  • SFTP-Auth: Password oder Public-Key für Produktion? → Public-Key empfohlen
  • Monitoring: Welche Grafana-Alerts sind Pflicht? → TBD mit OPS-Team
Reference in New Issue View Git Blame Copy Permalink