Express.js REST API - Silent Hang from Missing next()

// server.js — the entry point for our Book Library REST API
// Run: node server.js
// Then visit: http://localhost:3000/api/books

const express = require('express');

const app = express(); // create an Express application instance
const PORT = 3000;

// express.json() is middleware that parses incoming request bodies
// that have Content-Type: application/json. Without this, req.body is undefined.
app.use(express.json());

// In-memory data store — we'll replace this pattern with a real DB later
// but the API shape stays identical, which is the whole point of abstraction
let books = [
  { id: 1, title: 'The Pragmatic Programmer', author: 'Hunt & Thomas', year: 1999 },
  { id: 2, title: 'Clean Code', author: 'Robert C. Martin', year: 2008 },
  { id: 3, title: 'You Don\'t Know JS', author: 'Kyle Simpson', year: 2015 },
];

// GET /api/books — retrieve all books
// REST rule: GET never modifies data, always returns a collection or single resource
app.get('/api/books', (req, res) => {
  res.status(200).json({
    success: true,
    count: books.length,
    data: books,
  });
});

// GET /api/books/:id — retrieve one book by its ID
// :id is a route parameter — Express captures whatever is in that URL segment
app.get('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10); // always parse to a number — URL params are strings
  const book = books.find((b) => b.id === bookId);

  if (!book) {
    // 404 means the resource doesn't exist — not a server error, a client error
    return res.status(404).json({ success: false, message: `Book with id ${bookId} not found` });
  }

  res.status(200).json({ success: true, data: book });
});

// POST /api/books — create a new book
// The client sends book data in the request body as JSON
app.post('/api/books', (req, res) => {
  const { title, author, year } = req.body;

  // Basic validation — never trust client input
  if (!title || !author || !year) {
    return res.status(400).json({
      success: false,
      message: 'title, author, and year are required fields',
    });
  }

  // Generate a simple incrementing ID (a real DB would handle this)
  const newBook = {
    id: books.length > 0 ? Math.max(...books.map((b) => b.id)) + 1 : 1,
    title,
    author,
    year: parseInt(year, 10),
  };

  books.push(newBook);

  // 201 Created — not 200. The resource didn't exist before; now it does.
  res.status(201).json({ success: true, data: newBook });
});

// PUT /api/books/:id — replace/update an existing book
app.put('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book with id ${bookId} not found` });
  }

  const { title, author, year } = req.body;

  // Merge the existing book data with the incoming updates
  books[bookIndex] = { ...books[bookIndex], title, author, year: parseInt(year, 10) };

  res.status(200).json({ success: true, data: books[bookIndex] });
});

// DELETE /api/books/:id — remove a book
app.delete('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book with id ${bookId} not found` });
  }

  books.splice(bookIndex, 1); // remove the book from our array

  // 204 No Content — success, but there's nothing to return (the resource is gone)
  res.status(204).send();
});

app.listen(PORT, () => {
  console.log(`Book Library API running on http://localhost:${PORT}`);
});

// middleware.js — custom middleware functions for our Book Library API
// These are pure functions: testable, reusable, and single-purpose

