Initial commit mit MkDocs-Dokumentation
This commit is contained in:
221
docs/architecture/backend.md
Normal file
221
docs/architecture/backend.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# Backend-Services
|
||||
|
||||
Das Backend ist in Node.js/Express geschrieben und in **Services** aufgeteilt, die jeweils eine klar abgegrenzte Verantwortlichkeit haben.
|
||||
|
||||
---
|
||||
|
||||
## pipelineService.js
|
||||
|
||||
**Der Kern von Ripster** – orchestriert den gesamten Ripping-Workflow.
|
||||
|
||||
### Zuständigkeiten
|
||||
|
||||
- Verwaltung des Pipeline-Zustands als State Machine
|
||||
- Koordination zwischen allen externen Tools
|
||||
- Generierung von Encode-Plänen
|
||||
- Fehlerbehandlung und Recovery
|
||||
|
||||
### Haupt-Methoden
|
||||
|
||||
| Methode | Beschreibung |
|
||||
|---------|-------------|
|
||||
| `analyzeDisc()` | Startet MakeMKV-Analyse der eingelegten Disc |
|
||||
| `selectMetadata(jobId, omdbData, playlist)` | Setzt Metadaten und Playlist für einen Job |
|
||||
| `startJob(jobId)` | Startet den Ripping-Prozess |
|
||||
| `confirmEncode(jobId, trackSelection)` | Bestätigt Encode mit Track-Auswahl |
|
||||
| `cancelPipeline()` | Bricht aktiven Prozess ab |
|
||||
| `retryJob(jobId)` | Wiederholt fehlgeschlagenen Job |
|
||||
| `reencodeJob(jobId)` | Encodiert bestehende Raw-MKV neu |
|
||||
|
||||
### Zustandsübergänge
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> IDLE
|
||||
IDLE --> ANALYZING: analyzeDisc()
|
||||
ANALYZING --> METADATA_SELECTION: MakeMKV fertig
|
||||
METADATA_SELECTION --> READY_TO_START: selectMetadata()
|
||||
READY_TO_START --> RIPPING: startJob()
|
||||
RIPPING --> MEDIAINFO_CHECK: MKV erstellt
|
||||
MEDIAINFO_CHECK --> READY_TO_ENCODE: Tracks analysiert
|
||||
READY_TO_ENCODE --> ENCODING: confirmEncode()
|
||||
ENCODING --> FINISHED: HandBrake fertig
|
||||
ENCODING --> ERROR: Fehler
|
||||
RIPPING --> ERROR: Fehler
|
||||
ERROR --> IDLE: retryJob() / cancel
|
||||
FINISHED --> IDLE: cancel / neue Disc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## diskDetectionService.js
|
||||
|
||||
Überwacht das Disc-Laufwerk auf Disc-Einleger- und Auswurf-Ereignisse.
|
||||
|
||||
### Modi
|
||||
|
||||
| Modus | Beschreibung |
|
||||
|------|-------------|
|
||||
| `auto` | Erkennt verfügbare Laufwerke automatisch |
|
||||
| `explicit` | Überwacht ein bestimmtes Gerät (z.B. `/dev/sr0`) |
|
||||
|
||||
### Polling
|
||||
|
||||
Der Service pollt das Laufwerk im konfigurierten Intervall (`disc_poll_interval_ms`, Standard: 5000ms) und emittiert Events:
|
||||
|
||||
```js
|
||||
// Ereignisse
|
||||
emit('disc-detected', { device: '/dev/sr0' })
|
||||
emit('disc-removed', { device: '/dev/sr0' })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## processRunner.js
|
||||
|
||||
Verwaltet externe CLI-Prozesse.
|
||||
|
||||
### Features
|
||||
|
||||
- **Streaming**: stdout/stderr werden zeilenweise gelesen
|
||||
- **Progress-Callbacks**: Ermöglicht Echtzeit-Fortschrittsanzeige
|
||||
- **Graceful Shutdown**: SIGINT → Warte-Timeout → SIGKILL
|
||||
- **Prozess-Registry**: Verfolgt aktive Prozesse für sauberes Beenden
|
||||
|
||||
### Nutzung
|
||||
|
||||
```js
|
||||
const result = await runProcess(
|
||||
'HandBrakeCLI',
|
||||
['--input', rawFile, '--output', outputFile, '--preset', preset],
|
||||
{
|
||||
onStderr: (line) => parseHandBrakeProgress(line),
|
||||
onStdout: (line) => logger.debug(line)
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## websocketService.js
|
||||
|
||||
WebSocket-Server für Echtzeit-Client-Kommunikation.
|
||||
|
||||
### Betrieb
|
||||
|
||||
- Läuft auf Pfad `/ws` des Express-Servers
|
||||
- Hält eine Registry aller verbundenen Clients
|
||||
- Ermöglicht Broadcast an alle Clients oder gezieltes Senden
|
||||
|
||||
### API
|
||||
|
||||
```js
|
||||
broadcast({ type: 'PIPELINE_STATE_CHANGE', data: { state, jobId } });
|
||||
broadcast({ type: 'PROGRESS_UPDATE', data: { progress, eta } });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## omdbService.js
|
||||
|
||||
Integration mit der [OMDb API](https://www.omdbapi.com/).
|
||||
|
||||
### Methoden
|
||||
|
||||
| Methode | Beschreibung |
|
||||
|---------|-------------|
|
||||
| `searchByTitle(title, type)` | Suche nach Titel (movie/series) |
|
||||
| `fetchById(imdbId)` | Vollständige Metadaten per IMDb-ID |
|
||||
|
||||
### Zurückgegebene Daten
|
||||
|
||||
```json
|
||||
{
|
||||
"imdbId": "tt1375666",
|
||||
"title": "Inception",
|
||||
"year": "2010",
|
||||
"type": "movie",
|
||||
"poster": "https://...",
|
||||
"plot": "...",
|
||||
"director": "Christopher Nolan"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## settingsService.js
|
||||
|
||||
Verwaltet alle Anwendungseinstellungen.
|
||||
|
||||
### Features
|
||||
|
||||
- **Schema-getriebene Validierung**: Jede Einstellung hat Typ, Grenzen und Pflichtfeld-Flag
|
||||
- **Kategorisierung**: Einstellungen sind in Kategorien gruppiert (Paths, Tools, Encoding, ...)
|
||||
- **Persistenz**: Werte in SQLite, Schema ebenfalls in SQLite
|
||||
- **Defaults**: `defaultSettings.js` definiert Standardwerte
|
||||
|
||||
### Einstellungs-Kategorien
|
||||
|
||||
| Kategorie | Einstellungen |
|
||||
|-----------|--------------|
|
||||
| `paths` | `raw_dir`, `movie_dir`, `log_dir` |
|
||||
| `tools` | `makemkv_command`, `handbrake_command`, `mediainfo_command` |
|
||||
| `encoding` | `handbrake_preset`, `handbrake_extra_args`, `output_extension`, `filename_template` |
|
||||
| `drive` | `drive_mode`, `drive_device`, `disc_poll_interval_ms` |
|
||||
| `makemkv` | `makemkv_min_length_minutes`, `makemkv_backup_mode` |
|
||||
| `omdb` | `omdb_api_key`, `omdb_default_type` |
|
||||
| `notifications` | `pushover_user_key`, `pushover_api_token` |
|
||||
|
||||
---
|
||||
|
||||
## historyService.js
|
||||
|
||||
Datenbankoperationen für Job-Historie.
|
||||
|
||||
### Hauptoperationen
|
||||
|
||||
| Operation | Beschreibung |
|
||||
|-----------|-------------|
|
||||
| `listJobs(filters)` | Jobs nach Status/Titel filtern |
|
||||
| `getJob(id)` | Job-Details mit Logs abrufen |
|
||||
| `findOrphanRawFolders()` | Nicht-getrackte Raw-Ordner finden |
|
||||
| `importOrphanRaw(path)` | Orphan-Ordner als Job importieren |
|
||||
| `assignOmdb(id, omdbData)` | OMDb-Metadaten nachträglich zuweisen |
|
||||
| `deleteJob(id, deleteFiles)` | Job und optional Dateien löschen |
|
||||
|
||||
---
|
||||
|
||||
## notificationService.js
|
||||
|
||||
PushOver-Push-Benachrichtigungen.
|
||||
|
||||
```js
|
||||
await notify({
|
||||
title: 'Ripster: Job abgeschlossen',
|
||||
message: 'Inception (2010) wurde erfolgreich encodiert'
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## logger.js
|
||||
|
||||
Strukturiertes Logging mit täglicher Log-Rotation.
|
||||
|
||||
### Log-Level
|
||||
|
||||
| Level | Verwendung |
|
||||
|-------|-----------|
|
||||
| `debug` | Detaillierte Entwicklungs-Informationen |
|
||||
| `info` | Normale Betriebsereignisse |
|
||||
| `warn` | Warnungen, die Aufmerksamkeit benötigen |
|
||||
| `error` | Fehler, die den Betrieb beeinträchtigen |
|
||||
|
||||
### Log-Dateien
|
||||
|
||||
```
|
||||
logs/
|
||||
├── ripster-2024-01-15.log ← Tages-Log
|
||||
└── jobs/
|
||||
└── job-42-handbrake.log ← Prozess-spezifische Logs
|
||||
```
|
||||
Reference in New Issue
Block a user