Architecture

The router is designed as a lightweight HTTP routing layer built around Go’s standard net/http ecosystem.

Its architecture focuses on:

• fast route lookup
• predictable middleware execution
• low per-request overhead
• standard net/http compatibility
• explicit application behavior
• reusable request context handling

High-Level Flow

At a high level, each request goes through the following steps:

incoming HTTP request
↓
route lookup
↓
middleware chain
↓
handler execution
↓
response
↓
context cleanup

Routing Tree

Routes are stored internally in a radix-tree based structure.

This allows efficient matching for:

• static routes
• parameterized routes
• wildcard routes
• mounted handlers
• grouped route prefixes

Static routes can be resolved directly, while dynamic routes are matched through the routing tree.

Method Matching

HTTP methods are matched using internal bitmasks.

This allows the router to efficiently support routes with one or more HTTP methods:

r.HandleFunc("/documents", "GET POST", handler)

Instead of repeatedly comparing method strings at runtime, supported methods are converted into compact method masks during route registration.

Middleware Pipeline

Middleware is composed as a lightweight wrapping chain.

middleware
↓
middleware
↓
handler

Middleware can be registered globally:

r.Use(router.RequestID())

or on route groups:

api.Use(AuthMiddleware)

This keeps middleware behavior explicit and predictable.

Request Context

Each router-native handler receives a *router.Context.

func(w http.ResponseWriter, req *http.Request, ctx *router.Context)

The context provides:

• route parameters
• request-scoped storage
• middleware-to-handler communication

Contexts are reused internally to reduce per-request allocations.

Standard Library Compatibility

The router works directly with Go’s standard HTTP interfaces.

It supports router-native handlers:

func(w http.ResponseWriter, req *http.Request, ctx *router.Context)

and standard net/http handlers through mounting:

r.Mount("/metrics", promhttp.Handler())

This allows applications to integrate existing Go libraries without adapter-heavy designs.

Logging and Observability

The router uses Go’s standard log/slog ecosystem.

It does not configure logging automatically.

Instead, applications can decide which handler to use, where logs should be written, and whether request logging should be enabled.

Request logging is opt-in:

r.Use(router.Logger())

Design Principles

The router follows a few core principles:

• explicit configuration
• standard library compatibility
• predictable runtime behavior
• low allocation routing
• middleware as composition
• no hidden global behavior
• simple integration with existing Go services

Notes

The router is intentionally focused on HTTP routing and request handling.

Features such as logging, file rotation, TLS termination, metrics collection, and application-specific dependencies remain explicit so applications can choose the infrastructure that fits their deployment model.