HTTP Server Fundamentals

import http from 'node:http';
import net from 'node:net';

const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
  res.end('pong\n');
});

server.listen({ port: 0, host: '127.0.0.1' }, () => {
  const { port } = server.address();
  // A raw TCP client: write the request text by hand and print whatever comes back
  const socket = net.connect(port, '127.0.0.1');
  socket.write('GET /ping HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n');
  let raw = '';
  socket.setEncoding('utf8').on('data', (chunk) => (raw += chunk));
  socket.on('close', () => {
    console.log(raw.replaceAll('\r\n', '\\r\\n\n'));
    server.close();
  });
});

HTTP/1.1 200 OK\r\n
Content-Type: text/plain; charset=utf-8\r\n
Date: Sat, 03 Oct 2026 22:41:43 GMT\r\n
Connection: close\r\n
Content-Length: 5\r\n
\r\n
pong

import http from 'node:http';

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('Hello from the Bookshelf\n');
});

// port 0 asks the operating system for any free port
server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const { port } = server.address();
  console.log(`listening on http://127.0.0.1:${port}`);

  const response = await fetch(`http://127.0.0.1:${port}/`);
  console.log(response.status, response.headers.get('content-type'));
  console.log(await response.text());

  server.close();
});

listening on http://127.0.0.1:<port>
200 text/plain; charset=utf-8
Hello from the Bookshelf

import http from 'node:http';

const server = http.createServer();
server.on('request', (req, res) => {
  res.end('same behaviour\n');
});

import http from 'node:http';
import { once } from 'node:events';

const server = http.createServer((req, res) => res.end('ok'));
const stop = new AbortController();

server.listen({ port: 0, host: '127.0.0.1', signal: stop.signal });   // port 0: the OS picks a free port
await once(server, 'listening');                                       // address() is null before this
const { address, family, port } = server.address();
console.log({ address, family, portIsNumber: typeof port === 'number' && port > 0, listening: server.listening });

console.log((await fetch(`http://127.0.0.1:${port}/`)).status);

stop.abort();                                                          // closes the listening server
await once(server, 'close');
console.log('listening after abort:', server.listening);
server.closeAllConnections();                                          // drop fetch's idle socket

{
  address: '127.0.0.1',
  family: 'IPv4',
  portIsNumber: true,
  listening: true
}
200
listening after abort: false

import http from 'node:http';

const server = http.createServer((req, res) => {
  const { method, url, httpVersion, headers, rawHeaders } = req;

  // req.url is only the path and query; give URL a base so it can parse it
  const parsed = new URL(url, 'http://localhost');

  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({
    method,
    httpVersion,
    path: parsed.pathname,
    genre: parsed.searchParams.get('genre'),
    userAgent: headers['user-agent'],
    accept: headers.accept,
    rawHeaderNames: rawHeaders.filter((_, i) => i % 2 === 0),   // names exactly as the client sent them
    peer: req.socket.remoteAddress,
  }, null, 2));
});

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const { port } = server.address();
  const response = await fetch(`http://127.0.0.1:${port}/books?genre=fantasy&genre=sci-fi`, {
    headers: { Accept: 'application/json', 'X-Request-ID': 'abc-123' },
  });
  console.log(await response.text());
  server.close();
});

{
  "method": "GET",
  "httpVersion": "1.1",
  "path": "/books",
  "genre": "fantasy",
  "userAgent": "node",
  "accept": "application/json",
  "rawHeaderNames": [
    "host",
    "connection",
    "Accept",
    "X-Request-ID",
    "accept-language",
    "sec-fetch-mode",
    "user-agent",
    "accept-encoding"
  ],
  "peer": "127.0.0.1"
}

import http from 'node:http';
import { json } from 'node:stream/consumers';

class HttpError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

