2nd/10_Wiki/Topics/Architecture/Router_Implementation.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-router-implementation	Router Implementation	10_Wiki/Topics	verified	self	URL Router HTTP Router Trie Router	none	A	0.88	applied	router http frontend backend data-structure		2026-05-10	pending	language framework TypeScript/Go Hono/Express/React Router

Router Implementation

매 한 줄

"매 URL/path → handler 의 매칭을 최대한 효율적으로 dispatch". Web framework 의 가장 hot path 중 하나. 매 핵심 자료구조: linear array (Express, ~O(N)) → radix trie (httprouter, fastify) → static-first matcher (Hono RegExpRouter, 2023, O(1)). 매 frontend (React Router 7, TanStack Router) 도 같은 algorithm 을 client-side 에서 재현 + nested layout/loader 추가.

매 핵심

매 router 의 책임

• Path matching (static, param, wildcard, regex).
• Method dispatch (GET/POST/...).
• Middleware composition.
• Param extraction + type coercion (TanStack Router 의 zod 연동).
• 404 / 405 / OPTIONS 자동 처리.

매 자료구조 비교

• Linear: 매 Express — pattern 배열을 순회. O(N), N=route 수.
• Radix trie: 매 httprouter, fastify — prefix 공유로 O(L), L=path length. 매 backtracking 처리 복잡.
• RegExp 합성: 매 Hono RegExpRouter — 매 모든 route 를 single big regex 로 compile, O(1) match.
• Static map + dynamic trie: 매 hybrid — 매 static path 는 hashmap, 매 param path 는 trie.

매 응용

1. Hono RegExpRouter (Cloudflare Workers).
2. React Router 7 nested route + data loader.
3. TanStack Router file-based + typed search params.
4. Next.js App Router (file convention + nested layout).

💻 패턴

매 simplest: linear matcher (TS)

type Handler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
type Route = { method: string; pattern: RegExp; keys: string[]; handler: Handler };

const routes: Route[] = [];

function add(method: string, path: string, handler: Handler) {
  const keys: string[] = [];
  const pattern = new RegExp(
    '^' + path.replace(/:([a-zA-Z]+)/g, (_, k) => { keys.push(k); return '([^/]+)'; }) + '$',
  );
  routes.push({ method, pattern, keys, handler });
}

function dispatch(req: Request): Promise<Response> {
  const url = new URL(req.url);
  for (const r of routes) {
    if (r.method !== req.method) continue;
    const m = url.pathname.match(r.pattern);
    if (!m) continue;
    const params = Object.fromEntries(r.keys.map((k, i) => [k, m[i + 1]]));
    return Promise.resolve(r.handler(req, params));
  }
  return Promise.resolve(new Response('Not Found', { status: 404 }));
}

Radix trie node (TS)

type Node = {
  children: Map<string, Node>; // static segment
  param?: { name: string; child: Node };
  wildcard?: Node;
  handlers: Map<string, Handler>;
};

function insert(root: Node, method: string, path: string, h: Handler) {
  const segs = path.split('/').filter(Boolean);
  let n = root;
  for (const s of segs) {
    if (s.startsWith(':')) {
      n.param ??= { name: s.slice(1), child: emptyNode() };
      n = n.param.child;
    } else if (s === '*') {
      n.wildcard ??= emptyNode();
      n = n.wildcard;
    } else {
      let c = n.children.get(s);
      if (!c) { c = emptyNode(); n.children.set(s, c); }
      n = c;
    }
  }
  n.handlers.set(method, h);
}

function emptyNode(): Node {
  return { children: new Map(), handlers: new Map() };
}

Trie lookup

function find(root: Node, method: string, path: string)
  : { handler: Handler; params: Record<string, string> } | null {
  const segs = path.split('/').filter(Boolean);
  const params: Record<string, string> = {};
  let n = root;
  for (const s of segs) {
    const c = n.children.get(s);
    if (c) { n = c; continue; }
    if (n.param) { params[n.param.name] = s; n = n.param.child; continue; }
    if (n.wildcard) { n = n.wildcard; break; }
    return null;
  }
  const handler = n.handlers.get(method);
  return handler ? { handler, params } : null;
}

Hono-style RegExpRouter (compile-once)

// 매 모든 route 를 단일 alternation regex 로 build
// /users/:id  →  ^\/users\/([^/]+)$  (group 1 = id, route index = 0)
// /posts/:id  →  ^\/posts\/([^/]+)$  (group 1 = id, route index = 1)
// merged:     ^(?:\/users\/([^/]+)|\/posts\/([^/]+))$

