Runtime Activities API¶

Ripster verfolgt alle laufenden und kürzlich abgeschlossenen Aktivitäten (Skripte, Skript-Ketten, Cron-Jobs, interne Tasks) in Echtzeit über den RuntimeActivityService.

Übersicht¶

Aktivitäten entstehen, wenn Ripster intern Aktionen ausführt – z. B. beim Start eines Cron-Jobs, beim Ausführen einer Skript-Kette oder beim Durchlaufen von Pipeline-Schritten. Sie sind nicht persistent (kein DB-Speicher) und werden nur im Arbeitsspeicher gehalten.

Aktive Aktivitäten (active): Laufen gerade.
Letzte Aktivitäten (recent): Abgeschlossen, max. 120 Einträge.

Änderungen werden über WebSocket (RUNTIME_ACTIVITY_CHANGED) in Echtzeit gesendet.

Aktivitäts-Objekt¶

{
  "id": 7,
  "type": "chain",
  "name": "Post-Encode Aufräumen",
  "status": "running",
  "source": "cron",
  "message": "Schritt 2 von 3",
  "currentStep": "cleanup.sh",
  "currentStepType": "script",
  "currentScriptName": "cleanup.sh",
  "stepIndex": 2,
  "stepTotal": 3,
  "parentActivityId": null,
  "jobId": 42,
  "cronJobId": 3,
  "chainId": 5,
  "scriptId": null,
  "canCancel": true,
  "canNextStep": false,
  "outcome": "running",
  "errorMessage": null,
  "output": null,
  "stdout": null,
  "stderr": null,
  "stdoutTruncated": false,
  "stderrTruncated": false,
  "startedAt": "2026-03-10T10:00:00.000Z",
  "finishedAt": null,
  "durationMs": null,
  "exitCode": null,
  "success": null
}

Felder¶

Feld	Typ	Beschreibung
`id`	`number`	Eindeutige ID (Laufzähler, nicht persistent)
`type`	`string`	Art der Aktivität: `script` \| `chain` \| `cron` \| `task`
`name`	`string \\| null`	Anzeigename der Aktivität
`status`	`string`	Aktueller Status: `running` \| `success` \| `error`
`source`	`string \\| null`	Auslöser (z. B. `cron`, `pipeline`, `manual`)
`message`	`string \\| null`	Kurztext zum aktuellen Zustand
`currentStep`	`string \\| null`	Name des aktuell ausgeführten Schritts
`currentStepType`	`string \\| null`	Typ des Schritts (z. B. `script`, `wait`)
`currentScriptName`	`string \\| null`	Name des Skripts im aktuellen Schritt
`stepIndex`	`number \\| null`	Aktueller Schritt (1-basiert)
`stepTotal`	`number \\| null`	Gesamtanzahl Schritte
`parentActivityId`	`number \\| null`	ID der übergeordneten Aktivität
`jobId`	`number \\| null`	Verknüpfte Job-ID
`cronJobId`	`number \\| null`	Verknüpfte Cron-Job-ID
`chainId`	`number \\| null`	Verknüpfte Skript-Ketten-ID
`scriptId`	`number \\| null`	Verknüpfte Skript-ID
`canCancel`	`boolean`	Abbrechen über API möglich
`canNextStep`	`boolean`	Nächster Schritt über API auslösbar
`outcome`	`string \\| null`	Abschluss-Ergebnis: `success` \| `error` \| `cancelled` \| `skipped` \| `running`
`errorMessage`	`string \\| null`	Fehlermeldung (max. 2.000 Zeichen)
`output`	`string \\| null`	Allgemeine Ausgabe (max. 12.000 Zeichen)
`stdout`	`string \\| null`	Standardausgabe des Prozesses (max. 12.000 Zeichen)
`stderr`	`string \\| null`	Fehlerausgabe des Prozesses (max. 12.000 Zeichen)
`stdoutTruncated`	`boolean`	`true`, wenn `stdout` gekürzt wurde
`stderrTruncated`	`boolean`	`true`, wenn `stderr` gekürzt wurde
`startedAt`	`string`	ISO-8601-Zeitstempel des Starts
`finishedAt`	`string \\| null`	ISO-8601-Zeitstempel des Endes
`durationMs`	`number \\| null`	Laufzeit in Millisekunden
`exitCode`	`number \\| null`	Exit-Code des Prozesses
`success`	`boolean \\| null`	Erfolgsstatus (`null` bei laufender Aktivität)

