Handlers, Services & Repositories.

from dataclasses import dataclass
from flask import request, jsonify

@dataclass
class CreateBookRequest:
    title: str
    author: str

def create_book_handler():
    # Step 1 + 2: extract body and deserialize into a native dict/class.
    payload = request.get_json(silent=True)
    if payload is None:
        # Deserialization failed -> malformed payload.
        return jsonify({"error": "invalid request body"}), 400
    req = CreateBookRequest(**payload)
    # ... validation, transformation, delegation follow ...

// Express's json() body parser has already deserialized the body upstream,
// so req.body is a JavaScript object by the time the handler runs. That
// makes step 1 free and turns step 2 into "check the shape you expected".
app.post('/books', (req, res) => {
  // Step 1 + 2: extract the body and bind the fields we accept.
  const { title, author } = req.body ?? {}

  // express.json() leaves req.body empty when the payload is malformed.
  if (typeof title !== 'string' || typeof author !== 'string') {
    // Binding failed -> the payload is malformed.
    return res.status(400).json({ error: 'invalid request body' }) // 400
  }

  const createBookRequest = { title, author }
  // ... validation, transformation, delegation follow ...
})

import type { Request, Response } from 'express'

// CreateBookRequest is our native format, the bind target.
interface CreateBookRequest {
  title: string
  author: string
}

// A parsed body is `unknown` until something proves its shape. A type
// guard is that proof, and it is what lets the rest of the handler treat
// `req.body` as a CreateBookRequest without a cast.
function isCreateBookRequest(value: unknown): value is CreateBookRequest {
  const body = value as Partial<CreateBookRequest> | null
  return typeof body?.title === 'string' && typeof body?.author === 'string'
}

export function createBookHandler(req: Request, res: Response): void {
  // Step 1 + 2: extract the body and deserialize (bind) into the type.
  if (!isCreateBookRequest(req.body)) {
    // Deserialization failed -> the payload is malformed.
    res.status(400).json({ error: 'invalid request body' }) // 400
    return // terminate the request here; do not proceed.
  }

  const body: CreateBookRequest = req.body
  // ... validation, transformation, delegation follow ...
}

// CreateBookRequest is our native format, the bind target.
public record CreateBookRequest(String title, String author) {}

@RestController
class BookController {

    // Step 1 + 2 happen BEFORE this method runs: @RequestBody tells Spring
    // to read the body and let Jackson deserialize it into the record.
    @PostMapping("/books")
    ResponseEntity<?> createBook(@RequestBody CreateBookRequest req) {
        // ... validation, transformation, delegation follow ...
        return ResponseEntity.status(HttpStatus.CREATED).build(); // 201
    }

    // A body Jackson cannot read never reaches the handler, it arrives
    // here instead. Same outcome as the explicit `if` above: 400.
    @ExceptionHandler(HttpMessageNotReadableException.class)
    ResponseEntity<?> onUnreadableBody() {
        return ResponseEntity.badRequest()
            .body(Map.of("error", "invalid request body")); // 400
    }
}

def list_books_handler():
    sort = request.args.get("sort")  # None if absent

    # VALIDATION: if present, must be an allowed value.
    if sort is not None and sort not in ("name", "date"):
        return jsonify({"error": "sort must be 'name' or 'date'"}), 400

    # TRANSFORMATION: optional param -> inject a default.
    if sort is None:
        sort = "date"

    try:
        books = book_service.list_books(sort)  # delegate
    except Exception:
        return jsonify({"error": "could not fetch books"}), 500

    return jsonify(books), 200  # array of books

app.get('/books', async (req, res) => {
  const sort = req.query.sort // undefined if absent

  // VALIDATION: if present, it must be one of the allowed values.
  if (sort !== undefined && sort !== 'name' && sort !== 'date') {
    return res.status(400).json({ error: "sort must be 'name' or 'date'" })
  }

  // TRANSFORMATION: query params are optional -> inject a default.
  const sortBy = sort ?? 'date' // downstream layers never see undefined

  try {
    const books = await bookService.listBooks(sortBy) // delegate
    res.status(200).json(books) // 200 with the array of books
  } catch {
    res.status(500).json({ error: 'could not fetch books' }) // 500
  }
})

import type { Request, Response } from 'express'

const SORTS = ['name', 'date'] as const
type Sort = (typeof SORTS)[number]

