Building a REST API

bookshelf-api/
  package.json          type module, engines, scripts
  .env                  local settings (not committed); PORT, DB_PATH, CORS_ORIGINS, LOG_LEVEL
  src/
    config.js           reads and validates the environment once
    errors.js           HttpError, the problem details vocabulary
    log.js              JSON-lines logger
    http.js             sendJson, sendProblem, readJson (body limit)
    validate.js         book and query validation, cursors
    db.js               node:sqlite, migrations, the repository
    router.js           URLPattern routing with 404 / 405
    cors.js             CORS headers and preflight
    app.js              the request pipeline, start() and stop()
    main.js             process entry point: signals and exit codes
  test/
    api.test.js         end-to-end tests with node:test and fetch

// Read and validate configuration once, at start-up, and fail fast on bad values.
function integer(env, name, fallback, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
  const raw = env[name];
  if (raw === undefined || raw === '') return fallback;
  const value = Number(raw);
  if (!Number.isInteger(value) || value < min || value > max) {
    throw new Error(`${name} must be an integer between ${min} and ${max}, got "${raw}"`);
  }
  return value;
}

export function loadConfig(env = process.env) {
  return {
    host: env.HOST ?? '127.0.0.1',
    port: integer(env, 'PORT', 3000, { max: 65535 }),   // 0 asks the OS for a free port
    dbPath: env.DB_PATH ?? ':memory:',
    maxBodyBytes: integer(env, 'MAX_BODY_BYTES', 16 * 1024, { min: 1 }),
    corsOrigins: new Set((env.CORS_ORIGINS ?? '').split(',').map((s) => s.trim()).filter(Boolean)),
    shutdownTimeoutMs: integer(env, 'SHUTDOWN_TIMEOUT_MS', 10_000, { min: 1 }),
    logLevel: env.LOG_LEVEL ?? 'info',
  };
}

// An error that knows how to describe itself as an RFC 9457 problem details object.
export class HttpError extends Error {
  constructor(status, title, { detail, type = 'about:blank', errors, headers, cause } = {}) {
    super(detail ?? title, { cause });
    this.name = 'HttpError';
    this.status = status;
    this.title = title;
    this.detail = detail;
    this.type = type;
    this.errors = errors;
    this.headers = headers;
  }
}

export const notFound = (detail) => new HttpError(404, 'Not Found', { detail });
export const badRequest = (detail, cause) => new HttpError(400, 'Bad Request', { detail, cause });

export const PROBLEM_BASE = 'https://bookshelf.example/problems/';

import { HttpError } from './errors.js';

export function sendJson(res, status, body, headers = {}) {
  const payload = JSON.stringify(body);
  res.writeHead(status, {
    'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': Buffer.byteLength(payload),
    ...headers,
  });
  res.end(payload);
}

export function sendProblem(res, err, { instance, requestId }) {
  const body = {
    type: err.type, title: err.title, status: err.status,
    ...(err.detail && { detail: err.detail }),
    instance,
    ...(err.errors && { errors: err.errors }),
    requestId,
  };
  const payload = JSON.stringify(body);
  res.writeHead(err.status, {
    'Content-Type': 'application/problem+json; charset=utf-8',
    'Content-Length': Buffer.byteLength(payload),
    ...err.headers,
  });
  res.end(payload);
}

function mediaType(header = '') {
  return header.split(';')[0].trim().toLowerCase();
}

