Routing, the where of every request.

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from urllib.parse import urlsplit, parse_qs

# ABSTRACTION: Handler is an Abstract Base Class. @abstractmethod
# forces every subclass to define handle(). You cannot create a
# Handler directly, it is a pure contract.
class Handler(ABC):
    @abstractmethod
    def handle(self, req: "Request") -> "Response": ...

@dataclass
class Request:
    method: str
    path: str
    params: dict = field(default_factory=dict)  # path params (:id)
    query: dict = field(default_factory=dict)   # query params (?page=2)

@dataclass
class Response:
    status: int
    body: str

# INHERITANCE: BaseHandler is a concrete parent holding shared
# behaviour (logging). Subclasses inherit and reuse _log().
class BaseHandler(Handler):
    def __init__(self, name): self._name = name   # protected by convention
    def _log(self, req): print(f"[{self._name}] {req.method} {req.path}")

# POLYMORPHISM: each subclass OVERRIDES handle() differently, yet
# the router calls them all identically, handler.handle(req).
class GetUser(BaseHandler):           # IS-A BaseHandler IS-A Handler
    def handle(self, req):
        self._log(req)              # inherited from parent
        return Response(200, f"user id = {req.params['id']}")

class ListBooks(BaseHandler):
    def handle(self, req):
        self._log(req)
        page = req.query.get("page", ["1"])[0]   # query param
        return Response(200, f"books page {page}")

# ENCAPSULATION: self.__routes is name-mangled to _Router__routes,
# so it is effectively private. The public surface is register()
# and dispatch(); the table stays hidden.
class Router:
    def __init__(self):
        self.__routes: dict[tuple[str, str], Handler] = {}

    def register(self, method, pattern, handler):
        self.__routes[(method, pattern)] = handler  # method + path key

    def dispatch(self, method, url):
        parts = urlsplit(url)
        query = parse_qs(parts.query)               # ?a=1&b=2 -> dict
        for (m, pattern), handler in self.__routes.items():
            params = self.__match(pattern, parts.path)
            if m == method and params is not None:
                return handler.handle(
                    Request(method, parts.path, params, query))  # polymorphic
        return Response(404, "route not found")       # catch-all

    @staticmethod
    def __match(pattern, path):
        p = pattern.strip("/").split("/")
        q = path.strip("/").split("/")
        if len(p) != len(q): return None
        params = {}
        for seg, val in zip(p, q):
            if seg.startswith(":"):       # dynamic segment
                params[seg[1:]] = val    # bind :id -> "123"
            elif seg != val:            # static must match exactly
                return None
        return params

if __name__ == "__main__":
    r = Router()
    r.register("GET", "/api/users/:id", GetUser("users"))
    r.register("GET", "/api/books",     ListBooks("books"))
    print(r.dispatch("GET", "/api/users/123").body)   # user id = 123
    print(r.dispatch("GET", "/api/books?page=2").body) # books page 2

// ABSTRACTION: JavaScript has no `interface` keyword, so the contract is a
// base class whose handle() refuses to run. Anything that extends Handler
// and overrides handle() IS-A Handler. The router depends only on that
// contract, never on a concrete type.
class Handler {
  handle(req) {
    throw new Error("handle() must be implemented");
  }
}

class Request {
  constructor(method, path, params = {}, query = {}) {
    this.method = method;
    this.path = path;
    this.params = params; // extracted path params (:id)
    this.query = query;   // query params (?page=2)
  }
}

class Response {
  constructor(status, body) {
    this.status = status;
    this.body = body;
  }
}

// INHERITANCE: BaseHandler is a concrete parent holding shared behaviour
// (logging). Subclasses inherit and reuse log().
class BaseHandler extends Handler {
  #name; // ENCAPSULATION: a # field is truly private, not a convention

  constructor(name) {
    super();
    this.#name = name;
  }

  log(req) {
    console.log(`[${this.#name}] ${req.method} ${req.path}`);
  }
}

// POLYMORPHISM: each subclass OVERRIDES handle() differently, yet the
// router calls them all identically, handler.handle(req).
class GetUser extends BaseHandler {   // IS-A BaseHandler IS-A Handler
  handle(req) {
    this.log(req);                    // inherited from the parent
    return new Response(200, `user id = ${req.params.id}`);
  }
}

class ListBooks extends BaseHandler {
  handle(req) {
    this.log(req);
    const page = req.query.page ?? "1"; // query param drives pagination
    return new Response(200, `books page ${page}`);
  }
}

// ENCAPSULATION: #routes is unreachable from outside the class, so the
// table stays hidden. The public surface is register() and dispatch().
class Router {
  #routes = new Map(); // key = "METHOD /route"

  register(method, pattern, handler) {
    this.#routes.set(`${method} ${pattern}`, handler); // method + path = the key
  }

