The server from the previous lesson has a flaw that is embarrassing to show: it answers exactly the same thing to GET /events, to POST /orders and to DELETE /wipe-everything, always with a 200 OK. It does not look at the method, it does not look at the path and it does not look at the parameters. It is a deaf server.

In this lesson we give it ears and a voice. We are going to take apart the two objects the handler receives —req and res—, learn how to extract information from the request properly, and build the vocabulary Escena Viva will answer with for the rest of the course: the status codes, the headers that matter and a helper module, src/server/responses.js, along with the piece that will travel the furthest: the table that maps our domain error.appCode values to HTTP statuses. That table will survive the arrival of Express in Module 6.

1. req: the anatomy of IncomingMessage
2. req.url is not a URL: parsing it with new URL
3. res: the anatomy of ServerResponse
4. ERR_HTTP_HEADERS_SENT: the module's most frequent error
5. The status codes the course will use
6. The headers that matter
7. src/server/responses.js
8. From domain error.appCode to HTTP status
9. Redirects and the HEAD method

The handler's first argument is an instance of http.IncomingMessage. And the first thing to know about it is that it is a readable stream: IncomingMessage extends stream.Readable, with everything that implies since lesson 03-04 (data and end events, for await...of, backpressure). Node hands you the object as soon as it has finished reading the headers; the body may still be travelling over the network while your handler is already running. That is why the body has to be read patiently, and that is why it gets its own lesson (04-05).

The properties you use daily:

Two warnings worth money. The first: the keys of req.headers are normalized to lowercase, so req.headers['Content-Type'] is undefined and req.headers['content-type'] works. The bug is subtle because it raises no error, just a silent undefined. The second: behind a reverse proxy or a load balancer, req.socket.remoteAddress will give you the proxy's IP; the real client's arrives in X-Forwarded-For, a header that is only trustworthy if you control the proxy writing it. We will come back to it when rate-limiting requests by IP in lesson 08-06.

This is where nearly everyone writes their first bug. req.url is the protocol's request URL: a path with its query string, with no origin. And the temptation is to treat it as text:

That code fails in four real scenarios:

1. It does not decode. With GET /events?venue=Sala%20B%C3%B3veda you get the literal string Sala%20B%C3%B3veda, which matches neither 'Sala Boveda' nor anything else.
2. It breaks with more than one parameter. ?venue=X&sort=date leaves venue holding X&sort=date.
3. It ignores repeated parameters. ?category=jazz&category=comedy is valid HTTP and means two values.
4. It does not account for the fragment or redundant slashes, nor does it normalize anything.

The right tool is the URL class, global since Node 10 and a browser standard. It needs an absolute URL, so you pass it a base:

searchParams is a URLSearchParams: it decodes percent-encoding and +, supports repeated keys with getAll, and it is iterable. A practical check against our catalog:

One important detail about pathname: the URL class does not fully decode the path (for example %2F stays %2F, and rightly so: an encoded slash must not turn into a segment separator). If an identifier can carry encoded characters, apply decodeURIComponent to each segment separately, never to the whole path. It is a precaution we will pick up again when extracting route parameters in the next lesson.

A useful pattern for reading numeric parameters with a default value and validation:

The second argument is an http.ServerResponse, and its nature is symmetrical to req's: it is a writable stream, ServerResponse extends stream.Writable. That means res.write() returns false when the buffer fills up, that it emits drain, and that you can hook a pipeline to it —exactly what we will do in lesson 04-04 to serve files.

A response is built in three steps, and the order is not negotiable:

The methods, each with its nuance:

writeHead and setHeader can be combined —writeHead wins in case of conflict—, but mixing styles is confusing. In Escena Viva we will use setHeader for anything cumulative and writeHead only when the response closes immediately.

HTTP sends the headers before the body, because that is how the message travels. And once a byte has gone out through the socket, there is no way to get it back. That is why this code blows up:

In practice, the error is almost never that obvious: it shows up when one function responds and execution continues into another that responds as well.

The three rules that prevent it forever:

• Responding means finishing. Every call to a response helper is preceded by return (return sendError(...)), or lives inside an if/else with no way out.
• A handler responds exactly once. If you need to choose between several branches, compute first and respond at the end.
• In catch blocks, check res.headersSent before trying to respond with a 500: if the failure happened halfway through a stream, all you can do is res.end() or res.destroy(), because the client already received a 200 that you will not be able to take back.