// Read a JSON request body with a hard size limit; never buffers more than `limit` bytes.
export async function readJson(req, { limit }) {
  if (mediaType(req.headers['content-type']) !== 'application/json') {
    throw new HttpError(415, 'Unsupported Media Type', {
      detail: 'Send the body as application/json.',
    });
  }
  const tooLarge = () => new HttpError(413, 'Payload Too Large', {
    detail: `The request body must not exceed ${limit} bytes.`,
    headers: { Connection: 'close' },        // do not try to reuse a connection with unread bytes
  });
  const declared = req.headers['content-length'];
  if (declared !== undefined && Number(declared) > limit) throw tooLarge();

  const chunks = [];
  let size = 0;
  for await (const chunk of req) {           // IncomingMessage is a Readable stream
    size += chunk.length;
    if (size > limit) throw tooLarge();      // a chunked body has no declared length to trust
    chunks.push(chunk);
  }
  if (size === 0) throw new HttpError(400, 'Bad Request', { detail: 'The request body is empty.' });
  try {
    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch (cause) {
    throw new HttpError(400, 'Bad Request', { detail: 'The request body is not valid JSON.', cause });
  }
}

import { HttpError, PROBLEM_BASE } from './errors.js';

// ISBN-13 check digit: digits weighted 1,3,1,3,... must sum to a multiple of 10.
export function isValidIsbn13(isbn) {
  if (!/^\d{13}$/.test(isbn)) return false;
  const sum = [...isbn].reduce((acc, d, i) => acc + Number(d) * (i % 2 === 0 ? 1 : 3), 0);
  return sum % 10 === 0;
}

const FIELDS = ['isbn', 'title', 'author', 'year'];

// Validate a book payload. Returns a clean object that contains only known fields.
export function parseBook(input) {
  const errors = [];
  const fail = (field, detail) => errors.push({ pointer: `/${field}`, detail });

  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
    throw new HttpError(422, 'Unprocessable Content', {
      type: PROBLEM_BASE + 'validation-error',
      detail: 'The body must be a JSON object.',
    });
  }
  for (const key of Object.keys(input)) {
    if (!FIELDS.includes(key)) fail(key, 'Unknown field.');
  }

  const isbn = typeof input.isbn === 'string' ? input.isbn.replaceAll('-', '') : input.isbn;
  if (typeof isbn !== 'string') fail('isbn', 'Required, as a string.');
  else if (!isValidIsbn13(isbn)) fail('isbn', 'Must be a valid ISBN-13.');

  for (const field of ['title', 'author']) {
    const value = input[field];
    if (typeof value !== 'string') fail(field, 'Required, as a string.');
    else if (value.trim().length === 0 || value.length > 200) fail(field, 'Must be 1 to 200 characters.');
  }

  const { year } = input;
  if (year !== undefined && year !== null) {
    if (!Number.isInteger(year) || year < 1000 || year > new Date().getFullYear() + 1) {
      fail('year', 'Must be an integer between 1000 and next year.');
    }
  }

  if (errors.length > 0) {
    throw new HttpError(422, 'Unprocessable Content', {
      type: PROBLEM_BASE + 'validation-error',
      detail: `${errors.length} field(s) are invalid.`,
      errors,
    });
  }
  return { isbn, title: input.title.trim(), author: input.author.trim(), year: year ?? null };
}

// Query-string validation for the collection: limit (1-100) and an opaque cursor.
export function parseListQuery(searchParams) {
  const errors = [];
  let limit = 20;
  if (searchParams.has('limit')) {
    const raw = searchParams.get('limit');
    limit = /^\d{1,3}$/.test(raw) ? Number(raw) : NaN;
    if (!(limit >= 1 && limit <= 100)) errors.push({ pointer: '?limit', detail: 'Must be an integer from 1 to 100.' });
  }
  let after = 0;
  if (searchParams.has('cursor')) {
    const decoded = Buffer.from(searchParams.get('cursor'), 'base64url').toString('utf8');
    if (/^id:\d{1,15}$/.test(decoded)) after = Number(decoded.slice(3));
    else errors.push({ pointer: '?cursor', detail: 'Not a cursor issued by this API.' });
  }
  const q = searchParams.get('q') ?? '';
  if (q.length > 100) errors.push({ pointer: '?q', detail: 'Must be at most 100 characters.' });
  if (errors.length > 0) {
    throw new HttpError(400, 'Bad Request', {
      type: PROBLEM_BASE + 'invalid-query', detail: 'Invalid query parameters.', errors,
    });
  }
  return { limit, after, q };
}

export const encodeCursor = (id) => Buffer.from(`id:${id}`).toString('base64url');

{
  "type": "https://bookshelf.example/problems/validation-error",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "4 field(s) are invalid.",
  "instance": "/books",
  "errors": [
    { "pointer": "/extra", "detail": "Unknown field." },
    { "pointer": "/isbn", "detail": "Must be a valid ISBN-13." },
    { "pointer": "/title", "detail": "Must be 1 to 200 characters." },
    { "pointer": "/author", "detail": "Required, as a string." }
  ],
  "requestId": "23bb963b-a63b-4258-b8f5-a6d189e7ddff"
}

