How Node really works · Chapter 30 of 34

Static file server

By the end of this chapter you can serve a folder of files over HTTP with the right headers, caching, and no way out of the folder. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Projects
  • 5 tasks
  • Node.js
  • In the all labs plan

The first 2 chapters of How Node really works are free. This one comes with the all labs plan.

Why you need this

Anjali has finished the new menu site: an index.html, a stylesheet, a script, the logo and a menu.json the page reads. She wants it on Tapri's server. Kabir wants you to write that server yourself, because a static file server is the classic Node project and the classic security interview question.

The ten-line version, readFile on whatever path the URL names, works for the happy path. It sends the logo as text, reads every file whole, crashes on a strange URL, and, asked the right way, hands out files from outside the site folder, such as the server's own secrets.

What you build: 5 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    createStaticServer: serve the menu site with the right content types

    Write createStaticServer(root). It returns an http.Server (created, not listening) that serves the files inside the folder root. For GET /<path>, the query string is ignored (/menu.json?v=2 is menu.json) and the path is URL-decoded (/masala%20chai.txt is the file masala chai.txt). A path ending in / means that folder's index.html, so / serves index.html.

    A file is answered 200 with its exact bytes (images too), a Content-Type from CONTENT_TYPES looked up by the file's extension in lowercase, or application/octet-stream for any other extension, and a Content-Length equal to the file's size in bytes. Stream the body from the file instead of reading it whole.

  2. Task 2

    createStaticServer: answer missing files, folders and other methods properly

    A path with no file answers 404 with Content-Type text/plain; charset=utf-8 and the body Not found. That includes a missing file in any folder, a path that goes on past a file such as /menu.json/extra (stat fails with ENOTDIR, not ENOENT), and a folder URL ending in / when the folder has no index.html, such as /empty/.

    /specials/ serves specials/index.html as text/html. A folder named without its slash, /specials, answers 301 with Location: /specials/ (the same path plus /).

    Any method other than GET and HEAD (POST, PUT, DELETE) answers 405 with the header Allow: GET, HEAD. Any other stat error answers 500.

  3. Task 3

    createStaticServer: answer HEAD requests with headers only

    A HEAD request gets exactly the status and headers a GET would get, including the same Content-Type and a Content-Length of the file's full size, but no body. HEAD for a missing file is a 404 with no body. Do not read the file for a HEAD request.

  4. Task 4

    createStaticServer: let browsers cache files and revalidate them

    Every 200 response for a file also has Cache-Control: public, max-age=300, a Last-Modified header that is the file's modification time as toUTCString gives it, and an ETag made of the size and the modification time in whole milliseconds, in double quotes: "<size>-<mtimeMs rounded down>".

    When the request's If-None-Match header equals that ETag, answer 304 with the ETag header and no body. After the file changes its ETag changes too, so the old tag gets a 200 with the new content, and any other tag also gets 200.

  5. Task 5 · interview question

    Interview: createStaticServer never serves a file outside the site folder

    No request may ever get a file from outside root, however its path is written: ../ in plain text, .. or / encoded as %2e%2e or %2f (decoded only after the URL is parsed), many levels up to /etc/passwd, or a sibling folder whose name starts with the same letters as root (site-private next to site). Such a request answers 403 (400 or 404 are also accepted), never the file.

    A path with a null byte after decoding (/menu.json%00.png) and a path that cannot be decoded (/%E0%A4%A, where decodeURIComponent throws) answer 400. The server keeps serving afterwards.

What you will learn

  • From URL to file: the pathname, decoding, and what stat says.
  • Headers: Content-Type, Content-Length, HEAD and status codes.
  • Caching: ETag, If-None-Match and 304 Not Modified.
  • Path traversal: how a URL walks out of the folder, and why filtering strings does not stop it.

More in Projects

Build "Static file server" yourself

Tapri’s order server must never stall at the 4 pm rush. You learn why it would. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of How Node really works are free. This one comes with the all labs plan.