rebreak-monorepo/ops/WEBHOOK_MIGRATION_PLAN.md

Webhook-Migration: Standalone Listener → Nitro-Endpoint (Trucko-Pattern)

Owner: Backyard Erstellt: 2026-05-07 Status: PLAN — keine Implementierung in dieser Session. User-Direktive: „langsam starten". Ziel: Migration des GitHub-Webhook-Receivers vom standalone scripts/deploy-webhook/server.mjs zu einem Nitro-Endpoint im Backend (backend/server/api/webhook/github.post.ts) — analog zum Trucko-Monorepo.

---

1. Status quo (Stand 2026-05-07)

1.1 Aktuelle Pipeline

GitHub push → nginx (staging.rebreak.org/webhook)
            → 127.0.0.1:9000 (pm2: rebreak-webhook)
            → scripts/deploy-webhook/server.mjs (HMAC-Verify + Queue)
            → spawn bash scripts/deploy.sh
              → git fetch + reset --hard origin/main
              → pnpm install --frozen-lockfile (workspace-root)
              → cd backend && pnpm --filter rebreak-backend build
              → .output → .output-staging (atomisch via tmp)
              → pm2 restart rebreak-staging --update-env
              → pm2 restart rebreak-imap-staging / rebreak-idle-staging / dns-* (best-effort)

1.2 Beteiligte Dateien

Datei	Rolle
/srv/rebreak/scripts/deploy-webhook/server.mjs	Standalone Node-HTTP-Server auf Port 9000, HMAC-Verify, spawn deploy.sh
/srv/rebreak/scripts/deploy.sh	Pull → install → build → atomic-deploy → pm2 restart
/srv/rebreak/ecosystem.config.js	pm2-Service rebreak-webhook (cluster mode, 1 instance)
/etc/nginx/sites-enabled/staging.rebreak.org	location /webhook → proxy_pass http://127.0.0.1:9000/webhook
/etc/environment	GITHUB_WEBHOOK_SECRET (via Infisical-bootstrap), INFISICAL_CLIENT_ID/SECRET

1.3 Beobachtete Probleme

1. Push-Detection unzuverlässig: Manche Pushes triggern Deploy nicht (Listener empfängt Event nicht oder schweigt) — Symptom unklar (timing/network/hängender vorheriger spawn?).
2. deploy.sh exit code 1: Vergangene Logs zeigen cd apps/rebreak: No such file or directory (alter Pre-Cutover-Pfad in alten Logs; aktueller deploy.sh ist auf backend/ korrekt umgestellt — Symptom nicht mehr reproduzierbar, aber Vertrauensverlust).
3. Kein Healthcheck: /webhook antwortet nur auf POST mit valider Sig. Kein GET /webhook/health o.ä. — manuelles Debug nur via pm2 logs rebreak-webhook.
4. Kein Retry: Wenn git fetch netzwerkbedingt failt, bleibt Deploy hängen / aborts ohne Rescheduling.
5. Logs verstreut: Webhook-Logs in pm2 logs rebreak-webhook, Deploy-Output in dieselben Logs gestreamt aber mit [deploy] /[deploy:err]-Prefixen — kein strukturiertes Logging, kein File-Persistence über pm2-Restart hinweg.
6. Single-Point-of-Failure: Wenn rebreak-webhook pm2-Prozess crashed, gehen Pushes ins Leere — keine GitHub-Redelivery-Automatik (manuell via GitHub UI nötig).

---

2. Trucko-Pattern (das Vorbild)

Quelldatei: ~/mono/trucko-monorepo/backend/server/api/webhook/github.post.ts (957 Zeilen) Test-Coverage: ~/mono/trucko-monorepo/backend/tests/unit/webhook-hmac.test.ts (HMAC-Verify isoliert testbar)

2.1 Architektur-Eigenschaften

