Bugfix and Docs
This commit is contained in:
@@ -1,16 +1,12 @@
|
||||
# Cron API
|
||||
|
||||
Ripster enthält ein eingebautes Cron-System, mit dem **Skripte** und **Skript-Ketten** zeitgesteuert oder manuell ausgeführt werden können. Der Cron-Dienst benötigt keine externen Pakete – der Cron-Expression-Parser ist vollständig im Backend implementiert.
|
||||
Ripster enthält ein eingebautes Cron-System für Skripte und Skript-Ketten (`sourceType: script|chain`).
|
||||
|
||||
---
|
||||
|
||||
## Endpunkte
|
||||
## GET /api/crons
|
||||
|
||||
### `GET /api/crons`
|
||||
|
||||
Alle konfigurierten Cron-Jobs auflisten.
|
||||
|
||||
**Antwort:**
|
||||
Listet alle Cron-Jobs.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -21,13 +17,14 @@ Alle konfigurierten Cron-Jobs auflisten.
|
||||
"cronExpression": "0 2 * * *",
|
||||
"sourceType": "script",
|
||||
"sourceId": 3,
|
||||
"sourceName": "Backup-Skript",
|
||||
"enabled": true,
|
||||
"pushoverEnabled": true,
|
||||
"lastRunAt": "2026-03-09T02:00:00.000Z",
|
||||
"lastRunAt": "2026-03-10T02:00:00.000Z",
|
||||
"lastRunStatus": "success",
|
||||
"nextRunAt": "2026-03-10T02:00:00.000Z",
|
||||
"nextRunAt": "2026-03-11T02:00:00.000Z",
|
||||
"createdAt": "2026-03-01T10:00:00.000Z",
|
||||
"updatedAt": "2026-03-09T02:00:00.000Z"
|
||||
"updatedAt": "2026-03-10T02:00:05.000Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -35,11 +32,9 @@ Alle konfigurierten Cron-Jobs auflisten.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/crons`
|
||||
## POST /api/crons
|
||||
|
||||
Neuen Cron-Job anlegen.
|
||||
|
||||
**Body:**
|
||||
Erstellt Cron-Job.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -52,16 +47,25 @@ Neuen Cron-Job anlegen.
|
||||
}
|
||||
```
|
||||
|
||||
| Feld | Typ | Pflicht | Beschreibung |
|
||||
|------|-----|---------|-------------|
|
||||
| `name` | string | ✓ | Anzeigename |
|
||||
| `cronExpression` | string | ✓ | 5-Felder-Cron-Ausdruck (Minute Stunde Tag Monat Wochentag) |
|
||||
| `sourceType` | string | ✓ | `"script"` oder `"chain"` |
|
||||
| `sourceId` | number | ✓ | ID des Skripts bzw. der Kette |
|
||||
| `enabled` | boolean | – | Aktiviert (default: `true`) |
|
||||
| `pushoverEnabled` | boolean | – | PushOver-Benachrichtigung nach Ausführung (default: `true`) |
|
||||
Response: `201` mit `{ "job": { ... } }`
|
||||
|
||||
**Antwort:** `201 Created`
|
||||
---
|
||||
|
||||
## GET /api/crons/:id
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "job": { "id": 1, "name": "..." } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PUT /api/crons/:id
|
||||
|
||||
Aktualisiert Cron-Job. Felder wie bei `POST`.
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "job": { ... } }
|
||||
@@ -69,53 +73,27 @@ Neuen Cron-Job anlegen.
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/crons/:id`
|
||||
## DELETE /api/crons/:id
|
||||
|
||||
Einzelnen Cron-Job abrufen.
|
||||
|
||||
**Antwort:**
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "job": { ... } }
|
||||
{ "removed": { "id": 1, "name": "Nachtlauf Backup" } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `PUT /api/crons/:id`
|
||||
## GET /api/crons/:id/logs
|
||||
|
||||
Cron-Job aktualisieren. Body-Felder entsprechen `POST /api/crons`.
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "job": { ... } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `DELETE /api/crons/:id`
|
||||
|
||||
Cron-Job löschen.
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "removed": { "id": 1 } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/crons/:id/logs`
|
||||
|
||||
Ausführungs-Logs eines Cron-Jobs abrufen.
|
||||
Liefert Ausführungs-Logs.
|
||||
|
||||
**Query-Parameter:**
|
||||
|
||||
| Parameter | Typ | Default | Beschreibung |
|
||||
|-----------|-----|---------|-------------|
|
||||
| `limit` | number | 20 | Anzahl Einträge (max. 100) |
|
||||
| `limit` | number | `20` | Anzahl Einträge, max. `100` |
|
||||
|
||||
**Antwort:**
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -123,62 +101,54 @@ Ausführungs-Logs eines Cron-Jobs abrufen.
|
||||
{
|
||||
"id": 42,
|
||||
"cronJobId": 1,
|
||||
"startedAt": "2026-03-09T02:00:01.000Z",
|
||||
"finishedAt": "2026-03-09T02:00:05.000Z",
|
||||
"startedAt": "2026-03-10T02:00:01.000Z",
|
||||
"finishedAt": "2026-03-10T02:00:05.000Z",
|
||||
"status": "success",
|
||||
"exitCode": 0,
|
||||
"stdout": "Backup abgeschlossen.",
|
||||
"stderr": "",
|
||||
"triggeredBy": "cron"
|
||||
"output": "Backup abgeschlossen.",
|
||||
"errorMessage": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Feld | Beschreibung |
|
||||
|------|-------------|
|
||||
| `status` | `"success"`, `"error"` oder `"running"` |
|
||||
| `triggeredBy` | `"cron"` (zeitgesteuert) oder `"manual"` (manuell ausgelöst) |
|
||||
`status`: `running` | `success` | `error`
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/crons/:id/run`
|
||||
## POST /api/crons/:id/run
|
||||
|
||||
Cron-Job sofort manuell auslösen (unabhängig vom Zeitplan).
|
||||
Triggert Job manuell (asynchron).
|
||||
|
||||
**Antwort:**
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"exitCode": 0,
|
||||
"stdout": "...",
|
||||
"stderr": ""
|
||||
}
|
||||
{ "triggered": true, "cronJobId": 1 }
|
||||
```
|
||||
|
||||
Wenn Job bereits läuft: `409`.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/crons/validate-expression`
|
||||
## POST /api/crons/validate-expression
|
||||
|
||||
Cron-Ausdruck validieren und nächsten Ausführungszeitpunkt berechnen.
|
||||
Validiert 5-Felder-Cron-Ausdruck und berechnet nächsten Lauf.
|
||||
|
||||
**Body:**
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{ "cronExpression": "*/15 * * * *" }
|
||||
```
|
||||
|
||||
**Antwort (gültig):**
|
||||
**Gültige Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"nextRunAt": "2026-03-09T14:15:00.000Z"
|
||||
"nextRunAt": "2026-03-10T14:15:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Antwort (ungültig):**
|
||||
**Ungültige Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -190,54 +160,23 @@ Cron-Ausdruck validieren und nächsten Ausführungszeitpunkt berechnen.
|
||||
|
||||
---
|
||||
|
||||
## Cron-Expression-Format
|
||||
## Cron-Format
|
||||
|
||||
Ripster verwendet **5-Felder-Cron-Ausdrücke** (kein Sekunden-Feld):
|
||||
Ripster unterstützt 5 Felder:
|
||||
|
||||
```
|
||||
┌───────────── Minute (0-59)
|
||||
│ ┌────────── Stunde (0-23)
|
||||
│ │ ┌─────── Tag (1-31)
|
||||
│ │ │ ┌──── Monat (1-12)
|
||||
│ │ │ │ ┌─ Wochentag (0-7, 0 und 7 = Sonntag)
|
||||
│ │ │ │ │
|
||||
* * * * *
|
||||
```text
|
||||
Minute Stunde Tag Monat Wochentag
|
||||
```
|
||||
|
||||
### Beispiele
|
||||
Beispiele:
|
||||
|
||||
| Ausdruck | Beschreibung |
|
||||
|----------|-------------|
|
||||
| `0 2 * * *` | Täglich um 02:00 Uhr |
|
||||
| `*/15 * * * *` | Alle 15 Minuten |
|
||||
| `0 6 * * 1-5` | Montag–Freitag um 06:00 Uhr |
|
||||
| `30 23 * * 0` | Sonntags um 23:30 Uhr |
|
||||
| `0 0 1 * *` | Erster Tag des Monats um Mitternacht |
|
||||
|
||||
### Unterstützte Syntax
|
||||
|
||||
| Syntax | Bedeutung |
|
||||
|--------|----------|
|
||||
| `*` | Jeder Wert |
|
||||
| `*/n` | Jeder n-te Wert (Step) |
|
||||
| `a-b` | Bereich von a bis b |
|
||||
| `a,b,c` | Liste von Werten |
|
||||
| Kombinierbar | z. B. `1,5-10,*/3` |
|
||||
- `0 2 * * *` täglich 02:00
|
||||
- `*/15 * * * *` alle 15 Minuten
|
||||
- `0 6 * * 1-5` Mo-Fr 06:00
|
||||
|
||||
---
|
||||
|
||||
## WebSocket-Event
|
||||
## WebSocket-Events zu Cron
|
||||
|
||||
Bei Änderungen an Cron-Jobs (Anlegen, Aktualisieren, Löschen) wird ein `CRON_JOBS_UPDATED`-Event gesendet:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "CRON_JOBS_UPDATED",
|
||||
"payload": {
|
||||
"action": "created",
|
||||
"id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`action` ist `"created"`, `"updated"` oder `"deleted"`.
|
||||
- `CRON_JOBS_UPDATED` bei Create/Update/Delete
|
||||
- `CRON_JOB_UPDATED` bei Laufzeitstatus (`running` -> `success|error`)
|
||||
|
||||
Reference in New Issue
Block a user