Router Package

Overview

The rivaas.dev/router package provides a high-performance HTTP router with comprehensive features:

• Radix tree routing with bloom filters
• Compiled route tables for performance
• Built-in middleware support
• Request binding and validation
• OpenTelemetry native tracing
• API versioning
• Content negotiation

Package Structure

rivaas.dev/router/
├── router.go          # Core router and route registration
├── context.go         # Request context with pooling
├── route.go           # Route definitions and constraints
├── middleware/        # Built-in middleware
│   ├── accesslog/    # Structured access logging
│   ├── cors/         # CORS handling
│   ├── recovery/     # Panic recovery
│   └── ...           # More middleware
└── ...

Quick API Index

Core Types

• Router - Main router type
• Context - Request context
• Route - Route definition
• Group - Route group

Route Registration

• HTTP Methods: GET(), POST(), PUT(), DELETE(), PATCH(), OPTIONS(), HEAD()
• Route Groups: Group(prefix), Version(version)
• Middleware: Use(middleware...)
• Static Files: Static(), StaticFile(), StaticFS()

Request Handling

• Parameters: Param(), Query(), PostForm()
• Headers: Header(), GetHeader()
• Cookies: Cookie(), SetCookie()

Response Rendering

• JSON: JSON(), PureJSON(), IndentedJSON(), SecureJSON()
• Other: YAML(), String(), HTML(), Data()
• Files: ServeFile(), Download(), DataFromReader()

Configuration

• Router Options: See Options
• Route Constraints: See Route Constraints
• Middleware Options: See Middleware

Performance

Routing Performance

• Sub-microsecond routing: 119ns per operation
• High throughput: 8.4M+ requests/second
• Memory efficient: 16 bytes per request, 1 allocation
• Context pooling: Automatic context reuse
• Lock-free operations: Atomic operations for concurrent access

Optimization Features

• Compiled routes: Pre-compiled routes for static and dynamic paths
• Bloom filters: Fast negative lookups for static routes
• First-segment index: ASCII-only route narrowing (O(1) lookup)
• Parameter storage: Array-based for ≤8 params, map for >8
• Type caching: Reflection information cached per struct type

Thread Safety

All router operations are concurrent-safe:

• Route registration can occur from multiple goroutines
• Route trees use atomic operations for concurrent access
• Context pooling is thread-safe
• Middleware execution is goroutine-safe

Next Steps

• API Reference: See detailed API documentation
• Context API: Check Context methods
• Options: Review Router options
• Constraints: Learn about route constraints
• Troubleshooting: See common issues

External Links

• pkg.go.dev: rivaas.dev/router
• Source Code: GitHub
• Examples: Router Examples