Test
This commit is contained in:
243
docs/api/crons.md
Normal file
243
docs/api/crons.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## Endpunkte
|
||||
|
||||
### `GET /api/crons`
|
||||
|
||||
Alle konfigurierten Cron-Jobs auflisten.
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{
|
||||
"jobs": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Nachtlauf Backup",
|
||||
"cronExpression": "0 2 * * *",
|
||||
"sourceType": "script",
|
||||
"sourceId": 3,
|
||||
"enabled": true,
|
||||
"pushoverEnabled": true,
|
||||
"lastRunAt": "2026-03-09T02:00:00.000Z",
|
||||
"lastRunStatus": "success",
|
||||
"nextRunAt": "2026-03-10T02:00:00.000Z",
|
||||
"createdAt": "2026-03-01T10:00:00.000Z",
|
||||
"updatedAt": "2026-03-09T02:00:00.000Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/crons`
|
||||
|
||||
Neuen Cron-Job anlegen.
|
||||
|
||||
**Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Nachtlauf Backup",
|
||||
"cronExpression": "0 2 * * *",
|
||||
"sourceType": "script",
|
||||
"sourceId": 3,
|
||||
"enabled": true,
|
||||
"pushoverEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
| 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`) |
|
||||
|
||||
**Antwort:** `201 Created`
|
||||
|
||||
```json
|
||||
{ "job": { ... } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/crons/:id`
|
||||
|
||||
Einzelnen Cron-Job abrufen.
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{ "job": { ... } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `PUT /api/crons/:id`
|
||||
|
||||
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.
|
||||
|
||||
**Query-Parameter:**
|
||||
|
||||
| Parameter | Typ | Default | Beschreibung |
|
||||
|-----------|-----|---------|-------------|
|
||||
| `limit` | number | 20 | Anzahl Einträge (max. 100) |
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{
|
||||
"logs": [
|
||||
{
|
||||
"id": 42,
|
||||
"cronJobId": 1,
|
||||
"startedAt": "2026-03-09T02:00:01.000Z",
|
||||
"finishedAt": "2026-03-09T02:00:05.000Z",
|
||||
"status": "success",
|
||||
"exitCode": 0,
|
||||
"stdout": "Backup abgeschlossen.",
|
||||
"stderr": "",
|
||||
"triggeredBy": "cron"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Feld | Beschreibung |
|
||||
|------|-------------|
|
||||
| `status` | `"success"`, `"error"` oder `"running"` |
|
||||
| `triggeredBy` | `"cron"` (zeitgesteuert) oder `"manual"` (manuell ausgelöst) |
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/crons/:id/run`
|
||||
|
||||
Cron-Job sofort manuell auslösen (unabhängig vom Zeitplan).
|
||||
|
||||
**Antwort:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"exitCode": 0,
|
||||
"stdout": "...",
|
||||
"stderr": ""
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/crons/validate-expression`
|
||||
|
||||
Cron-Ausdruck validieren und nächsten Ausführungszeitpunkt berechnen.
|
||||
|
||||
**Body:**
|
||||
|
||||
```json
|
||||
{ "cronExpression": "*/15 * * * *" }
|
||||
```
|
||||
|
||||
**Antwort (gültig):**
|
||||
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"nextRunAt": "2026-03-09T14:15:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Antwort (ungültig):**
|
||||
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"error": "Cron-Ausdruck muss genau 5 Felder haben (Minute Stunde Tag Monat Wochentag).",
|
||||
"nextRunAt": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cron-Expression-Format
|
||||
|
||||
Ripster verwendet **5-Felder-Cron-Ausdrücke** (kein Sekunden-Feld):
|
||||
|
||||
```
|
||||
┌───────────── Minute (0-59)
|
||||
│ ┌────────── Stunde (0-23)
|
||||
│ │ ┌─────── Tag (1-31)
|
||||
│ │ │ ┌──── Monat (1-12)
|
||||
│ │ │ │ ┌─ Wochentag (0-7, 0 und 7 = Sonntag)
|
||||
│ │ │ │ │
|
||||
* * * * *
|
||||
```
|
||||
|
||||
### 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` |
|
||||
|
||||
---
|
||||
|
||||
## WebSocket-Event
|
||||
|
||||
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"`.
|
||||
@@ -42,6 +42,14 @@ Konfigurierbar über die Umgebungsvariable `PORT`.
|
||||
|
||||
[:octicons-arrow-right-24: History API](history.md)
|
||||
|
||||
- :material-clock-outline: **Cron API**
|
||||
|
||||
---
|
||||
|
||||
Cron-Jobs verwalten, manuell auslösen und Ausführungs-Logs abrufen.
|
||||
|
||||
[:octicons-arrow-right-24: Cron API](crons.md)
|
||||
|
||||
- :material-lightning-bolt: **WebSocket Events**
|
||||
|
||||
---
|
||||
|
||||
@@ -113,12 +113,19 @@ Disc erkannt.
|
||||
"payload": {
|
||||
"device": {
|
||||
"path": "/dev/sr0",
|
||||
"discLabel": "INCEPTION"
|
||||
"discLabel": "INCEPTION",
|
||||
"label": "INCEPTION",
|
||||
"model": "ASUS BW-16D1HT",
|
||||
"fstype": "udf",
|
||||
"mountpoint": null,
|
||||
"mediaProfile": "bluray"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`mediaProfile` ist `"bluray"`, `"dvd"`, `"other"` oder `null` (wenn nicht bestimmbar). Der Wert wird aus Dateisystemtyp (UDF/ISO9660), Laufwerk-Modell und Disc-Label abgeleitet.
|
||||
|
||||
### DISC_REMOVED
|
||||
|
||||
Disc entfernt.
|
||||
@@ -160,6 +167,22 @@ Fehler im Laufwerkserkennungsdienst.
|
||||
}
|
||||
```
|
||||
|
||||
### CRON_JOBS_UPDATED
|
||||
|
||||
Wird gesendet, wenn ein Cron-Job angelegt, aktualisiert oder gelöscht wurde.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "CRON_JOBS_UPDATED",
|
||||
"payload": {
|
||||
"action": "created",
|
||||
"id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`action` ist `"created"`, `"updated"` oder `"deleted"`.
|
||||
|
||||
---
|
||||
|
||||
## Reconnect-Verhalten
|
||||
|
||||
Reference in New Issue
Block a user