class RegExpRouter {
  private routes: { handler: Handler; keys: string[] }[] = [];
  private re?: RegExp;

  add(path: string, handler: Handler) {
    const keys: string[] = [];
    const pat = path.replace(/:([a-zA-Z]+)/g, (_, k) => { keys.push(k); return '([^/]+)'; });
    this.routes.push({ handler, keys });
    return pat;
  }

  build(patterns: string[]) {
    this.re = new RegExp('^(?:' + patterns.map(p => `(${p})`).join('|') + ')$');
  }

  match(path: string) {
    const m = this.re!.exec(path);
    if (!m) return null;
    // 매 어떤 alternative 가 hit 했는지 — group index 로 식별
    const idx = m.findIndex((g, i) => i > 0 && g !== undefined && i % 2 === 1);
    // (단순화 — 실제 Hono 는 grouping 인덱스를 정교하게 관리)
    return { route: this.routes[idx / 2 | 0] };
  }
}

Go: net/http 1.22+ pattern matching

// 매 Go 1.22 (2024) 부터 method + path pattern 내장
mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    fmt.Fprintf(w, "user %s", id)
})
mux.HandleFunc("POST /users", createUser)
http.ListenAndServe(":8080", mux)

React Router 7 (data router + loader)

import { createBrowserRouter, RouterProvider } from 'react-router';

const router = createBrowserRouter([
  {
    path: '/',
    Component: RootLayout,
    children: [
      { index: true, Component: Home },
      {
        path: 'users/:id',
        loader: async ({ params }) => fetch(`/api/users/${params.id}`).then(r => r.json()),
        Component: UserPage,
      },
    ],
  },
]);

export default () => <RouterProvider router={router} />;

TanStack Router (typed)

import { createRoute, createRouter } from '@tanstack/react-router';
import { z } from 'zod';

const userRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/users/$id',
  validateSearch: z.object({ tab: z.enum(['profile', 'orders']).default('profile') }),
  loader: ({ params }) => fetch(`/api/users/${params.id}`).then(r => r.json()),
  component: UserPage,
});
// 매 params + search 모두 type-safe

Trailing-slash + 405 normalization

function normalize(path: string) {
  if (path.length > 1 && path.endsWith('/')) return path.slice(0, -1);
  return path;
}
// 405: path 는 hit 하나 method 가 없을 때
// → Allow header 에 등록된 method 들을 응답

매 결정 기준

상황	Approach
Edge runtime (Workers, Deno)	Hono RegExpRouter — cold start O(1)
Node monolith	Fastify (radix trie)
Go service	net/http 1.22 또는 chi
Static-heavy (mostly fixed paths)	Hashmap + fallback trie
SPA	React Router 7 또는 TanStack Router
Type-safe params + search	TanStack Router
File convention	Next.js App / Remix / TanStack Start

기본값: 매 backend — radix trie (Hono/Fastify). 매 frontend — TanStack Router (typed) 또는 React Router 7.

🔗 Graph

• 부모: HTTP · Web Framework · Trie
• 변형: Radix Trie Router · RegExp Router · File-based Router
• 응용: Hono · Fastify · React Router · TanStack Router · Next.js App Router
• Adjacent: Middleware · Reverse Proxy · Service Mesh

🤖 LLM 활용

언제: 매 router algorithm 학습, 매 small framework 작성, 매 path-matching DSL 설계. 언제 X: 매 production framework 직접 구현 — 매 edge case (UTF-8, percent-decode, security) 가 매 무궁무진. Hono/Fastify/React Router 사용.

❌ 안티패턴

• Linear scan at scale: 매 1000+ route — Express 의 약점.
• Regex DOS: 매 사용자 input 을 path pattern 으로 — ReDoS.
• Param shadowing: 매 /:id vs /users 우선순위 모호 — static 우선.
• No 405 / Allow: 매 매칭은 되나 method 없을 때 404 (incorrect — should be 405).
• Router 가 business logic 보유: 매 router 는 dispatch 만, handler 가 logic.
• Untyped params: 매 frontend 에서 매 params.id 가 any — TanStack 의 typed router 사용.

🧪 검증 / 중복

• Verified: Hono RegExpRouter benchmark (yusukebe.com 2023), httprouter (julienschmidt 2014), Go 1.22 release notes (2024), React Router v7 docs (2025).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — linear/trie/regexp + Go 1.22 + React Router 7 + TanStack