// Read a JSON body from the request stream, refusing bodies larger than `limit` bytes
async function readJson(req, limit = 1024) {
  if (Number(req.headers['content-length']) > limit) {
    throw new HttpError(413, 'Payload Too Large');
  }
  const chunks = [];
  let size = 0;
  for await (const chunk of req) {       // IncomingMessage is a Readable stream
    size += chunk.length;
    if (size > limit) throw new HttpError(413, 'Payload Too Large');
    chunks.push(chunk);
  }
  try {
    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch {
    throw new HttpError(400, 'Body is not valid JSON');
  }
}

const server = http.createServer(async (req, res) => {
  try {
    if (req.method === 'POST' && req.url === '/books') {
      const book = await readJson(req);
      res.writeHead(201, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ received: book }));
    } else if (req.method === 'POST' && req.url === '/consumers') {
      // the same job in one line with the stream consumers (no size limit!)
      res.end(JSON.stringify({ received: await json(req) }) + '\n');
    } else {
      throw new HttpError(404, 'Not Found');
    }
  } catch (err) {
    const status = err.status ?? 500;
    res.writeHead(status, { 'Content-Type': 'text/plain', Connection: 'close' });
    res.end(`${status} ${err.status ? err.message : 'Internal Server Error'}\n`);
  }
});

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  const post = (path, body) => fetch(base + path, { method: 'POST', body })
    .then(async (r) => `${r.status} ${await r.text()}`.trim());

  console.log(await post('/books', JSON.stringify({ title: 'Dune' })));
  console.log(await post('/books', '{ not json'));
  console.log(await post('/books', 'x'.repeat(5000)));
  console.log(await post('/consumers', JSON.stringify({ title: 'Emma' })));
  server.close();
  server.closeAllConnections();
});

201 {"received":{"title":"Dune"}}
400 400 Body is not valid JSON
413 413 Payload Too Large
200 {"received":{"title":"Emma"}}

import http from 'node:http';
import { pipeline } from 'node:stream/promises';

const server = http.createServer(async (req, res) => {
  if (req.method !== 'POST') {
    res.writeHead(405, { Allow: 'POST' }).end();
    return;
  }
  res.writeHead(200, { 'Content-Type': req.headers['content-type'] ?? 'application/octet-stream' });
  try {
    await pipeline(req, res);               // bytes flow straight through; nothing is buffered
  } catch {
    res.destroy();                          // the client vanished or the body was malformed
  }
});

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const url = `http://127.0.0.1:${server.address().port}/`;
  const r = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: 'echo me' });
  console.log(r.status, r.headers.get('content-type'), JSON.stringify(await r.text()));
  console.log((await fetch(url)).status);
  server.close();
  server.closeAllConnections();
});

200 text/plain "echo me"
405

import http, { STATUS_CODES } from 'node:http';

const server = http.createServer((req, res) => {
  switch (req.url) {
    case '/implicit':                       // headers are sent with the first write
      res.statusCode = 201;
      res.statusMessage = STATUS_CODES[201]; // optional: Node derives it from the code
      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
      res.setHeader('Set-Cookie', ['a=1; HttpOnly', 'b=2; HttpOnly']);
      res.setHeader('X-Powered-By', 'bookshelf');
      res.removeHeader('X-Powered-By');
      res.end('created\n');                  // Content-Length is computed for us
      break;
    case '/explicit':                       // writeHead sends the head immediately
      res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' });
      console.log('headersSent after writeHead:', res.headersSent);
      res.write('part one, ');
      res.end('part two\n');                 // no Content-Length known up front: chunked
      break;
    case '/no-content':
      res.writeHead(204).end();              // writeHead() returns the response (v11.10+)
      break;
    case '/too-late':
      res.end('body\n');
      try {
        res.setHeader('X-Too-Late', '1');
      } catch (err) {
        console.log(err.code);               // ERR_HTTP_HEADERS_SENT
      }
      break;
    default:
      res.statusCode = 404;
      res.end();
  }
});

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  for (const path of ['/implicit', '/explicit', '/no-content', '/too-late', '/nope']) {
    const r = await fetch(base + path);
    const body = await r.text();
    const headers = [...r.headers].filter(([k]) => !['date', 'keep-alive', 'connection'].includes(k));
    console.log(path, r.status, r.statusText, JSON.stringify(headers), JSON.stringify(body));
  }
  server.close();
  server.closeAllConnections();
});

/implicit 201 Created [["content-length","8"],["content-type","text/plain; charset=utf-8"],["set-cookie","a=1; HttpOnly"],["set-cookie","b=2; HttpOnly"]] "created\n"
headersSent after writeHead: true
/explicit 200 OK [["cache-control","no-store"],["content-type","text/plain; charset=utf-8"],["transfer-encoding","chunked"]] "part one, part two\n"
/no-content 204 No Content [] ""
ERR_HTTP_HEADERS_SENT
/too-late 200 OK [["content-length","5"]] "body\n"
/nope 404 Not Found [["content-length","0"]] ""

