@5minds/processcube_app_sdk 8.2.3-develop-17340a-mlmezagc → 8.2.3-develop-d7a750-mnizx1s1

package/README.md

@@ -48,9 +48,192 @@ import { DynamicLink } from '@5minds/processcube_app_sdk/client';
 
 ### External Tasks
 
-External Tasks ermöglichen es, Logik in einer Next.js App auszuführen, die von der ProcessCube Engine als Aufgabe vergeben wird. Dazu wird eine Datei `external_task.ts` (oder `.js`) im `app/`-Verzeichnis der Next.js App angelegt. Der Verzeichnispfad bestimmt das Topic, unter dem die Engine den Task erkennt — z.B. wird `app/order/process/external_task.ts` zum Topic `order/process`.
+External Tasks ermöglichen es, eigene Geschäftslogik in einer Next.js App auszuführen, die von der ProcessCube Engine als Aufgabe vergeben wird. Erreicht ein BPMN-Prozess einen External Service Task, veröffentlicht die Engine diesen unter einem **Topic**. Ein passender Worker in der App holt sich den Task ab, verarbeitet ihn und gibt das Ergebnis zurück.
 
-Die External Tasks werden automatisch erkannt und als eigene Worker-Prozesse gestartet, wenn `useExternalTasks: true` in der SDK-Konfiguration gesetzt ist:
+Das App SDK übernimmt dabei die komplette Infrastruktur: Worker-Prozesse werden automatisch gestartet, überwacht und bei Fehlern neu gestartet. Der Entwickler schreibt nur die eigentliche Handler-Funktion.
+
+#### Architektur
+
+Das folgende Diagramm zeigt die drei beteiligten Schichten und ihre Kommunikation:
+
+```mermaid
+graph LR
+  subgraph ProcessCube Engine
+    E[Engine]
+  end
+
+  subgraph Next.js App – Hauptprozess
+    A[ExternalTaskAdapter]
+    W[File Watcher]
+    T[Token Management]
+  end
+
+  subgraph Eigener Node.js Prozess je Topic
+    WP1[Worker Process<br/>Topic: order/process]
+    WP2[Worker Process<br/>Topic: invoice/send]
+  end
+
+  E -- "HTTP: Fetch & Lock /<br/>Finish / Error /<br/>Extend Lock" --> WP1
+  E -- "HTTP: Fetch & Lock /<br/>Finish / Error /<br/>Extend Lock" --> WP2
+
+  A -- "IPC: create / restart /<br/>updateIdentity" --> WP1
+  A -- "IPC: create / restart /<br/>updateIdentity" --> WP2
+
+  W -- "Dateiänderung erkannt" --> A
+  T -- "Token-Refresh" --> A
+```
+
+**Hauptkomponenten:**
+
+| Komponente | Aufgabe |
+|---|---|
+| **ExternalTaskAdapter** | Läuft im Hauptprozess der Next.js App. Überwacht das Dateisystem, startet Worker-Prozesse, verwaltet Tokens und koordiniert Restarts. |
+| **ExternalTaskWorkerProcess** | Eigenständiger Node.js-Kindprozess (einer pro Topic). Lädt den transpilierten Handler, verbindet sich per HTTP-Long-Polling mit der Engine und verarbeitet Tasks. |
+| **ProcessCube Engine** | Verwaltet BPMN-Prozesse und vergibt External Tasks an Worker über das Fetch-and-Lock-Protokoll. |
+
+#### Lebenszyklus eines External Tasks
+
+Das folgende Sequenzdiagramm zeigt, wie ein External Task von der Engine zum Worker gelangt, verarbeitet und abgeschlossen wird:
+
+```mermaid
+sequenceDiagram
+  participant Engine as ProcessCube Engine
+  participant Worker as Worker Process
+
+  loop Polling-Schleife
+    Worker->>Engine: POST /external_tasks/fetch_and_lock<br/>(workerId, topic, maxTasks, lockDuration)
+    Note right of Engine: Long-Polling — Anfrage wartet<br/>bis Task verfügbar oder Timeout
+    Engine-->>Worker: ExternalTask[] (mit Payload)
+  end
+
+  Note over Worker: Handler-Funktion wird aufgerufen:<br/>handler(payload, task, signal)
+
+  loop Lock-Verlängerung
+    Worker->>Engine: PUT /external_tasks/{id}/extend_lock<br/>(additionalDuration)
+    Note right of Engine: Lock wird verlängert,<br/>damit der Task nicht abläuft
+  end
+
+  alt Erfolg
+    Worker->>Engine: PUT /external_tasks/{id}/finish<br/>(result)
+    Note right of Engine: Ergebnis wird als<br/>Prozessvariable gespeichert
+  else Fehler
+    Worker->>Engine: PUT /external_tasks/{id}/error<br/>(errorCode, errorMessage)
+    Note right of Engine: Fehler wird im<br/>Prozess behandelt
+  end
+```
+
+**Ablauf im Detail:**
+
+1. Der Worker pollt die Engine per HTTP-Long-Polling nach neuen Tasks für sein Topic.
+2. Sobald ein Task verfügbar ist, sperrt die Engine ihn (Lock) und liefert ihn mit dem Payload aus.
+3. Der Worker ruft die Handler-Funktion auf und übergibt Payload, Task-Metadaten und ein AbortSignal.
+4. Während der Verarbeitung verlängert der Worker automatisch den Lock, damit die Engine den Task nicht vorzeitig freigibt.
+5. Nach Abschluss meldet der Worker das Ergebnis (Finish) oder einen Fehler (Error) an die Engine.
+
+#### Worker-Startup und IPC-Kommunikation
+
+Das App SDK startet pro `external_task.ts`-Datei einen eigenen Node.js-Kindprozess. Die Kommunikation zwischen Hauptprozess (Adapter) und Kindprozess (Worker) läuft über IPC (Inter-Process Communication):
+
+```mermaid
+sequenceDiagram
+  participant FS as Dateisystem
+  participant Adapter as ExternalTaskAdapter<br/>(Hauptprozess)
+  participant Worker as Worker Process<br/>(Kindprozess)
+  participant Engine as ProcessCube Engine
+
+  FS->>Adapter: Neue Datei erkannt:<br/>app/order/process/external_task.ts
+
+  Adapter->>Adapter: Datei transpilieren (esbuild)
+  Adapter->>Adapter: Topic ableiten: order/process
+
+  Adapter->>Worker: fork() — neuer Node.js-Prozess
+
+  Adapter->>Worker: IPC: { action: "create",<br/>topic, identity, moduleString }
+
+  Worker->>Worker: Handler-Modul aus String laden
+  Worker->>Engine: Polling starten (Fetch & Lock)
+  Note over Worker,Engine: Worker verarbeitet Tasks…
+
+  Note over FS: Datei wird geändert
+
+  FS->>Adapter: Dateiänderung erkannt
+
+  Adapter->>Adapter: Datei neu transpilieren
+  Adapter->>Worker: IPC: { action: "restart",<br/>topic, identity, moduleString }
+
+  Worker->>Worker: Alten Worker stoppen
+  Worker->>Worker: Neuen Handler laden
+  Worker->>Engine: Polling neu starten
+
+  Note over Adapter: Token läuft ab (85% Lebensdauer)
+
+  Adapter->>Adapter: Neuen Token holen (OpenID Connect)
+  Adapter->>Worker: IPC: { action: "updateIdentity",<br/>identity }
+```
+
+**IPC-Nachrichten:**
+
+| Action | Richtung | Beschreibung |
+|---|---|---|
+| `create` | Adapter → Worker | Initialer Start: Übergibt Topic, Identity und transpilierten Handler-Code |
+| `restart` | Adapter → Worker | Hot-Reload: Stoppt den alten Worker und startet mit neuem Code (gleiche Worker-ID) |
+| `updateIdentity` | Adapter → Worker | Aktualisiert den Auth-Token auf dem laufenden Worker |
+
+#### Fehlerbehandlung und Restart-Strategie
+
+Das System hat zwei Ebenen der Fehlerbehandlung: im Worker-Prozess selbst und im Adapter (Hauptprozess).
+
+```mermaid
+flowchart TD
+  A[Fehler im Worker] --> B{Verbindungsfehler?<br/>ECONNREFUSED / ETIMEDOUT /<br/>ECONNRESET / etc.}
+
+  B -- Ja --> C{Retries < Max?<br/>Standard: 6}
+  C -- Ja --> D[Exponentieller Backoff<br/>1s → 2s → 4s → … → 30s max]
+  D --> E[Erneut verbinden]
+  E --> F{Verbindung OK?}
+  F -- Ja --> G[Weiter arbeiten ✓]
+  F -- Nein --> C
+
+  C -- Nein --> H[Worker beenden<br/>Exit Code 3]
+
+  B -- Nein --> I{Uncaught Exception?}
+  I -- Ja --> J[Worker beenden<br/>Exit Code 4]
+  I -- Nein --> K[Fehler loggen,<br/>Worker beenden<br/>Exit Code 3]
+
+  H --> L[Adapter erkennt Exit]
+  J --> L
+  K --> L
+
+  L --> M{Restarts < 6 in<br/>letzten 5 Minuten?}
+  M -- Ja --> N[Exponentieller Backoff<br/>1s → 2s → 4s → … → 30s max]
+  N --> O[Worker neu starten]
+  O --> P{Start OK?}
+  P -- Ja --> G
+  P -- Nein --> L
+
+  M -- Nein --> Q[Worker bleibt gestoppt ✗<br/>Manueller Eingriff nötig]
+```
+
+**Worker-Level (Kindprozess):**
+
+- Bei Verbindungsfehlern (ECONNREFUSED, ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN, Socket Hang Up) versucht der Worker bis zu **6 Reconnects** mit exponentiellem Backoff (1s → 2s → 4s → 8s → 16s → 30s max).
+- Die Anzahl der Retries ist über die Umgebungsvariable `PROCESSCUBE_APP_SDK_ETW_RETRY` konfigurierbar.
+- Nach Ausschöpfung der Retries beendet sich der Worker mit Exit Code 3.
+- Bei unbehandelten Exceptions beendet sich der Worker mit Exit Code 4.
+
+**Adapter-Level (Hauptprozess):**
+
+- Erkennt der Adapter einen Worker-Exit mit Code 3 oder 4, wird ein Neustart versucht.
+- Maximal **6 Neustarts** innerhalb eines **5-Minuten-Fensters** sind erlaubt.
+- Die Backoff-Zeiten steigen exponentiell: 1s → 2s → 4s → 8s → 16s → 30s.
+- Wird das Limit erreicht, bleibt der Worker gestoppt — ein manueller Eingriff (z.B. App-Neustart) ist nötig.
+- Nach Ablauf des 5-Minuten-Fensters wird der Zähler zurückgesetzt.
+
+#### Setup und Konfiguration
+
+##### 1. Next.js Plugin aktivieren
+
+In der `next.config.js` wird das SDK-Plugin eingebunden und External Tasks aktiviert:
 
 ```javascript
 // next.config.js
@@ -59,53 +242,91 @@ const { withApplicationSdk } = require('@5minds/processcube_app_sdk/server');
 module.exports = withApplicationSdk({
   applicationSdk: {
     useExternalTasks: true,
+    // Optional: Eigenes Verzeichnis für External Tasks
+    // customExternalTasksDirPath: './my-tasks',
   },
 });
 ```
 