export async function listBooksHandler(req: Request, res: Response): Promise<void> {
  const sort = req.query.sort // string | string[] | undefined | ...

  // VALIDATION: if present, it must be one of the allowed values.
  if (sort !== undefined && !SORTS.includes(sort as Sort)) {
    res.status(400).json({ error: "sort must be 'name' or 'date'" })
    return
  }

  // TRANSFORMATION: optional param -> inject a default. Note what the
  // narrowed type buys you: the service takes a `Sort`, so a typo in a
  // future edit stops compiling instead of reaching the database.
  const sortBy: Sort = (sort as Sort | undefined) ?? 'date'

  try {
    const books = await bookService.listBooks(sortBy) // delegate
    res.status(200).json(books) // 200 with the array of books
  } catch {
    res.status(500).json({ error: 'could not fetch books' }) // 500
  }
}

@GetMapping("/books")
ResponseEntity<?> listBooks(@RequestParam(required = false) String sort) {
    // VALIDATION: if present, it must be one of the allowed values.
    if (sort != null && !sort.equals("name") && !sort.equals("date")) {
        return ResponseEntity.badRequest()
            .body(Map.of("error", "sort must be 'name' or 'date'")); // 400
    }

    // TRANSFORMATION: query params are optional -> inject a default.
    // (@RequestParam(defaultValue = "date") would do exactly this for you;
    // it is spelled out here so the step stays visible.)
    String sortBy = (sort == null) ? "date" : sort;

    try {
        List<Book> books = bookService.listBooks(sortBy); // delegate
        return ResponseEntity.ok(books); // 200 with the array of books
    } catch (DataAccessException e) {
        return ResponseEntity.internalServerError()
            .body(Map.of("error", "could not fetch books")); // 500
    }
}

class BookService:
    def __init__(self, repo, mailer):
        self.repo = repo
        self.mailer = mailer

    # No request, no response, no status codes, just logic.
    def list_books(self, sort: str) -> list:
        # Orchestration: ask the repository for what it needs.
        books = self.repo.find_all_books(sort)
        # Could merge other repo calls, enrich, notify, etc.
        return books

    # A purely-logic service that never touches the DB:
    def notify_owner(self, email: str) -> None:
        self.mailer.send(email, "Your book was added")

// Notice: no req, no res, no status codes.
// You cannot tell from these methods that they serve an API.
class BookService {
  constructor(repo, mailer) {
    this.repo = repo
    this.mailer = mailer
  }

  async listBooks(sort) {
    // Orchestration: call the repository for the data it needs.
    const books = await this.repo.findAllBooks(sort)
    // Could also: enrich, merge other repo calls, send notifications...
    return books
  }

  // A service that needs no database at all is perfectly valid:
  async notifyOwner(email) {
    await this.mailer.send(email, 'Your book was added')
  }
}

// The types tell the same story the comments do: every name in this
// signature is a domain word (Book, Sort, Mailer). Not one of them is
// an HTTP word, which is exactly the isolation we are after.
export class BookService {
  constructor(
    private readonly repo: BookRepo,
    private readonly mailer: Mailer,
  ) {}

  async listBooks(sort: Sort): Promise<Book[]> {
    // Orchestration: ask the repository for what it needs.
    const books = await this.repo.findAllBooks(sort)
    // Could merge other repo calls, enrich, notify, etc.
    return books
  }

  // A purely-logic service that never touches the DB:
  async notifyOwner(email: string): Promise<void> {
    await this.mailer.send(email, 'Your book was added')
  }
}

// No HttpServletRequest, no ResponseEntity, no status codes. Nothing here
// says "web", this class would work unchanged behind a CLI or a queue.
@Service
public class BookService {
    private final BookRepo repo;
    private final Mailer mailer;

    BookService(BookRepo repo, Mailer mailer) {
        this.repo = repo;
        this.mailer = mailer;
    }

    public List<Book> listBooks(String sort) {
        // Orchestration: call the repository for the data it needs.
        List<Book> books = repo.findAllBooks(sort);
        // Could also: enrich, merge other repo calls, send notifications...
        return books;
    }

    // A service that needs no database at all is perfectly valid:
    public void notifyOwner(String email) {
        mailer.send(email, "Your book was added");
    }
}