  dispatch(method, url) {
    const { pathname, searchParams } = new URL(url, "http://localhost");
    const query = Object.fromEntries(searchParams.entries()); // ?a=1&b=2 -> object

    for (const [key, handler] of this.#routes) {
      const [m, pattern] = key.split(" ");
      const params = Router.#match(pattern, pathname);
      if (m === method && params !== null) {
        // polymorphic dispatch: the router never asks which class this is
        return handler.handle(new Request(method, pathname, params, query));
      }
    }
    return new Response(404, "route not found"); // catch-all fallback
  }

  // #match compares "/users/:id" against "/users/123", returning the params.
  static #match(pattern, path) {
    const p = pattern.replace(/^\/|\/$/g, "").split("/");
    const q = path.replace(/^\/|\/$/g, "").split("/");
    if (p.length !== q.length) return null;

    const params = {};
    for (const [i, seg] of p.entries()) {
      if (seg.startsWith(":")) {   // dynamic segment
        params[seg.slice(1)] = q[i]; // bind :id -> "123"
      } else if (seg !== q[i]) {   // static segment must match exactly
        return null;
      }
    }
    return params;
  }
}

const r = new Router();
r.register("GET", "/api/users/:id", new GetUser("users"));
r.register("GET", "/api/books",     new ListBooks("books"));

console.log(r.dispatch("GET", "/api/users/123").body);    // user id = 123
console.log(r.dispatch("GET", "/api/books?page=2").body); // books page 2

// ABSTRACTION: TypeScript has a real `interface` keyword, so the contract is
// a type the compiler checks, not a base class that throws at runtime.
// Anything with a matching handle() IS-A Handler. The router depends only on
// that contract, never on a concrete type.
interface Handler {
  handle(req: Request): Response;
}

type Params = Record<string, string>;
type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; // a typo like "GTE" won't compile

class Request {
  readonly method: Method;
  readonly path: string;
  readonly params: Params; // extracted path params (:id)
  readonly query: Params;  // query params (?page=2)

  constructor(method: Method, path: string, params: Params = {}, query: Params = {}) {
    this.method = method;
    this.path = path;
    this.params = params;
    this.query = query;
  }
}

class Response {
  readonly status: number;
  readonly body: string;

  constructor(status: number, body: string) {
    this.status = status;
    this.body = body;
  }
}

// INHERITANCE: BaseHandler is an abstract parent holding shared behaviour
// (logging). It can't be instantiated on its own, and `abstract handle()`
// turns a forgotten override into a compile error instead of a runtime throw.
abstract class BaseHandler implements Handler {
  #name: string; // ENCAPSULATION: a # field is private at runtime, not just to the compiler

  constructor(name: string) {
    this.#name = name;
  }

  protected log(req: Request): void { // subclasses may call it, outside code may not
    console.log(`[${this.#name}] ${req.method} ${req.path}`);
  }

  abstract handle(req: Request): Response;
}

// POLYMORPHISM: each subclass OVERRIDES handle() differently, yet the
// router calls them all identically, handler.handle(req).
class GetUser extends BaseHandler {   // IS-A BaseHandler IS-A Handler
  handle(req: Request): Response {
    this.log(req);                    // inherited from the parent
    return new Response(200, `user id = ${req.params.id}`);
  }
}

class ListBooks extends BaseHandler {
  handle(req: Request): Response {
    this.log(req);
    const page = req.query.page ?? "1"; // query param drives pagination
    return new Response(200, `books page ${page}`);
  }
}

// ENCAPSULATION: #routes is unreachable from outside the class, so the
// table stays hidden. The public surface is register() and dispatch().
class Router {
  #routes = new Map<string, Handler>(); // key = "METHOD /route"

  register(method: Method, pattern: string, handler: Handler): void {
    this.#routes.set(`${method} ${pattern}`, handler); // method + path = the key
  }

  dispatch(method: Method, url: string): Response {
    const { pathname, searchParams } = new URL(url, "http://localhost");
    const query: Params = Object.fromEntries(searchParams.entries()); // ?a=1&b=2 -> object

    for (const [key, handler] of this.#routes) {
      const [m, pattern] = key.split(" ");
      const params = Router.#match(pattern, pathname);
      if (m === method && params !== null) {
        // polymorphic dispatch: the router never asks which class this is
        return handler.handle(new Request(method, pathname, params, query));
      }
    }
    return new Response(404, "route not found"); // catch-all fallback
  }

  // #match compares "/users/:id" against "/users/123", returning the params.
  static #match(pattern: string, path: string): Params | null {
    const p = pattern.replace(/^\/|\/$/g, "").split("/");
    const q = path.replace(/^\/|\/$/g, "").split("/");
    if (p.length !== q.length) return null;