import { DatabaseSync } from 'node:sqlite';

// Each entry is applied once, in order; PRAGMA user_version stores how many have run.
const MIGRATIONS = [
  `CREATE TABLE books (
     id         INTEGER PRIMARY KEY,
     isbn       TEXT NOT NULL UNIQUE,
     title      TEXT NOT NULL,
     author     TEXT NOT NULL,
     year       INTEGER,
     created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
   ) STRICT`,
  `CREATE INDEX books_title ON books (title COLLATE NOCASE)`,
];

export function openDatabase(path) {
  const db = new DatabaseSync(path, { timeout: 5000 });  // wait up to 5 s on a locked file
  db.exec('PRAGMA foreign_keys = ON');
  if (path !== ':memory:') db.exec('PRAGMA journal_mode = WAL');
  const { user_version: current } = db.prepare('PRAGMA user_version').get();
  for (let v = current; v < MIGRATIONS.length; v++) {
    db.exec('BEGIN');
    try {
      db.exec(MIGRATIONS[v]);
      db.exec(`PRAGMA user_version = ${v + 1}`);          // v is our own counter, never user input
      db.exec('COMMIT');
    } catch (err) {
      db.exec('ROLLBACK');
      throw err;
    }
  }
  return db;
}

// SQLITE_CONSTRAINT_UNIQUE is extended result code 2067 (see sqlite.org/rescode.html).
export const isUniqueViolation = (err) => err?.code === 'ERR_SQLITE_ERROR' && err.errcode === 2067;

const escapeLike = (s) => s.replace(/[\\%_]/g, '\\$&');

export function createBookRepository(db) {
  const columns = 'id, isbn, title, author, year, created_at AS createdAt';
  const insert = db.prepare(
    `INSERT INTO books (isbn, title, author, year) VALUES (?, ?, ?, ?) RETURNING ${columns}`);
  const byId = db.prepare(`SELECT ${columns} FROM books WHERE id = ?`);
  const replace = db.prepare(
    `UPDATE books SET isbn = ?, title = ?, author = ?, year = ? WHERE id = ? RETURNING ${columns}`);
  const remove = db.prepare('DELETE FROM books WHERE id = ?');
  // Keyset pagination: "rows after the last id I saw", served by the primary key.
  const page = db.prepare(
    `SELECT ${columns} FROM books
      WHERE id > ? AND title LIKE ? ESCAPE '\\'
      ORDER BY id LIMIT ?`);

  return {
    create: (b) => insert.get(b.isbn, b.title, b.author, b.year),
    find: (id) => byId.get(id),
    replace: (id, b) => replace.get(b.isbn, b.title, b.author, b.year, id),
    delete: (id) => remove.run(id).changes > 0,
    // Ask for limit + 1 rows: the extra row tells us whether a next page exists.
    list({ after, q, limit }) {
      const rows = page.all(after, `%${escapeLike(q)}%`, limit + 1);
      const hasMore = rows.length > limit;
      const items = hasMore ? rows.slice(0, limit) : rows;
      return { items, nextAfter: hasMore ? items.at(-1).id : null };
    },
    ping: () => db.prepare('SELECT 1 AS ok').get().ok === 1,
  };
}

// A tiny router on top of the URLPattern global (Node.js 24+).
export function createRouter() {
  const routes = [];

  function route(path) {
    let entry = routes.find((r) => r.path === path);
    if (!entry) {
      entry = { path, pattern: new URLPattern({ pathname: path }), handlers: new Map() };
      routes.push(entry);
    }
    return entry;
  }

  return {
    add(method, path, handler) {
      route(path).handlers.set(method, handler);
      return this;
    },
    match(method, pathname) {
      for (const { pattern, handlers } of routes) {
        const result = pattern.exec({ pathname });
        if (!result) continue;
        const handler = handlers.get(method) ?? (method === 'HEAD' ? handlers.get('GET') : undefined);
        const allow = [...new Set([...handlers.keys(), ...(handlers.has('GET') ? ['HEAD'] : []), 'OPTIONS'])];
        return handler
          ? { handler, params: result.pathname.groups, allow }
          : { handler: null, params: {}, allow };          // path exists, method does not
      }
      return null;                                         // no such path
    },
  };
}