class BookRepo:
    def __init__(self, db):
        self.db = db

    # ONE method, ONE result shape: all books, sorted.
    def find_all_books(self, sort: str) -> list:
        # Build the query from data passed down by the service.
        query = f"SELECT id, title, author FROM books ORDER BY {sort}"
        cur = self.db.execute(query)
        return [dict(row) for row in cur.fetchall()]

    # SEPARATE method for one book. No optional toggle parameter.
    def find_book_by_id(self, book_id: int) -> dict:
        cur = self.db.execute(
            "SELECT id, title, author FROM books WHERE id = ?", (book_id,))
        return dict(cur.fetchone())

class BookRepo {
  constructor(db) {
    this.db = db // a node-postgres Pool
  }

  // ONE method, ONE shape of result: all books, sorted.
  async findAllBooks(sort) {
    // A column name can never be a bound parameter, so it goes through a
    // fixed lookup rather than into the string. Values always use $1, $2.
    const column = { name: 'title', date: 'created_at' }[sort] ?? 'created_at'
    const { rows } = await this.db.query(
      `SELECT id, title, author FROM books ORDER BY ${column}`)
    return rows
  }

  // SEPARATE method for one book. No optional toggle parameter.
  async findBookById(id) {
    const { rows } = await this.db.query(
      'SELECT id, title, author FROM books WHERE id = $1', [id])
    return rows[0] ?? null
  }
}

import type { Pool } from 'pg'

const SORT_COLUMNS: Record<Sort, string> = { name: 'title', date: 'created_at' }

export class BookRepo {
  constructor(private readonly db: Pool) {}

  // ONE method, ONE shape of result: all books, sorted.
  async findAllBooks(sort: Sort): Promise<Book[]> {
    // Because `sort` is a `Sort` and not a `string`, the lookup is total:
    // there is no value it could hold that produces a column we did not
    // write ourselves. The type is the injection defence.
    const { rows } = await this.db.query<Book>(
      `SELECT id, title, author FROM books ORDER BY ${SORT_COLUMNS[sort]}`)
    return rows
  }

  // SEPARATE method for one book. No optional toggle parameter.
  // The return type says "may be missing" out loud, so the service has
  // to decide what that means instead of tripping over undefined.
  async findBookById(id: number): Promise<Book | null> {
    const { rows } = await this.db.query<Book>(
      'SELECT id, title, author FROM books WHERE id = $1', [id])
    return rows[0] ?? null
  }
}

@Repository
public class BookRepo {
    // A column name can never be a bound parameter, so it goes through a
    // fixed map rather than into the string. Values always use ?.
    private static final Map<String, String> SORT_COLUMNS =
        Map.of("name", "title", "date", "created_at");

    private final JdbcClient db;

    BookRepo(JdbcClient db) {
        this.db = db;
    }

    // ONE method, ONE shape of result: all books, sorted.
    public List<Book> findAllBooks(String sort) {
        String column = SORT_COLUMNS.getOrDefault(sort, "created_at");
        return db.sql("SELECT id, title, author FROM books ORDER BY " + column)
                 .query(Book.class)
                 .list();
    }

    // SEPARATE method for one book. No optional toggle parameter.
    public Optional<Book> findBookById(long id) {
        return db.sql("SELECT id, title, author FROM books WHERE id = ?")
                 .param(id)
                 .query(Book.class)
                 .optional();
    }
}

# A WSGI/Flask-style middleware receives the request and a `next`
# callable that invokes the rest of the chain.
def logging_middleware(next):
    def wrapper(request):
        print(f"{request.method} {request.path}")  # do work

        # EARLY EXIT example (short-circuit, never calls next):
        if request.headers.get("X-Blocked") == "yes":
            return Response("forbidden", status=403)  # stops here

        return next(request)  # === next(): continue the chain ===
    return wrapper

// Express middleware is the shape the whole idea is named after:
// (req, res, next). Calling next() passes execution along the chain.
function loggingMiddleware(req, res, next) {
  console.log(`${req.method} ${req.path}`) // do work

  // EARLY EXIT example (short-circuit, never calls next):
  if (req.get('X-Blocked') === 'yes') {
    return res.status(403).send('forbidden') // request stops here
  }

  next() // === next(): continue the chain ===
}

app.use(loggingMiddleware)

import type { NextFunction, Request, Response } from 'express'

// The three parameters, spelled out by their types: the request, the
// response, and the `next` callable that invokes the rest of the chain.
// The `void` return is the reminder that a middleware communicates by
// calling next() or by writing a response, never by returning a value.
function loggingMiddleware(req: Request, res: Response, next: NextFunction): void {
  console.log(`${req.method} ${req.path}`) // do work

  // EARLY EXIT example (short-circuit, never calls next):
  if (req.get('X-Blocked') === 'yes') {
    res.status(403).send('forbidden') // request stops here
    return
  }

  next() // === next(): continue the chain ===
}

