Capstone: designing and hardening a production Node service

The checklist is the architecture

By the end of this lesson you will be able to trace a single request through a fully-hardened service and name the incident each skipped layer produces — so the next time a pull request cuts a corner, you’ll recognise it before it reaches production.

Going from prototype to production is not a rewrite — it is applying every unit of this track to one small HTTP service and refusing to skip any of them. The useful lens is a request-lifecycle checklist: for each cross-cutting concern, name what you do and the concrete signal for done when. Skip a row and you don’t get a smaller service; you get a future incident with a name. The 12factor manifesto and the Node best-practices repo are both, underneath, exactly this list — config in the environment, dependencies declared and locked, processes disposable, logs as event streams.

The senior move is to treat these as composing layers, not a feature backlog. Errors, the event loop, the middleware order, shutdown, validation, config, and observability are not independent checkboxes — they interlock. A graceful shutdown is worthless if the load balancer never learns you’re draining (that’s the readiness probe). An error boundary is worthless if a blocked loop means the boundary never runs. Below is the readiness checklist that this whole lesson defends.

The request lifecycle, hardened end to end

Trace one request and you can see every unit doing its job. The ingress or load balancer routes to a process whose HTTP server already has timeouts set — server.requestTimeout, headersTimeout, and a per-route handler timeout — so no single client can pin a connection open forever (unit 05). The request enters an ordered middleware stack, and order is load-bearing: logging first (so you log even rejected requests), then a body parser with a size cap (so a 4 MB body can’t blow up memory or block parse), then auth, then schema validation, then the handler. The handler calls a thin service layer, which calls a repository that issues parameterized queries — never string concatenation — and a domain failure becomes a typed error (unit 07, unit 03).

Threaded through all of it is request context. A pino structured logger carries a request/trace ID through AsyncLocalStorage, so every log line from deep in the stack is correlated to its request without passing the ID by hand. diagnostics_channel lets you publish instrumentation points (DB query start/end, cache hit) that exporters subscribe to without coupling. At the very end sits a single error boundary: error-handling middleware that maps error type to HTTP status (ValidationError→400, NotFoundError→404, anything unknown→500), sends a safe JSON body with no stack, and logs the full error object with its cause chain. That is unit 03’s strategy expressed as exactly one place in the wiring.

Bootstrap and shutdown: the wiring that decides uptime

Two pieces of plumbing decide whether deploys are invisible or destructive: the bootstrap that installs the safety net before anything serves, and the shutdown that drains before exiting. When you look at a new service’s index.js or server.ts entry point, ask yourself: does it install the process net before listen, and does it handle SIGTERM before the first request can arrive? On SIGTERM you do not slam the server shut — you flip readiness to not ready (so the load balancer stops sending new requests), stop accepting connections, let in-flight requests finish, close the DB pool, and arm a hard timeout so a stuck request can’t block shutdown forever. Skipping this is the dropped-checkout incident from the hook.

import { createServer } from "node:http";
import { app } from "./app.js";          // ordered middleware + error boundary
import { logger } from "./logger.js";
import { closePool } from "./db.js";

let ready = false;
const server = createServer(app);
server.requestTimeout = 30_000;          // unit 05: bound every request
server.headersTimeout = 10_000;

// unit 03: process net — record, then die; a supervisor restarts clean
process.on("uncaughtException", (err) => { logger.fatal({ err }); shutdown(1); });
process.on("unhandledRejection", (err) => { logger.fatal({ err }); shutdown(1); });

async function shutdown(code = 0) {
  ready = false;                         // readiness flips → LB drains us
  server.close(async () => {             // stop accepting; finish in-flight
    await closePool();
    process.exit(code);
  });
  setTimeout(() => process.exit(code), 10_000).unref(); // hard cap
}
process.on("SIGTERM", () => shutdown(0));

server.listen(3000, () => { ready = true; logger.info("listening"); });
// liveness = process is up; readiness = `ready` flag (12-factor disposability)