// ─── REQUEST LOGGER ───────────────────────────────────────────────────────────
// Logs every incoming request: method, URL, and response time
// This runs for EVERY request because we'll register it with app.use() at the top
const requestLogger = (req, res, next) => {
  const startTime = Date.now();

  // res.on('finish') fires AFTER the response is sent — so we get accurate timing
  res.on('finish', () => {
    const duration = Date.now() - startTime;
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.originalUrl} — ${res.statusCode} (${duration}ms)`);
  });

  next(); // CRITICAL: without next(), the request just hangs — no response ever sent
};

// ─── API KEY AUTHENTICATION ────────────────────────────────────────────────────
// Checks that the client sent a valid API key in the x-api-key header
// In production you'd validate against a database or use JWT — same pattern, more logic
const requireApiKey = (req, res, next) => {
  const VALID_API_KEY = process.env.API_KEY || 'dev-secret-key-12345';
  const clientKey = req.headers['x-api-key'];

  if (!clientKey) {
    // 401 Unauthorized — the client didn't provide credentials at all
    return res.status(401).json({
      success: false,
      message: 'Missing x-api-key header. Include your API key to access this endpoint.',
    });
  }

  if (clientKey !== VALID_API_KEY) {
    // 403 Forbidden — credentials were provided but they're wrong
    return res.status(403).json({
      success: false,
      message: 'Invalid API key. Check your credentials and try again.',
    });
  }

  // Attach the key to the request object for downstream use if needed
  req.apiKey = clientKey;
  next(); // credentials are valid — continue to the route handler
};

// ─── BOOK BODY VALIDATOR ───────────────────────────────────────────────────────
// Validates that POST and PUT requests have the required book fields
// By extracting this to middleware, our route handlers stay clean
const validateBookBody = (req, res, next) => {
  const { title, author, year } = req.body;
  const errors = [];

  if (!title || typeof title !== 'string' || title.trim() === '') {
    errors.push('title must be a non-empty string');
  }
  if (!author || typeof author !== 'string' || author.trim() === '') {
    errors.push('author must be a non-empty string');
  }
  if (!year || isNaN(parseInt(year, 10)) || parseInt(year, 10) < 1000) {
    errors.push('year must be a valid 4-digit number');
  }

  if (errors.length > 0) {
    // Pass an Error object to next() — this triggers Express's error handler
    const validationError = new Error('Validation failed');
    validationError.statusCode = 400;
    validationError.details = errors;
    return next(validationError); // jumps straight to the error-handling middleware
  }

  next();
};

// ─── GLOBAL ERROR HANDLER ──────────────────────────────────────────────────────
// This MUST have exactly 4 parameters — Express detects it as an error handler by signature
// Register this LAST with app.use() — after all routes
const globalErrorHandler = (err, req, res, next) => {
  console.error(`[ERROR] ${err.message}`, err.stack);

  const statusCode = err.statusCode || 500; // default to 500 if no specific code was set
  const response = {
    success: false,
    message: err.message || 'An unexpected server error occurred',
  };

  // Include validation details if present (avoids leaking stack traces to clients)
  if (err.details) {
    response.errors = err.details;
  }

  res.status(statusCode).json(response);
};

module.exports = { requestLogger, requireApiKey, validateBookBody, globalErrorHandler };

// routes/books.js — all book-related routes live here
// This file knows NOTHING about auth or logging — those are app-level concerns

const express = require('express');
const router = express.Router(); // create a Router instance — not a full app
const { validateBookBody } = require('../middleware');

// Simulated data layer — in a real app this would be a service/repository
// The key point: swapping this to a real DB doesn't change the routes at all
let books = [
  { id: 1, title: 'The Pragmatic Programmer', author: 'Hunt & Thomas', year: 1999 },
  { id: 2, title: 'Clean Code', author: 'Robert C. Martin', year: 2008 },
];

// GET / — maps to GET /api/books when mounted at /api/books
// Notice: the path here is '/', not '/api/books' — the prefix is added at mount time
router.get('/', (req, res) => {
  // req.query lets you read URL query parameters like ?author=Martin
  const { author, year } = req.query;

  let results = [...books];

  if (author) {
    results = results.filter((b) =>
      b.author.toLowerCase().includes(author.toLowerCase())
    );
  }
  if (year) {
    results = results.filter((b) => b.year === parseInt(year, 10));
  }

  res.status(200).json({ success: true, count: results.length, data: results });
});

// GET /:id — maps to GET /api/books/:id
router.get('/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const book = books.find((b) => b.id === bookId);

  if (!book) {
    return res.status(404).json({ success: false, message: `Book ${bookId} not found` });
  }
  res.status(200).json({ success: true, data: book });
});

// POST / — validateBookBody middleware runs BEFORE the route handler
// If validation fails, the route handler never executes — the error bubbles to globalErrorHandler
router.post('/', validateBookBody, (req, res) => {
  const { title, author, year } = req.body;
  const newBook = {
    id: books.length > 0 ? Math.max(...books.map((b) => b.id)) + 1 : 1,
    title: title.trim(),
    author: author.trim(),
    year: parseInt(year, 10),
  };
  books.push(newBook);
  res.status(201).json({ success: true, data: newBook });
});

router.put('/:id', validateBookBody, (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book ${bookId} not found` });
  }

  books[bookIndex] = { id: bookId, ...req.body, year: parseInt(req.body.year, 10) };
  res.status(200).json({ success: true, data: books[bookIndex] });
});

router.delete('/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book ${bookId} not found` });
  }

  books.splice(bookIndex, 1);
  res.status(204).send();
});

module.exports = router;


// ─── app.js — main application file that wires everything together ─────────────
// (In a real project this would be a separate file)