app.use(loggingMiddleware)

// A servlet Filter is Java's middleware. It receives the request, the
// response, and a FilterChain, and chain.doFilter IS next(): pass
// execution to the next filter, or on to the controller.
@Component
public class LoggingFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest req,
                                    HttpServletResponse res,
                                    FilterChain chain)
            throws ServletException, IOException {
        log.info("{} {}", req.getMethod(), req.getRequestURI()); // do work

        // EARLY EXIT example (short-circuit, never calls the chain):
        if ("yes".equals(req.getHeader("X-Blocked"))) {
            res.sendError(HttpServletResponse.SC_FORBIDDEN, "forbidden");
            return; // request stops here
        }

        chain.doFilter(req, res); // === next(): continue the chain ===
    }
}

ALLOWED_ORIGIN = "https://app.example.com"

def cors_middleware(next):
    def wrapper(request):
        resp = next(request)
        origin = request.headers.get("Origin")  # runtime gives us this
        if origin == ALLOWED_ORIGIN:
            resp.headers["Access-Control-Allow-Origin"] = origin
        return resp
    return wrapper

def auth_middleware(next):
    def wrapper(request):
        token = request.headers.get("Authorization")
        try:
            user_id, role = verify_token(token)
        except Exception:
            return Response("unauthorized", status=401)  # stop
        # SUCCESS: stash identity in the request context, then continue.
        request.context["user_id"] = user_id
        request.context["role"] = role
        return next(request)
    return wrapper

const ALLOWED_ORIGIN = 'https://app.example.com'

function corsMiddleware(req, res, next) {
  const origin = req.get('Origin') // runtime gives us this
  if (origin === ALLOWED_ORIGIN) {
    res.set('Access-Control-Allow-Origin', origin)
  }
  next() // pass along; browser blocks if header absent
}

function authMiddleware(req, res, next) {
  const token = req.get('Authorization')
  let claims
  try {
    claims = verifyToken(token)
  } catch {
    return res.status(401).send('unauthorized') // 401, stop
  }
  // SUCCESS: stash identity in the request context, then continue.
  req.context = { ...req.context, userId: claims.userId, role: claims.role }
  next()
}

import type { NextFunction, Request, Response } from 'express'

const ALLOWED_ORIGIN = 'https://app.example.com'

export function corsMiddleware(req: Request, res: Response, next: NextFunction): void {
  const origin = req.get('Origin') // runtime gives us this
  if (origin === ALLOWED_ORIGIN) {
    res.set('Access-Control-Allow-Origin', origin)
  }
  next() // pass along; browser blocks if header absent
}

export function authMiddleware(req: Request, res: Response, next: NextFunction): void {
  const token = req.get('Authorization')
  let claims: TokenClaims
  try {
    claims = verifyToken(token)
  } catch {
    res.status(401).send('unauthorized') // 401, stop
    return
  }
  // SUCCESS: stash identity in the request context, then continue.
  // `req.context` is typed once via declaration merging (next section),
  // so every handler downstream reads it without a cast.
  req.context = { ...req.context, userId: claims.userId, role: claims.role }
  next()
}

@Component
public class CorsFilter extends OncePerRequestFilter {
    private static final String ALLOWED_ORIGIN = "https://app.example.com";

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                    FilterChain chain)
            throws ServletException, IOException {
        String origin = req.getHeader("Origin"); // runtime gives us this
        if (ALLOWED_ORIGIN.equals(origin)) {
            res.setHeader("Access-Control-Allow-Origin", origin);
        }
        chain.doFilter(req, res); // pass along; browser blocks if header absent
    }
}

@Component
public class AuthFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                    FilterChain chain)
            throws ServletException, IOException {
        String token = req.getHeader("Authorization");
        TokenClaims claims;
        try {
            claims = verifyToken(token);
        } catch (InvalidTokenException e) {
            res.sendError(HttpServletResponse.SC_UNAUTHORIZED, "unauthorized"); // 401, stop
            return;
        }
        // SUCCESS: stash identity in the request context, then continue.
        // Request attributes ARE the servlet request context: a key-value
        // map that lives and dies with this one request.
        req.setAttribute("userId", claims.userId());
        req.setAttribute("role", claims.role());
        chain.doFilter(req, res);
    }
}