// CORS for browser clients. Disallowed origins simply receive no CORS headers.
export function createCors({ origins }) {
  const allowed = (origin) => origin !== undefined && origins.has(origin);

  return {
    // Headers added to every response whose request carries an allowed Origin.
    headersFor(req) {
      const origin = req.headers.origin;
      const headers = { Vary: 'Origin' };                 // responses differ per Origin: tell caches
      if (allowed(origin)) {
        headers['Access-Control-Allow-Origin'] = origin;  // an exact, allow-listed value; never "*" blindly
        headers['Access-Control-Expose-Headers'] = 'Location, Link, X-Request-Id';
      }
      return headers;
    },
    // A preflight is an OPTIONS request that names the method the browser wants to use.
    isPreflight: (req) =>
      req.method === 'OPTIONS' && req.headers.origin !== undefined &&
      req.headers['access-control-request-method'] !== undefined,
    preflightHeaders(req, allow) {
      const headers = this.headersFor(req);
      if (allowed(req.headers.origin)) {
        headers['Access-Control-Allow-Methods'] = allow.join(', ');
        headers['Access-Control-Allow-Headers'] = 'Content-Type';
        headers['Access-Control-Max-Age'] = '600';
      }
      return headers;
    },
  };
}

HTTP/1.1 204 No Content
Vary: Origin
Access-Control-Allow-Origin: https://app.example
Access-Control-Expose-Headers: Location, Link, X-Request-Id
Allow: GET, POST, HEAD, OPTIONS
Access-Control-Allow-Methods: GET, POST, HEAD, OPTIONS
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600

const LEVELS = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 };

// One JSON object per line on stdout: easy for a container runtime or log shipper to collect.
export function createLogger({ level = 'info', write = (line) => process.stdout.write(line), base = {} } = {}) {
  const threshold = LEVELS[level] ?? LEVELS.info;
  const emit = (name) => (fields, msg) => {
    if (LEVELS[name] < threshold) return;
    if (typeof fields === 'string') [fields, msg] = [{}, fields];
    const { err, ...rest } = fields;
    const entry = { time: new Date().toISOString(), level: name, msg, ...base, ...rest };
    if (err) entry.err = { name: err.name, message: err.message, stack: err.stack };
    write(JSON.stringify(entry) + '\n');   // JSON.stringify escapes newlines: no log injection
  };
  return {
    debug: emit('debug'), info: emit('info'), warn: emit('warn'), error: emit('error'),
    child: (extra) => createLogger({ level, write, base: { ...base, ...extra } }),
  };
}

{"time":"2026-10-03T23:33:13.000Z","level":"info","msg":"request","requestId":"b23891a4-…","method":"POST","path":"/books","status":201,"ms":2,"completed":true}
{"time":"2026-10-03T23:33:13.061Z","level":"info","msg":"request","requestId":"23bb963b-…","method":"POST","path":"/books","status":422,"ms":0,"completed":true}
{"time":"2026-10-03T23:33:13.072Z","level":"info","msg":"request","requestId":"01b09a1c-…","method":"POST","path":"/books","status":413,"ms":0,"completed":true}

import { createServer } from 'node:http';
import { once } from 'node:events';
import { randomUUID } from 'node:crypto';
import { HttpError, notFound, badRequest, PROBLEM_BASE } from './errors.js';
import { sendJson, sendProblem, readJson } from './http.js';
import { createRouter } from './router.js';
import { createCors } from './cors.js';
import { createLogger } from './log.js';
import { openDatabase, createBookRepository, isUniqueViolation } from './db.js';
import { parseBook, parseListQuery, encodeCursor } from './validate.js';

const REQUEST_ID = /^[A-Za-z0-9._-]{8,64}$/;

