Writing middleware: signatures, next(), and the three framework models

The Express signature

In Express, a middleware is (req, res, next) => {}. It has exactly three legal endings:

• Pass through — call next() to hand control to the next middleware.
• Terminate — send a response (res.json(...), res.end()) and do not call next(). This short-circuits the chain.
• Fail — call next(err) to skip ahead to error-handling middleware.

The two failure modes are doing both (send a response and call next(), leading to a double-send) or neither (no response, no next() — the request hangs until it times out). Together these three endings form a complete, closed contract — and every production bug in middleware traces back to breaking exactly one of them.

Error middleware is a different shape

Express recognizes error-handling middleware by arity: it must declare four parameters, (err, req, res, next). Drop the unused next and Express treats it as ordinary middleware and never routes errors to it — a silent, infuriating bug. Error middleware also must be registered last, after all routes, because the chain reaches it only via next(err) from earlier layers.

Koa: the async onion

Koa replaces the three-arg callback with async (ctx, next) => {} and a true onion model. Code before await next() runs on the way in; code after it runs on the way out, in reverse order. This makes wrap-around timing trivial:

async (ctx, next) => {
  const start = Date.now();      // inbound
  await next();                  // run everything inside
  ctx.set('X-Time', `${Date.now() - start}`); // outbound
}

Because it is promise-based, a throw anywhere propagates naturally to an upstream try/catch middleware — error handling is just a middleware that wraps the rest in try/catch around await next().

Fastify: hooks, not one primitive, plus encapsulation

Fastify splits the single middleware idea into named lifecycle hooks that fire in a fixed order:

onRequest → preParsing → preValidation → preHandler → handler → onSend → onResponse

This lets you reject early at onRequest (before body parsing — the cheapest rejection point) or run logic at preHandler once the validated body exists. The bigger difference is encapsulation: hooks (and decorators) registered inside a plugin apply only to that plugin’s routes, not globally. Express middleware, by contrast, leaks down the whole chain from where it is mounted. Encapsulation is why large Fastify apps stay scoped where large Express apps accrete global middleware.

The ordering choice is not free, and it is where the chain-length-vs-latency tradeoff bites. Each middleware is a function call plus whatever work it does; a lean layer (set a header, attach a request ID) costs well under a microsecond, but every layer is paid on every request whether or not it is needed. A global body-parser mounted before the router runs JSON.parse on bodies for routes that have none; an auth middleware mounted globally hashes and verifies a token even for a public health check. Rejecting at the wrong point compounds it: reject an unauthenticated request at onRequest and you skip body parsing, validation, and the handler — reject it inside the handler and you have paid for all of them first. The discipline is to order cheap, high-rejection-rate layers first and scope expensive layers narrowly. In practice this is why Express benchmarks at roughly 11–15k req/s while Fastify reaches 30k+ on the same hardware: not raw routing speed alone, but Fastify’s encapsulation keeping each route’s chain short instead of forcing every request through one fat global stack.