+Das Plugin erkennt automatisch, ob die App im Development- oder Production-Modus läuft, und startet die Worker entsprechend. Während des Build-Prozesses (`next build`) werden keine Worker gestartet.
+
+##### 2. Handler-Datei anlegen
+
+External Tasks werden durch Dateien mit dem Namen `external_task.ts` (oder `.js`) definiert. Das Verzeichnis, in dem die Datei liegt, bestimmt automatisch das **Topic**, unter dem sich der Worker bei der Engine registriert.
+
+```
+app/
+├── order/
+│   └── process/
+│       └── external_task.ts    → Topic: order/process
+├── invoice/
+│   └── send/
+│       └── external_task.ts    → Topic: invoice/send
+└── notification/
+    └── email/
+        └── external_task.ts    → Topic: notification/email
+```
+
+Das SDK sucht Handler-Dateien standardmäßig in `./app` oder `./src/app`. Ein eigenes Verzeichnis kann über `customExternalTasksDirPath` konfiguriert werden.
+
+> **Wichtig:** Pro Verzeichnis darf nur eine `external_task.ts` oder `external_task.js` existieren. Beide Dateien im selben Verzeichnis führen zu einem Fehler.
+
 #### Handler-Signatur
 
-Der Handler wird als `default export` exportiert und erhält bis zu drei Parameter:
+Der Handler wird als **Default-Export** der Datei definiert. Er erhält bis zu drei Parameter:
 
 ```typescript
 export default async function handleExternalTask(
-  payload: any, // Prozess-Variablen
-  task: ExternalTask<any>, // Task-Metadaten (optional)
-  signal: AbortSignal, // Abort-Signal (optional)
+  payload: any,
+  task: ExternalTask<any>,
+  signal: AbortSignal,
 ) {
-  // Aufgabe bearbeiten
+  // Geschäftslogik hier
   return { result: 'done' };
 }
 ```
 