Snapshot-Objekt¶

Alle Aktivitäts-Endpunkte geben einen Snapshot zurück:

{
  "active": [ /* laufende Aktivitäten, nach startedAt absteigend */ ],
  "recent": [ /* abgeschlossene Aktivitäten, nach finishedAt absteigend, max. 120 */ ],
  "updatedAt": "2026-03-10T10:05:00.000Z"
}

Endpunkte¶

GET `/api/activities`¶

Aktuellen Aktivitäts-Snapshot abrufen.

Antwort:

{
  "active": [],
  "recent": [
    {
      "id": 5,
      "type": "script",
      "name": "notify.sh",
      "status": "success",
      "outcome": "success",
      "startedAt": "2026-03-10T09:58:00.000Z",
      "finishedAt": "2026-03-10T09:58:02.000Z",
      "durationMs": 2100,
      "exitCode": 0,
      "success": true,
      "canCancel": false,
      "canNextStep": false
    }
  ],
  "updatedAt": "2026-03-10T10:05:00.000Z"
}

POST `/api/activities/:id/cancel`¶

Aktive Aktivität abbrechen (nur wenn canCancel: true).

Parameter:

Name	In	Typ	Beschreibung
`id`	path	`number`	Aktivitäts-ID
`reason`	body	`string`	Optionaler Abbruchgrund

Request Body:

{ "reason": "Manueller Abbruch durch Benutzer" }

Antwort (Erfolg):

{
  "ok": true,
  "action": null,
  "snapshot": { "active": [], "recent": [], "updatedAt": "..." }
}

Fehlercodes:

HTTP	Bedeutung
`404`	Aktivität nicht gefunden oder bereits abgeschlossen
`409`	Abbrechen wird von dieser Aktivität nicht unterstützt

POST `/api/activities/:id/next-step`¶

Nächsten Schritt einer Aktivität auslösen (nur wenn canNextStep: true).

Parameter:

Name	In	Typ	Beschreibung
`id`	path	`number`	Aktivitäts-ID

Antwort (Erfolg):

{
  "ok": true,
  "action": null,
  "snapshot": { "active": [], "recent": [], "updatedAt": "..." }
}

Fehlercodes:

HTTP	Bedeutung
`404`	Aktivität nicht gefunden
`409`	Nächster Schritt wird von dieser Aktivität nicht unterstützt

POST `/api/activities/clear-recent`¶

Alle abgeschlossenen Aktivitäten aus recent löschen.

Antwort:

{
  "ok": true,
  "removed": 14,
  "snapshot": { "active": [], "recent": [], "updatedAt": "..." }
}

Grenzwerte¶

Wert	Limit
Maximale `recent`-Einträge	120
Maximale Länge `stdout` / `stderr` / `output`	12.000 Zeichen
Maximale Länge `errorMessage` / `message`	2.000 Zeichen
Maximale Länge `outcome`	40 Zeichen

Gekürzte Ausgaben erhalten den Suffix ...[gekürzt] (bei Inline-Text) bzw. \n...[gekürzt] (bei mehrzeiligem Output).

Echtzeit-Updates¶

Änderungen werden automatisch als RUNTIME_ACTIVITY_CHANGED WebSocket-Event gesendet. Die Frontend-Komponente braucht GET /api/activities nur beim initialen Laden aufzurufen.