• Webhook ist ein Nitro-API-Endpoint im Backend selbst — kein separater Listener. Pfad: backend/server/api/webhook/github.post.ts → wird über das Backend-pm2 (rebreak-staging) bedient.
• HMAC-Sig-Verify identisch wie unsere server.mjs (sha256, timingSafeEqual).
• Reads useRuntimeConfig() für GITHUB_WEBHOOK_SECRET, GITHUB_USERNAME, GITHUB_TOKEN — Secrets kommen via Infisical → Nuxt/Nitro runtimeConfig (kein extra /etc/environment-Parsing).
• Affected-Detection: Liest payload.commits[].added/modified/removed, normalisiert Pfade, mapped auf eine Tabelle affected = { rebreak: bool, backend: bool, nginx: bool, ... }. Nur betroffene Apps werden gebaut.
• Queue-Mechanismus mit Merge: queueDeployment() mergt affected-Flags wenn ein zweiter Push während eines laufenden Builds reinkommt → kein Doppel-Build, aber kein Verlust.
• Inline-Build-Steps via executeCommand()-Helper: Jeder Step (git fetch / install / build / pm2 restart) ist ein einzelner spawned bash mit Timeout + structured stdout/stderr-Capture. Kein externes deploy.sh.
• Token-basierter Pull: Nutzt GITHUB_USERNAME + GITHUB_TOKEN für https://...@github.com/... — kein SSH-Deploy-Key-Handling im Webhook.
• Atomisches Output-Swap für rebreak: cp -r .output .output-staging-new && rm -rf .output-staging && mv .output-staging-new .output-staging (identisch zu unserem deploy.sh).
• Logs in pm2-stream: Alles via console.log("[Webhook] ...") — landet in pm2 logs backend, zentral.
• Healthcheck implizit: Wenn das Backend lebt, lebt der Webhook. pm2 zeigt backend online → Webhook funktioniert.

2.2 Was das Trucko-Pattern besser macht

Aspekt	Standalone-Listener (Status quo)	Nitro-Endpoint (Trucko)
Single Source of Truth	2 pm2-Services (webhook + app)	1 pm2-Service (Backend allein)
Secret-Handling	/etc/environment parsing manuell	useRuntimeConfig() via Infisical
Affected-Logik	Nicht vorhanden, baut immer alles	Granular, nur betroffene Apps
Logs	2 verschiedene pm2-Streams	1 zentraler Stream
Test-Coverage	Keine Tests	webhook-hmac.test.ts (vitest)
Code-Lokation	scripts/ (separater Code-Pfad)	backend/server/api/ (gleiche TS-Codebase)
Crash-Resilience	Eigener Prozess kann sterben ohne app	Wenn Backend lebt, lebt Webhook

---

3. Migrations-Schritte (für nächste Session — NICHT jetzt)

Phase 1: Endpoint anlegen (Mac, kein Server-Change)

1. Datei backend/server/api/webhook/github.post.ts erstellen — kopiere Trucko-Vorlage, passe an:
   • Repo-Pfad: /srv/rebreak (statt /srv/trucko-monorepo)
   • affected-Map: nur rebreak-native, backend, nginx, dns, imap (kein pizzabox/driver/etc.)
   • Build-Steps: nur Backend-Build (pnpm --filter rebreak-backend build) + atomic-output-swap + pm2 restart rebreak-staging
   • Entferne Trucko-spezifische nginx-conf-Listen (die unsere ops/nginx-Files haben andere Namen)
2. nitro.config.ts: runtimeConfig um githubWebhookSecret, githubUsername, githubToken ergänzen (analog Trucko).
3. Test-File backend/tests/unit/webhook-hmac.test.ts mitmigrieren (vitest setup falls nötig).
4. Lokal pnpm --filter rebreak-backend build → checken dass Endpoint im .output/server/chunks/routes/api/webhook/github.post.mjs landet.

Phase 2: Infisical-Secrets setzen (User-Eskalation)

5. Infisical Project rebreak-staging:
   • GITHUB_WEBHOOK_SECRET (bereits vorhanden in /etc/environment, in Infisical spiegeln)
   • GITHUB_USERNAME (z.B. chahinebrini)
   • GITHUB_TOKEN (PAT mit repo-Scope für git-pull über HTTPS) → diese Secrets werden via start-staging.sh als NUXT_* env vars dem Backend bereitgestellt.

Phase 3: Parallel-Betrieb (Failsafe)

6. Beide Endpoints aktiv halten:
   • GitHub-Webhook bleibt auf https://staging.rebreak.org/webhook (alter Listener auf Port 9000).
   • Neuer Endpoint zusätzlich erreichbar unter https://staging.rebreak.org/api/webhook/github (Backend-Routing).
7. Auf GitHub: zweite Webhook-Konfig anlegen, beide aktiv. Beide verifizieren mit demselben Secret.
8. Logs beide Streams beobachten — wenn neuer Endpoint zuverlässig deployt, alter wird redundant.

Phase 4: Cutover

9. GitHub-Webhook umstellen: alten URL-Webhook deaktivieren, nur neuer /api/webhook/github aktiv.
10. nginx: location /webhook → proxy_pass http://127.0.0.1:9000 ENTFERNEN (oder auf Backend umrouten).
11. pm2 stop rebreak-webhook && pm2 delete rebreak-webhook (NUR auf User-Approval — destruktiv).
12. scripts/deploy-webhook/ archivieren (nicht löschen — Reference).
13. scripts/deploy.sh entweder:
    • a) behalten als Fallback-Tool für manuelles bash deploy.sh auf SSH (empfohlen), oder
    • b) Code-Logik ins Backend-Endpoint inline-spawnen wie Trucko es tut (mehr Code, aber 100% Single-Source).