-Der Rückgabewert wird als Ergebnis an die Engine zurückgegeben und steht im Prozess als Variable zur Verfügung.
+| Parameter | Typ | Beschreibung |
+|---|---|---|
+| `payload` | `any` | Die Prozessvariablen, die der BPMN-Prozess dem External Task mitgibt. Enthält die im Prozessmodell definierte Payload-Expression. |
+| `task` | `ExternalTask<any>` | Metadaten des Tasks: `id`, `workerId`, `topic`, `correlationId`, `processInstanceId`, `processDefinitionId`, `flowNodeInstanceId`, `lockExpirationTime`, `state`, `createdAt`. Optional. |
+| `signal` | `AbortSignal` | Wird ausgelöst, wenn ein Boundary Event (z.B. Timer) den Task abbricht. Optional. |
 
-#### Konfiguration
+**Rückgabewert:** Das zurückgegebene Objekt wird als Ergebnis an die Engine gemeldet und steht im BPMN-Prozess als Variable zur Verfügung.
 
-Über einen benannten `config`-Export können Worker-Einstellungen angepasst werden:
+#### Worker-Konfiguration
+
+Über einen benannten `config`-Export können Worker-Einstellungen pro Handler angepasst werden:
 
 ```typescript
 import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';
 
 export const config: ExternalTaskConfig = {
-  lockDuration: 5000, // Lock-Dauer in ms (default: 30000)
-  maxTasks: 5, // Gleichzeitige Tasks (default: 10)
+  lockDuration: 5000,   // Lock-Dauer in ms (Standard: 30000)
+  maxTasks: 5,          // Gleichzeitige Tasks pro Polling-Zyklus (Standard: 10)
 };
 ```
 
