At the end of the previous lesson one loose end was left: POST /api/orders reads req.body, but req.body does not exist unless something created it first. That "something" is a middleware, and middleware is not just another Express feature: it is Express. Everything the framework does —routing, reading bodies, serving static files, handling errors— is built on the same mechanism: a list of (req, res, next) functions walked in order, passing the baton along. In this lesson we take that mechanism apart to the bottom, write Escena Viva's own middleware and compare Express's built-ins with the body.js and static.js you programmed by hand in Module 4.

1. What a middleware is
2. The journey of a request
3. next(), next(error) and not calling next()
4. Types of middleware
5. Registration order is execution order
6. Middleware with a mount path
7. Escena Viva's own middleware
8. Built-in middleware: json, urlencoded, static
9. Asynchronous middleware
10. Middleware factories

A middleware is a function with this signature:

The conceptual key: a route is a middleware too. app.get('/health', handler) adds to the same stack an entry that, besides the method and the pattern, holds a function with the same signature; when Express processes a request it walks a single list where middleware and routes live together. You already did this in Module 4 without calling it that: you chained readBody before the POST /orders handler and checked the content type, all before the logic. Express turns that pattern into the framework's central mechanism.

Two paths, a normal one and an error one. A middleware can jump from the normal path to the error path at any point, and there is no going back: once inside the error handler, the remaining normal middleware no longer run.

These options are the entire grammar of the mechanism.

Symptoms of the bad version: curl sits there, the browser spins forever, no error shows up in the server console and the process is perfectly healthy. It is baffling precisely because there is no error: nobody has simply finished the response. To diagnose it:

That way a hung request leaves a trace on stderr with its method and its path, and all you have left to do is look at which middleware on that route has an if with no exit.

Rule: after next(...), write return unless it is the last line. Calling next() twice triggers the Cannot set headers after they are sent to the client warning, another classic that is hard to track down.

They are all the same thing: functions in the stack. The only one distinguished by its shape is the error one, which has four parameters; Express counts the arguments (fn.length) to decide whether it is a normal or an error middleware, and that is why forgetting the fourth parameter means your handler never runs (06-07).

There are no priorities and no clever resolution: Express walks the stack top to bottom, in the exact order in which you registered each entry.

In the bad version the middleware is registered, yes, but after the route: since the route responds, the chain ends before reaching it.

The canonical order in createApplication(), which we will keep completing and will close in 06-05: settings (disable('x-powered-by'), set('trust proxy')), security and headers (helmet, cors), observability (requestId, requestLogger), body parsing (express.json), static files (express.static), API routes, the 404 middleware and, always last, the error handler.

app.use(fn) always runs; app.use('/api', fn) only if the path starts with /api. Mounting with a prefix has a surprising effect: inside the mounted middleware, req.url loses the prefix.

Inside a middleware mounted at /api, for GET /api/events/evt-001?x=1:

That rewriting is what lets src/routes/events.js declare router.get('/:id') without knowing it will be mounted at /api/events. It is the same technique express.static uses: mounted at /downloads, it looks on disk only for the relative part.

Logging tip: in request-logger.js always use req.originalUrl. With req.url inside a mount, your logs will show incomplete paths and you will not be able to correlate them with what the client sees.

It generates a unique identifier per request: the foundation of traceability, which will show up in the logs, in the error responses (06-07) and in the structured logging of Module 11.

An important detail: the received identifier is validated. Blindly accepting a client header would allow injecting line breaks into the logs or enormous values; the regex bounds length and characters.

It measures the real duration of every request and writes it to stderr, following the course convention.

Why res.on('finish') and not measuring after next(): because next() returns control as soon as the next middleware suspends on an asynchronous operation, not when the response has been sent. The finish event of ServerResponse —the same stream object from Module 3— is the only reliable point.

Serving the availability of Sala Bóveda from a thirty-second cache is exactly how you sell a ticket that no longer exists.

In src/app.js they end up registered in this order: app.use(requestId) first, because everything else uses it; app.use(createRequestLogger()) second, to measure from as early as possible; and then express.json({ limit }).

It is configured with express.json({ limit: '100kb', type: 'application/json', strict: true }): limit is the equivalent of your BYTE_LIMIT, type bounds which Content-Type it parses and strict accepts only objects and arrays at the root. An honest comparison with what you wrote in Module 4:

It is your own design with more edge cases covered. A body that exceeds the limit returns 413 and broken JSON returns 400; those errors reach the central handler like any other, and in 06-07 we will translate them into our format by looking at their type property. One surprising detail: if the Content-Type is not JSON, express.json() does not complain, it simply does nothing and req.body stays as {}. If you want the 415 from Module 4, you have to demand it explicitly:

It parses classic HTML forms with app.use(express.urlencoded({ extended: true, limit: '20kb' })). With extended: true it uses the qs library and accepts nested structures (filter[venue]=Sala+Boveda); with false it uses the core querystring and everything stays flat. Escena Viva is a JSON API and does not need it, but it is worth knowing about in case you add a contact form.

