Escena Viva already returns impeccable JSON, but nobody buys tickets by reading JSON. What is missing is the part the user sees: some HTML, a stylesheet and a bit of browser JavaScript that consumes the API we have just built.

Serving files from disk over HTTP looks like the simplest task in the module, and it is exactly the opposite: it is where the interesting problems pile up. One of them is a textbook security hole that empties your entire project with a single request, and which we are going to exploit and close in section 2. The rest have to do with doing it properly: sending with constant memory instead of loading the file into RAM, declaring the right type, and making sure the second visit downloads nothing.

All of this reuses Module 3 while barely adding concepts: resolveWithin from lesson 03-03, createReadStream and pipeline from 03-04 and 03-05, stat from 03-02 and zlib.createGzip from 03-05. This time, wired to the network.

1. Escena Viva's mini front-end
2. From URL to disk path: the attack and the defense
3. The Content-Type by extension
4. Sending the file: createReadStream and pipeline
5. stat, Content-Length, default index and 404
6. Client-side caching: Cache-Control, ETag, Last-Modified and the 304
7. Range requests: Range and 206
8. Compression negotiated with Accept-Encoding
9. In production this gets delegated

Create the public/ folder at the root of the project with three files. The HTML is deliberately minimal:

And the browser JavaScript consumes the API from the previous lesson:

public/styles.css can be anything; what matters is that it exists and is big enough for the caching in section 6 to be noticeable. The folder split is intentional: public/ holds what anyone may read; data/events.json and src/, never.

The idea is obvious: the URL path is glued onto the public directory. And this is how the bug gets written:

It looks reasonable because path.join normalizes. The problem is that normalizing includes resolving the .., and the one who sets the pathname is the client: curl -s 'http://localhost:3000/../data/events.json'.

A browser collapses the .. before sending the request, so the attack does not come from the address bar: it comes from curl, from a script, or by encoding the sequence as %2e%2e%2f so it does not even look like what it is. path.join('/…/public', '/../data/events.json') returns /…/data/events.json, and your server hands over the whole catalog with total naturalness. With enough ../../, it hands over /etc/passwd. This is called path traversal and it is still near the top of web vulnerabilities decades after it was discovered.

We already wrote the defense in lesson 03-03: resolveWithin resolves the path and checks with path.relative that the result is still inside the base, throwing PATH_NOT_ALLOWED if it is not.

Two details that make the defense complete:

• Decoding happens before resolving. Otherwise %2e%2e%2f would pass the filter without being ../ yet, and the file system would interpret it afterwards. Decode first and validate second is the correct order; the other way round is a classic vulnerability.
• PATH_NOT_ALLOWED is already in the 04-02 table and maps to 403. The central error handler translates it on its own: the attacker gets a clean 403 Forbidden and you get the attempt logged in stderr.

Check it:

There is one case path does not cover, and we already warned about it in 03-03: a symbolic link inside public/ pointing outside produces a path that looks legitimate. If your public directory accepts files uploaded by third parties, validate with fs.realpath as well before serving.

The browser decides what to do with the response by its Content-Type, not by its extension or its content. If you serve styles.css as text/plain, the browser does not apply it; if you serve app.js as text/html, it does not run it; and in both cases there is no visible error, just an unstyled page that costs you half an afternoon.

Two rules that are not optional. The first: charset=utf-8 on anything textual. Without it, "Sala Bóveda" can end up as "Sala Bóveda", because the browser guesses the encoding and sometimes guesses wrong.

The second is about security. Browsers do sniffing: if the Content-Type looks dubious to them, they peek at the first bytes and decide for themselves. It sounds useful and it is dangerous: a file uploaded by a user and served as text/plain can be interpreted as HTML and run its <script> on your domain. The header that turns it off is one line:

With it, the browser obeys your Content-Type without arguing. It is one of the headers helmet sets for you in lesson 06-05; it pays to know what it does before delegating it.

The easy version, res.end(await fs.readFile(filePath)), works with styles.css and takes the server down with the 40 MB poster. readFile loads the whole file into memory before sending a single byte: with ten clients downloading at once that is 400 MB of RAM, and there is no backpressure. You have known the right way since lesson 03-05:

Three reasons why it should always be this way:

Backpressure is the point most people underestimate. res is a writable stream and pipeline respects its pace: if the client is on a slow connection, the disk read pauses by itself. And pipeline propagates errors and destroys both ends, which is exactly what plain pipe does not do: if the client closes the tab halfway through a download, pipe would leave the ReadStream open holding a file descriptor, and that is the classic leak that ends in EMFILE: too many open files after days of uptime.