-Die `lockDuration` bestimmt, wie oft der Worker der Engine signalisiert, dass er noch aktiv ist. Der Standardwert ist 30 Sekunden.
+| Option | Typ | Standard | Beschreibung |
+|---|---|---|---|
+| `lockDuration` | `number` | `30000` | Dauer in Millisekunden, für die ein Task gesperrt wird. Bestimmt auch das Intervall der Lock-Verlängerung und die maximale Verzögerung bei Abort-Signalen. |
+| `maxTasks` | `number` | `10` | Maximale Anzahl gleichzeitig abgeholter Tasks pro Polling-Zyklus. |
 
 #### Abort-Handling bei Boundary Events
 
-Wenn ein Boundary Event (z.B. ein Timer) einen External Task abbricht, wird das `AbortSignal` ausgelöst. Damit der Worker schnell auf den Abbruch reagiert, sollte die `lockDuration` reduziert werden — die Engine kann den Abbruch erst beim nächsten Lock-Renewal mitteilen.
+Wenn ein BPMN Boundary Event (z.B. ein Timer oder Signal) einen External Task abbricht, löst die Engine den Abbruch beim nächsten Lock-Renewal aus. Das `AbortSignal` im Handler wird daraufhin ausgelöst.
+
+**Wichtig:** Die `lockDuration` bestimmt die maximale Verzögerung bis zum Abort, da die Engine den Abbruch erst beim nächsten Lock-Renewal mitteilen kann:
 
-| lockDuration    | Max. Verzögerung bis Abort |
-| --------------- | -------------------------- |
-| 30000 (default) | bis zu 30 Sekunden         |
-| 5000            | bis zu 5 Sekunden          |
-| 1000            | bis zu 1 Sekunde           |
+| lockDuration | Max. Verzögerung bis Abort |
+|---|---|
+| `30000` (Standard) | bis zu 30 Sekunden |
+| `5000` | bis zu 5 Sekunden |
+| `1000` | bis zu 1 Sekunde |
 
-Vollständiges Beispiel mit Abort-Handling:
+Für zeitkritische Abbrüche sollte die `lockDuration` entsprechend reduziert werden.
+
+**Beispiel mit Abort-Handling:**
 
 ```typescript
 import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';
@@ -115,25 +336,133 @@ export const config: ExternalTaskConfig = {
 };
 
 export default async function handleExternalTask(payload: any, _task: any, signal: AbortSignal) {
+  // Listener für Cleanup-Aktionen bei Abbruch
   signal.addEventListener(
     'abort',
     () => {
       console.log('Task wurde durch Boundary Event abgebrochen');
+      // Hier ggf. Ressourcen freigeben
     },
     { once: true },
   );
 
-  // Signal vor und nach asynchronen Operationen prüfen
+  // Signal vor asynchronen Operationen prüfen
   if (signal.aborted) return;
 
   const result = await doWork(payload);
 
+  // Signal nach asynchronen Operationen prüfen
   if (signal.aborted) return;
 
   return result;
 }
 ```
 
