@werk/servicewerk (0.1.0)
Installation
@werk:registry=https://gitlab.amandy.love/api/packages/werk/npm/npm install @werk/servicewerk@0.1.0"@werk/servicewerk": "0.1.0"About this package
Servicewerk
Servicewerk ist die zentrale Komponente zur Steuerung, Verwaltung und Überwachung von langlebigen Hintergrund-Diensten (Services) und periodischen, zeitgesteuerten Aufgaben (Timern) im lokalen Werkzeug-Ökosystem. Es nutzt Aktenwerk als Deklarations- und Organisationsschicht und Befehlswerk als robuste Ausführungs-Engine.
1. Kernkonzepte & Architektur
Servicewerk verfolgt ein daemonless (daemonfreies) Design für maximale Einfachheit, Ausfallsicherheit und geringen Ressourcenverbrauch:
- Kein permanenter Hintergrund-Daemon: Anstelle eines permanent laufenden, monolithischen Daemons läuft jeder Hintergrund-Service in seinem eigenen, isolierten und entkoppelten Runner-Prozess (
runner.js). - Prozess- und PID-Tracking: Der Zustand und die Prozess-IDs (PIDs) aller aktiven Runner werden in einer zentralen, dateibasierten Zustandsdatei (
~/.local/share/werk/servicewerk-state.json) gepflegt. - Ausfallsicherheit: Stürzt ein Dienst-Runner ab oder wird er beendet, hat dies keinen Einfluss auf andere laufende Dienste. Die CLI kann verwaiste oder abgestürzte Dienste jederzeit anhand der PIDs erkennen und reparieren.
- Prozessgruppen-Management: Beim Beenden eines Dienstes signalisiert Servicewerk die gesamte Prozessgruppe (
-pid), wodurch der Runner und alle von ihm (über Befehlswerk) gestarteten Subprozesse zuverlässig und rückstandsfrei beendet werden.
2. Deklaration von Akten (Manifeste)
Services und Timer werden als Standard-Akten über Manifestdateien (akte.toml) deklariert:
A. Langlebiger Hintergrund-Dienst (kind = "service")
Deklariert einen langlebigen Prozess wie einen Webserver oder Mail-Daemon:
schema = "akte/v1"
id = "service.postwerk"
kind = "service"
name = "Postwerk Mail-Daemon"
description = "Hintergrund-Dienst zur Verarbeitung ausgehender E-Mails."
version = "0.1.0"
[owner]
project = "postwerk"
[data.service]
command = "node dist/index.js" # Auszuführender Befehl
autostart = true # Automatischer Start bei Systemstart/Sync
restart = "on-failure" # Restart-Policy: always | on-failure | no
delay = "5s" # Verzögerung vor dem Restart (z. B. "5s", "10m")
B. Periodische Aufgabe (kind = "timer")
Deklariert eine Aufgabe, die intervall- oder cron-basiert ausgeführt wird:
schema = "akte/v1"
id = "timer.database-backup"
kind = "timer"
name = "Datenbank-Backup"
description = "Sichert die lokale Datenbank jede Nacht."
version = "0.1.0"
[owner]
project = "database"
[data.timer]
command = "pg_dump -U postgres dbname" # Auszuführender Befehl
schedule = "0 2 * * *" # Cron-Ausdruck (jeden Tag um 02:00 Uhr)
# Alternativ: interval = "1h" # Intervall-basierte Ausführung (z. B. "1h", "30s")
timeout = "15m" # Maximal zulässige Laufzeit
3. Installation
Führen Sie das lokale Installationsskript aus, um Servicewerk zu bauen und die CLI in Ihrem globalen Bin-Verzeichnis zu registrieren:
./install.sh
Stellen Sie sicher, dass der Pfad ~/.local/share/werk/bin in Ihrer PATH-Umgebungsvariable enthalten ist, um servicewerk direkt in der Shell aufzurufen:
export PATH="$HOME/.local/share/werk/bin:$PATH"
4. CLI-Schnittstelle
Nach der Installation steht Ihnen der Befehl servicewerk zur Verfügung:
| Befehl | Beschreibung |
|---|---|
servicewerk list (oder ls) |
Listet alle registrierten Services und Timer sowie deren aktuellen Status auf. |
servicewerk start <id> |
Startet einen Hintergrund-Dienst im Hintergrund. |
servicewerk stop <id> |
Beendet einen laufenden Dienst kontrolliert (inkl. aller Subprozesse). |
servicewerk restart <id> |
Startet einen Dienst neu (führt Stop und Start nacheinander aus). |
servicewerk status <id> |
Zeigt detaillierte Statusinformationen (PID, Uptime, Exit-Codes, Fehler, nächste Ausführungszeit). |
servicewerk logs <id> |
Zeigt die Logs eines Dienstes/Timers an. Nutzen Sie -f für Live-Streaming und --tail <n> für die Zeilenanzahl. |
servicewerk autostart |
Startet alle Dienste, bei denen autostart = true konfiguriert ist. |
servicewerk scheduler run |
Startet die Timer-Scheduler-Engine im Vordergrund. |
Optionen
--json: Gibt die Ausgaben aller Abfragebefehle im maschinenlesbaren JSON-Format aus (ideal zur Weiterverarbeitung durch andere Tools wie Tuiwerk).-h, --help: Zeigt die Hilfe an.
5. Entwickler-Informationen
Projektstruktur
servicewerk/
├── package.json # Monorepo- und Testkonfiguration
├── tsconfig.json # TypeScript-Konfiguration
├── install.sh # Lokales Installationsskript
├── packages/
│ ├── core/ # Core-Bibliothek (Manager, Scheduler, Runner)
│ └── cli/ # CLI-Anwendung
└── tests/ # Bun-basierte Unit- und Integrationstests
Tests ausführen
Die Tests verwenden eine vollständig isolierte temporäre Umgebung, ohne das echte Benutzerverzeichnis zu beeinflussen. Ausführung via:
bun test
Dependencies
Dependencies
| ID | Version |
|---|---|
| @servicewerk/core | ^0.1.0 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^20.12.7 |
| typescript | ^5.4.5 |