The Middleware Pattern

Before this

• Building an HTTP Server — Routes, handlers, and the request lifecycle from socket to response.

Why this exists

Every route in an API needs to check authentication, parse the request body, and log the request — writing that logic inside each of forty route handlers means forty copies of the same three things, and forty places to fix a bug in any of them. Middleware runs that shared logic once, in a pipeline every request passes through before reaching its specific handler.

The mental model

Think of middleware as a series of checkpoints a request passes through, one after another, before reaching its final destination (the route handler). Each checkpoint can inspect or modify the request, respond directly and stop the request from going further, or wave it through to the next checkpoint — that decision is made by whether it calls `next()`.

How it works

The mechanism

A request enters the pipeline and passes through each registered middleware in order. Each middleware either calls next() to pass control forward, or responds directly and ends the pipeline there. Only if every middleware in the chain calls next() does the request finally reach its matched route handler, which then produces the actual response.

flowchart LR
  R[Request] --> M1[Logger middleware]
  M1 -->|next| M2[Auth middleware]
  M2 -->|next, if valid| H[Route handler]
  M2 -->|else: res.status 401| End[Response sent, pipeline stops]
  H --> Resp[Response]

What people get wrong

Middleware and route handlers are fundamentally different kinds of functions.

A route handler is really just the LAST middleware in the chain for that specific route — it has the same signature (req, res, next) and follows the same rules, it just conventionally doesn't call next() because it's expected to send the final response. Seeing them as the same underlying mechanism clarifies why middleware composes so naturally with routing — there's no separate system, just a convention about which one sends the actual response.

Forgetting to call next() in a middleware just means that middleware's logic doesn't run.

Forgetting next() (and not sending a response either) means the ENTIRE pipeline stops there — the request hangs indefinitely, since nothing ever tells the router to move on or complete the response. This is one of the most common middleware bugs, and its symptom (a request that hangs and eventually times out, with no error message anywhere) doesn't obviously point back to a missing next() call.

Middleware order doesn't matter as long as all the necessary middleware is registered somewhere.

Since middleware runs strictly in registration order, and each one can inspect what earlier middleware attached to the request, order determines both WHAT information is available at each step and whether earlier gating (like auth) has already happened by the time a later middleware runs. A logging middleware registered after an authentication middleware that short-circuits will never log rejected requests at all, which may hide exactly the requests you'd most want visibility into.

When not to use it

The logic is specific to exactly one route and will never apply to any other.

Put it directly in that route's handler rather than as separate middleware — middleware's value is in being SHARED across multiple routes; a single-use piece of logic gains nothing from the extra indirection.

You need to handle an error thrown anywhere in the middleware chain or a route handler.

A dedicated error-handling middleware (recognized by having four parameters: err, req, res, next), registered last — this is a distinct middleware signature specifically for catching errors that occur earlier in the pipeline.

Terms

Middleware

— A function that runs during the request-response cycle, with the ability to inspect/modify the request, respond directly, or pass control to the next function in the pipeline.

next()

— The function a middleware calls to pass control to the next middleware (or route handler) in the pipeline; not calling it (without responding) hangs the request.

Short-circuit

— A middleware responding directly and not calling next(), stopping the request from reaching any subsequent middleware or the route handler.

Error-handling middleware

— A middleware with a four-argument signature (err, req, res, next), specifically for catching and responding to errors thrown earlier in the pipeline.

In an interview

Connected ideas

• Sessions vs JWTs — Two ways to remember who's calling, with genuinely different failure modes — especially logout.
• Logging & Observability — Structured logs, metrics, traces — being able to answer 'what happened?' at 3am.