+#### Authentifizierung und Token-Management
+
+Ist eine ProcessCube Authority konfiguriert, holt der Adapter automatisch Tokens per **OpenID Connect Client Credentials Grant** und verteilt sie an alle Worker.
+
+```mermaid
+sequenceDiagram
+  participant Authority as OpenID Authority
+  participant Adapter as ExternalTaskAdapter
+  participant W1 as Worker 1
+  participant W2 as Worker 2
+
+  Adapter->>Authority: Client Credentials Grant<br/>(client_id, client_secret, scope: engine_etw)
+  Authority-->>Adapter: TokenSet (access_token, expires_in)
+
+  Adapter->>W1: IPC: create (mit Identity)
+  Adapter->>W2: IPC: create (mit Identity)
+
+  Note over Adapter: Token-Refresh bei 85%<br/>der Lebensdauer
+
+  Adapter->>Authority: Client Credentials Grant (Refresh)
+  Authority-->>Adapter: Neues TokenSet
+
+  Adapter->>W1: IPC: updateIdentity
+  Adapter->>W2: IPC: updateIdentity
+```
+
+- Der Token wird bei **85% seiner Lebensdauer** automatisch erneuert.
+- Alle aktiven Worker erhalten den neuen Token per IPC-Nachricht.
+- Der initiale Token-Abruf hat **10 Versuche** mit exponentiellem Backoff (max. 30s).
+- Der periodische Token-Refresh versucht es **unbegrenzt** mit Backoff (max. 60s).
+- Ist keine Authority konfiguriert, wird eine Dummy-Identity verwendet (für lokale Entwicklung ohne Auth).
+
+#### Umgebungsvariablen
+
+| Variable | Pflicht | Standard | Beschreibung |
+|---|---|---|---|
+| `PROCESSCUBE_ENGINE_URL` | Nein | `http://localhost:10560` | URL der ProcessCube Engine |
+| `PROCESSCUBE_AUTHORITY_URL` | Nein | — | URL des OpenID-Providers. Wenn gesetzt, wird Token-basierte Authentifizierung aktiviert. |
+| `PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID` | Wenn Authority | — | Client-ID für den OpenID Client Credentials Grant |
+| `PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET` | Wenn Authority | — | Client-Secret für den OpenID Client Credentials Grant |
+| `PROCESSCUBE_APP_SDK_ETW_RETRY` | Nein | `6` | Maximale Anzahl der Reconnect-Versuche im Worker-Prozess bei Verbindungsfehlern |
+
+#### Vollständiges Beispiel
+
+Eine `external_task.ts` mit allen Features — Konfiguration, typisiertem Payload, Fehlerbehandlung und Abort-Support:
+
+```typescript
+import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';
+
+// Worker-Konfiguration
+export const config: ExternalTaskConfig = {
+  lockDuration: 5000,  // 5s Lock für schnelle Abort-Reaktion
+  maxTasks: 3,         // Maximal 3 Tasks gleichzeitig
+};
+
+// Typen für Payload und Ergebnis
+interface OrderPayload {
+  orderId: string;
+  customerEmail: string;
+  items: Array<{ productId: string; quantity: number }>;
+}
+
+interface OrderResult {
+  confirmationId: string;
+  processedAt: string;
+}
+
+export default async function handleExternalTask(
+  payload: OrderPayload,
+  task: any,
+  signal: AbortSignal,
+): Promise<OrderResult | undefined> {
+  console.log(`Verarbeite Bestellung ${payload.orderId} (Task: ${task.id})`);
+
+  // Abort-Handler für Cleanup
+  signal.addEventListener(
+    'abort',
+    () => {
+      console.log(`Bestellung ${payload.orderId} wurde abgebrochen`);
+    },
+    { once: true },
+  );
+
+  if (signal.aborted) return;
+
+  // Geschäftslogik
+  const confirmation = await processOrder(payload);
+
+  if (signal.aborted) return;
+
+  await sendConfirmationEmail(payload.customerEmail, confirmation);
+
+  if (signal.aborted) return;
+
+  return {
+    confirmationId: confirmation.id,
+    processedAt: new Date().toISOString(),
+  };
+}
+```
+
+#### Hot-Reload
+
+Im Development-Modus überwacht das SDK die Handler-Dateien per File-Watcher. Änderungen an einer `external_task.ts` werden automatisch erkannt: Die Datei wird neu transpiliert und der Worker per IPC-Nachricht (`restart`) mit dem neuen Code neu gestartet — ohne die App neu starten zu müssen. Die Worker-ID bleibt dabei erhalten.
+
 ## Wie kann ich das Projekt aufsetzen?
 
 ### Setup/Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@5minds/processcube_app_sdk",
-  "version": "8.2.3-develop-17340a-mlmezagc",
+  "version": "8.2.3-develop-d7a750-mnizx1s1",
   "description": "The SDK for ProcessCube Apps",
   "type": "module",
   "main": "build/common/index.cjs",