import http from 'node:http';
import net from 'node:net';

const server = http.createServer({ maxHeaderSize: 1024 }, (req, res) => {
  const { headers, headersDistinct, rawHeaders } = req;
  res.end(JSON.stringify({ joined: headers['x-tag'], distinct: headersDistinct['x-tag'],
    raw: rawHeaders.filter((_, i) => i % 2 === 0).filter((n) => /x-tag/i.test(n)) }) + '\n');
});

const raw = (port, text) => new Promise((resolve) => {
  const s = net.connect(port, '127.0.0.1');
  s.write(text);
  let out = '';
  s.setEncoding('utf8').on('data', (c) => (out += c)).on('close', () => {
    const [head, body] = out.split('\r\n\r\n');
    resolve(head.split('\r\n')[0] + (body?.startsWith('{') ? ` | ${body.trim()}` : ''));   // status line, and the body when there is one
  });
});

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const { port } = server.address();
  console.log(await raw(port, 'GET / HTTP/1.1\r\nHost: x\r\nX-Tag: a\r\nx-tag: b\r\nConnection: close\r\n\r\n'));
  console.log(await raw(port, 'THIS IS NOT HTTP\r\n\r\n'));
  console.log(await raw(port, `GET / HTTP/1.1\r\nHost: x\r\nX-Big: ${'a'.repeat(2000)}\r\n\r\n`));
  console.log(await raw(port, 'GET / HTTP/1.1\r\n\r\n'));
  server.close();
});

HTTP/1.1 200 OK | {"joined":"a, b","distinct":["a","b"],"raw":["X-Tag","x-tag"]}
HTTP/1.1 400 Bad Request
HTTP/1.1 431 Request Header Fields Too Large
HTTP/1.1 400 Bad Request

import http from 'node:http';

// A tiny router: one URLPattern per route, matched on the pathname only
const routes = [];
const route = (method, pathname, handler) =>
  routes.push({ method, pattern: new URLPattern({ pathname }), handler });

const books = new Map([['1', { id: '1', title: 'Dune' }], ['2', { id: '2', title: 'Emma' }]]);
const send = (res, status, body) => {
  res.writeHead(status, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(body));
};

route('GET', '/books', (req, res) => send(res, 200, [...books.values()]));
route('GET', '/books/:id', (req, res, { id }) =>
  books.has(id) ? send(res, 200, books.get(id)) : send(res, 404, { error: 'No such book' }));
route('GET', '/files/*', (req, res, groups) => send(res, 200, { rest: groups[0] }));
route('GET', '/authors/:id(\\d+)', (req, res, { id }) => send(res, 200, { author: Number(id) }));

function dispatch(req, res) {
  const { pathname } = new URL(req.url, 'http://localhost');
  const allowed = new Set();
  for (const { method, pattern, handler } of routes) {
    const match = pattern.exec({ pathname });
    if (!match) continue;
    if (method === req.method) return handler(req, res, match.pathname.groups);
    allowed.add(method);
  }
  if (allowed.size) {
    res.setHeader('Allow', [...allowed].join(', '));
    return send(res, 405, { error: 'Method Not Allowed' });
  }
  send(res, 404, { error: 'Not Found' });
}

const server = http.createServer(dispatch);
server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  for (const [method, path] of [
    ['GET', '/books'], ['GET', '/books/2'], ['GET', '/books/99'], ['GET', '/files/a/b.txt'],
    ['GET', '/authors/7'], ['GET', '/authors/abc'], ['DELETE', '/books/1'], ['GET', '/nowhere'],
  ]) {
    const r = await fetch(base + path, { method });
    console.log(method, path, r.status, r.headers.get('allow') ?? '', await r.text());
  }
  server.close();
  server.closeAllConnections();
});

GET /books 200  [{"id":"1","title":"Dune"},{"id":"2","title":"Emma"}]
GET /books/2 200  {"id":"2","title":"Emma"}
GET /books/99 404  {"error":"No such book"}
GET /files/a/b.txt 200  {"rest":"a/b.txt"}
GET /authors/7 200  {"author":7}
GET /authors/abc 404  {"error":"Not Found"}
DELETE /books/1 405 GET {"error":"Method Not Allowed"}
GET /nowhere 404  {"error":"Not Found"}

