Documentation
¶
Overview ¶
Package router is part of the GoFastr framework. See https://github.com/DonaldMurillo/gofastr for documentation.
Index ¶
- func Param(r *http.Request, name string) string
- func Params(r *http.Request) map[string]string
- type Middleware
- type RegisteredRoute
- type Router
- func (r *Router) Delete(pattern string, handler http.Handler)
- func (r *Router) DeleteFunc(pattern string, fn http.HandlerFunc)
- func (r *Router) Get(pattern string, handler http.Handler)
- func (r *Router) GetFunc(pattern string, fn http.HandlerFunc)
- func (r *Router) Group(prefix string, mw ...Middleware) *Router
- func (r *Router) Handle(method, pattern string, handler http.Handler)
- func (r *Router) HandleFunc(method, pattern string, fn http.HandlerFunc)
- func (r *Router) NotFound(handler http.Handler)
- func (r *Router) Patch(pattern string, handler http.Handler)
- func (r *Router) PatchFunc(pattern string, fn http.HandlerFunc)
- func (r *Router) Post(pattern string, handler http.Handler)
- func (r *Router) PostFunc(pattern string, fn http.HandlerFunc)
- func (r *Router) Put(pattern string, handler http.Handler)
- func (r *Router) PutFunc(pattern string, fn http.HandlerFunc)
- func (r *Router) Routes() []RegisteredRoute
- func (r *Router) RoutesFiltered(hide func(RegisteredRoute) bool) []RegisteredRoute
- func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
- func (r *Router) Use(mw ...Middleware)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Param ¶
Param extracts a single path parameter by name from the request. It uses the Go 1.22+ r.PathValue() method.
SECURITY: the returned value is truncated at the first CR, LF, or NUL byte so a path-parameter payload can't be smuggled into downstream headers, log lines, SSE frames, or query strings.
Types ¶
type Middleware ¶
type Middleware = middleware.Middleware
Middleware is the same shape as middleware.Middleware: a function that wraps an http.Handler with additional behavior. Declared as a type alias so values produced by core/middleware (and batteries that return middleware.Middleware) can be passed to Router.Use without an explicit conversion.
type RegisteredRoute ¶
RegisteredRoute is the (method, pattern) pair returned by Router.Routes(). Used by framework introspection tooling so an agent / debug endpoint can enumerate what's mounted.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router wraps http.ServeMux with method-based routing, path parameter extraction, middleware chaining, and route grouping.
It uses the Go 1.22+ ServeMux pattern syntax (e.g. "GET /users/{id}") which natively supports method matching and path parameter capture.
The middleware chain is resolved per request and protected by an RWMutex. Concurrent Use() and ServeHTTP() are safe — useful when plugins / batteries / OnStart hooks contribute middleware while requests are already flowing.
func (*Router) DeleteFunc ¶
func (r *Router) DeleteFunc(pattern string, fn http.HandlerFunc)
DeleteFunc registers a handler function for DELETE requests on the given pattern.
func (*Router) GetFunc ¶
func (r *Router) GetFunc(pattern string, fn http.HandlerFunc)
GetFunc registers a handler function for GET requests on the given pattern.
func (*Router) Group ¶
func (r *Router) Group(prefix string, mw ...Middleware) *Router
Group creates a sub-router with the given path prefix and optional middleware. The sub-router inherits its parent's middleware chain — resolved at request time, so middleware added to the parent after Group still participates. NotFound is resolved up the parent chain at request time as well; a sub-router has no notFound of its own unless one is explicitly registered.
func (*Router) Handle ¶
Handle registers a handler for the given method and pattern. The pattern uses Go 1.22+ ServeMux syntax, e.g. "GET /users/{id}".
The middleware chain is resolved per-request, not at registration time, so middleware appended via Use AFTER Handle still wraps this handler. This lets plugins contribute middleware from their Init without forcing a strict register-middleware-first ordering.
The composed handler is cached per route; a route handles steady-state traffic with a single atomic load. Any Use anywhere in the router tree bumps the root chain-version and forces the next request on each route to recompose.
func (*Router) HandleFunc ¶
func (r *Router) HandleFunc(method, pattern string, fn http.HandlerFunc)
HandleFunc registers a handler function for the given method and pattern. This is a convenience wrapper around Handle that accepts an http.HandlerFunc.
func (*Router) NotFound ¶
NotFound sets a custom handler for 404 (Not Found) responses. The router's middleware chain wraps the handler at request time, so 404 responses go through the same recovery, logging, security headers, etc. as matched routes — and middleware added after NotFound still applies.
Internally wrapped in a cachedRoute so the chain composition is memoised between Use bumps.
func (*Router) PatchFunc ¶
func (r *Router) PatchFunc(pattern string, fn http.HandlerFunc)
PatchFunc registers a handler function for PATCH requests on the given pattern.
func (*Router) PostFunc ¶
func (r *Router) PostFunc(pattern string, fn http.HandlerFunc)
PostFunc registers a handler function for POST requests on the given pattern.
func (*Router) PutFunc ¶
func (r *Router) PutFunc(pattern string, fn http.HandlerFunc)
PutFunc registers a handler function for PUT requests on the given pattern.
func (*Router) Routes ¶
func (r *Router) Routes() []RegisteredRoute
Routes returns the set of (method, pattern) pairs registered via Handle on this router and its child Groups. Order matches registration. Safe to call concurrently with Handle / Use.
Used by framework introspection tooling to enumerate the mounted surface; not consulted on the request hot path.
SECURITY: the returned slice includes EVERY registered pattern, including admin-only paths. Don't expose this output to anonymous callers as-is — wrap it in an auth gate, or use [RoutesFiltered] to drop patterns that match a deny predicate.
func (*Router) RoutesFiltered ¶
func (r *Router) RoutesFiltered(hide func(RegisteredRoute) bool) []RegisteredRoute
RoutesFiltered returns the set of registered routes EXCLUDING any pattern for which hide(route) returns true. Use this when exposing the route list over a public introspection endpoint so admin paths aren't trivially enumerated.
Typical pattern:
r.RoutesFiltered(func(rt router.RegisteredRoute) bool {
return strings.HasPrefix(rt.Pattern, "/admin/") ||
strings.HasPrefix(rt.Pattern, "/internal/")
})
hide may be nil — that case returns every route (equivalent to [Routes]).
func (*Router) ServeHTTP ¶
func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP implements http.Handler. It dispatches requests through the underlying ServeMux. If no route matches and a custom notFound handler is set, it delegates to that handler (already a cachedRoute, so the chain composition is memoised between Use bumps).
func (*Router) Use ¶
func (r *Router) Use(mw ...Middleware)
Use adds middleware to the router. Middleware is applied in the order they are added: the first middleware is the outermost wrapper.
Safe to call concurrently with in-flight ServeHTTP — the mutation is guarded by an RWMutex. Bumps the root chain-version so every cached per-route handler in the tree recomposes on the next request.
Source Files