236 lines
6.5 KiB
Markdown
236 lines
6.5 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"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:**
|
||
|
||
```json
|
||
{
|
||
"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:**
|
||
|
||
```json
|
||
{ "reason": "Manueller Abbruch durch Benutzer" }
|
||
```
|
||
|
||
**Antwort (Erfolg):**
|
||
|
||
```json
|
||
{
|
||
"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):**
|
||
|
||
```json
|
||
{
|
||
"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:**
|
||
|
||
```json
|
||
{
|
||
"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.md#runtime_activity_changed) WebSocket-Event gesendet. Die Frontend-Komponente braucht `GET /api/activities` nur beim initialen Laden aufzurufen.
|