feat(worker): Worker mit pg-boss, Vorgaenge und Docker-Betrieb (#007)

Die Oberflaeche legt einen Vorgang an und schickt nur dessen ID in die
Warteschlange; der Worker fuehrt ihn aus und haelt Status, Ergebnis
oder Fehler fest. So bleiben lange SSH-Vorgaenge aus dem Webprozess
heraus, und der Fortschritt ist ohne Job-Interna sichtbar.

Kein automatisches Wiederholen: ein halb ausgefuehrter Schreibvorgang
auf einem Host gehoert vor einen Menschen. Fehlertexte aus fremden
Bibliotheken erreichen die Oberflaeche nie.

Dockerfile und Compose fuer den Betrieb: Master-Key als Secret nur im
Worker, Datenbank in einem internen Netz.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/worker/ausfuehren.ts

@@ -0,0 +1,84 @@
+import type { Prisma, Vorgang } from "@/generated/prisma/client";
+import type { VorgangsArt } from "@/generated/prisma/enums";
+import { prisma } from "@/lib/db";
+
+/**
+ * Fuehrt einen Vorgang aus (#007): Status setzen, Handler rufen, Ergebnis oder Fehler
+ * festhalten. Ohne pg-boss geschrieben, damit es sich mit einer Handler-Tabelle testen
+ * laesst; src/worker/index.ts verdrahtet es mit der Warteschlange.
+ */
+export type HandlerErgebnis = {
+  readonly status?: "ERLEDIGT" | "WARTET_AUF_BESTAETIGUNG";
+  readonly ergebnis?: Prisma.InputJsonValue;
+  readonly plan?: Prisma.InputJsonValue;
+};
+
+export type HandlerKontext = {
+  readonly vorgang: Vorgang;
+  /** Entschluesselbares Geheimnis aus dem Job (nur Bootstrap per Passwort). */
+  readonly geheim?: string;
+};
+
+export type Handler = (kontext: HandlerKontext) => Promise<HandlerErgebnis>;
+export type HandlerTabelle = Partial<Record<VorgangsArt, Handler>>;
+
+/**
+ * Fehler, deren Meldung fuer die Oberflaeche gedacht ist. Alle anderen werden zu einer
+ * allgemeinen Meldung – ein Stacktrace oder eine ssh2-Meldung kann Pfade, Adressen oder
+ * im schlimmsten Fall Schluesselmaterial tragen.
+ */
+export class VorgangsFehler extends Error {
+  constructor(nachricht: string, optionen?: ErrorOptions) {
+    super(nachricht, optionen);
+    this.name = "VorgangsFehler";
+  }
+}
+
+export function fehlerText(fehler: unknown): string {
+  if (fehler instanceof VorgangsFehler) return fehler.message;
+  return "Interner Fehler im Worker. Details stehen im Worker-Log.";
+}
+
+export async function vorgangAusfuehren(
+  vorgangId: string,
+  handler: HandlerTabelle,
+  geheim?: string,
+): Promise<void> {
+  // Nur WARTEND darf starten. Das bedingte Update ist zugleich die Sperre gegen einen
+  // zweiten Worker, der denselben Job bekommt.
+  const gestartet = await prisma.vorgang.updateMany({
+    where: { id: vorgangId, status: "WARTEND" },
+    data: { status: "LAEUFT", gestartetAm: new Date() },
+  });
+  if (gestartet.count === 0) return;
+  const vorgang = await prisma.vorgang.findUniqueOrThrow({ where: { id: vorgangId } });
+
+  const ausfuehrer = handler[vorgang.art];
+  try {
+    if (!ausfuehrer) {
+      throw new VorgangsFehler(`Für Vorgänge der Art ${vorgang.art} gibt es noch keine Ausführung.`);
+    }
+    const ergebnis = await ausfuehrer({ vorgang, ...(geheim ? { geheim } : {}) });
+    await prisma.vorgang.update({
+      where: { id: vorgangId },
+      data: {
+        status: ergebnis.status ?? "ERLEDIGT",
+        ergebnis: ergebnis.ergebnis,
+        plan: ergebnis.plan,
+        beendetAm: ergebnis.status === "WARTET_AUF_BESTAETIGUNG" ? null : new Date(),
+      },
+    });
+  } catch (fehler) {
+    if (!(fehler instanceof VorgangsFehler)) {
+      // Ins Log nur Name und Meldung, nie das ganze Objekt (cause-Ketten, Puffer).
+      console.error(
+        `Vorgang ${vorgangId} (${vorgang.art}) fehlgeschlagen:`,
+        fehler instanceof Error ? `${fehler.name}: ${fehler.message}` : String(fehler),
+      );
+    }
+    await prisma.vorgang.update({
+      where: { id: vorgangId },
+      data: { status: "FEHLGESCHLAGEN", fehler: fehlerText(fehler), beendetAm: new Date() },
+    });
+  }
+}

src/worker/handler.ts

@@ -0,0 +1,7 @@
+import type { HandlerTabelle } from "@/worker/ausfuehren";
+
+/**
+ * Welche Vorgangsart wer ausfuehrt. Waechst mit den Issues: Host-Key (#009), Bootstrap
+ * (#010), Ausrollen (#016), Abgleich (#021) …
+ */
+export const HANDLER: HandlerTabelle = {};

src/worker/index.ts

@@ -0,0 +1,43 @@
+import "dotenv/config";
+import type { Job } from "pg-boss";
+import { VERSION } from "@/lib/version";
+import { WARTESCHLANGE, warteschlangeHolen, type VorgangsJob } from "@/server/vorgaenge/warteschlange";
+import { vorgangAusfuehren } from "@/worker/ausfuehren";
+import { HANDLER } from "@/worker/handler";
+
+/**
+ * Einstieg des Worker-Prozesses (#007). Nur hier liegen Master-Key und Deployment-Key,
+ * und nur von hier aus spricht sshkv SSH mit den Hosts.
+ */
+async function starten(): Promise<void> {
+  const boss = await warteschlangeHolen();
+
+  await boss.work<VorgangsJob>(
+    WARTESCHLANGE,
+    { batchSize: 1, localConcurrency: 4 },
+    async (jobs: Job<VorgangsJob>[]) => {
+      for (const job of jobs) {
+        await vorgangAusfuehren(job.data.vorgangId, HANDLER, job.data.geheim);
+        if (job.data.geheim) {
+          // Das verschluesselte Geheimnis soll nicht bis zur Aufraeumrunde liegen bleiben.
+          await boss.deleteJob(WARTESCHLANGE, job.id).catch(() => undefined);
+        }
+      }
+    },
+  );
+
+  console.log(`sshkv-worker ${VERSION} bereit.`);
+
+  const beenden = async (signal: string) => {
+    console.log(`${signal} empfangen, beende laufende Vorgänge …`);
+    await boss.stop({ graceful: true, timeout: 30_000 });
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void beenden("SIGTERM"));
+  process.on("SIGINT", () => void beenden("SIGINT"));
+}
+
+starten().catch((fehler: unknown) => {
+  console.error("Worker konnte nicht starten:", fehler instanceof Error ? fehler.message : String(fehler));
+  process.exit(1);
+});