spec: single-process-single-worker

[filafb]

Summary

Adds an SDD specification (specs/single-process-single-worker.md, Status: Draft) proposing single-process mode for @vtex/api: when the resolved worker count is 1, the SDK runs the HTTP server directly in the main process and skips Node's cluster layer entirely — no master, no fork(), no IPC connection forwarding.

@vtex/api is injected into all VTEX IO applications, so today's unconditional "master + at least one worker" topology multiplies a fixed per-replica cost (an idle master process + IPC accept/distribute hop) across the whole platform whenever a service runs a single worker. This spec eliminates that for the single-worker case while leaving multi-worker (workers > 1) behavior unchanged.

Decisions captured

• Trigger: single-process mode iff serviceJSON.workers === 1; getWorkers/default worker count untouched.
• Unconditional rollout — no env flag.
• Applies in LINKED/dev mode too — debugger attaches to the main process (replacing cluster.setupMaster inspect-port indirection).
• No self-restart on crash — container/orchestrator restart is the recovery mechanism.

Spec contents

• Business Context — problem, 4 user stories, key scenarios, FRs/NFRs, explicit out-of-scope (default worker-count change and SO_REUSEPORT redesign are deferred).
• Arch Decisions — bootstrap branch design, before/after mermaid diagrams, master-responsibility mapping table, alternatives, risks, 4 decisions, implementation plan. Decision 4 includes a full recovery trade-off analysis: in-process re-fork vs container restart, and a recovery-under-load note showing the master's unbounded connection queue can amplify load-induced crashes into a degradation loop, whereas single-process mode sheds load and reroutes to sibling replicas (minReplicas ≥ 2 is the default topology).
• Technical Contract — ServiceJSON.workers as the decision input (no schema change), reused interfaces, integration points, invariants.

Out of scope

No implementation — this PR contains the spec file only. Changing the default worker count (cgroup-aware) and replacing cluster with SO_REUSEPORT are deferred to separate specs.

🤖 Generated with Claude Code

[sonar-workflows]

Quality Gate failed

• 315 New Issues (is greater than 0)
• 30.30% Coverage on New Code (is less than 80.00%)
• 0.00% Security Hotspots Reviewed on New Code (is less than 100.00%)

Project ID: node-vtex-api

View in SonarQube