Phase 5: Hardening

14. Healthcheck-Endpoint hinzufügen: backend/server/api/webhook/health.get.ts → returns { ok, lastDeploy, queueDepth }.
15. Persistent Deploy-Log: in /var/log/rebreak/deploys.jsonl schreiben (statt nur pm2-stream).
16. Slack/Discord-Notifier on deploy-fail (optional).

---

4. Risk-Assessment

Top 3 Risks bei Migration

1. Self-Deploy-Loop / Race-Condition beim Restart: Der Webhook lebt im Backend-Prozess. Wenn der Webhook pm2 restart rebreak-staging aufruft, killt der Prozess sich selbst, BEVOR die HTTP-Response gesendet ist. → GitHub bekommt timeout, retry-storm. Mitigation: Trucko macht's auch, und es funktioniert dort. Schlüssel: pm2 restart ist async + setTimeout(2000) vor dem restart, response wurde schon vor Build-Start gesendet (return { ok } BEVOR queueDeployment() läuft im Background). Muss bei uns gleich strukturiert werden.

2. Build-Failure crashed Webhook-Capability: Wenn ein Bad-Push das Backend-Build kaputt macht, hat der nächste Push keinen Webhook-Endpoint mehr (Backend offline). → Stuck-State, manuelles SSH nötig zum Recovery. Mitigation: Atomic-Output-Swap (.output → .output-staging via mv) bleibt. Alter Build überlebt im .output-staging, Backend bleibt online auch wenn neuer Build failed. PLUS: Listener als Failsafe parallel erstmal behalten (Phase 3).

3. Infisical-Secret-Loading-Lücke: Wenn useRuntimeConfig() zur Build-Zeit aufgerufen wird (statt Runtime), landen die Secrets nicht im Endpoint. Trucko nutzt runtimeConfig → wird per NUXT_*-env bei Start aufgelöst. Unsere start-staging.sh muss NUXT_GITHUB_WEBHOOK_SECRET, NUXT_GITHUB_USERNAME, NUXT_GITHUB_TOKEN setzen — sonst 401 für jeden Push. Mitigation: Phase 2 explizit verifizieren via curl https://staging.rebreak.org/api/webhook/github -X POST -H "x-hub-signature-256: sha256=..." -d '...' mit Test-Payload BEVOR GitHub-Webhook umgestellt wird.

Weitere Risiken (lower-priority)

• GitHub-Token-Lifetime: PAT läuft ab → silent fail. Mitigation: Token mit langer Lifetime, ggf. Rotation-Reminder.
• Body-Parsing-Reihenfolge: Nitro liest body normal als JSON, aber HMAC braucht raw-body. Trucko liest manuell event.req.on("data") — Nitro-Middleware darf body nicht vorher konsumiert haben. Ggf. Plugin-Order checken.
• OOM während Build: 4 GB RAM, NODE_OPTIONS=--max-old-space-size=1536 reicht heute. Wenn Backend-Build wächst → OOM-kill mid-build → nicht-atomar.

---

5. Fallback-Plan

Wenn Migration scheitert:

1. Listener bleibt aktiv während Migration (Phase 3 ist parallel-Betrieb).
2. Rollback-Path:
   • GitHub-Webhook URL zurück auf /webhook (alter Listener).
   • pm2 restart rebreak-webhook (falls gestoppt).
   • Neuer Endpoint im Backend bleibt vorhanden, antwortet aber nicht mehr aus GitHub-Pushes — kein Schaden.
3. Total-Rollback (nur falls Backend-Endpoint Backend-Builds blockiert):
   • File backend/server/api/webhook/github.post.ts löschen, neu builden, deployen.
   • Cleanup: runtimeConfig-Einträge in nitro.config.ts zurückrollen.

---

6. Empfohlener erster Schritt (für nächste Session)

Read-only Investigation: Prüfen welche Infisical-Secrets aktuell im Backend-Runtime verfügbar sind (pm2 logs rebreak-staging | grep -i webhook + Infisical-CLI infisical secrets --env=staging | grep GITHUB). Damit ist klar ob Phase 2 trivial ist (Secrets bereits da) oder neue Secrets nötig sind. Erst danach Phase 1 (Endpoint anlegen) auf Mac, ohne deployen.

---

7. Was NICHT in Scope

• Code-Änderungen am App-Code (Nitro-Routes außerhalb /webhook/).
• Mail-Stack-Touchups (Mo's Scope).
• nginx-Routing-Änderung jetzt — erst nach Cutover-Phase 4.
• Force-Push / git history-rewrite.