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

A middleware that adds a request ID works perfectly. A copy of it that also calls an async audit log starts throwing Cannot set headers after they are sent under load — but only sometimes. The bug is not the audit call. It is that the async error escapes the middleware, the framework’s default handler responds, and then the original code path responds too. Two responses, one socket. The middleware contract was broken in the most common way there is.

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).

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.