import http from 'node:http';
import { createReadStream } from 'node:fs';
import { stat } from 'node:fs/promises';
import path from 'node:path';
import { pipeline } from 'node:stream/promises';

const root = path.resolve(import.meta.dirname, 'public');
const types = new Map([
  ['.html', 'text/html; charset=utf-8'],
  ['.css', 'text/css; charset=utf-8'],
  ['.js', 'text/javascript; charset=utf-8'],
  ['.json', 'application/json'],
  ['.svg', 'image/svg+xml'],
  ['.txt', 'text/plain; charset=utf-8'],
]);

function fail(res, status) {
  res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end(`${status} ${http.STATUS_CODES[status]}\n`);
}

async function serveStatic(req, res) {
  if (req.method !== 'GET' && req.method !== 'HEAD') {
    res.setHeader('Allow', 'GET, HEAD');
    return fail(res, 405);
  }

  let pathname;
  try {
    pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
  } catch {
    return fail(res, 400);                       // malformed percent-encoding
  }
  if (pathname.includes('\0')) return fail(res, 400);

  const file = path.join(root, pathname.endsWith('/') ? `${pathname}index.html` : pathname);
  if (!file.startsWith(root + path.sep)) return fail(res, 403);   // path traversal

  let info;
  try {
    info = await stat(file);
  } catch {
    return fail(res, 404);
  }
  if (!info.isFile()) return fail(res, 404);

  res.writeHead(200, {
    'Content-Type': types.get(path.extname(file)) ?? 'application/octet-stream',
    'Content-Length': info.size,
    'Last-Modified': info.mtime.toUTCString(),
    'X-Content-Type-Options': 'nosniff',
  });
  if (req.method === 'HEAD') return res.end();

  try {
    // pipeline() applies backpressure and destroys the file stream if the client goes away
    await pipeline(createReadStream(file), res);
  } catch (err) {
    if (err.code !== 'ERR_STREAM_PREMATURE_CLOSE') console.error(err.message);
    res.destroy();                               // the head is already sent: all we can do is hang up
  }
}

const server = http.createServer((req, res) => {
  serveStatic(req, res).catch(() => res.headersSent ? res.destroy() : fail(res, 500));
});

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  for (const [method, p] of [['GET', '/'], ['GET', '/css/site.css'], ['HEAD', '/big.txt'],
                             ['GET', '/missing.html'], ['POST', '/'], ['GET', '/css']]) {
    const r = await fetch(base + p, { method });
    const body = await r.text();
    console.log(method, p, r.status, r.headers.get('content-type'), r.headers.get('content-length'), JSON.stringify(body));
  }
  server.close();
  server.closeAllConnections();
});

mkdir -p public/css
echo '<h1>Bookshelf</h1>' > public/index.html
echo 'body { margin: 0 }' > public/css/site.css
head -c 20000000 /dev/zero | tr '\0' 'a' > public/big.txt
node static-server.mjs

GET / 200 text/html; charset=utf-8 19 "<h1>Bookshelf</h1>\n"
GET /css/site.css 200 text/css; charset=utf-8 19 "body { margin: 0 }\n"
HEAD /big.txt 200 text/plain; charset=utf-8 20000000 ""
GET /missing.html 404 text/plain; charset=utf-8 null "404 Not Found\n"
POST / 405 text/plain; charset=utf-8 null "405 Method Not Allowed\n"
GET /css 404 text/plain; charset=utf-8 null "404 Not Found\n"

import http from 'node:http';
import { text } from 'node:stream/consumers';

let connections = 0;
const server = http.createServer((req, res) => {
  res.end('ok');
});
server.on('connection', () => connections++);

console.log('server defaults:', {
  keepAliveTimeout: server.keepAliveTimeout,
  keepAliveTimeoutBuffer: server.keepAliveTimeoutBuffer,
  headersTimeout: server.headersTimeout,
  requestTimeout: server.requestTimeout,
  maxRequestsPerSocket: server.maxRequestsPerSocket,
});

// Promise wrapper around http.request that reads the body and reports the Keep-Alive header
const get = (port, agent) => new Promise((resolve, reject) => {
  http.get({ port, host: '127.0.0.1', agent }, async (res) => {
    await text(res);
    resolve(`${res.headers.connection}/${res.headers['keep-alive'] ?? '-'}`);
  }).on('error', reject);
});

