We closed Module 3 with one sentence: the project knows how to read and write, but it does not know how to talk to anyone. Escena Viva has a catalog on disk, reports by month, hardened paths and pipelines that process sales in constant memory. All of that is consumed by a single person: whoever runs the command in their terminal.

That changes today. By the end of this lesson, any browser on your network will be able to ask Escena Viva for data.

And you will see right away that this is not unfamiliar territory. A Node HTTP server is an EventEmitter that emits request —the same on and emit from lesson 02-05—, starting it is an asynchronous operation confirmed by an event, and keeping the process alive is exactly the event loop reference-counting mechanism we studied in 02-01. The node:http module adds no new concepts: it connects the ones you already have to the network.

1. HTTP in five minutes: request, response and a real exchange
2. http.createServer: the server is an EventEmitter
3. server.listen, the listening event and the port
4. Escena Viva's first server
5. Three ways to test it: browser, curl and node -e
6. Why the process no longer exits on its own
7. Startup errors: EADDRINUSE and EACCES
8. Graceful shutdown: server.close() and SIGINT

HTTP is a request and response protocol built on text. The client opens a TCP connection, sends a block of text in a very specific format, and the server replies with another block. That is all. Neither the client nor the server keeps any memory of what happened between one request and the next: HTTP is stateless, and everything that looks like state (sessions, carts, logged-in users) is built on top, as we will see in Module 8.

A request has four parts and a response three:

Here is a complete exchange, exactly as it travels over the wire. The blank line is what separates the headers from the body, and it is mandatory:

Notice two details that will save you hours of debugging later on:

• The path that reaches the server does not include the domain. Host: localhost:3000 travels in a separate header. That is why, as we will see in the next lesson, req.url is /events and never http://localhost:3000/events.
• Headers are plain Name: value text, case-insensitive, and they can repeat. Node always hands them to you normalized to lowercase.

The good news is that you are not going to write that text by hand: the node:http module parses it on arrival and generates it when you respond. You work with two objects, req and res.

The minimal server fits in four lines:

Save it as hello.js, run it with node hello.js and open http://localhost:3000. You already have a web server.

Now the important part: the function you pass to createServer is nothing special. http.Server inherits from net.Server, which inherits from EventEmitter. Passing the handler to the constructor is pure syntactic sugar: Node does a server.on('request', handler) for you. These two versions are exactly equivalent:

Knowing this is not trivia: it means you can register several request listeners, and that everything you learned about EventEmitter applies here. A real use case is separating request logging from the logic:

Diagnostics go to stderr and data to stdout, as we have been doing since Module 1.

These are the server events that matter in this module:

The difference between connection and request deserves a moment. They are not interchangeable: HTTP/1.1 keeps the connection open by default (Connection: keep-alive), so a browser loading a page with three images may open one connection and send four requests over it. Seeing it live makes the concept clear:

Reload the page a couple of times and you will see the request counter climb much faster than the connection counter. That detail comes back in section 8, when we try to shut the server down.

listen is what puts the server into listening mode. Its usual signature is listen(port, host, callback), and it is asynchronous: when the call returns, the socket is not ready yet.

That callback is not error-first: it is simply a listening listener registered with once. That is why this version does the same thing:

server.address() returns { address, family, port } and only has a value after listening; before that it returns null. It is the correct way to find out the real port when you ask for port 0, which means "let the operating system pick a free one" —an essential trick in the automated tests of Module 9, where you cannot fix a port without risking collisions.

The second argument, the host, decides who may connect: '127.0.0.1' accepts connections only from this same machine, and '0.0.0.0' (the default value) accepts them on every network interface, which is what you need in containers or to test from your phone.

In development, 127.0.0.1 is the prudent choice: it keeps your half-finished server from being exposed to the coffee shop's network. In Docker, on the other hand, it is a classic mistake, because the container would not receive the traffic forwarded from outside (we will cover this in Module 11).

Let's get to the real code. Create src/server/server.js. The rule we impose on ourselves from minute one is the one we have been defending all course long: no synchronous I/O inside the handler. The catalog is read with getCatalog(), which has been asynchronous since lesson 03-01.

Four decisions that carry through the whole module:

