Worker Process Manager

[martianboy]

Tracking issue for adding first‑class worker‑process orchestration to Peanar—from lightweight dev ergonomics to production‑ready health & scaling helpers—without turning the library into a full‑blown process supervisor like pm2.

---

🎯 Goal

Provide opinionated, opt‑in tooling and guidelines so Peanar users can run workers safely and efficiently (local dev → single‑VM prod → container/Kubernetes) while keeping Peanar itself lean and broker‑centric.

---

📝 Scope

Layer	What we deliver	Status
L0 Docs	Deployment recipes, systemd & k8s snippets, best‑practice guide	☐
L1 Lifecycle Helpers	@peanar/worker-lifecycle utilities • signal capture • graceful drain • health probe stub	☐
L2 Dev Launcher	CLI: peanar run -w <n> ./worker.js (forks via cluster/child_process)	☐
L3 Metrics & Autoscale Hints	Prom/OTLP gauges for lag & in‑flight; pure‑function recommendedReplicas()	☐
L4 Mini‑Supervisor (opt‑in)	peanar supervise wrapper with simple restart/back‑off	☐

---

🚫 Non‑Goals

• Replicating pm2/systemd/k8s features (log rotation, CPU pinning, remote dashboards, etc.).
• Shipping opinionated infrastructure code (Helm charts, Terraform).
• Implementing an autoscaler—only hints.

---

📐 Design Tenets

1. Stateless CLI, stateful workers – no cross‑process coordination.
2. Graceful by default – shutdown contract & drain API.
3. Opt‑in everything – existing setups remain untouched.
4. Metrics first‑class – expose, don’t store/visualise.

---

✅ Acceptance Criteria

• A dev can run peanar run -w $(nproc) ./worker.js and see all child PIDs, live reload on SIGINT, and clean drain on SIGTERM.
• Health probe returns JSON: { "status": "ok", "lag": <int>, "inFlight": <int> } and is consumable by Kubernetes readinessProbe.
• Metrics exported in Prometheus format behind a toggle.
• Docs include copy‑paste examples for systemd, Docker Compose, and k8s Deployment + HPA.
• All new packages covered by unit tests; L2‑L4 paths have integration tests with real RabbitMQ.
• No breaking changes to peanar@core.

---

📋 Task Breakdown

General

• Create @peanar/cli workspace package
• CI matrix update (Node 18 + latest, Linux/macOS)

Layer 0 – Documentation

• Write “Running Workers in Production” guide
• Add sample manifests (systemd, Compose, k8s) to /examples

Layer 1 – Lifecycle Helpers

• Implement hookCaptureSignals() util
• Implement startHealthProbe() server
• Docs + usage snippet

Layer 2 – Dev Launcher

• CLI argument parsing (commander)
• Fork logic with cluster / fallback to child_process
• Live statistics banner (optional)
• Unit & integration tests

Layer 3 – Metrics & Autoscale Hints

• Prom exporter (prom-client)
• autoscale.recommendedReplicas() function
• Docs & examples

Layer 4 – Mini‑Supervisor (optional)

• Back‑off restart logic
• CLI flags: --max-restarts, --restart-window
• Disabled by default; flag‑guarded

DX / Tooling

• TypeScript typings & strict mode
• API reference generation

---

❓ Open Questions

1. Default bundle – Ship CLI inside peanar or separate package?
2. Metrics back‑ends – Prometheus only, or add StatsD / OTLP hooks?
3. Target Node versions – keep Node 18 LTS baseline?

---

_Use this epic to coordinate PRs; link each Layer’s implementation issue/PR here and tick boxes as they merge.