An important nuance: if the client aborts, pipeline rejects with ERR_STREAM_PREMATURE_CLOSE. That is not a server failure and it must not reach the error handler as a 500:

Before opening the stream it is worth doing a stat, which gives us three things at once: whether it exists, the exact size in bytes —which goes straight into Content-Length, with nothing to compute, and beats letting Node use chunked because the browser can show real progress— and the modification date, which we will use in section 6.

It also solves two cases: the index file, because GET / asks for no particular file and we have to serve the directory's index.html; and the nonexistent file, which becomes a 404 by applying the discipline from 03-01: try and catch, never check first with exists —between the check and the open the file can disappear, and it is one extra system call on every request.

Putting it all together, src/server/static.js:

It hooks into the router as a last resort: if no API route matches, we try to serve a static file before giving a 404.

Reloading the page downloads the CSS and the JS again even though not a single byte has changed. HTTP has two mechanisms to avoid that, and they complement each other.

Cache-Control: max-age=N says: "for N seconds, don't even ask me". The browser serves the file from its own disk with no request at all. It is as fast as it gets and also the most dangerous: if you publish a new version, whoever has the old one cached will not find out until it expires.

Beware the naming trap: no-cache does not mean "don't cache", it means "cache but revalidate before using". The one that forbids storing is no-store.

Conditional validation is the second mechanism, and it is the one that produces the 304. It works like this: the server sends a tag with the response; the browser stores it and, next time, sends it back asking "is this still valid?". If it is, the server answers 304 Not Modified with no body.

There are two possible tags:

• Last-Modified, a date. The client returns it in If-Modified-Since. Its resolution is one second, so two changes within the same second go unnoticed.
• ETag, an opaque version identifier. The client returns it in If-None-Match. It is the preferred mechanism: more precise and with no time zone ambiguity.

A strong ETag would be a hash of the content, but that forces you to read the whole file on every request, exactly what we wanted to avoid. The practical solution —the one almost every server uses— is a weak ETag derived from the stat: size and modification date.

And in serveStatic, right before writing the body:

The improvement is measurable in two commands:

Zero body bytes. On a page with twenty resources, the difference between the first visit and the second stops being a megabyte and becomes a handful of headers.

A client can ask for a chunk of a file instead of the whole thing. That is what a video player does when you jump to minute 12, and what a download manager does when resuming an interrupted download. For an event poster it is not essential, but it is worth knowing how it works.

The client asks with the Range: bytes=0-1023 header, and the server, if it accepts, responds 206 Partial Content with Content-Range and only those bytes:

The two classic mistakes: forgetting that createReadStream's end is inclusive (hence the -1 and the +1), and returning 200 instead of 206, which makes the client believe you sent the whole file and reassemble it wrong.

CSS and JS are text and compress enormously: a 100 KB CSS drops to 15-20 KB with gzip. But compressing is only valid if the client understands it, and that is negotiated: the client announces Accept-Encoding: gzip, deflate, br and the server chooses and declares it in Content-Encoding.

Three points where almost everybody gets it wrong:

• Removing Content-Length. If you leave it, you announce the uncompressed file size and the client will wait for bytes that never arrive, hanging until its timeout.
• The Vary: Accept-Encoding header. Without it, an intermediate cache can store the compressed version and hand it to a client that does not accept gzip, which will see binary garbage.
• Not compressing what is already compressed. A .webp, a .png or a .zip do not shrink; you only burn CPU and, on small files, the response can even grow. Hence the 1 KB threshold and the COMPRESSIBLE list.

Check it: curl -s -o /dev/null -w '%{size_download}\n' http://localhost:3000/styles.css returns 1842 bytes, and with -H 'Accept-Encoding: gzip' it drops to 612.

You have written a correct static file server: hardened, with MIME types, streams, conditional caching, ranges and compression. And in production, almost certainly, you will not use it. The reason is economic, not technical: a reverse proxy such as Nginx or a CDN serves static files with native code that has been optimized for twenty years, without occupying your event loop, and a CDN additionally places them physically near the user. Your Node process should be doing what only it can do.

What has not been wasted time is understanding the mechanisms: when you configure expires in Nginx or a CDN's cache rules in lesson 11-04, you will be configuring exactly what you have just implemented by hand.