• createServer() is exported without starting it. Separating construction from startup is what will let us bring the server up on a random port inside a test (Module 9) without the file opening a port merely because it was imported. The require.main === module check is what keeps it runnable with node src/server/server.js.
• The .catch is not optional. http.createServer completely ignores whatever the handler returns. If the handler is async and throws, the promise is left rejected with no owner: the client hangs until its timeout expires and, since Node 15, the process crashes with unhandledRejection. A single corrupt event in the JSON would take down the entire server.
• res.headersSent avoids the ERR_HTTP_HEADERS_SENT error: if the failure happened after you started writing the response, the headers can no longer be changed. It is the most common error in this module and we take it apart in 04-02.
• The port comes from the environment. process.env.PORT lets you change it without touching the code; in production the platform imposes it. Configuration by environment is the topic of lesson 11-01.

Start the server:

The browser is the fastest test (http://localhost:3000), but it is also the one that teaches you the least: you see neither headers nor status code, and it adds phantom requests such as /favicon.ico that pollute your logs. It is useful, but not enough.

curl -i http://localhost:3000/ shows the complete response, headers included. It is the tool we will use throughout the module:

There are the seed numbers: 3 events, 7 sessions, capacity 3000, 1811 sold and 1189 available. Note that there is no Content-Length but a Transfer-Encoding: chunked; in 04-02 we will explain exactly why and when each one is preferable.

curl flags we will use: -i includes the headers, -s silences the progress bar, -X forces the method, -H adds a header and -d sends a body.

And node -e, to test from Node itself with fetch (the client API we will study in depth in 04-06):

Run the server and notice something that had never happened in this course: the process does not end. Every previous script did its job and returned control to the terminal. This one just sits there, apparently doing nothing.

It is not magic, it is the event loop reference counting from lesson 02-01. Node exits when there are no pending operations left that could produce future work. A listening socket is exactly that: an active handle that can wake the loop at any moment. As long as it exists, the count never reaches zero and the process stays alive.

You can verify it by unreferencing it:

That program prints listening and exits immediately, without having served anything. The server was correctly started; it had simply stopped counting. unref() has legitimate uses (a secondary metrics server that must not prevent shutdown), but for the main server it is a guaranteed bug. ref() undoes the effect.

The practical consequence is that, from now on, your process has a lifecycle: it starts, serves for days and has to be able to shut down properly. That is what section 8 is about.

Start the server in one terminal and, without stopping it, start it in another:

Recognize that message: Unhandled 'error' event is the one from lesson 02-05. An EventEmitter that emits error with no listeners throws the exception and takes down the process. http.Server is no exception to that rule.

The two startup failures you will see in practice:

EACCES surprises anyone who tries to listen on port 80 "because that's the HTTP one". On Unix-like systems, ports below 1024 are reserved privileges: only root can open them. The right answer is never to run Node as root, but to listen on a high port and let Nginx or the platform's load balancer listen on 80/443 (Module 11).

The fix is to register an error listener before calling listen, and to give a message people can understand:

error.code (the system property) is what comes from libuv; do not confuse it with our domain error.appCode, which we will translate into HTTP statuses in the next lesson. And process.exitCode = 1 instead of process.exit(1): let the process finish naturally, flushing its output buffers, as we already saw in Module 1.

To find the culprit behind an EADDRINUSE on Linux or macOS: lsof -i :3000 tells you which process holds the port, and kill <PID> frees it.

When you press Ctrl+C, your terminal sends the SIGINT signal to the process, and Node's default behavior is to die on the spot. That is acceptable in a script; in a server, it means cutting in-flight requests off mid-sentence: a client is left without its response, and a file write can be left half done.

Graceful shutdown means stopping the acceptance of new connections and waiting for the live ones to finish:

The delicate point is number 2, and it comes from what we saw in section 2: close() does not close existing connections, only the listening socket. With keep-alive, a browser that has asked you for a page leaves its TCP connection open for a few seconds in case it needs something else. Those idle connections are not serving anything, but they count as live, so close() sits there waiting and it looks like your server "won't close". closeIdleConnections() (Node 18.2+) handles exactly that case: it closes the ones with no request in flight and respects the ones that have one.

About the signals: SIGINT is your Ctrl+C; SIGTERM is the one Docker, systemd and deployment platforms send to ask for an orderly shutdown, with a grace period after which they send SIGKILL, which cannot be caught. Hence the safety timer: better to close yourself in 10 seconds than to be killed at 30 leaving files half written. In Module 11 we will come back to this with PM2 and Docker.

• Forgetting res.end(). The client waits forever. In the browser it looks like a tab spinning endlessly, and in curl like a response that never arrives. Every execution path of the handler must finish with an end().
• Doing synchronous I/O in the handler. A readFileSync on one route blocks the event loop and therefore every client at once, not just the one who asked for it. It is acceptable at startup; never inside request.
• An async handler with no .catch. Rejected promise with no owner, hanging client and a crashed process. Always wrap it, the way createServer() does.
• Not listening to the server's error event. An EADDRINUSE takes down your process with an incomprehensible stack trace instead of a useful message.
• Confusing connection with request. With keep-alive, one connection serves many requests. Counting connections is not counting visits.
• Tip: export createServer() without starting it and start it only under require.main === module. Your Module 9 self, writing integration tests, will thank you.
• Tip: during development, node --watch src/server/server.js restarts the process when you save. No dependencies and no nodemon.

Extend src/server/server.js so it keeps a count of TCP connections and of HTTP requests served, and exposes them in the JSON summary under the keys connections and requests. Then, with the server running, run curl three times in a row and afterwards reload the browser page three times. Explain why the two numbers do not grow the same way.

Write src/server/start.js that takes the port from process.argv (with process.env.PORT as a second option and 3000 as a third), starts the server and handles the three cases: successful startup (prints the real URL obtained from server.address()), EADDRINUSE (clear message and exitCode 1) and EACCES. Test it with ports 3000, 80 and with two instances at once.

Add a slow route to the handler: if req.url is /slow, wait 5 seconds with sleep (from src/utils/sleep.js) before responding. Run curl http://localhost:3000/slow and, while it waits, press Ctrl+C on the server. Check that the request completes and that only afterwards does closed cleanly appear. Repeat with closeIdleConnections() removed and explain what changes.

Solution 1. The counters are server state, so they live in createServer:

Three curl calls produce 3 connections and 3 requests: curl closes its connection when each invocation finishes. Three browser reloads normally produce 1 connection and 6 requests or more: the browser reuses the connection thanks to keep-alive and, on top of that, asks for /favicon.ico on its own. That asymmetry is precisely the reason closeIdleConnections() exists.

Solution 2. The key is that the error listener must be registered before listen, because the failure is emitted asynchronously but immediately:

With port 80 and no privileges you get EACCES; with two instances on 3000, the second one gives EADDRINUSE. Without the listener, both cases would be a stack dump with Unhandled 'error' event.

Solution 3. With closeIdleConnections() you will see the slow request complete and the process finish an instant later. Without it, if you have used the browser beforehand, the process hangs until the keep-alive expires (5 seconds by default, server.keepAliveTimeout), or even until the forced 10-second deadline if the browser renews the connection. It is the exact symptom of "my server won't close with Ctrl+C", and now you know the fault is not in your code, but in an idle connection that is still counting.

Escena Viva is on the network. And it got there with no new concepts: http.createServer returns an EventEmitter that emits request —it makes no difference whether you pass the handler to the constructor or register it with on—, plus connection, listening, close and that error which, if you do not listen for it, takes down your process just as in lesson 02-05. listen(port, host, callback) is asynchronous and its callback is nothing more than a once('listening'); server.address() gives you the real port, essential when you ask for port 0.

You have the first real server in src/server/server.js, with the discipline we will keep all module long: an asynchronous handler from minute one, a mandatory .catch so that a rejected promise does not cost you the process, a port configurable with process.env.PORT and createServer() exported without starting. You know how to test it with the browser, with curl -i —which shows the headers— and with node -e. You understand why the process no longer exits on its own: the listening socket keeps the event loop's reference count up, and unref() proves it by switching that off. And you know how to start and stop it properly: EADDRINUSE and EACCES caught with useful messages, and a graceful shutdown with SIGINT/SIGTERM, server.close() and closeIdleConnections(), because persistent connections do not close by themselves.

What our server does, however, is embarrassing: it answers the same thing to /, to /events and to /anything-at-all, always with a 200, without looking at the method or the parameters. It is time to really read what reaches us and to build carefully what we return. In the next lesson, Handling Requests and Responses, we take apart req —which is a readable stream— and res —which is a writable stream—, we learn to parse the URL without slicing strings by hand, we review the status codes the whole course will use and we build src/server/responses.js with the table that maps our domain error.appCode values to HTTP statuses.