Compare commits

...

4 Commits

Author SHA1 Message Date
abf169abeb fix documentation 2025-05-07 12:30:52 -05:00
e4abb99df9 param slice buffer 2025-04-26 18:34:00 -05:00
5be8eac6d8 cleanup 2025-04-26 17:38:17 -05:00
9dbfbee993 Fix handler visibility 2025-04-26 16:56:05 -05:00
5 changed files with 681 additions and 365 deletions

155
DOCS.md Normal file
View File

@ -0,0 +1,155 @@
# Router Package Documentation
A fast, lightweight HTTP router for Go with support for middleware, route groups, and path parameters.
## Core Types
### Router
Main router that implements `http.Handler`.
```go
router := router.New()
```
### Handler
Request handler function type.
```go
type Handler func(w http.ResponseWriter, r *http.Request, params []string)
```
### Middleware
Function type for middleware.
```go
type Middleware func(Handler) Handler
```
### Group
Route group with a prefix.
```go
group := router.Group("/api")
```
## Router Methods
### New()
Creates a new router.
```go
router := router.New()
```
### ServeHTTP(w, r)
Implements `http.Handler` interface.
### Use(mw ...Middleware)
Adds global middleware.
```go
router.Use(loggingMiddleware, authMiddleware)
```
### Handle(method, path, handler)
Registers a handler for the given method and path.
```go
router.Handle("GET", "/users", listUsersHandler)
```
### HTTP Method Shortcuts
```go
router.Get("/users", listUsersHandler)
router.Post("/users", createUserHandler)
router.Put("/users/[id]", updateUserHandler)
router.Patch("/users/[id]", patchUserHandler)
router.Delete("/users/[id]", deleteUserHandler)
```
### Group(prefix)
Creates a route group with prefix.
```go
api := router.Group("/api")
```
### WithMiddleware(mw ...Middleware)
Applies middleware to the next route registration.
```go
router.WithMiddleware(authMiddleware).Get("/admin", adminHandler)
```
## Group Methods
### Use(mw ...Middleware)
Adds middleware to the group.
```go
api.Use(apiKeyMiddleware)
```
### Group(prefix)
Creates a nested group.
```go
v1 := api.Group("/v1")
```
### HTTP Method Shortcuts
```go
api.Get("/users", listUsersHandler)
api.Post("/users", createUserHandler)
api.Put("/users/[id]", updateUserHandler)
api.Patch("/users/[id]", patchUserHandler)
api.Delete("/users/[id]", deleteUserHandler)
```
### WithMiddleware(mw ...Middleware)
Applies middleware to the next route registration in this group.
```go
api.WithMiddleware(authMiddleware).Get("/admin", adminHandler)
```
## Path Parameters
Dynamic segments in paths are defined using square brackets.
```go
router.Get("/users/[id]", func(w http.ResponseWriter, r *http.Request, params []string) {
id := params[0]
// ...
})
```
## Wildcards
Wildcard segments capture all remaining path segments.
```go
router.Get("/files/*path", func(w http.ResponseWriter, r *http.Request, params []string) {
path := params[0]
// ...
})
```
Notes:
- Wildcards must be the last segment in a path
- Only one wildcard is allowed per path

276
EXAMPLES.md Normal file
View File