What it does better than your version: HTTP ranges, dotfiles, fallthrough (which lets a nonexistent file carry on to your 404 instead of responding right there) and a list of MIME types you will never want to maintain by hand. What your version did and this one does not: compression, delegated to a dedicated middleware. It is a better separation of responsibilities than yours.

A middleware can be async and in Express 5 this simply works: if getCatalog rejects (unreadable file, corrupt JSON) in async function loadCatalog(req, res, next) { req.catalog = await getCatalog(); next(); }, Express catches the rejected promise and calls next(error) for you.

In Express 4 that code left the request hanging if the promise rejected, and you had to wrap every handler with const asyncHandler = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next). If you run into asyncHandler, express-async-handler or wrapAsync in a project, you now know what they are: Express 4 leftovers that are unnecessary in Express 5. We will go deeper in 06-07.

The exception that is still yours: callbacks inside a handler. Express can only catch what the promise you return rejects with; it does not see a throw inside a setTimeout or inside a stream.on('data').

A fixed middleware serves one case. A factory —a function that returns a middleware— serves them all, and it is the pattern used by express.json({ limit }), helmet({ ... }) and cors({ ... }).

Three concrete advantages: it is configurable without duplicating code; it does the expensive work only once (compiling regexes, reading configuration, opening resources), so the returned middleware does only the bare minimum per request; and it is testable, because in Module 9 you will be able to call requireHeader('X', {...}) and test the returned function with fake objects, without bringing up a server.

It is exactly the same pattern as the createRequestLogger(options) you already wrote in section 7. When you hesitate between exporting a middleware or a factory, export the factory: it costs one extra line and saves you a refactor.

• Not calling next() on some path. The request hangs with no errors. Use the hang detector in development and write return after every next(...).
• Calling next() and responding as well. It triggers Cannot set headers after they are sent; it usually comes from a forgotten return.
• Registering express.json() after the routes. req.body will be undefined: the number one error in your first POSTs.
• Registering the error handler in the middle. It only catches what was registered before it; it always goes last.
• Using req.url in logs inside a mount. You will see paths without the prefix: use req.originalUrl.
• Global middleware that is only needed on one route. noCache across the whole application destroys the static files' cache; mount each one in the narrowest scope.
• Expensive work inside the middleware instead of in the factory. Compiling a regex on every request is pure waste.
• Trusting client headers without validating. X-Request-Id comes from outside: bound its length and characters.
• Tip: a middleware must do one thing. If yours authenticates, logs and compresses, that is three, and three is the number of places where you will go looking for the bug.

Write src/middleware/response-time.js with a createResponseTime() factory that adds an X-Response-Time header with the milliseconds the request took. Hint: you cannot set headers in res.on('finish') because they have already been sent; you have to intercept the exact moment before by wrapping res.end.

Create an application with three middleware, where the second one has a path that does not call next(). Check with curl that the request hangs, add the detector from section 3 and prove that the problem shows up on stderr with method and path.

Serve public/ with express.static configured with maxAge: '1h' and etag: true. With curl -si check: that the first request returns 200 with ETag and Cache-Control, that repeating it with -H 'If-None-Match: <etag>' returns 304 with no body, and that requesting /public/../.env does not escape the directory. Contrast the result with what your static.js did.

Solution 1

res.on('finish') is no good because by then the headers have already travelled over the network: setHeader would throw or be ignored. res.on('close') is even worse, because it can fire with the connection already closed. This end wrapper is the technique morgan uses internally.

Solution 2

curl -s --max-time 5 localhost:3000/tickets hangs and stderr shows [hang] GET /tickets; adding -H 'X-Venue: Sala Boveda' it responds {"venue":"Sala Boveda"}.

Solution 3

The third case works because express.static normalizes the path and rejects anything outside the base directory, just like your resolveWithin; the difference is that this protection now lives in a package that millions of deployments exercise every day, not in twenty lines of yours.

Middleware is the single mechanism the whole of Express is built on: a stack of (req, res, next) functions walked in the exact order of registration, where each one reads, modifies, short-circuits or passes the baton, and where next(error) opens a second path there is no coming back from. You have seen the full journey diagram, the framework's most frustrating bug —not calling next()— and how to diagnose it, the difference between req.url, req.baseUrl and req.originalUrl when mounting with a prefix, and why registration order admits no exceptions.

Escena Viva now has its own middleware: requestId for traceability, createRequestLogger measuring with res.on('finish') and writing to stderr, noCache mounted only where capacity changes, and requireHeader as an example of a configurable factory. And you have confirmed that express.json() is your body.js with more edge cases covered, and that express.static() is your static.js plus mime-types.js with range support and dotfiles. All of them are yours so far.

In the next lesson, Essential Third-Party Middleware, we assemble the minimum kit that no API should go to production without: helmet and its security headers one by one, cors so that Escena Viva's public/app.js can call the API from another origin, morgan for HTTP logging, compression for bandwidth and express-rate-limit so a script cannot exhaust the Auditorio Ribera's capacity in ten seconds. Each one put through the audit filter you learned in Module 5, and all of them ordered in the definitive version of createApplication().