Plugin-System

Das Plugin-System ist die zentrale Erweiterungsschnittstelle von Cuby. Jedes Produkt ist technisch ein Plugin, das über definierte Lifecycle-Methoden installiert, konfiguriert, gestartet und gestoppt wird.

Plugin-Namenskonvention

Plugins folgen dem npm-Paket-Muster: @processcube/[name].cuby

Beispiel: @processcube/engine.cuby, @processcube/ticketpilot.cuby

Plugin-Lifecycle

Plugin-Interface

Jedes Plugin exportiert folgende Methoden:


{
  // Route-Registrierung (Main-Thread)
  init(router, cuby, context) {},
 
  // Lifecycle-Methoden (Worker-Prozess)
  deploy(productDir, config, onProgress, cuby, context) {},
  start(productDir, cuby, context) {},
  stop(cuby, context) {},
  undeploy(productDir, cuby, context) {},
 
  // Konfiguration
  getConfig() {}
}

Ausführungsorte

Phase	Ausführungsort	Beschreibung
`init()`	Main-Thread (PluginLoader)	Route-Registrierung, Socket.IO-Events
`deploy()`	Worker-Prozess (Node.js v22)	Artefakte deployen, Konfiguration anwenden
`start()`	Worker-Prozess (Node.js v22)	Prozess starten, Ressourcen verbinden
`stop()`	Worker-Prozess (Node.js v22)	Graceful Shutdown, Ressourcen freigeben
`undeploy()`	Worker-Prozess (Node.js v22)	Artefakte entfernen, Cleanup

Plugin-Routes

Plugins können eigene API-Endpunkte registrieren:


init(router, cuby, context) {
  router.get('/status', (req) => {
    return Response.json({ status: 'ok' });
  });
 
  router.post('/action', async (req) => {
    const body = await req.json();
    return Response.json({ success: true });
  });
}

Die Routes sind erreichbar unter: /api/plugins/{instanceId}/{route}

Router-Methoden

Methode	Beschreibung
`router.get(pattern, handler)`	GET-Route registrieren
`router.post(pattern, handler)`	POST-Route registrieren
`router.put(pattern, handler)`	PUT-Route registrieren
`router.delete(pattern, handler)`	DELETE-Route registrieren

Handler-Signatur: (request: Request) => Response | Promise<Response>

Cuby-Kontext API

Plugins erhalten einen cuby-Kontext mit folgenden Methoden:

ProcessCube®-Verwaltung

Methode	Beschreibung
`registerProcessCube(opts)`	Engine/LowCode/Authority-Instanz registrieren
`getProcessCubes()`	Alle registrierten Instanzen abrufen
`setProcessCubeConfig(pcId, config)`	Konfiguration für eine ProcessCube®-Instanz setzen
`getProcessCubeConfig(pcId)`	Konfiguration einer ProcessCube®-Instanz lesen
`removeProcessCubeConfig(pcId)`	Konfiguration entfernen

Port-Management

Methode	Beschreibung
`reservePort(desiredPort)`	Port für das Plugin reservieren
`releasePort(port)`	Port freigeben

Secrets

Methode	Beschreibung
`getSecret(name)`	Plugin-Secret lesen (scoped auf instanceId)
`setSecret(name, value)`	Plugin-Secret speichern
`deleteSecret(name)`	Plugin-Secret entfernen

Deployment

Methode	Beschreibung
`deployProcesses(pcId, dir, strategy)`	BPMN-Prozesse zur Engine deployen
`undeployProcesses(pcId, dir)`	BPMN-Prozesse entfernen
`deployFlows(pcId, dir, url)`	Node-RED Flows zu LowCode deployen
`undeployFlows(pcId, dir, url)`	Node-RED Flows entfernen

Authority / OAuth

Methode	Beschreibung
`createExternalTaskWorker(pcId, data)`	External Task Worker in Authority anlegen
`deleteExternalTaskWorker(pcId, clientId)`	External Task Worker entfernen
`createOtherClient(pcId, data)`	OAuth-Client in Authority anlegen
`deleteOtherClient(pcId, clientId)`	OAuth-Client entfernen

Federation

Methode	Beschreibung
`registerCuby(url, apiKey)`	Sub-Cuby-Instanz registrieren

Konfigurations-Komponente

Plugins können eine React-Komponente für den Konfigurationsdialog bereitstellen:

Datei: config-component.js im Paketverzeichnis
Format: ES-Modul mit Default-Export
Rendering: Wird im Browser als React-Komponente geladen

Props

Prop	Typ	Beschreibung
`config`	`object`	Aktueller Konfigurationszustand
`onChange`	`function`	Callback um Konfiguration zu ändern
`product`	`object`	Produkt-Informationen (id, name, version)

Beispiel


function ConfigComponent({ config, onChange, product }) {
  const [value, setValue] = useState(config.value || '');
 
  useEffect(() => {
    onChange({ value });
  }, [value]);
 
  return (
    <div>
      <label>Einstellung:</label>
      <input value={value} onChange={(e) => setValue(e.target.value)} />
    </div>
  );
}
 
export default ConfigComponent;

Hinweise:

React ist über die Shims verfügbar (gleiche Instanz wie Host)
Tailwind CSS Klassen sind verfügbar
Kein Bundling nötig — die Datei wird direkt geladen

Detail-Komponente

Plugins können eine React-Komponente für die Detail-Ansicht bereitstellen:

Datei: detail-component.js im Paketverzeichnis
Wird auf der Produkt-Detail-Seite eingebettet
Gleiche Lademechanik wie die Konfigurations-Komponente

Worker-Architektur

Lifecycle-Methoden laufen in separaten Node.js-Child-Prozessen (nicht im Bun-Hauptprozess):

Grund: Die kompilierte Bun-Binary löst transitive Dependencies bei dynamischem import() nicht korrekt auf
Worker-Skript: Wird als .cuby-worker.mjs ins Produktverzeichnis geschrieben und mit dem verwalteten Node.js (v22) ausgeführt
Kommunikation: JSON-Lines-Protokoll über stdin/stdout
RPC: Cuby-Methoden-Aufrufe werden vom Worker über das Protokoll an den Main-Thread weitergeleitet
Logs: Jede Lifecycle-Methode schreibt eine eigene Log-Datei (deploy.log, start.log, etc.)

Socket.IO Plugin-Namespaces

Plugins können eigene Socket.IO-Events über dedizierte Namespaces registrieren:

Namespace-Pfad: /plugins/<instanceId> (URL-encoded)
Registrierung: In init() via router.onSocket(event, handler) und router.emitSocket(event, data, options?)
Auth: Die Socket.IO-Auth-Middleware wird automatisch auf Plugin-Namespaces angewandt
Cleanup: Namespace wird bei Stop, Deinstallation oder Crash automatisch entfernt und bei Auto-Restart neu erstellt

ProcessCube®-Integration

Plugins können sich mit ProcessCube® Engine- und LowCode-Instanzen verbinden:

Plugin ruft cuby.registerProcessCube() mit Engine-URL, LowCode-URL(s) und optionalen Auth-Daten auf
Cuby wartet auf Health-Check der Instanz (bis zu 30 Versuche, je 2 Sekunden)
Bei Authority-Konfiguration wird ein OAuth2-Token abgerufen
Socket.IO-Verbindung zum LowCode-Endpoint /cuby wird hergestellt
Konfigurationsaustausch über cuby:get, cuby:keys, cuby:update Events

Weiterführend

Plugin-Entwicklung — Schritt-für-Schritt-Anleitung für eigene Plugins
App SDK — SDK für die Entwicklung von ProcessCube®-Anwendungen mit Next.js