def create_book_handler(request):
    req = CreateBookRequest(**request.get_json())

    # Read the trusted user id FROM THE CONTEXT, not from the body.
    # The auth middleware put it there after verifying the token.
    user_id = request.context["user_id"]
    role = request.context["role"]

    if role not in ("admin", "user"):
        return Response("forbidden", status=403)

    # Persist with the SERVER-VERIFIED owner id, never the client's.
    book = book_service.create(req, user_id)
    return jsonify(book), 201

app.post('/books', async (req, res) => {
  const { title, author } = req.body ?? {}

  // Read the trusted user id FROM THE CONTEXT, not from the body.
  // The auth middleware put it there after verifying the token.
  const { userId, role } = req.context

  if (role !== 'admin' && role !== 'user') {
    return res.status(403).send('forbidden')
  }

  // Persist with the SERVER-VERIFIED owner id, never the client's.
  const book = await bookService.create({ title, author }, userId)
  res.status(201).json(book) // 201
})

import type { Request, Response } from 'express'

// Declare the context's shape ONCE and every handler in the codebase
// sees it. This is how you stop `req.context` from decaying into an
// `any` bag that each handler guesses at.
declare module 'express-serve-static-core' {
  interface Request {
    context: { userId: number; role: string; requestId: string }
  }
}

export async function createBookHandler(req: Request, res: Response): Promise<void> {
  const body = req.body as CreateBookRequest

  // Read the trusted user id FROM THE CONTEXT, not from the body.
  // The auth middleware put it there after verifying the token.
  const { userId, role } = req.context

  if (role !== 'admin' && role !== 'user') {
    res.status(403).send('forbidden')
    return
  }

  // Persist with the SERVER-VERIFIED owner id, never the client's.
  const book = await bookService.create(body, userId)
  res.status(201).json(book) // 201
}

@PostMapping("/books")
ResponseEntity<?> createBook(@RequestBody CreateBookRequest req,
                             HttpServletRequest http) {
    // Read the trusted user id FROM THE REQUEST CONTEXT, not from req.
    // The auth filter put it there after verifying the token.
    long userId = (long) http.getAttribute("userId");
    String role = (String) http.getAttribute("role");

    if (!role.equals("admin") && !role.equals("user")) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN).body("forbidden");
    }

    // Persist with the SERVER-VERIFIED owner id, never the client's.
    Book book = bookService.create(req, userId);
    return ResponseEntity.status(HttpStatus.CREATED).body(book); // 201
}

import uuid

def request_id_middleware(next):
    def wrapper(request):
        rid = str(uuid.uuid4())  # one unique id for this request
        request.context["request_id"] = rid
        print(f"[{rid}] {request.method} {request.path}")
        resp = next(request)
        resp.headers["X-Request-ID"] = rid  # echo it back / forward it
        return resp
    return wrapper

import { randomUUID } from 'node:crypto'

function requestIdMiddleware(req, res, next) {
  const id = randomUUID() // one unique id for this request
  req.context = { ...req.context, requestId: id }
  res.set('X-Request-ID', id) // echo it back / forward it
  console.log(`[${id}] ${req.method} ${req.path}`)
  next()
}

import { randomUUID } from 'node:crypto'
import type { NextFunction, Request, Response } from 'express'

export function requestIdMiddleware(req: Request, res: Response, next: NextFunction): void {
  const id = randomUUID() // one unique id for this request
  req.context = { ...req.context, requestId: id }
  res.set('X-Request-ID', id) // echo it back / forward it
  console.log(`[${id}] ${req.method} ${req.path}`)
  // Node also ships AsyncLocalStorage, which carries the id through
  // awaits into code that never sees `req` at all, the logger, the
  // database layer, an outbound fetch. Same context, no hand-off.
  next()
}

@Component
public class RequestIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                    FilterChain chain)
            throws ServletException, IOException {
        String id = UUID.randomUUID().toString(); // one unique id for this request
        req.setAttribute("requestId", id);
        res.setHeader("X-Request-ID", id); // echo it back / forward it

        // MDC is the logging framework's own per-request context. Put the
        // id in once and EVERY log line from this request carries it, with
        // no logging call having to pass it along by hand.
        MDC.put("requestId", id);
        try {
            log.info("{} {}", req.getMethod(), req.getRequestURI());
            chain.doFilter(req, res);
        } finally {
            MDC.clear(); // threads are pooled, never leak it to the next request
        }
    }
}