async function run(label, agent, port) {
  connections = 0;
  const seen = [];
  for (let i = 0; i < 5; i++) seen.push(await get(port, agent));   // sequential requests
  console.log(label.padEnd(26), 'TCP connections:', connections, ' response says:', seen[0]);
  agent.destroy();
}

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const { port } = server.address();
  await run('new Agent()', new http.Agent(), port);
  await run('new Agent({ keepAlive })', new http.Agent({ keepAlive: true }), port);
  await run('http.globalAgent', http.globalAgent, port);
  console.log('globalAgent.keepAlive:', http.globalAgent.keepAlive, ' maxSockets:', http.globalAgent.maxSockets, ' maxFreeSockets:', http.globalAgent.maxFreeSockets);
  server.close();
});

server defaults: {
  keepAliveTimeout: 5000,
  keepAliveTimeoutBuffer: 1000,
  headersTimeout: 60000,
  requestTimeout: 300000,
  maxRequestsPerSocket: 0
}
new Agent()                TCP connections: 5  response says: close/-
new Agent({ keepAlive })   TCP connections: 1  response says: keep-alive/timeout=5
http.globalAgent           TCP connections: 1  response says: keep-alive/timeout=5
globalAgent.keepAlive: true  maxSockets: Infinity  maxFreeSockets: 256

import http from 'node:http';

const server = http.createServer(async (req, res) => {
  if (req.url === '/slow') await new Promise((r) => setTimeout(r, 300));
  res.end('done\n');
});

// Stop accepting connections, let in-flight requests finish, then hang up on idle sockets
function shutdown(graceMs = 5000) {
  return new Promise((resolve) => {
    console.time('shutdown');
    server.close(() => {                      // runs once every connection has ended
      console.timeEnd('shutdown');
      resolve();
    });
    const sweep = setInterval(() => server.closeIdleConnections(), 50);
    setTimeout(() => server.closeAllConnections(), graceMs).unref();   // last resort
    server.once('close', () => clearInterval(sweep));
  });
}

server.listen({ port: 0, host: '127.0.0.1' }, async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  await (await fetch(`${base}/`)).text();
  const slow = fetch(`${base}/slow`).then((r) => r.text());   // still in flight while we shut down
  await new Promise((r) => setTimeout(r, 50));
  await shutdown();
  console.log('in-flight request answered:', JSON.stringify(await slow));
});

shutdown: 253.791ms
in-flight request answered: "done\n"

import http from 'node:http';
{
  await using server = http.createServer((req, res) => res.end('ok'));
  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
  const r = await fetch(`http://127.0.0.1:${server.address().port}`);
  console.log(r.status, await r.text());
}   // leaving the block calls server[Symbol.asyncDispose](), i.e. server.close()
console.log('closed');

200 ok
closed

import http from 'node:http';
import { createReadStream } from 'node:fs';
import { stat } from 'node:fs/promises';
import path from 'node:path';
import { pipeline } from 'node:stream/promises';
import { randomUUID } from 'node:crypto';

export class HttpError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

const json = (res, status, body) => {
  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
  res.end(JSON.stringify(body));
};