export function createApp(config, { log = createLogger({ level: config.logLevel }) } = {}) {
  const db = openDatabase(config.dbPath);
  const books = createBookRepository(db);
  const cors = createCors({ origins: config.corsOrigins });
  const router = createRouter();
  let draining = false;

  const bookId = (params) => Number(params.id);
  const conflict = () => new HttpError(409, 'Conflict', {
    type: PROBLEM_BASE + 'duplicate-isbn', detail: 'A book with this ISBN already exists.',
  });

  // ---- routes ----------------------------------------------------------------------------
  router
    .add('GET', '/health', ({ res }) => sendJson(res, 200, { status: 'ok' }))
    .add('GET', '/ready', ({ res }) => {
      const ready = !draining && books.ping();
      sendJson(res, ready ? 200 : 503, { status: ready ? 'ready' : 'draining' });
    })
    .add('GET', '/books', ({ res, url }) => {
      const query = parseListQuery(url.searchParams);
      const { items, nextAfter } = books.list(query);
      const headers = {};
      let next = null;
      if (nextAfter !== null) {
        const params = new URLSearchParams({ cursor: encodeCursor(nextAfter), limit: String(query.limit) });
        if (query.q) params.set('q', query.q);
        next = `/books?${params}`;
        headers.Link = `<${next}>; rel="next"`;
      }
      sendJson(res, 200, { data: items, page: { limit: query.limit, next } }, headers);
    })
    .add('POST', '/books', async ({ req, res }) => {
      const input = parseBook(await readJson(req, { limit: config.maxBodyBytes }));
      try {
        const book = books.create(input);
        sendJson(res, 201, book, { Location: `/books/${book.id}` });
      } catch (err) {
        throw isUniqueViolation(err) ? conflict() : err;
      }
    })
    .add('GET', '/books/:id(\\d{1,15})', ({ res, params }) => {
      const book = books.find(bookId(params));
      if (!book) throw notFound(`There is no book with id ${params.id}.`);
      sendJson(res, 200, book);
    })
    .add('PUT', '/books/:id(\\d{1,15})', async ({ req, res, params }) => {
      const input = parseBook(await readJson(req, { limit: config.maxBodyBytes }));
      try {
        const book = books.replace(bookId(params), input);
        if (!book) throw notFound(`There is no book with id ${params.id}.`);
        sendJson(res, 200, book);
      } catch (err) {
        throw isUniqueViolation(err) ? conflict() : err;
      }
    })
    .add('DELETE', '/books/:id(\\d{1,15})', ({ res, params }) => {
      if (!books.delete(bookId(params))) throw notFound(`There is no book with id ${params.id}.`);
      res.writeHead(204).end();
    });

  // ---- the request pipeline ---------------------------------------------------------------
  async function handle(req, res) {
    const started = performance.now();
    const requestId = REQUEST_ID.test(req.headers['x-request-id'] ?? '') ? req.headers['x-request-id'] : randomUUID();
    const reqLog = log.child({ requestId });

    // 1. Identity and baseline headers, set before anything can fail.
    res.setHeader('X-Request-Id', requestId);
    res.setHeader('X-Content-Type-Options', 'nosniff');
    res.setHeader('Cache-Control', 'no-store');
    if (draining) res.setHeader('Connection', 'close');
    for (const [name, value] of Object.entries(cors.headersFor(req))) res.setHeader(name, value);

    // 2. One access-log line per request, written when the response is done (or the socket died).
    res.on('close', () => {
      reqLog.info({
        method: req.method, path: req.url?.split('?')[0], status: res.statusCode,
        ms: Math.round(performance.now() - started), completed: res.writableFinished,
      }, 'request');
    });

    let url;
    try {
      // 3. Parse the request target. Only origin-form ("/path?query") is accepted.
      if (!req.url?.startsWith('/') || req.url.startsWith('//')) throw badRequest('Malformed request target.');
      try { url = new URL(req.url, 'http://bookshelf.invalid'); } catch (cause) { throw badRequest('Malformed URL.', cause); }

      // 4. Route.
      const found = router.match(req.method, url.pathname);
      if (!found) throw notFound(`No route for ${url.pathname}.`);

      // 5. CORS preflight and plain OPTIONS are answered here, before the method check.
      if (req.method === 'OPTIONS') {
        const headers = cors.isPreflight(req) ? cors.preflightHeaders(req, found.allow) : {};
        res.writeHead(204, { Allow: found.allow.join(', '), ...headers }).end();
        return;
      }
      if (!found.handler) {
        throw new HttpError(405, 'Method Not Allowed', { headers: { Allow: found.allow.join(', ') } });
      }

      // 6. Handler: parses the body, validates, talks to the database, writes the response.
      await found.handler({ req, res, url, params: found.params, log: reqLog });
    } catch (err) {
      // 7. Any error ends here as a problem details response.
      if (req.destroyed && !(err instanceof HttpError)) {
        reqLog.warn({ code: err.code }, 'client went away');   // the socket is gone: nobody to answer
        return;
      }
      const problem = err instanceof HttpError ? err : new HttpError(500, 'Internal Server Error');
      if (!(err instanceof HttpError)) reqLog.error({ err }, 'unhandled error');
      else if (err.cause) reqLog.debug({ err: err.cause }, 'cause');
      if (res.headersSent) {
        res.destroy();                   // too late for a clean error response: abort the connection
      } else {
        sendProblem(res, problem, { instance: url?.pathname ?? '/', requestId });
      }
    }
  }

  const server = createServer({ requestTimeout: 30_000, headersTimeout: 15_000, keepAliveTimeout: 5_000 }, handle);
  server.on('clientError', (err, socket) => {
    // Raised for requests the parser itself rejects (before our handler runs).
    if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
    else socket.destroy();
    log.warn({ code: err.code }, 'client error');
  });

  async function start() {
    server.listen({ port: config.port, host: config.host });
    await once(server, 'listening');
    return server.address();
  }

  // Graceful shutdown: stop accepting, let in-flight requests finish, then release resources.
  async function stop() {
    if (draining) return;
    draining = true;
    log.info('draining');
    const closed = once(server, 'close');
    server.close();                      // refuse new connections; also closes idle keep-alive ones
    // A connection that was busy when we started draining becomes idle later: sweep until closed.
    const sweep = setInterval(() => server.closeIdleConnections(), 100);
    sweep.unref();
    const timer = setTimeout(() => {
      log.warn('shutdown timeout, closing remaining connections');
      server.closeAllConnections();
    }, config.shutdownTimeoutMs);
    timer.unref();
    await closed;
    clearInterval(sweep);
    clearTimeout(timer);
    db.close();
    log.info('stopped');
  }

  return { server, start, stop };
}