The first digit gives the family: 2xx went well, 3xx look elsewhere, 4xx you got it wrong (the client), 5xx I got it wrong (the server). That border between 4xx and 5xx is the most important of all: a 500 is an alert for the developer; a 4xx is not.

Three distinctions that come up in any interview and, more importantly, that any badly built API gets wrong:

• 400 versus 422. 400 is "I don't understand what you're sending me" (broken JSON, wrong type). 422 is "I understand you perfectly and your request makes no sense" (you ask for 8 tickets with a limit of 6). Many APIs use 400 for both; we will distinguish, because the resulting error message is far more useful.
• 401 versus 403. 401 is "I don't know who you are" and usually comes with WWW-Authenticate; 403 is "I know who you are and I won't let you". The official names are the reverse of what they seem, which is why they get mixed up.
• 404 versus 409. If the session does not exist, 404. If it exists but there are no tickets left, 409: the resource is there, what fails is the state.

Content-Type declares what you are sending. For text, always with charset:

Without charset=utf-8, an old browser can render Bóveda as Bóveda. In JSON the standard already mandates UTF-8, but declaring it costs nothing and in text/html and text/plain it is essential.

Content-Length versus Transfer-Encoding: chunked. If you know the exact size in bytes, declare it: the client can show a progress bar and reuse the connection better. If you do not know it —because you are generating the response on the fly or sending a stream—, Node uses chunked automatically, splitting the body into length-prefixed chunks.

Using body.length here is a classic and very damaging mistake: 'Bóveda' has 6 characters and 7 bytes in UTF-8. Announcing one byte too few makes the client truncate the response and fail the JSON.parse, with an incomprehensible message.

Cache-Control says how long the response may be stored. In an API of live data, no-store; in a static file, seconds or years (04-04). Location points to where the resource is: mandatory in a 201 (where the created thing ended up) and in a 3xx (where to go).

Writing statusCode, setHeader and end in every branch is repetitive and, above all, it is where inconsistencies creep in: one route forgetting the charset, another returning the error as plain text. Let's centralize it.

Three deliberate decisions. Every error has the same shape ({ error: { code, message, status } }): a client can program against code, which is stable, instead of against message, which will change. Content-Length is always computed with Buffer.byteLength, never with length. And headersSent is checked in a single place, so a double response pollutes the log but does not take down the process.

We reach the module's key piece. Since Module 2, our domain has thrown errors with their own appCode: SESSION_NOT_FOUND, INSUFFICIENT_CAPACITY, INVALID_QUANTITY. That vocabulary belongs to Escena Viva and knows nothing about HTTP: which is exactly what we want, because SalesManager must be usable from a CLI, from a scheduled job or from an API.

The bridge between the two worlds is a table, and it lives in the HTTP layer, not in the domain:

Why this is the right thing and not an architect's luxury:

• The domain stays uncontaminated. Event.reserve keeps throwing INSUFFICIENT_CAPACITY without knowing the number 409 exists, so it can still be used from src/catalog.js in the terminal.
• The default failure is 500 and it is noisy. An unknown appCode means somebody invented a new error and forgot to register it here: we want to find out, not to have it silently become a 400.
• 5xx responses leak nothing. The internal message goes to stderr for us; the client gets generic text. A stack trace in the response is a gift to anyone hunting for your Node version and your disk paths.
• There is one single table. When we reach Express in lesson 06-07, the error handler will change shape, but it will still consult this very file.

Using it is one line:

In the next lesson that try/catch will stop repeating itself on every route: it will move up once into the router's dispatcher.

A redirect is a 3xx with the Location header. The four that matter:

Careful with the 301: browsers store it aggressively and, if you get the target wrong, users will keep going to the bad place even after you fix the server, because they will not even ask you again. When in doubt, 302.

The HEAD method asks for a response identical to GET's but with no body: it is used to check a resource's size or date before downloading it. The good news is that Node handles it almost by itself: if the method is HEAD, it discards whatever body you write and sends only the headers. Even so, being explicit avoids generating useless work:

Note that Content-Length is still sent even though there is no body: it is precisely the piece of data the client came looking for.

