Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/03-scaling-infrastructure/worker-queues.md
T

19 KiB
Raw Blame History

Worker-Trennung in 5 Queue-Gruppen

Historical implementation plan. The canonical current operations reference is docs/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:
    # 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):

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.)