import { loadConfig } from './config.js';
import { createApp } from './app.js';
import { createLogger } from './log.js';

const config = loadConfig();
const log = createLogger({ level: config.logLevel });
const app = createApp(config, { log });

const address = await app.start();
log.info({ port: address.port, host: address.address }, 'listening');

// First signal: graceful shutdown. Second signal: give up and exit immediately.
let stopping = false;
for (const signal of ['SIGINT', 'SIGTERM']) {
  process.on(signal, async () => {
    if (stopping) process.exit(1);
    stopping = true;
    log.info({ signal }, 'signal received');
    try {
      await app.stop();
    } catch (err) {
      log.error({ err }, 'error during shutdown');
      process.exitCode = 1;
    }
  });
}

{
  "name": "bookshelf-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "scripts": {
    "start": "node --env-file-if-exists=.env src/main.js",
    "test": "node --test"
  }
}

cat > .env <<'ENV'
PORT=0
DB_PATH=bookshelf.db
CORS_ORIGINS=https://app.example
LOG_LEVEL=info
ENV
npm start

BASE=http://127.0.0.1:52380
curl -si -X POST $BASE/books -H 'Content-Type: application/json' \
  -d '{"isbn":"978-0-13-235088-4","title":"Clean Code","author":"Robert C. Martin","year":2008}'
curl -si "$BASE/books?limit=2"
curl -s "$BASE/books?limit=2&cursor=aWQ6Mg"
curl -si -X PATCH $BASE/books/1

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /books/1

{"id":1,"isbn":"9780132350884","title":"Clean Code","author":"Robert C. Martin","year":2008,"createdAt":"2026-10-03T23:30:41.898Z"}

HTTP/1.1 200 OK
Link: </books?cursor=aWQ6Mg&limit=2>; rel="next"

{"data":[{"id":1,…},{"id":2,…}],"page":{"limit":2,"next":"/books?cursor=aWQ6Mg&limit=2"}}