    const params: Params = {};
    for (const [i, seg] of p.entries()) {
      if (seg.startsWith(":")) {   // dynamic segment
        params[seg.slice(1)] = q[i]; // bind :id -> "123"
      } else if (seg !== q[i]) {   // static segment must match exactly
        return null;
      }
    }
    return params;
  }
}

const r = new Router();
r.register("GET", "/api/users/:id", new GetUser("users"));
r.register("GET", "/api/books",     new ListBooks("books"));

console.log(r.dispatch("GET", "/api/users/123").body);    // user id = 123
console.log(r.dispatch("GET", "/api/books?page=2").body); // books page 2

// Exporting makes this file a module, so the local Request/Response classes
// shadow the global fetch types instead of clashing with them.
export { Router, type Handler };

// run: javac Router.java && java Router
import java.net.URI;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.Map;

// ABSTRACTION: Handler is a real Java interface, a pure contract. Anything
// that implements handle() IS-A Handler. The router depends only on that
// contract, never on a concrete type.
interface Handler {
    Response handle(Request req);
}

// Records are immutable data carriers: Java generates the constructor,
// accessors (req.path()), equals, hashCode and toString.
record Request(String method, String path, Map<String, String> params, Map<String, String> query) {}

record Response(int status, String body) {}

// INHERITANCE: BaseHandler is an abstract parent holding shared behaviour
// (logging). It can't be instantiated on its own, and any concrete subclass
// that forgets to implement handle() fails to compile.
abstract class BaseHandler implements Handler {
    private final String name; // ENCAPSULATION: private is enforced by the compiler and the JVM

    protected BaseHandler(String name) {
        this.name = name;
    }

    protected void log(Request req) { // subclasses may call it, outside code may not
        System.out.printf("[%s] %s %s%n", name, req.method(), req.path());
    }
}

// POLYMORPHISM: each subclass OVERRIDES handle() differently, yet the
// router calls them all identically, handler.handle(req).
class GetUser extends BaseHandler {   // IS-A BaseHandler IS-A Handler
    GetUser(String name) {
        super(name);
    }

    @Override
    public Response handle(Request req) {
        log(req);                     // inherited from the parent
        return new Response(200, "user id = " + req.params().get("id"));
    }
}

class ListBooks extends BaseHandler {
    ListBooks(String name) {
        super(name);
    }

    @Override
    public Response handle(Request req) {
        log(req);
        String page = req.query().getOrDefault("page", "1"); // query param drives pagination
        return new Response(200, "books page " + page);
    }
}

// ENCAPSULATION: routes is private, so the table stays hidden.
// The public surface is register() and dispatch().
public class Router {
    private final Map<String, Handler> routes = new LinkedHashMap<>(); // key = "METHOD /route"

    public void register(String method, String pattern, Handler handler) {
        routes.put(method + " " + pattern, handler); // method + path = the key
    }

    public Response dispatch(String method, String url) {
        URI uri = URI.create(url);
        String path = uri.getPath();
        Map<String, String> query = parseQuery(uri.getRawQuery()); // ?a=1&b=2 -> map

        for (Map.Entry<String, Handler> route : routes.entrySet()) {
            String[] key = route.getKey().split(" ", 2);
            Map<String, String> params = match(key[1], path);
            if (key[0].equals(method) && params != null) {
                // polymorphic dispatch: the router never asks which class this is
                return route.getValue().handle(new Request(method, path, params, query));
            }
        }
        return new Response(404, "route not found"); // catch-all fallback
    }

    // match compares "/users/:id" against "/users/123", returning the params.
    private static Map<String, String> match(String pattern, String path) {
        String[] p = pattern.replaceAll("^/|/$", "").split("/");
        String[] q = path.replaceAll("^/|/$", "").split("/");
        if (p.length != q.length) return null;

        Map<String, String> params = new HashMap<>();
        for (int i = 0; i < p.length; i++) {
            if (p[i].startsWith(":")) {              // dynamic segment
                params.put(p[i].substring(1), q[i]); // bind :id -> "123"
            } else if (!p[i].equals(q[i])) {         // static segment must match exactly
                return null;
            }
        }
        return params;
    }

    private static Map<String, String> parseQuery(String raw) {
        Map<String, String> query = new HashMap<>();
        if (raw == null) return query;
        for (String pair : raw.split("&")) {
            String[] kv = pair.split("=", 2);
            String value = kv.length > 1 ? kv[1] : "";
            query.put(URLDecoder.decode(kv[0], StandardCharsets.UTF_8),
                      URLDecoder.decode(value, StandardCharsets.UTF_8));
        }
        return query;
    }

    public static void main(String[] args) {
        Router r = new Router();
        r.register("GET", "/api/users/:id", new GetUser("users"));
        r.register("GET", "/api/books",     new ListBooks("books"));

        System.out.println(r.dispatch("GET", "/api/users/123").body());    // user id = 123
        System.out.println(r.dispatch("GET", "/api/books?page=2").body()); // books page 2
    }
}