• Reading req.headers['Content-Type'] with capitals. It returns undefined with no error. The keys are always lowercase.
• Splitting req.url with split('?') or split('/'). It breaks with encoded parameters, repeated ones and more than one. Use new URL(req.url, base).
• Computing Content-Length with body.length. It counts characters, not bytes; with an accent or an ñ, the response arrives truncated. Use Buffer.byteLength.
• Responding without return. It is the number one cause of ERR_HTTP_HEADERS_SENT.
• Sending a body in a 204 or a 304. The spec forbids it and some proxies choke on it.
• Returning 200 with { "error": ... } inside, or the stack trace in a 500. The status is part of the response, and the trace goes to the log, never to the client.
• Tip: decide from the start on a single error format for the whole API and never change it. Your clients will appreciate it more than any feature.
• Tip: in catch blocks that wrap streams, check res.headersSent; if they already went out, the only honest thing left is res.destroy().

Extend the handler so that GET /events accepts ?venue= and ?category= (the latter repeatable) and returns the filtered catalog, in the shape { total, filters, events }. Validate that venue is not empty and respond 400 with code: 'INVALID_PARAMETER' if it is. Check it with curl -s 'http://localhost:3000/events?venue=Sala%20B%C3%B3veda'.

Add to src/server/http-errors.js the codes CORRUPT_DATA (the catalog JSON is broken: that's our fault) and UNSUPPORTED_FORMAT (the client asks for a format we don't serve). Choose the status for each and justify it. Then write src/server/check-errors.js, a script that walks STATUS_BY_CODE and prints a code | status | family table, plus the count per family.

Make the handler answer HEAD /events with the same headers as GET /events but with no body, and check with curl -I that Content-Length matches exactly the number of bytes curl -s ... | wc -c returns. Add a venue with an accent to the catalog and verify that it still adds up.

Solution 1. All the information comes from searchParams, and the validation throws with error.appCode so the table can translate it:

With ?venue=Sala%20B%C3%B3veda it returns 1 event (evt-002, Noche de Monologos). Had you used split('='), the comparison would be against 'Sala%20B%C3%B3veda' and the result zero events: a filter that "finds nothing" and looks like a data problem.

Solution 2. CORRUPT_DATA is a 500: the catalog file is our responsibility and the client can do nothing about it, so on top of that we want it logged. UNSUPPORTED_FORMAT is a 406 Not Acceptable, the specific status for "I cannot produce any of the formats you accept"; if you would rather not widen the course's vocabulary, 400 is defensible, but 406 is more precise. The script relies on the family being the first digit:

Solution 3. The key is computing the body the same way for both methods and deciding only at the end whether to send it:

curl -I (which sends HEAD) and curl -s ... | wc -c must give the same number. When you add a venue with an accent, Buffer.byteLength grows more than the character count —each accented character takes two bytes in UTF-8—, and that is where you see why body.length would have lied.

You now know how to listen and answer properly. req is an IncomingMessage which, besides method, headers —always lowercase—, httpVersion and socket.remoteAddress, is a readable stream whose body may still be travelling. Its url is not a complete URL but path plus query, and the only sensible way to interpret it is new URL(req.url, base) with searchParams: it decodes percent-encoding, supports repeated keys with getAll and does not break on ?venue=Sala%20B%C3%B3veda.

res is a ServerResponse and a writable stream, with an inviolable order: status and headers first, body afterwards, end() always. From that comes the module's most frequent error, ERR_HTTP_HEADERS_SENT, cured by a simple rule: responding means finishing, and you respond only once. You have the complete catalog of statuses the course will use, with the borders people get wrong most often —400 versus 422, 401 versus 403, 404 versus 409— and the essential headers, including the discipline of computing Content-Length with Buffer.byteLength and not with String.length.

And Escena Viva takes away two modules that will stay with it to the end: src/server/responses.js, with sendJson, sendText, sendError, sendNoContent and sendRedirect, all sharing a single error format; and src/server/http-errors.js, with the table that maps error.appCode to an HTTP status —EVENT_NOT_FOUND to 404, INSUFFICIENT_CAPACITY to 409, INVALID_QUANTITY to 400— and a noisy 500 by default for whatever we cannot classify.

We are missing the obvious: deciding which handler serves each request. In the next lesson, Manual Routing, we will start with the naive if/else, see exactly where it breaks, and build src/server/router.js with a route table, /events/:id-style patterns compiled into regular expressions, parameter extraction, 405 responses with an Allow header and a central try/catch that will use the table you have just written.