Performance

The router package is designed for low-latency HTTP workloads and high request throughput.

The routing engine focuses on:

• zero-allocation route matching
• optimized radix-tree traversal
• low-overhead middleware execution
• minimized lock contention
• pooled request context reuse
• efficient HTTP method matching

The goal is predictable request handling performance without unnecessary abstraction overhead.

Benchmark Results

Benchmarks executed on:

Apple M2 Max
Go 1.25
darwin/arm64

Example benchmark results:

Benchmark_NLG_StaticMatch                 21.04 ns/op     0 B/op     0 allocs/op
Benchmark_NLG_Wildcard                    36.18 ns/op     0 B/op     0 allocs/op
Benchmark_NLG_Param_1                     28.30 ns/op     0 B/op     0 allocs/op
Benchmark_NLG_Param_4                     44.80 ns/op     0 B/op     0 allocs/op
Benchmark_NLG_Param_7                     62.35 ns/op     0 B/op     0 allocs/op
Benchmark_NLG_Param_50                   329.8 ns/op      0 B/op     0 allocs/op
Benchmark_NLG_NotFound                    25.60 ns/op     0 B/op     0 allocs/op
Benchmark_NLG_Router_Lookup_Bitmask       25.16 ns/op     0 B/op     0 allocs/op

These benchmarks include:

• static routes
• parameterized routes
• wildcard routes
• large route trees
• route lookup operations

Zero Allocation Routing

Static route matching performs with:

0 B/op
0 allocs/op

This reduces:

• garbage collector pressure
• latency spikes
• memory churn
• allocation overhead under load

The router avoids unnecessary allocations during route lookup and parameter extraction.

Radix Tree Routing

Routes are internally stored in a radix-tree structure.

This allows efficient lookup for:

• static routes
• parameterized routes
• wildcard branches
• grouped routes

The router prioritizes:

1. static routes
2. parameterized routes
3. wildcard routes

to keep matching predictable and fast.

Fast Pattern Matchers

Prepared pattern matchers are implemented as direct Go functions instead of full regular expressions.

Example:

/users/{id:isDigits}

instead of:

/users/{id:(\\d+)}

This reduces the overhead of regexp evaluation while keeping route validation readable.

Prepared matchers are optimized for common route patterns such as:

• IDs
• UUIDs
• slugs
• dates
• safe paths
• hexadecimal values

Context Pooling

Request contexts are internally pooled and reused between requests.

This minimizes allocations for:

• parameter storage
• request-scoped values
• middleware communication

Pooling is automatic and fully transparent to applications.

HTTP Method Bitmasking

HTTP methods are internally represented using bitmasks.

This allows fast method matching without repeated string comparisons.

Example:

r.HandleFunc("/users", "GET POST PUT", handler)

Method matching remains efficient even when multiple methods are registered on the same route.

Middleware Performance

Middleware execution uses a lightweight wrapping chain:

middleware -> middleware -> handler

The middleware pipeline avoids reflection and runtime dispatching overhead.

This keeps per-request middleware execution predictable and efficient.

Wildcard Performance

Wildcard routes are optimized for branch-style matching.

Example:

/files/*

Wildcards are intended for:

• static assets
• frontend SPAs
• mounted services
• reverse proxies

while still maintaining low lookup overhead.

Benchmarking

Run benchmarks locally:

go test -bench=. -benchmem

Example:

Benchmark_NLG_StaticMatch    21.04 ns/op    0 allocs/op

Use benchmarks to evaluate route complexity, middleware overhead, and application-specific workloads.

Design Goals

The router is designed around several core principles:

• low allocations
• predictable routing behavior
• standard library compatibility
• explicit middleware composition
• efficient route matching
• production-ready concurrency safety

The focus is long-term maintainability and operational simplicity rather than framework abstraction layers.

Notes

Benchmark results vary depending on:

• CPU architecture
• Go version
• route complexity
• middleware stack
• request patterns

Always benchmark using realistic application workloads before making performance assumptions.