@ -0,0 +1,276 @@
# Examples
## Basic Usage
```go
package main
import (
"fmt"
"net/http"
"github.com/yourusername/router"
)
func main() {
r := router.New()
r.Get("/", func(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "Hello World!")
})
r.Get("/about", func(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "About page")
})
http.ListenAndServe(":8080", r)
}
```
## Path Parameters
```go
r := router.New()
// Single parameter
r.Get("/users/[id]", func(w http.ResponseWriter, r *http.Request, params []string) {
id := params[0]
fmt.Fprintf(w, "User ID: %s", id)
})
// Multiple parameters
r.Get("/posts/[category]/[id]", func(w http.ResponseWriter, r *http.Request, params []string) {
category := params[0]
id := params[1]
fmt.Fprintf(w, "Category: %s, Post ID: %s", category, id)
})
// Wildcard
r.Get("/files/*path", func(w http.ResponseWriter, r *http.Request, params []string) {
path := params[0]
fmt.Fprintf(w, "File path: %s", path)
})
```
## Middleware
```go
// Logging middleware
func LoggingMiddleware(next router.Handler) router.Handler {
return router.Handler(func(w http.ResponseWriter, r *http.Request, params []string) {
fmt.Printf("[%s] %s\n", r.Method, r.URL.Path)
next(w, r, params)
})
}
// Auth middleware
func AuthMiddleware(next router.Handler) router.Handler {
return router.Handler(func(w http.ResponseWriter, r *http.Request, params []string) {
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
next(w, r, params)
})
}
// Global middleware
r := router.New()
r.Use(LoggingMiddleware)
// Route-specific middleware
r.WithMiddleware(AuthMiddleware).Get("/admin", adminHandler)
```
## Route Groups
```go
r := router.New()
// API group
api := r.Group("/api")
api.Get("/status", statusHandler)
// Versioned API
v1 := api.Group("/v1")
v1.Get("/users", listUsersHandler)
v1.Post("/users", createUserHandler)
v2 := api.Group("/v2")
v2.Get("/users", listUsersV2Handler)
```
## Combining Features
```go
r := router.New()
// Global middleware
r.Use(LoggingMiddleware)
// API group with middleware
api := r.Group("/api")
api.Use(ApiKeyMiddleware)
// Admin group with auth middleware
admin := r.Group("/admin")
admin.Use(AuthMiddleware)
// Users endpoints with versioning
users := api.Group("/v1/users")
users.Get("/", listUsersHandler)
users.Post("/", createUserHandler)
users.Get("/[id]", getUserHandler)
users.Put("/[id]", updateUserHandler)
users.Delete("/[id]", deleteUserHandler)
// Special case with route-specific middleware
api.WithMiddleware(CacheMiddleware).Get("/cached-resource", cachedResourceHandler)
```
## Error Handling
```go
r := router.New()
err := r.Get("/users/[id]", getUserHandler)
if err != nil {
// Handle error
}
// Custom NotFound handler
oldServeHTTP := r.ServeHTTP
r.ServeHTTP = func(w http.ResponseWriter, req *http.Request) {
h, params, ok := r.Lookup(req.Method, req.URL.Path)
if !ok {
// Custom 404 handler
w.WriteHeader(http.StatusNotFound)
fmt.Fprintf(w, "Custom 404: %s not found", req.URL.Path)
return
}
h(w, req, params)
}
```
## Complete Application Example
```go
package main
import (
"fmt"
"log"
"net/http"
"github.com/yourusername/router"
)
func main() {
r := router.New()
// Global middleware
r.Use(LoggingMiddleware)
// Basic routes
r.Get("/", homeHandler)
r.Get("/about", aboutHandler)
// API routes
api := r.Group("/api")
api.Use(ApiKeyMiddleware)
// Users API
users := api.Group("/users")
users.Get("/", listUsersHandler)
users.Post("/", createUserHandler)
users.Get("/[id]", getUserHandler)
users.Put("/[id]", updateUserHandler)
users.Delete("/[id]", deleteUserHandler)
// Admin routes with auth
admin := r.Group("/admin")
admin.Use(AuthMiddleware)
admin.Get("/", adminDashboardHandler)
admin.Get("/users", adminUsersHandler)
// Start server
log.Println("Server starting on :8080")
log.Fatal(http.ListenAndServe(":8080", r))
}
// Handlers
func homeHandler(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "Welcome to the home page")
}
func aboutHandler(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "About us")
}
func listUsersHandler(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "List of users")
}
func getUserHandler(w http.ResponseWriter, r *http.Request, params []string) {
id := params[0]
fmt.Fprintf(w, "User details for ID: %s", id)
}
func createUserHandler(w http.ResponseWriter, r *http.Request, _ []string) {
// Parse form data or JSON body
fmt.Fprintf(w, "User created")
}
func updateUserHandler(w http.ResponseWriter, r *http.Request, params []string) {
id := params[0]
fmt.Fprintf(w, "User updated: %s", id)
}
func deleteUserHandler(w http.ResponseWriter, r *http.Request, params []string) {
id := params[0]
fmt.Fprintf(w, "User deleted: %s", id)
}
func adminDashboardHandler(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "Admin Dashboard")
}
func adminUsersHandler(w http.ResponseWriter, r *http.Request, _ []string) {
fmt.Fprintf(w, "Admin Users Management")
}
// Middleware
func LoggingMiddleware(next router.Handler) router.Handler {
return router.Handler(func(w http.ResponseWriter, r *http.Request, params []string) {
log.Printf("[%s] %s", r.Method, r.URL.Path)
next(w, r, params)
})
}
func ApiKeyMiddleware(next router.Handler) router.Handler {
return router.Handler(func(w http.ResponseWriter, r *http.Request, params []string) {
apiKey := r.Header.Get("X-API-Key")
if apiKey == "" {
http.Error(w, "API key required", http.StatusUnauthorized)
return
}
next(w, r, params)
})
}
func AuthMiddleware(next router.Handler) router.Handler {
return router.Handler(func(w http.ResponseWriter, r *http.Request, params []string) {
// Check session or JWT
authorized := checkUserAuth(r)
if !authorized {
http.Redirect(w, r, "/login", http.StatusSeeOther)
return
}
next(w, r, params)
})
}
func checkUserAuth(r *http.Request) bool {
// Implementation of auth check
return r.Header.Get("Authorization") != ""
}
```

View File