const appSetup = `
const express = require('express');
const { requestLogger, requireApiKey, globalErrorHandler } = require('./middleware');
const bookRouter = require('./routes/books');

const app = express();

app.use(express.json());         // parse JSON bodies — runs for ALL routes
app.use(requestLogger);          // log every request — runs for ALL routes
app.use(requireApiKey);          // auth gate — runs for ALL routes below this line

// Mount the book router at /api/books
// All routes in bookRouter are now prefixed with /api/books
app.use('/api/books', bookRouter);

// 404 handler — catches any request that didn't match a route above
app.use((req, res) => {
  res.status(404).json({ success: false, message: 'Route not found' });
});

// Error handler — MUST be registered last, MUST have 4 params
app.use(globalErrorHandler);

app.listen(3000, () => console.log('API running on http://localhost:3000'));
`;

console.log('Route structure:\n', appSetup);

// error-handling.js — dedicated error patterns for production Express APIs

// ─── Wrapper for async route handlers ──────────────────────────────────────────
// Without this, an async error crashes the server or causes a silent unhandled rejection
const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// Usage:
// app.get('/api/books', asyncHandler(async (req, res) => {
//   const books = await db.findMany();
//   res.json(books);
// }));

// ─── OR: install express-async-errors at the top of server.js ──────────────────
// require('express-async-errors');
// This patches Express to catch async rejections everywhere — no wrapper needed.

// ─── Custom error class for API errors ──────────────────────────────────────────
// Allows you to set HTTP status codes on errors consistently
class ApiError extends Error {
  constructor(statusCode, message, details = null) {
    super(message);
    this.statusCode = statusCode;
    this.details = details;
  }
}

// Usage:
// throw new ApiError(403, 'You do not have permission to access this resource');

// ─── Global error handler (must be registered last) ────────────────────────────
const globalErrorHandler = (err, req, res, next) => {
  // Log full error internally
  console.error(`[ERROR ${new Date().toISOString()}] ${err.message}`, err.stack);

  // Determine status code
  const statusCode = err.statusCode || 500;

  // Build response body
  const response = {
    success: false,
    message: statusCode === 500 ? 'An unexpected error occurred' : err.message,
  };

  // Include validation errors if present (never leak stack in production)
  if (err.details) {
    response.errors = err.details;
  }

  // In development, you might include the stack trace for debugging
  if (process.env.NODE_ENV === 'development') {
    response.stack = err.stack;
  }

  res.status(statusCode).json(response);
};

module.exports = { asyncHandler, ApiError, globalErrorHandler };

// production-setup.js — environment configuration and graceful shutdown

const express = require('express');
const pino = require('pino');          // structured JSON logging
const { ApiError, globalErrorHandler } = require('./error-handling');

// ─── Configuration ─────────────────────────────────────────────────────────────
const requiredEnvVars = ['DATABASE_URL', 'API_KEY'];
const missing = requiredEnvVars.filter((v) => !process.env[v]);
if (missing.length > 0) {
  console.error(`Missing required environment variables: ${missing.join(', ')}`);
  process.exit(1);
}

const config = {
  port: parseInt(process.env.PORT, 10) || 3000,
  databaseUrl: process.env.DATABASE_URL,
  apiKey: process.env.API_KEY,
  nodeEnv: process.env.NODE_ENV || 'development',
};

// ─── Structured Logger ─────────────────────────────────────────────────────────
const logger = pino({
  level: config.nodeEnv === 'production' ? 'info' : 'debug',
  formatters: {
    // Ensures every log line has a timestamp and service name for correlation
    bindings: () => ({ service: 'book-library-api' }),
  },
});

// Express middleware to attach logger to each request
const requestLogger = (req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    logger.info({
      method: req.method,
      url: req.originalUrl,
      status: res.statusCode,
      durationMs: Date.now() - start,
    });
  });
  next();
};

// ─── Server and Graceful Shutdown ──────────────────────────────────────────────
const app = express();
app.use(express.json());
app.use(requestLogger);

// ... routes ...

app.use(globalErrorHandler);

const server = app.listen(config.port, () => {
  logger.info(`Server started on port ${config.port}`);
});

const gracefulShutdown = (signal) => {
  logger.info(`${signal} received — shutting down gracefully...`);
  server.close(() => {
    logger.info('All connections closed. Exiting.');
    process.exit(0);
  });

  // If connections don't close within 10 seconds, force exit
  setTimeout(() => {
    logger.error('Forcing shutdown after timeout');
    process.exit(1);
  }, 10000).unref();
};

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));