{"data":[{"id":3,…},{"id":4,…}],"page":{"limit":2,"next":"/books?cursor=aWQ6NA&limit=2"}}

HTTP/1.1 405 Method Not Allowed
Content-Type: application/problem+json; charset=utf-8
Allow: GET, PUT, DELETE, HEAD, OPTIONS

{"level":"info","msg":"signal received","signal":"SIGTERM"}
{"level":"info","msg":"draining"}
{"level":"info","msg":"stopped"}

import { describe, it, before, after } from 'node:test';
import assert from 'node:assert/strict';
import http from 'node:http';
import { once } from 'node:events';
import { loadConfig } from '../src/config.js';
import { createApp } from '../src/app.js';
import { createLogger } from '../src/log.js';

const ISBNS = ['9780132350884', '9780201633610', '9780134685991', '9781491950296', '9781098145187'];

describe('Bookshelf REST API', () => {
  let app;
  let base;
  const logLines = [];

  const send = (path, { method = 'GET', body, headers = {} } = {}) =>
    fetch(base + path, {
      method,
      headers: { ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...headers },
      body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body),
    });

  before(async () => {
    const config = loadConfig({ PORT: '0', DB_PATH: ':memory:', MAX_BODY_BYTES: '512', CORS_ORIGINS: 'https://app.example' });
    const log = createLogger({ level: 'info', write: (line) => logLines.push(JSON.parse(line)) });
    app = createApp(config, { log });
    const { port } = await app.start();            // port 0: the OS picks a free port
    base = `http://127.0.0.1:${port}`;
  });

  after(() => app.stop());

  it('creates, reads, replaces and deletes a book', async () => {
    const created = await send('/books', { method: 'POST', body: { isbn: '978-0-13-235088-4', title: 'Clean Code', author: 'Robert C. Martin', year: 2008 } });
    assert.equal(created.status, 201);
    const book = await created.json();
    assert.equal(created.headers.get('location'), `/books/${book.id}`);
    assert.equal(book.isbn, '9780132350884');           // hyphens are normalised away

    const read = await send(`/books/${book.id}`);
    assert.deepEqual(await read.json(), book);

    const put = await send(`/books/${book.id}`, { method: 'PUT', body: { isbn: book.isbn, title: 'Clean Code, 2nd ed.', author: book.author } });
    assert.equal((await put.json()).title, 'Clean Code, 2nd ed.');

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

  it('answers errors as problem details', async () => {
    const res = await send('/books', { method: 'POST', body: { isbn: '123', title: '', extra: true } });
    assert.equal(res.status, 422);
    assert.match(res.headers.get('content-type'), /^application\/problem\+json/);
    const problem = await res.json();
    assert.equal(problem.status, 422);
    assert.deepEqual(problem.errors.map((e) => e.pointer).sort(), ['/author', '/extra', '/isbn', '/title']);
    assert.equal(problem.requestId, res.headers.get('x-request-id'));
  });

  it('rejects bad bodies before they reach the database', async () => {
    assert.equal((await send('/books', { method: 'POST', body: '{ nope' })).status, 400);
    assert.equal((await send('/books', { method: 'POST', body: 'plain', headers: { 'content-type': 'text/plain' } })).status, 415);
    const big = await send('/books', { method: 'POST', body: { title: 'x'.repeat(2000) } });
    assert.equal(big.status, 413);
    assert.equal(big.headers.get('connection'), 'close');
  });

  it('answers 404, 405 and OPTIONS with the right headers', async () => {
    assert.equal((await send('/nope')).status, 404);
    const res = await send('/books/1', { method: 'PATCH', body: {} });
    assert.equal(res.status, 405);
    assert.equal(res.headers.get('allow'), 'GET, PUT, DELETE, HEAD, OPTIONS');
  });

  it('returns 409 for a duplicate ISBN', async () => {
    const body = { isbn: ISBNS[1], title: 'Refactoring', author: 'Martin Fowler' };
    assert.equal((await send('/books', { method: 'POST', body })).status, 201);
    const res = await send('/books', { method: 'POST', body });
    assert.equal(res.status, 409);
    assert.match((await res.json()).type, /duplicate-isbn$/);
  });

  it('paginates with an opaque cursor and a Link header', async () => {
    for (const [i, isbn] of ISBNS.slice(2).entries()) {
      await send('/books', { method: 'POST', body: { isbn, title: `Paged ${i}`, author: 'A. Writer' } });
    }
    const seen = [];
    let path = '/books?limit=2&q=paged';
    while (path) {
      const res = await send(path);
      const { data, page } = await res.json();
      assert.ok(data.length <= 2);
      seen.push(...data.map((b) => b.title));
      assert.equal(res.headers.get('link'), page.next && `<${page.next}>; rel="next"`);
      path = page.next;
    }
    assert.deepEqual(seen, ['Paged 0', 'Paged 1', 'Paged 2']);
    assert.equal((await send('/books?limit=1000')).status, 400);
    assert.equal((await send('/books?cursor=garbage')).status, 400);
  });

  it('treats LIKE wildcards in q literally', async () => {
    const { data } = await (await send('/books?q=%25')).json();   // q is a literal percent sign
    assert.deepEqual(data, []);
  });

  it('implements CORS for an allow-listed origin only', async () => {
    const preflight = await send('/books', {
      method: 'OPTIONS',
      headers: { Origin: 'https://app.example', 'Access-Control-Request-Method': 'POST' },
    });
    assert.equal(preflight.status, 204);
    assert.equal(preflight.headers.get('access-control-allow-origin'), 'https://app.example');
    assert.match(preflight.headers.get('access-control-allow-methods'), /POST/);

    const evil = await send('/books', { headers: { Origin: 'https://evil.example' } });
    assert.equal(evil.status, 200);                                // CORS is enforced by browsers, not the server
    assert.equal(evil.headers.get('access-control-allow-origin'), null);
    assert.equal(evil.headers.get('vary'), 'Origin');
  });

  it('logs one line per request without leaking the body', async () => {
    logLines.length = 0;
    await send('/books', { method: 'POST', body: { isbn: '123', title: 'Secret Title', author: 'x' } });
    const access = logLines.filter((l) => l.msg === 'request');
    assert.equal(access.length, 1);
    assert.equal(access[0].status, 422);
    assert.ok(!JSON.stringify(access[0]).includes('Secret Title'));
  });
});

describe('graceful shutdown', () => {
  it('finishes the in-flight request, then refuses new connections', async () => {
    const config = loadConfig({ PORT: '0', DB_PATH: ':memory:' });
    const app = createApp(config, { log: createLogger({ level: 'silent' }) });
    const { port } = await app.start();

    // Start a POST but hold back the end of the body, so the request is in flight.
    const payload = JSON.stringify({ isbn: ISBNS[0], title: 'Drained', author: 'A. Writer' });
    const req = http.request({ port, host: '127.0.0.1', method: 'POST', path: '/books',
      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } });
    req.write(payload.slice(0, 10));
    await new Promise((resolve) => setTimeout(resolve, 50));

    const stopped = app.stop();                                   // begins draining
    await new Promise((resolve) => setTimeout(resolve, 50));
    await assert.rejects(fetch(`http://127.0.0.1:${port}/health`)); // listener is closed: new connections fail

    req.end(payload.slice(10));
    const [res] = await once(req, 'response');
    assert.equal(res.statusCode, 201);                            // the in-flight request still completed
    res.resume();
    const started = performance.now();
    await stopped;                                                // resolves once the connection is swept
    assert.ok(performance.now() - started < 2000, 'did not wait for keep-alive timeouts');
  });
});

node --test

▶ Bookshelf REST API
  ✔ creates, reads, replaces and deletes a book
  ✔ answers errors as problem details
  ✔ rejects bad bodies before they reach the database
  ✔ answers 404, 405 and OPTIONS with the right headers
  ✔ returns 409 for a duplicate ISBN
  ✔ paginates with an opaque cursor and a Link header
  ✔ treats LIKE wildcards in q literally
  ✔ implements CORS for an allow-listed origin only
  ✔ logs one line per request without leaking the body
✔ Bookshelf REST API
▶ graceful shutdown
  ✔ finishes the in-flight request, then refuses new connections
✔ graceful shutdown
ℹ tests 10
ℹ pass 10
ℹ fail 0