• Gluing url.pathname onto the base directory with path.join. That is the path traversal vulnerability. Always resolveWithin, and decoding before validating.
• Serving with readFile. It works until the day of the big file or the traffic spike. createReadStream + pipeline, no exceptions.
• Using pipe instead of pipeline. It neither propagates errors nor destroys the source: leaked file descriptors and, in the long run, EMFILE.
• Forgetting charset=utf-8 on the text types. Broken accents that only show up in some browsers.
• Leaving Content-Length in place when compressing or when responding 304. A hanging client in the first case, an invalid response in the second.
• Compressing images, or serving the whole project directory. You burn CPU and save nothing; and data/, src/ and .env are not public.
• Tip: X-Content-Type-Options: nosniff from day one: one line that closes a whole family of attacks. And to debug caching, curl -I shows ETag, Last-Modified and Cache-Control without downloading the body.

Write src/lab/test-traversal.js that, with the server running, requests these paths with fetch and prints a path | status | first 40 characters table: /index.html, /styles.css, /../data/events.json, /%2e%2e/data/events.json, /../../etc/hosts and /subdir/../styles.css. Explain why the last one must return 200.

Write a shell script that requests styles.css three times: with no conditional headers, with the ETag obtained from the first response, and with a made-up If-None-Match. Print the status and the downloaded bytes of each one and compute the percentage saved. Then modify the file (touch public/styles.css) and repeat: explain what changes and why touching the date is enough.

Extend the negotiation so it also supports br (Brotli, with zlib.createBrotliCompress), preferring it over gzip when the client accepts both. Check with three requests (gzip, br, no header) that the response's Content-Encoding is right in each case, and compare the three sizes.

Solution 1. The expected result is 200 for /index.html, /styles.css and /subdir/../styles.css, and 403 for the other three.

/subdir/../styles.css returns 200 and that is correct: resolveWithin does not forbid .., it forbids leaving the base. Once resolved, that path points at public/styles.css, which is inside. Rejecting every string containing .. would be a blacklist defense, more fragile and with false positives: the good one validates the result, not the input.

Solution 2. The made-up ETag returns 200 with the full body: it does not match the current one, so the server assumes the client has an old version.

After the touch, the ETag changes even though the content is identical, because our tag is computed from mtimeMs and the size. That is the price of the weak ETag: it can invalidate too much (one unnecessary download) but never too little (serving stale content), and that split of risks is exactly the one we want.

Solution 3. The negotiation is resolved by looking at what the client accepts and choosing by our own preference:

Brotli compresses text somewhat better than gzip (on the order of 15-20% less on a typical CSS) in exchange for more CPU, which is why it is preferred for static files that also get cached. With no Accept-Encoding header, the file is served uncompressed with its original Content-Length.

Escena Viva now has a face. The same server that exposes the API serves public/index.html, public/styles.css and public/app.js, and along the way you have closed the most common hole of all: mapping the URL to disk with path.join lets GET /../../data/events.json walk off with your catalog, and the defense is resolveWithin from lesson 03-03, decoding before validating, with PATH_NOT_ALLOWED translating itself into 403 thanks to the 04-02 table. Rejecting the path by its result and not by whether it contains .. is what keeps /subdir/../styles.css working.

You know how to declare the type with your own MIME table —src/server/mime-types.js, with charset=utf-8 on everything textual and application/octet-stream by default— and why X-Content-Type-Options: nosniff is not optional. You send with createReadStream and pipeline, not with readFile: constant memory, automatic backpressure and destruction of both ends if the client aborts, with ERR_STREAM_PREMATURE_CLOSE treated as what it is —a disconnection, not a 500—. And stat gives you in one shot the existence check, the exact Content-Length and the date, plus the default index and the 404.

Caching is no longer a mystery: Cache-Control with its max-age, no-cache (revalidate) and no-store (don't store), and conditional validation with a weak ETag computed from size and mtime plus Last-Modified, answering 304 Not Modified with no body when If-None-Match or If-Modified-Since arrive —from 1842 bytes to 0—. You have seen Range/206 requests with their inclusive end, and compression negotiated through Accept-Encoding with zlib.createGzip, Content-Encoding, Vary and the mandatory removal of Content-Length. All of it knowing that in production this gets delegated to a reverse proxy or a CDN, and that what you learned is what you need to configure them.

So far, Escena Viva only hands things out: everything is GET requests. What is missing is what turns a website into a platform: receiving. In the next lesson, Receiving Data: Request Bodies and JSON, we will accumulate the Buffer chunks arriving over req —and you will see why concatenating into a string splits multibyte characters—, we will set a mandatory size limit with its 413, we will parse JSON and forms, and we will implement POST /orders, with its hand-written validation, its call into the domain and its 201 response with Location.