production

Going to production

The gap between "it runs" and "it runs unattended" is a short list of specific behaviours. Most of them are invisible until a deploy drops requests or a restart loop starts at 2am.

29 tests ship with this code and pass (bun test, tsc --noEmit clean, Bun 1.3.10).

SKILL="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/production}"; SKILL="${SKILL:-PASTE_THE_DIR_THIS_SKILL_MD_WAS_READ_FROM}"  # that var is UNSET in a Bash tool (MEASURED) — so paste it. `:?` would ABORT the block and copy nothing
mkdir -p src; if [ -d "$SKILL/assets" ]; then cp -r "$SKILL/assets/production" src/runtime   # logger + shutdown + tests + Dockerfile + dockerignore.example
else echo "SKILL is still the placeholder — paste the real dir above and re-run"; fi

The Dockerfile and dockerignore.example are copied alongside the code — move them to the repo root (.dockerignore) rather than leaving them under src/.

Shutdown: the ordering is the whole thing

When an orchestrator removes a pod it does two things roughly at once — sends SIGTERM, and tells the load balancer to stop routing. Those propagate at different speeds, so for a second or two after SIGTERM traffic is still arriving. Stopping the listener first (the obvious implementation) drops exactly those requests, which is why deploys "occasionally" 502.

1. flip readiness to NOT ready     → the LB removes us on its next probe
2. wait drainDelayMs (default 5s)  → let in-flight routing decisions land
3. server.stop()                   → stop accepting; MEASURED to wait for in-flight requests
4. close resources (DB, queues)    → only now, when nothing can still need them
5. exit 0

MEASURED (Bun 1.3.10): server.stop() with no argument resolves only after in-flight requests finish — a 300 ms request signalled at t+80 ms drained in 226 ms. stop(true) force-closes and is the deadline fallback. A shipped test asserts the sequence order and that stop is called without force on the happy path.