@ -43,14 +43,9 @@ r.Get("/files/*path", func(w router.Res, r router.Req, params []string) {
fmt.Fprintf(w, "File path: %s", filePath)
})
// Standard http.HandlerFunc adapter
r.Get("/simple", router.StandardHandler(func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Simple handler without params")
}))
// Lookup routes manually
if handler, params, ok := r.Lookup("GET", "/users/123"); ok {
handler.Serve(params)
handler(nil, nil, params)
}
// Or simply serve them
@ -62,13 +57,11 @@ http.ListenAndServe(":8080", r)
```go
// Create logging middleware
func LoggingMiddleware(next router.Handler) router.Handler {
return &router.simpleHandler{
fn: func(params []string) {
fmt.Println("Request started")
next.Serve(params)
fmt.Println("Request completed")
},
}
return router.Handler(func(w router.Res, r router.Req, params []string) {
fmt.Println("Request started")
next(w, r, params)
fmt.Println("Request completed")
})
}
// Apply middleware globally
@ -108,29 +101,29 @@ http.ListenAndServe(":8080", r)
Benchmark comparing Router to the standard `http.ServeMux`:
```
cpu: AMD Ryzen 9 7950X 16-Core Processor
cpu: 13th Gen Intel(R) Core(TM) i7-1370P
BenchmarkComparison/root_path
Router: 2.098 ns/op 0 B/op 0 allocs/op
ServeMux: 32.010 ns/op 0 B/op 0 allocs/op
Router: 1.798 ns/op 0 B/op 0 allocs/op
ServeMux: 40.98 ns/op 0 B/op 0 allocs/op
BenchmarkComparison/static_path
Router: 16.050 ns/op 0 B/op 0 allocs/op
ServeMux: 67.980 ns/op 0 B/op 0 allocs/op
Router: 18.41 ns/op 0 B/op 0 allocs/op
ServeMux: 86.04 ns/op 0 B/op 0 allocs/op
BenchmarkComparison/dynamic_path
Router: 39.170 ns/op 16 B/op 1 allocs/op
ServeMux: 174.000 ns/op 48 B/op 3 allocs/op
Router: 24.23 ns/op 0 B/op 0 allocs/op
ServeMux: 221.9 ns/op 48 B/op 3 allocs/op
BenchmarkComparison/not_found
Router: 10.580 ns/op 0 B/op 0 allocs/op
ServeMux: 178.100 ns/op 56 B/op 3 allocs/op
Router: 10.76 ns/op 0 B/op 0 allocs/op
ServeMux: 210.2 ns/op 56 B/op 3 allocs/op
```
- Root path lookups are 15x faster
- Static paths are 4x faster with zero allocations
- Dynamic paths are 4.4x faster with fewer allocations
- Not found paths are 16.8x faster with zero allocations
- Root path lookups are 22x faster
- Static paths are 4.7x faster with zero allocations
- Dynamic paths are 9x faster with zero allocations
- Not found paths are 19.5x faster with zero allocations
## License

450
router.go
View File

@ -3,44 +3,36 @@ package router
import (
"fmt"
"net/http"
"slices"
)
// Res is an alias for http.ResponseWriter for shorter, cleaner code
type Res = http.ResponseWriter
// Req is an alias for *http.Request for shorter, cleaner code
type Req = *http.Request
// Handler is an interface for handling HTTP requests with path parameters.
type Handler interface {
Serve(params []string)
// Handler is a request handler with parameters.
type Handler func(w Res, r Req, params []string)
func (h Handler) Serve(w Res, r Req, params []string) {
h(w, r, params)
}
// Middleware wraps a handler with additional functionality.
type Middleware func(Handler) Handler
// node represents a segment in the URL path and its handling logic.
type node struct {
segment string // the path segment this node matches
handler Handler // handler for this path, if it's an endpoint
children []*node // child nodes for subsequent path segments
isDynamic bool // true for param segments like [id]
isWildcard bool // true for catch-all segments like *filepath
maxParams uint8 // maximum number of parameters in paths under this node
segment string
handler Handler
children []*node
isDynamic bool
isWildcard bool
maxParams uint8
}
// Router routes HTTP requests by method and path.
// It supports static paths, path parameters, wildcards, and middleware.
type Router struct {
get *node
post *node
put *node
patch *node
delete *node
middleware []Middleware // Global middleware
get, post, put, patch, delete *node
middleware []Middleware
paramsBuffer []string
}
// Group represents a route group with a path prefix and shared middleware.
type Group struct {
router *Router
prefix string
@ -50,99 +42,65 @@ type Group struct {
// New creates a new Router instance.
func New() *Router {
return &Router{
get: &node{},
post: &node{},
put: &node{},
patch: &node{},
delete: &node{},
middleware: []Middleware{},
get: &node{},
post: &node{},
put: &node{},
patch: &node{},
delete: &node{},
middleware: []Middleware{},
paramsBuffer: make([]string, 64),
}
}
// ServeHTTP implements http.Handler interface
// ServeHTTP implements http.Handler.
func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request) {
handler, params, found := r.Lookup(req.Method, req.URL.Path)
if !found {
h, params, ok := r.Lookup(req.Method, req.URL.Path)
if !ok {
http.NotFound(w, req)
return
}
// Create an HTTP-specific handler wrapper
httpHandler := &httpHandler{
w: w,
r: req,
h: func(w http.ResponseWriter, r *http.Request, params []string) {
handler.Serve(params)
},
}
httpHandler.Serve(params)
h(w, req, params)
}
// httpHandler adapts net/http handlers to the router.
type httpHandler struct {
w Res
r Req
h func(w Res, r Req, params []string)
}
// Serve executes the http handler with parameters.
func (h *httpHandler) Serve(params []string) {
h.h(h.w, h.r, params)
}
// Use adds middleware to the router's global middleware stack.
func (r *Router) Use(middleware ...Middleware) *Router {
r.middleware = append(r.middleware, middleware...)
// Use adds middleware to the router.
func (r *Router) Use(mw ...Middleware) *Router {
r.middleware = append(r.middleware, mw...)
return r
}
// Group creates a new route group with the given path prefix.
// Group creates a new route group.
func (r *Router) Group(prefix string) *Group {
return &Group{
router: r,
prefix: prefix,
middleware: []Middleware{},
}
return &Group{router: r, prefix: prefix, middleware: []Middleware{}}
}
// Use adds middleware to the group's middleware stack.
func (g *Group) Use(middleware ...Middleware) *Group {
g.middleware = append(g.middleware, middleware...)
// Use adds middleware to the group.
func (g *Group) Use(mw ...Middleware) *Group {
g.middleware = append(g.middleware, mw...)
return g
}
// Group creates a nested group with an additional prefix.
// Group creates a nested group.
func (g *Group) Group(prefix string) *Group {
return &Group{
router: g.router,
prefix: g.prefix + prefix,
middleware: append([]Middleware{}, g.middleware...),
}
return &Group{router: g.router, prefix: g.prefix + prefix, middleware: slices.Clone(g.middleware)}
}
// applyMiddleware wraps a handler with middleware in reverse order.
func applyMiddleware(handler Handler, middleware []Middleware) Handler {
h := handler
for i := len(middleware) - 1; i >= 0; i-- {
h = middleware[i](h)
// applyMiddleware applies middleware in reverse order.
func applyMiddleware(h Handler, mw []Middleware) Handler {
for i := len(mw) - 1; i >= 0; i-- {
h = mw[i](h)
}
return h
}
// HandlerFunc is a function that handles HTTP requests with parameters.
type HandlerFunc func(w http.ResponseWriter, r *http.Request, params []string)
// Handle registers a handler for the given method and path.
func (r *Router) Handle(method, path string, handler HandlerFunc) error {
func (r *Router) Handle(method, path string, h Handler) error {
root := r.methodNode(method)
if root == nil {
return fmt.Errorf("unsupported method: %s", method)
}
return r.addRoute(root, path, &httpHandler{h: handler}, r.middleware)
return r.addRoute(root, path, h, r.middleware)
}
// methodNode returns the root node for the given HTTP method.
func (r *Router) methodNode(method string) *node {
switch method {
case "GET":
@ -160,335 +118,295 @@ func (r *Router) methodNode(method string) *node {
}
}
// Get registers a handler for GET requests at the given path.
func (r *Router) Get(path string, handler HandlerFunc) error {
return r.Handle("GET", path, handler)
// Get registers a GET handler.
func (r *Router) Get(path string, h Handler) error {
return r.Handle("GET", path, h)
}
// Post registers a handler for POST requests at the given path.
func (r *Router) Post(path string, handler HandlerFunc) error {
return r.Handle("POST", path, handler)
// Post registers a POST handler.
func (r *Router) Post(path string, h Handler) error {
return r.Handle("POST", path, h)
}
// Put registers a handler for PUT requests at the given path.
func (r *Router) Put(path string, handler HandlerFunc) error {
return r.Handle("PUT", path, handler)
// Put registers a PUT handler.
func (r *Router) Put(path string, h Handler) error {
return r.Handle("PUT", path, h)
}
// Patch registers a handler for PATCH requests at the given path.
func (r *Router) Patch(path string, handler HandlerFunc) error {
return r.Handle("PATCH", path, handler)
// Patch registers a PATCH handler.
func (r *Router) Patch(path string, h Handler) error {
return r.Handle("PATCH", path, h)
}
// Delete registers a handler for DELETE requests at the given path.
func (r *Router) Delete(path string, handler HandlerFunc) error {
return r.Handle("DELETE", path, handler)
// Delete registers a DELETE handler.
func (r *Router) Delete(path string, h Handler) error {
return r.Handle("DELETE", path, h)
}
// buildGroupMiddleware returns combined middleware for the group
func (g *Group) buildGroupMiddleware() []Middleware {
middleware := append([]Middleware{}, g.router.middleware...)
return append(middleware, g.middleware...)
mw := slices.Clone(g.router.middleware)
return append(mw, g.middleware...)
}
// Handle registers a handler for the given method and path.
func (g *Group) Handle(method, path string, handler HandlerFunc) error {
// Handle registers a handler in the group.
func (g *Group) Handle(method, path string, h Handler) error {
root := g.router.methodNode(method)
if root == nil {
return fmt.Errorf("unsupported method: %s", method)
}
fullPath := g.prefix + path
return g.router.addRoute(root, fullPath, &httpHandler{h: handler}, g.buildGroupMiddleware())
return g.router.addRoute(root, g.prefix+path, h, g.buildGroupMiddleware())
}
// Get registers a handler for GET requests at the given path.
func (g *Group) Get(path string, handler HandlerFunc) error {
return g.Handle("GET", path, handler)
// Get registers a GET handler in the group.
func (g *Group) Get(path string, h Handler) error {
return g.Handle("GET", path, h)
}
// Post registers a handler for POST requests at the given path.
func (g *Group) Post(path string, handler HandlerFunc) error {
return g.Handle("POST", path, handler)
// Post registers a POST handler in the group.
func (g *Group) Post(path string, h Handler) error {
return g.Handle("POST", path, h)
}
// Put registers a handler for PUT requests at the given path.
func (g *Group) Put(path string, handler HandlerFunc) error {
return g.Handle("PUT", path, handler)
// Put registers a PUT handler in the group.
func (g *Group) Put(path string, h Handler) error {
return g.Handle("PUT", path, h)
}
// Patch registers a handler for PATCH requests at the given path.
func (g *Group) Patch(path string, handler HandlerFunc) error {
return g.Handle("PATCH", path, handler)
// Patch registers a PATCH handler in the group.
func (g *Group) Patch(path string, h Handler) error {
return g.Handle("PATCH", path, h)
}
// Delete registers a handler for DELETE requests at the given path.
func (g *Group) Delete(path string, handler HandlerFunc) error {
return g.Handle("DELETE", path, handler)
// Delete registers a DELETE handler in the group.
func (g *Group) Delete(path string, h Handler) error {
return g.Handle("DELETE", path, h)
}
// WithMiddleware applies specific middleware to the next route registration.
func (r *Router) WithMiddleware(middleware ...Middleware) *MiddlewareRouter {
return &MiddlewareRouter{
router: r,
middleware: middleware,
}
// WithMiddleware applies specific middleware for next registration.
func (r *Router) WithMiddleware(mw ...Middleware) *MiddlewareRouter {
return &MiddlewareRouter{router: r, middleware: mw}
}
// WithMiddleware applies specific middleware to the next route registration.
func (g *Group) WithMiddleware(middleware ...Middleware) *MiddlewareGroup {
return &MiddlewareGroup{
group: g,
middleware: middleware,
}
// WithMiddleware applies specific middleware for next group route.
func (g *Group) WithMiddleware(mw ...Middleware) *MiddlewareGroup {
return &MiddlewareGroup{group: g, middleware: mw}
}
// MiddlewareRouter handles route registration with specific middleware.
type MiddlewareRouter struct {
router *Router
middleware []Middleware
}
// MiddlewareGroup handles group route registration with specific middleware.
type MiddlewareGroup struct {
group *Group
middleware []Middleware
}
// buildMiddleware returns combined middleware for the middleware router
func (mr *MiddlewareRouter) buildMiddleware() []Middleware {
middleware := append([]Middleware{}, mr.router.middleware...)
return append(middleware, mr.middleware...)
mw := slices.Clone(mr.router.middleware)
return append(mw, mr.middleware...)
}
// Handle registers a handler for the given method and path.
func (mr *MiddlewareRouter) Handle(method, path string, handler HandlerFunc) error {
// Handle registers a handler with middleware router.
func (mr *MiddlewareRouter) Handle(method, path string, h Handler) error {
root := mr.router.methodNode(method)
if root == nil {
return fmt.Errorf("unsupported method: %s", method)
}
return mr.router.addRoute(root, path, &httpHandler{h: handler}, mr.buildMiddleware())
return mr.router.addRoute(root, path, h, mr.buildMiddleware())
}
// Get registers a handler for GET requests with specific middleware.
func (mr *MiddlewareRouter) Get(path string, handler HandlerFunc) error {
return mr.Handle("GET", path, handler)
// Get registers a GET handler with middleware router.
func (mr *MiddlewareRouter) Get(path string, h Handler) error {
return mr.Handle("GET", path, h)
}
// Post registers a handler for POST requests with specific middleware.
func (mr *MiddlewareRouter) Post(path string, handler HandlerFunc) error {
return mr.Handle("POST", path, handler)
// Post registers a POST handler with middleware router.
func (mr *MiddlewareRouter) Post(path string, h Handler) error {
return mr.Handle("POST", path, h)
}
// Put registers a handler for PUT requests with specific middleware.
func (mr *MiddlewareRouter) Put(path string, handler HandlerFunc) error {
return mr.Handle("PUT", path, handler)
// Put registers a PUT handler with middleware router.
func (mr *MiddlewareRouter) Put(path string, h Handler) error {
return mr.Handle("PUT", path, h)
}
// Patch registers a handler for PATCH requests with specific middleware.
func (mr *MiddlewareRouter) Patch(path string, handler HandlerFunc) error {
return mr.Handle("PATCH", path, handler)
// Patch registers a PATCH handler with middleware router.
func (mr *MiddlewareRouter) Patch(path string, h Handler) error {
return mr.Handle("PATCH", path, h)
}
// Delete registers a handler for DELETE requests with specific middleware.
func (mr *MiddlewareRouter) Delete(path string, handler HandlerFunc) error {
return mr.Handle("DELETE", path, handler)
// Delete registers a DELETE handler with middleware router.
func (mr *MiddlewareRouter) Delete(path string, h Handler) error {
return mr.Handle("DELETE", path, h)
}
// buildMiddleware returns combined middleware for the middleware group
func (mg *MiddlewareGroup) buildMiddleware() []Middleware {
middleware := append([]Middleware{}, mg.group.router.middleware...)
middleware = append(middleware, mg.group.middleware...)
return append(middleware, mg.middleware...)
mw := slices.Clone(mg.group.router.middleware)
mw = append(mw, mg.group.middleware...)
return append(mw, mg.middleware...)
}
// Handle registers a handler for the given method and path.
func (mg *MiddlewareGroup) Handle(method, path string, handler HandlerFunc) error {
// Handle registers a handler with middleware group.
func (mg *MiddlewareGroup) Handle(method, path string, h Handler) error {
root := mg.group.router.methodNode(method)
if root == nil {
return fmt.Errorf("unsupported method: %s", method)
}
fullPath := mg.group.prefix + path
return mg.group.router.addRoute(root, fullPath, &httpHandler{h: handler}, mg.buildMiddleware())
return mg.group.router.addRoute(root, mg.group.prefix+path, h, mg.buildMiddleware())
}
// Get registers a handler for GET requests with specific middleware.
func (mg *MiddlewareGroup) Get(path string, handler HandlerFunc) error {
return mg.Handle("GET", path, handler)
// Get registers a GET handler with middleware group.
func (mg *MiddlewareGroup) Get(path string, h Handler) error {
return mg.Handle("GET", path, h)
}
// Post registers a handler for POST requests with specific middleware.
func (mg *MiddlewareGroup) Post(path string, handler HandlerFunc) error {
return mg.Handle("POST", path, handler)
// Post registers a POST handler with middleware group.
func (mg *MiddlewareGroup) Post(path string, h Handler) error {
return mg.Handle("POST", path, h)
}
// Put registers a handler for PUT requests with specific middleware.
func (mg *MiddlewareGroup) Put(path string, handler HandlerFunc) error {
return mg.Handle("PUT", path, handler)
// Put registers a PUT handler with middleware group.
func (mg *MiddlewareGroup) Put(path string, h Handler) error {
return mg.Handle("PUT", path, h)
}
// Patch registers a handler for PATCH requests with specific middleware.
func (mg *MiddlewareGroup) Patch(path string, handler HandlerFunc) error {
return mg.Handle("PATCH", path, handler)
// Patch registers a PATCH handler with middleware group.
func (mg *MiddlewareGroup) Patch(path string, h Handler) error {
return mg.Handle("PATCH", path, h)
}
// Delete registers a handler for DELETE requests with specific middleware.
func (mg *MiddlewareGroup) Delete(path string, handler HandlerFunc) error {
return mg.Handle("DELETE", path, handler)
// Delete registers a DELETE handler with middleware group.
func (mg *MiddlewareGroup) Delete(path string, h Handler) error {
return mg.Handle("DELETE", path, h)
}
// Adapter for standard http.HandlerFunc
func StandardHandler(handler http.HandlerFunc) HandlerFunc {
return func(w http.ResponseWriter, r *http.Request, _ []string) {
handler(w, r)
}
}
// readSegment extracts the next path segment starting at the given position.
// Returns the segment, the position after it, and whether there are more segments.
// readSegment extracts the next path segment.
func readSegment(path string, start int) (segment string, end int, hasMore bool) {
if start >= len(path) {
return "", start, false
}
if path[start] == '/' {
start++
}
if start >= len(path) {
return "", start, false
}
end = start
for end < len(path) && path[end] != '/' {
end++
}
return path[start:end], end, end < len(path)
}
// addRoute adds a new route to the prefix tree with middleware.
func (r *Router) addRoute(root *node, path string, handler Handler, middleware []Middleware) error {
wrappedHandler := applyMiddleware(handler, middleware)
// addRoute adds a new route to the trie.
func (r *Router) addRoute(root *node, path string, h Handler, mw []Middleware) error {
h = applyMiddleware(h, mw)
if path == "/" {
root.handler = wrappedHandler
root.handler = h
return nil
}
current := root
pos := 0
var lastWildcard bool
paramsCount := uint8(0)
lastWC := false
count := uint8(0)
for {
segment, newPos, hasMore := readSegment(path, pos)
if segment == "" {
seg, newPos, more := readSegment(path, pos)
if seg == "" {
break
}
isDynamic := len(segment) > 2 && segment[0] == '[' && segment[len(segment)-1] == ']'
isWildcard := len(segment) > 0 && segment[0] == '*'
if isWildcard {
if lastWildcard {
isDyn := len(seg) > 2 && seg[0] == '[' && seg[len(seg)-1] == ']'
isWC := len(seg) > 0 && seg[0] == '*'
if isWC {
if lastWC || more {
return fmt.Errorf("wildcard must be the last segment in the path")
}
if hasMore {
return fmt.Errorf("wildcard must be the last segment in the path")
}
lastWildcard = true
lastWC = true
}
if isDynamic || isWildcard {
paramsCount++
if isDyn || isWC {
count++
}
var child *node
for _, n := range current.children {
if n.segment == segment {
child = n
for _, c := range current.children {
if c.segment == seg {
child = c
break
}
}
if child == nil {
child = &node{
segment: segment,
isDynamic: isDynamic,
isWildcard: isWildcard,
}
child = &node{segment: seg, isDynamic: isDyn, isWildcard: isWC}
current.children = append(current.children, child)
}
if child.maxParams < paramsCount {
child.maxParams = paramsCount
if child.maxParams < count {
child.maxParams = count
}
current = child
pos = newPos
}
current.handler = wrappedHandler
current.handler = h
return nil
}
// Lookup finds a handler matching the given method and path.
// Returns the handler, any captured parameters, and whether a match was found.
// Lookup finds a handler matching method and path.
func (r *Router) Lookup(method, path string) (Handler, []string, bool) {
root := r.methodNode(method)
if root == nil {
return nil, nil, false
}
if path == "/" {
return root.handler, []string{}, root.handler != nil
return root.handler, nil, root.handler != nil
}
params := make([]string, 0, root.maxParams)
h, found := match(root, path, 0, &params)
buffer := r.paramsBuffer
if cap(buffer) < int(root.maxParams) {
buffer = make([]string, root.maxParams)
r.paramsBuffer = buffer
}
buffer = buffer[:0]
h, paramCount, found := match(root, path, 0, &buffer)
if !found {
return nil, nil, false
}
return h, params, true
return h, buffer[:paramCount], true
}
// match recursively traverses the prefix tree to find a matching handler.
// It populates params with any captured path parameters or wildcard matches.
func match(current *node, path string, start int, params *[]string) (Handler, bool) {
// Check for wildcard children first
for _, child := range current.children {
if child.isWildcard {
remaining := path[start:]
if len(remaining) > 0 && remaining[0] == '/' {
remaining = remaining[1:]
// match traverses the trie to find a handler.
func match(current *node, path string, start int, params *[]string) (Handler, int, bool) {
paramCount := 0
for _, c := range current.children {
if c.isWildcard {
rem := path[start:]
if len(rem) > 0 && rem[0] == '/' {
rem = rem[1:]
}
*params = append(*params, remaining)
return child.handler, child.handler != nil
*params = append(*params, rem)
return c.handler, 1, c.handler != nil
}
}
// Read current segment
segment, pos, hasMore := readSegment(path, start)
if segment == "" {
return current.handler, current.handler != nil
seg, pos, more := readSegment(path, start)
if seg == "" {
return current.handler, 0, current.handler != nil
}
// Try to match children
for _, child := range current.children {
if child.segment == segment || child.isDynamic {
if child.isDynamic {
*params = append(*params, segment)
for _, c := range current.children {
if c.segment == seg || c.isDynamic {
if c.isDynamic {
*params = append(*params, seg)
paramCount++
}
if !hasMore {
return child.handler, child.handler != nil
if !more {
return c.handler, paramCount, c.handler != nil
}
if h, found := match(child, path, pos, params); found {
return h, true
h, nestedCount, ok := match(c, path, pos, params)
if ok {
return h, paramCount + nestedCount, true
}
}
}
return nil, false
return nil, 0, false
}

View File

@ -8,40 +8,20 @@ import (
assert "git.sharkk.net/Go/Assert"
)
// simpleHandler implements the Handler interface
type simpleHandler struct {
fn func(params []string)
}
func (h *simpleHandler) Serve(params []string) {
h.fn(params)
}
// newHandler creates a simple Handler from a function
func newHandler(fn func(params []string)) Handler {
return &simpleHandler{fn: fn}
}
func TestRootPath(t *testing.T) {
r := New()
r.Get("/", func(w Res, r Req, params []string) {
// No-op for testing
})
r.Get("/", func(w Res, r Req, params []string) {})
h, params, found := r.Lookup("GET", "/")
_, _, found := r.Lookup("GET", "/")
assert.True(t, found)
h.Serve(params)
}
func TestStaticPath(t *testing.T) {
r := New()
r.Get("/users/all", func(w Res, r Req, params []string) {
// No-op for testing
})
r.Get("/users/all", func(w Res, r Req, params []string) {})
h, params, found := r.Lookup("GET", "/users/all")
_, _, found := r.Lookup("GET", "/users/all")
assert.True(t, found)
h.Serve(params)
}
func TestSingleParameter(t *testing.T) {
@ -55,7 +35,7 @@ func TestSingleParameter(t *testing.T) {
h, params, found := r.Lookup("GET", "/users/123")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, called)
}
@ -71,15 +51,13 @@ func TestMultipleParameters(t *testing.T) {
h, params, found := r.Lookup("GET", "/users/123/posts/456")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, called)
}
func TestNonExistentPath(t *testing.T) {
r := New()
r.Get("/users/[id]", func(w Res, r Req, params []string) {
// No-op for testing
})
r.Get("/users/[id]", func(w Res, r Req, params []string) {})
_, _, found := r.Lookup("GET", "/posts/123")
assert.False(t, found)
@ -87,9 +65,7 @@ func TestNonExistentPath(t *testing.T) {
func TestWrongMethod(t *testing.T) {
r := New()
r.Get("/users/[id]", func(w Res, r Req, params []string) {
// No-op for testing
})
r.Get("/users/[id]", func(w Res, r Req, params []string) {})
_, _, found := r.Lookup("POST", "/users/123")
assert.False(t, found)
@ -106,7 +82,7 @@ func TestTrailingSlash(t *testing.T) {
h, params, found := r.Lookup("GET", "/users/123/")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, called)
}
@ -143,7 +119,7 @@ func TestWildcardPath(t *testing.T) {
h, params, found := r.Lookup("GET", "/files/docs/report.pdf")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, called)
})
@ -157,7 +133,7 @@ func TestWildcardPath(t *testing.T) {
h, params, found := r.Lookup("GET", "/download/")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, called)
})
@ -172,7 +148,7 @@ func TestWildcardPath(t *testing.T) {
h, params, found := r.Lookup("GET", "/users/123/settings/profile/avatar")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, called)
})
@ -192,13 +168,11 @@ func TestMiddleware(t *testing.T) {
t.Run("global middleware", func(t *testing.T) {
r := New()
// Track middleware execution
executed := false
r.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
executed = true
next.Serve(params)
next(w, r, params)
})
})
@ -206,7 +180,7 @@ func TestMiddleware(t *testing.T) {
h, params, found := r.Lookup("GET", "/test")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, executed)
})
@ -217,17 +191,17 @@ func TestMiddleware(t *testing.T) {
order := []int{}
r.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
order = append(order, 1)
next.Serve(params)
next.Serve(nil, nil, params)
order = append(order, 4)
})
})
r.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
order = append(order, 2)
next.Serve(params)
next.Serve(nil, nil, params)
order = append(order, 3)
})
})
@ -238,7 +212,7 @@ func TestMiddleware(t *testing.T) {
h, params, found := r.Lookup("GET", "/test")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
// Check middleware execution order (first middleware wraps second)
assert.Equal(t, len(order), 5)
@ -255,9 +229,9 @@ func TestMiddleware(t *testing.T) {
executed := false
middleware := func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
executed = true
next.Serve(params)
next.Serve(nil, nil, params)
})
}
@ -265,7 +239,7 @@ func TestMiddleware(t *testing.T) {
h, params, found := r.Lookup("GET", "/test")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, executed)
})
}
@ -281,7 +255,7 @@ func TestGroup(t *testing.T) {
h, params, found := r.Lookup("GET", "/api/users")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
})
t.Run("nested groups", func(t *testing.T) {
@ -294,7 +268,7 @@ func TestGroup(t *testing.T) {
h, params, found := r.Lookup("GET", "/api/v1/users")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
})
t.Run("group middleware", func(t *testing.T) {
@ -304,9 +278,9 @@ func TestGroup(t *testing.T) {
// Create group with middleware
api := r.Group("/api")
api.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
executed = true
next.Serve(params)
next.Serve(nil, nil, params)
})
})
@ -314,7 +288,7 @@ func TestGroup(t *testing.T) {
h, params, found := r.Lookup("GET", "/api/users")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
assert.True(t, executed)
})
@ -325,18 +299,18 @@ func TestGroup(t *testing.T) {
// Create group with middleware
api := r.Group("/api")
api.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
order = append(order, 1)
next.Serve(params)
next.Serve(nil, nil, params)
})
})
// Create nested group with additional middleware
v1 := api.Group("/v1")
v1.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
order = append(order, 2)
next.Serve(params)
next.Serve(nil, nil, params)
})
})
@ -346,7 +320,7 @@ func TestGroup(t *testing.T) {
h, params, found := r.Lookup("GET", "/api/v1/users")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
// Check middleware execution order
assert.Equal(t, len(order), 3)
@ -362,17 +336,17 @@ func TestGroup(t *testing.T) {
// Create group with middleware
api := r.Group("/api")
api.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
order = append(order, 1)
next.Serve(params)
next.Serve(nil, nil, params)
})
})
// Add route with specific middleware
api.WithMiddleware(func(next Handler) Handler {
return newHandler(func(params []string) {
return Handler(func(w Res, r Req, params []string) {
order = append(order, 2)
next.Serve(params)
next.Serve(nil, nil, params)
})
}).Get("/users", func(w Res, r Req, params []string) {
order = append(order, 3)
@ -380,7 +354,7 @@ func TestGroup(t *testing.T) {
h, params, found := r.Lookup("GET", "/api/users")
assert.True(t, found)
h.Serve(params)
h.Serve(nil, nil, params)
// Check middleware execution order
assert.Equal(t, len(order), 3)
@ -479,8 +453,8 @@ func BenchmarkWildcardLookup(b *testing.B) {
func BenchmarkMiddleware(b *testing.B) {
passthrough := func(next Handler) Handler {
return newHandler(func(params []string) {
next.Serve(params)
return Handler(func(w Res, r Req, params []string) {
next.Serve(nil, nil, params)
})
}
@ -491,7 +465,7 @@ func BenchmarkMiddleware(b *testing.B) {
b.ResetTimer()
for i := 0; i < b.N; i++ {
h, params, _ := r.Lookup("GET", "/test")
h.Serve(params)
h.Serve(nil, nil, params)
}
})
@ -503,13 +477,13 @@ func BenchmarkMiddleware(b *testing.B) {
b.ResetTimer()
for i := 0; i < b.N; i++ {
h, params, _ := r.Lookup("GET", "/test")
h.Serve(params)
h.Serve(nil, nil, params)
}
})
b.Run("five_middleware", func(b *testing.B) {
r := New()
for i := 0; i < 5; i++ {
for range 5 {
r.Use(passthrough)
}
r.Get("/test", func(w Res, r Req, params []string) {})
@ -517,7 +491,7 @@ func BenchmarkMiddleware(b *testing.B) {
b.ResetTimer()
for i := 0; i < b.N; i++ {
h, params, _ := r.Lookup("GET", "/test")
h.Serve(params)
h.Serve(nil, nil, params)
}
})
}
@ -551,8 +525,8 @@ func BenchmarkGroups(b *testing.B) {
r := New()
api := r.Group("/api")
api.Use(func(next Handler) Handler {
return newHandler(func(params []string) {
next.Serve(params)
return Handler(func(w Res, r Req, params []string) {
next.Serve(nil, nil, params)
})
})
v1 := api.Group("/v1")
@ -561,7 +535,7 @@ func BenchmarkGroups(b *testing.B) {
b.ResetTimer()
for i := 0; i < b.N; i++ {
h, params, _ := r.Lookup("GET", "/api/v1/users")
h.Serve(params)
h.Serve(nil, nil, params)
}
})
}