async function readJson(req, limit = 64 * 1024) {
  const chunks = [];
  let size = 0;
  for await (const chunk of req) {
    size += chunk.length;
    if (size > limit) throw new HttpError(413, 'Payload Too Large');
    chunks.push(chunk);
  }
  try {
    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch {
    throw new HttpError(400, 'Body is not valid JSON');
  }
}

export function createApp({ publicDir = path.resolve(import.meta.dirname, 'public') } = {}) {
  const books = new Map();
  const routes = [];
  const route = (method, pathname, handler) =>
    routes.push({ method, pattern: new URLPattern({ pathname }), handler });

  route('GET', '/api/books', (req, res, _params, url) => {
    const genre = url.searchParams.get('genre');
    const all = [...books.values()];
    json(res, 200, genre ? all.filter((b) => b.genre === genre) : all);
  });
  route('GET', '/api/books/:id', (req, res, { id }) => {
    if (!books.has(id)) throw new HttpError(404, 'No such book');
    json(res, 200, books.get(id));
  });
  route('POST', '/api/books', async (req, res) => {
    const { title, genre = 'unknown' } = await readJson(req);
    if (typeof title !== 'string' || title.trim() === '') throw new HttpError(422, 'title is required');
    const book = { id: randomUUID(), title: title.trim(), genre };
    books.set(book.id, book);
    res.setHeader('Location', `/api/books/${book.id}`);
    json(res, 201, book);
  });
  route('DELETE', '/api/books/:id', (req, res, { id }) => {
    if (!books.delete(id)) throw new HttpError(404, 'No such book');
    res.writeHead(204).end();
  });

  async function serveStatic(req, res, pathname) {
    const file = path.join(publicDir, pathname.endsWith('/') ? `${pathname}index.html` : pathname);
    if (!file.startsWith(publicDir + path.sep)) throw new HttpError(403, 'Forbidden');
    const info = await stat(file).catch(() => null);
    if (!info?.isFile()) throw new HttpError(404, 'Not Found');
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Length': info.size });
    if (req.method === 'HEAD') return res.end();
    await pipeline(createReadStream(file), res);
  }

  async function handle(req, res) {
    const url = new URL(req.url, 'http://localhost');
    const pathname = decodeURIComponent(url.pathname);
    const allowed = new Set();
    for (const { method, pattern, handler } of routes) {
      const match = pattern.exec({ pathname });
      if (!match) continue;
      if (method === req.method) return handler(req, res, match.pathname.groups, url);
      allowed.add(method);
    }
    if (allowed.size) {
      res.setHeader('Allow', [...allowed].join(', '));
      throw new HttpError(405, 'Method Not Allowed');
    }
    if (req.method === 'GET' || req.method === 'HEAD') return serveStatic(req, res, pathname);
    throw new HttpError(404, 'Not Found');
  }

  return http.createServer(async (req, res) => {
    try {
      await handle(req, res);
    } catch (err) {
      if (res.headersSent) return res.destroy(err);          // too late for a status code
      const status = err instanceof HttpError ? err.status
        : err instanceof URIError ? 400 : 500;
      if (status === 500) console.error(err);
      json(res, status, { error: status === 500 ? 'Internal Server Error' : err.message });
    }
  });
}

// Run directly (node app.mjs) but not when imported by a test
if (import.meta.main) {
  const server = createApp();
  server.listen({ port: Number(process.env.PORT ?? 3000), host: '127.0.0.1' }, () => {
    console.log('Bookshelf listening on', server.address());
  });
}

import { test, before, after } from 'node:test';
import assert from 'node:assert/strict';
import { createApp } from './app.mjs';

let server;
let base;
before(async () => {
  server = createApp();
  await new Promise((resolve) => server.listen({ port: 0, host: '127.0.0.1' }, resolve));
  base = `http://127.0.0.1:${server.address().port}`;
});
after(() => {
  server.close();
  server.closeAllConnections();
});

test('create, read, filter and delete a book', async () => {
  const created = await fetch(`${base}/api/books`, {
    method: 'POST',
    body: JSON.stringify({ title: 'Dune', genre: 'sci-fi' }),
  });
  assert.equal(created.status, 201);
  const book = await created.json();
  assert.equal(created.headers.get('location'), `/api/books/${book.id}`);

  const list = await (await fetch(`${base}/api/books?genre=sci-fi`)).json();
  assert.deepEqual(list, [book]);

  assert.equal((await fetch(`${base}/api/books/${book.id}`, { method: 'DELETE' })).status, 204);
  assert.equal((await fetch(`${base}/api/books/${book.id}`)).status, 404);
});

test('validation, methods and static files', async () => {
  const bad = await fetch(`${base}/api/books`, { method: 'POST', body: '{}' });
  assert.equal(bad.status, 422);
  const wrong = await fetch(`${base}/api/books`, { method: 'PUT' });
  assert.equal(wrong.status, 405);
  assert.equal(wrong.headers.get('allow'), 'GET, POST');
  assert.equal((await fetch(`${base}/api/nowhere`)).status, 404);
  assert.match(await (await fetch(`${base}/`)).text(), /Bookshelf/);
  assert.equal((await fetch(`${base}/%zz`)).status, 400);
});

✔ create, read, filter and delete a book
✔ validation, methods and static files
ℹ tests 2
ℹ pass 2
ℹ fail 0