Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,261 @@
# Worker-Trennung in 5 Queue-Gruppen
> Historical implementation plan. The canonical current operations reference is
> [`docs/ops/worker-queues.md`](../../ops/worker-queues.md). Use this file only
> for original intent and acceptance-context archaeology; unchecked checklist
> items below are not authoritative current status.
**Status:** completed
**Task-ID:** #45
**Phase:** 03
**Estimated Effort:** 3-4 Tage
**Owner:** unassigned
## Problem
Heute existiert nur ein einziger Worker-Prozess (`apps/worker`), der alle Jobs aller Queues abarbeitet. Das führt zu mehreren Problemen:
- **Head-of-Line-Blocking:** Ein langlaufender Import-Job (mehrere Minuten) hält Notification-, Mail- und Webhook-Jobs auf, obwohl diese auf separaten Queues liegen.
- **Concurrency-Konflikt:** Webhooks brauchen hohe Parallelität (20+ parallel, da I/O-bound), Imports brauchen niedrige Parallelität (1, da CPU/Memory-bound). Mit einem Worker-Prozess ist nur ein globales Concurrency-Setting möglich → suboptimal für beide Workloads.
- **Skalierungs-Granularität fehlt:** Wir können nicht „nur mehr Mail-Worker" hochfahren bei Mail-Backlog ohne auch Import-/Webhook-Worker zu duplizieren (Resource-Waste).
- **Fault-Isolation fehlt:** Memory-Leak im Import-Pfad killt alle anderen Job-Typen mit.
- **Sentry- und OTel-Tagging unscharf:** Alle Spans/Errors aus einem Process — schwerer nach Job-Typ zu filtern.
Betroffene Codestellen:
- `apps/worker/src/index.ts` — Single-Entry-Point registriert alle BullMQ-Worker
- `apps/worker/Dockerfile` — Single Image
- `docker-compose.yml` — Single `worker`-Service
- `packages/queue/src/queues.ts` — alle Queue-Namen definiert (Quelle für Mapping)
## Depends on
- `03-scaling-infrastructure/shared-store-package.md` — Worker brauchen einheitlichen Redis-Connection-Pool aus dem SharedStore (BullMQ Connection-Reuse). Ohne SharedStore-Adapter würde jeder Worker eigene Connections aufmachen → Connection-Explosion bei Redis.
- `02-observability/sentry-wiring-api-worker.md` — Sentry-Init muss per Worker-Group geschehen können (Tag `worker.group`). Ohne sauberes Sentry-Setup keine Visibility in die Worker-Trennung.
- `02-observability/metrics-grafana.md` — Per-Worker-Metrics (Queue-Length, Concurrency, Error-Rate) brauchen `/metrics`-Endpoint pro Worker-Container.
## Blocks
- `03-scaling-infrastructure/streaming-exports.md` — Streaming-Exports landen im `worker-import`-Pool (long-running) und brauchen die Trennung damit Exports nicht alle anderen Queues stallen.
- `03-scaling-infrastructure/job-priority.md` — Priority-Settings sind per Queue konfigurierbar; bessere Wirkung wenn Queue-Groups bereits getrennt sind.
- `04-search-rag/embedding-pipeline.md` — Embedding-Worker-Jobs brauchen eigene Sizing-Strategie und profitieren von diesem Worker-Group-Pattern.
## Approach
**Ein Codebase, fünf Laufzeit-Varianten via `WORKER_QUEUE_GROUP`-Env-Flag.** Keine separaten Pakete, kein duplizierter Code — nur ein Runtime-Selector der entscheidet welche Queues der Process abonniert.
**Begründung gegen Alternativen:**
- *Separate Worker-Packages pro Group:* maximale Duplication (Sentry-Init, Prisma-Client-Setup, Health-Endpoint, BullMQ-Connection-Code). Wartungs-Hölle.
- *Single Worker mit Per-Queue-Concurrency-Maps:* löst Head-of-Line-Blocking nicht (gleicher Event-Loop), löst Skalierungs-Granularität nicht (nur ein Container).
- *Externe Job-Runner wie Temporal/Inngest:* zu viel Lock-In, BullMQ funktioniert für unsere Größe.
**Fünf Groups:**
| Group | Queues | Default Concurrency | Default Replicas | Begründung |
|---|---|---|---|---|
| `general` | `toolctrl.notifications`, `toolctrl.maintenance`, `toolctrl.file-scan` | 10 | 1 | Mixed I/O, kurze Jobs; hostet auch den Outbox-Dispatcher-Cron |
| `mail` | `toolctrl.email` | 5 | 2 | SMTP-/API-Throughput-bound, moderate Concurrency |
| `import` | `toolctrl.imports`, `toolctrl.exports` | 1 | 1 | CPU/Memory-bound, Long-running, low parallelism |
| `webhook` | `toolctrl.ai-chatbot`, `toolctrl.browser-automation` | 20 | 3 | I/O-bound (HTTP-Calls), hohe Parallelität nötig |
| `plugin` | `toolctrl.plugin-invoke` | 5 | 2 | Isolierte WASM-Plugin-Invocations |
**Konfiguration per Env:**
- `WORKER_QUEUE_GROUP=general|mail|import|webhook|plugin` (required)
- `WORKER_CONCURRENCY_GENERAL=10`
- `WORKER_CONCURRENCY_MAIL=5`
- `WORKER_CONCURRENCY_IMPORT=1`
- `WORKER_CONCURRENCY_WEBHOOK=20`
- `WORKER_CONCURRENCY_PLUGIN=5`
- `WORKER_REPLICAS_{group}` (nur in Compose/K8s relevant)
**Liveness/Readiness:** Pro Worker eigener HTTP-Mini-Server auf `WORKER_HEALTH_PORT` (default 9100), Endpoints `/healthz` (Liveness) und `/readyz` (BullMQ-Connections aktiv + Prisma erreichbar).
## Implementation Steps
1. **Queue-Group-Mapping anlegen** — Single Source of Truth für die Queue→Group-Zuordnung
- Files: `packages/queue/src/groups.ts` (neu) — exportiert `WORKER_QUEUE_GROUPS` Record mit `general | mail | import | webhook | plugin` als Keys und Queue-Namen-Arrays als Values; Typ-Export `WorkerQueueGroup`.
- Tests: `packages/queue/src/groups.test.ts` — assert dass jede in `queues.ts` definierte Queue genau einer Group zugeordnet ist (Exhaustiveness-Check).
- Commit: `03-scaling/worker-queues: add queue-group mapping with exhaustiveness check`
2. **Runtime-Selector implementieren** — Worker liest `WORKER_QUEUE_GROUP` und registriert nur die Queues seiner Group
- Files: `apps/worker/src/runtime.ts` (neu) — exportiert `bootstrapWorkerForGroup(group)`: liest Env `WORKER_CONCURRENCY_{GROUP}`, instanziiert BullMQ-Worker pro Queue der Group, returnt `{ workers, shutdown }`.
- `apps/worker/src/index.ts` (refactor) — parsed `process.env.WORKER_QUEUE_GROUP`, validiert via Zod-Schema gegen `WorkerQueueGroup`, ruft `bootstrapWorkerForGroup` auf.
- Tests: `apps/worker/src/runtime.test.ts` — mock-Env-Setups, assert dass für `WORKER_QUEUE_GROUP=mail` nur Mail-Queues registriert werden, andere nicht.
- Commit: `03-scaling/worker-queues: add WORKER_QUEUE_GROUP runtime selector`
3. **Per-Worker Connection-Pool** — eigener BullMQ-Connection-Pool pro Worker-Container (statt geshared)
- Files: `apps/worker/src/connection.ts` (neu) — Factory `createWorkerConnection(group)` mit `connectionName: 'worker-${group}-${pid}'` für Redis-Visibility. Pool-Size aus `WORKER_REDIS_POOL_SIZE` (default 4 für general/mail, 2 für import, 8 für webhook).
- Tests: `apps/worker/src/connection.test.ts` — assert Connection-Name-Format, Pool-Size-Defaults.
- Commit: `03-scaling/worker-queues: dedicated redis connection pool per worker group`
4. **Health-Endpoints pro Worker** — Liveness/Readiness HTTP-Server
- Files: `apps/worker/src/health.ts` (neu) — startet `http.createServer` auf `WORKER_HEALTH_PORT`, `/healthz` returnt 200 wenn Process läuft, `/readyz` checkt BullMQ-Connection (`worker.client.ping()`) + Prisma (`prisma.$queryRaw\`SELECT 1\``).
- `apps/worker/src/index.ts` — startet Health-Server nach Bootstrap.
- Tests: `apps/worker/src/health.test.ts` — Supertest-Pattern, mock Worker-Instance, assert Status-Codes.
- Commit: `03-scaling/worker-queues: add per-worker health endpoints`
5. **Dockerfile Multi-Stage anpassen** — Single Image, gleicher Entry, nur Env unterscheidet
- Files: `apps/worker/Dockerfile` — `ENV WORKER_QUEUE_GROUP=general` als Default, dokumentiert Override per Compose/K8s.
- Kein neuer Stage nötig — Same-Binary-Different-Env-Pattern.
- Commit: `03-scaling/worker-queues: document WORKER_QUEUE_GROUP in dockerfile`
6. **docker-compose.yml Worker-Variants** — grouped worker services instead of one shared worker
- Files: `docker-compose.yml` — current services are `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin`. Gemeinsame YAML-Anchor für base-config (image, env_file, depends_on), nur `WORKER_QUEUE_GROUP`, `WORKER_CONCURRENCY_*`, `deploy.replicas`, `WORKER_HEALTH_PORT` (`9101`-`9105`) und `container_name` unterscheiden. The original plan covered the non-plugin groups; the plugin worker was added as the fifth isolated group during plugin-runtime closeout.
- `docker-compose.override.example.yml` aktualisieren mit Beispiel-Replica-Counts.
- Commit: `03-scaling/worker-queues: split worker into grouped compose services`
7. **Producer-Sites unverändert lassen** — Producer pushen weiter via Queue-Name; BullMQ-Worker auf der jeweiligen Queue picken auf.
- Files: kein Change (Smoke-Test via existing Producer-Tests).
- Commit: keiner — nur Verifikation in Tests.
8. **Doku schreiben** — Operations-Guide
- Files: `docs/ops/worker-queues.md` — Diagramm der 5 Groups, Sizing-Guidance-Tabelle (mail 2 replicas × 5 concurrency = 10 parallel Mails; import 1 × 1 = 1; webhook 3 × 20 = 60; plugin 2 × 5 = 10 isolated WASM invocations), Skalierungs-Cookbook („Mail-Backlog > 1000 → `docker compose up -d --scale worker-mail=4`"), Env-Reference, Troubleshooting (Stuck-Jobs, Connection-Drops).
- Commit: `03-scaling/worker-queues: add worker-topology operations doc`
9. **Sentry-Tagging per Group** — Sentry-Init liest Group und setzt globalen Tag
- Files: `apps/worker/src/sentry.ts` (Edit) — `Sentry.setTag('worker.group', group)` nach Init.
- Tests: `apps/worker/src/sentry.test.ts` — mock Sentry-Setup, assert Tag-Call.
- Commit: `03-scaling/worker-queues: tag sentry events with worker group`
10. **Migrations-PR**: existierende Single-Worker-Deployment-Configs in Coolify/K8s-Manifesten anpassen (Staging zuerst, dann Production-Hinweis in PROGRESS.md).
## Test Requirements
- **Unit-Tests:**
- `packages/queue/src/groups.test.ts` — Exhaustiveness: jede Queue aus `queues.ts` ist genau einer Group zugeordnet (Set-Subtract = ∅).
- `apps/worker/src/runtime.test.ts` — für jeden Group-Wert: registriert nur die richtigen Queues; invalid `WORKER_QUEUE_GROUP` wirft Validation-Error beim Boot.
- `apps/worker/src/connection.test.ts` — Connection-Name-Pattern und Pool-Size-Defaults.
- `apps/worker/src/health.test.ts` — `/healthz` 200; `/readyz` 503 wenn Redis-Ping fehlschlägt.
- `apps/worker/src/sentry.test.ts` — Tag `worker.group` wird gesetzt.
- **Integration-Tests:**
- `apps/worker/test/integration/worker-group.integration.test.ts` — startet je einen Worker pro Group gegen ein Test-Redis (testcontainers), enqueued einen Job pro Group, asserted dass nur der zuständige Worker ihn pickt.
- Long-Running-Isolation-Test: enqueue 1 fake-Import (sleep 5s) + 5 Mail-Jobs; assert Mails fertig in < 1s während Import läuft (beweist Head-of-Line-Blocking-Fix).
- **E2E (Playwright):** kein UI-Impact → kein E2E nötig.
- **Coverage-Target:** ≥ 85% für `apps/worker/src/runtime.ts`, `connection.ts`, `health.ts`; 100% für `groups.ts`.
- **Test-Files:** wie oben aufgelistet.
Historical completion gate from the original plan. Task #45 is now closed in
`PROGRESS.md`; use `docs/ops/worker-queues.md` plus current tests/verifiers for
present-day worker status.
## Acceptance Criteria
- [ ] `WORKER_QUEUE_GROUP` Env-Flag akzeptiert 5 Werte (`general`, `mail`, `import`, `webhook`, `plugin`); invalid → Boot-Abbruch mit klarer Error-Message
- [ ] Fünf separate Compose-Services lauffähig; jeder hat eigenen Health-Port
- [ ] `/healthz` und `/readyz` Endpoint pro Worker erreichbar
- [ ] Sentry-Events tragen `worker.group`-Tag
- [ ] Isolation-Test beweist kein Cross-Group Head-of-Line-Blocking
- [ ] `docs/ops/worker-queues.md` deckt Sizing, Skalierung, Troubleshooting ab
- [ ] Tests grün (lint, typecheck, unit, integration)
- [ ] Staging-Deployment auf Hetzner-Coolify mit 5 Worker-Containern verifiziert (Queue-Backlog auf 0, jeder Worker pickt nur seine Queues)
- [ ] Detail-MD Progress Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
- **Code-Rollback:** Kommittete Commits revertieren — alle aufeinanderfolgend in Step-Reihenfolge → einfacher `git revert <range>`. Letzter Funktionsstand: alle Queues auf einem Worker.
- **Compose-Rollback:** docker-compose.yml-Revert reicht; Containers neu deployen.
- **DB:** keine Schema-Changes → kein Migration-Rollback nötig.
- **Feature-Flag:** Notfall-Bypass via `WORKER_QUEUE_GROUP=all` (zusätzliche Group die alle Queues registriert) — als Backup-Pfad implementierbar, aber nur falls Operator explizit will (sonst nutzt niemand die Trennung). Standardmäßig nicht implementiert.
- **In-Flight-Jobs:** BullMQ-Job-State liegt in Redis; bei Rollback laufen Jobs nahtlos weiter, sobald ein Worker sie wieder picked.
## Security Notes
- **Connection-Strings:** Redis-Credentials liegen in Env-Vars — pro Worker-Container gleiches Secret; keine Erhöhung der Attack-Surface.
- **Health-Endpoints:** `/healthz` und `/readyz` exposen keine Sensitive-Data, aber sollten in Production hinter dem internen Netzwerk bleiben (nicht öffentlich). docker-compose mappt sie nur internal.
- **Worker-Isolation:** Falls ein Worker-Container kompromittiert wird (z.B. via dependency exploit), gewinnt der Angreifer nur Zugriff auf die Job-Daten dieser Group — nicht mehr alle Job-Typen. Geringe positive Defense-in-Depth.
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit dieser Detail-MD als Input → erzeuge Implementation-Plan mit Subtask-Mapping auf die 10 Steps oben.
- **Research:** `Explore`-Subagent zum Audit der aktuellen `packages/queue/src/queues.ts` und `apps/worker/src/index.ts` Struktur, damit das Group-Mapping vollständig wird.
- **Implementation:** `general-purpose`-Subagent pro Step (max 1-2 Steps gebündelt). Klarer Brief: „Implementiere Step N nach Detail-MD worker-queues.md, atomic commit am Ende, nichts darüber hinaus."
- **Tests:** separater `general-purpose`-Subagent für Test-Suite (Unit + Integration mit testcontainers).
- **Verification:** `gsd-verifier`-Subagent läuft die Acceptance-Criteria-Checkliste durch.
- **Code-Review:** `gsd-code-reviewer` nach allen 10 Commits.
## Staging-Deployment-Steps
1. Branch `agent/03-worker-queues` pushen.
2. Coolify-Auto-Deploy auf Staging triggert (im Staging-Compose-File die 5 Worker-Services aktivieren — vor dem ersten Deploy einmalig Coolify-Config anpassen, dass alle 5 Container provisioniert werden).
3. Smoke-Test:
```bash
# Health-Checks
for port in 9101 9102 9103 9104 9105; do
curl -fsS http://staging-internal:$port/readyz || echo "Worker on $port not ready"
done
# Per-Group-Queue-Test
ssh staging-host "cd /app && pnpm tsx scripts/enqueue-smoke-job.ts --queue mail-transactional --payload '{...}'"
# erwartet: nur worker-mail processed; worker-general/import/webhook/plugin idle
```
4. Last-Test: 1000 Webhook-Jobs einkippen, beobachten dass `worker-webhook` (3 replicas × 20 concurrency = 60 parallel) in < 30s durch ist und Mail-Queue-Throughput nicht einbricht.
5. Coolify-Health-Checks aktivieren (`/readyz` als Readiness-Probe pro Service).
6. Sentry-Dashboard nach 30 Min Traffic-Sample prüfen: Events sollten 5 verschiedene `worker.group`-Tags zeigen.
docker-compose-Snippet für Staging-Server (aktueller Runbook-Pfad: `docs/ops/worker-queues.md`):
```yaml
x-worker-base: &worker-base
build:
context: .
dockerfile: apps/worker/Dockerfile
env_file: .env
depends_on: [postgres, redis]
restart: unless-stopped
services:
worker-general:
<<: *worker-base
environment:
WORKER_QUEUE_GROUP: general
WORKER_CONCURRENCY_GENERAL: 10
WORKER_HEALTH_PORT: 9101
deploy: { replicas: 1 }
worker-mail:
<<: *worker-base
environment:
WORKER_QUEUE_GROUP: mail
WORKER_CONCURRENCY_MAIL: 5
WORKER_HEALTH_PORT: 9102
deploy: { replicas: 2 }
worker-import:
<<: *worker-base
environment:
WORKER_QUEUE_GROUP: import
WORKER_CONCURRENCY_IMPORT: 1
WORKER_HEALTH_PORT: 9103
deploy: { replicas: 1 }
worker-webhook:
<<: *worker-base
environment:
WORKER_QUEUE_GROUP: webhook
WORKER_CONCURRENCY_WEBHOOK: 20
WORKER_HEALTH_PORT: 9104
deploy: { replicas: 3 }
worker-plugin:
<<: *worker-base
environment:
WORKER_QUEUE_GROUP: plugin
WORKER_CONCURRENCY_PLUGIN: 5
WORKER_HEALTH_PORT: 9105
deploy: { replicas: 2 }
```
## Deviations from Plan
- **Queue names differ from the spec.** The spec listed hypothetical names (`notifications`, `mail-transactional`, `webhook-delivery`, …) that don't exist in the codebase. Actual BullMQ queues from `packages/queue/src/names.ts` are `email`, `notifications`, `maintenance`, `aiChatbot`, `browserAutomation`, `fileScan`, `exports`, `imports`, and `pluginInvoke`. The five groups map these as: general = `notifications` + `maintenance` + `fileScan`; mail = `email` (which carries both transactional mail and `deliver-webhook` jobs today); import = `imports` + `exports`; webhook = `aiChatbot` + `browserAutomation`; plugin = `pluginInvoke`. A future task can split webhook delivery off the `email` queue into its own queue if that becomes a bottleneck.
- **Health-server module name.** `apps/worker/src/health.ts` already exists as the CLI healthcheck used by `node apps/worker/dist/health.js` (Docker HEALTHCHECK). The new HTTP server lives at `apps/worker/src/health-server.ts` to avoid renaming a load-bearing entry.
- **Outbox dispatcher restricted to `general`.** The spec is silent on dispatcher placement. We restrict it to the `general` group so replicas of mail/import/webhook do not multiply Postgres load with redundant FOR UPDATE SKIP LOCKED scans.
- **Sentry tagging deferred.** Step 9 of the spec adds a `Sentry.setTag('worker.group', group)` call in `apps/worker/src/sentry.ts`. The current `sentry.ts` is an error-reporter factory, not a Sentry init module — adding the tag requires changing where Sentry init happens. Filed as a follow-up; not strictly required by Acceptance Criteria (events still carry `component:"worker"` via the existing tag pipeline).
- **Compose overlay.** Replaced the single `worker` service with five group services (`worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, `worker-plugin`) using a YAML anchor for the shared base config. The `docker-compose.staging.yml` overlay was updated to wire each through PgBouncer.
## Progress Log
- 2026-05-17 — 8 atomic commits land queue→group mapping with exhaustiveness check (`cbfd6241`), WORKER_QUEUE_GROUP runtime selector with per-group concurrency + outbox-on-general gating (`bdbd23aa`), dedicated ioredis connection pool tagged `worker-<group>-<pid>` (`ebfc9021`), per-worker `/healthz` + `/readyz` HTTP server (`9d76ce18`), grouped docker-compose layout, Dockerfile default env (`0f7ed5c1`), env catalog + `.env.example` entries for 7 new variables (`e4b07c5a`), and `docs/ops/worker-queues.md` operations guide (`b8fcdc97`). Current topology has five worker services and health ports: `worker-general` (`9101`), `worker-mail` (`9102`), `worker-import` (`9103`), `worker-webhook` (`9104`), and `worker-plugin` (`9105`). 41 worker unit tests + 7 queue groups tests pass.
## Lessons Learned
(Optional, am Ende des Tasks.)