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) MethodNotAllowed(handler http.Handler)
- 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) SetRegisterHook(fn func(method, pattern string))
- func (r *Router) SetRouteGate(fn func(pattern string) bool)
- 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) MethodNotAllowed ¶ added in v0.18.0
MethodNotAllowed sets a custom handler for 405 (Method Not Allowed) responses. The router sets the RFC-compliant Allow header (filtered to exclude gated methods) BEFORE dispatching, so the handler inherits it without recomputing the allowed method set.
The router's middleware chain wraps the handler at request time, so 405 responses go through the same recovery, logging, security headers, etc. as matched routes — and middleware added after MethodNotAllowed still applies. Mirrors [NotFound] exactly, including the cachedRoute memoisation.
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, it distinguishes a genuine 404 from a method mismatch (405): when the path exists under some non-gated method, it emits a 405 with the filtered Allow header; otherwise it falls through to the custom NotFound handler (if any) or the mux's native 404.
func (*Router) SetRegisterHook ¶ added in v0.17.0
SetRegisterHook installs a callback fired for every Handle call across the router tree (subgroups funnel to root). Framework code uses it to attribute routes to the module whose Init registered them. Pass nil to clear. Must be called on the root router; setting on a child forwards to root.
func (*Router) SetRouteGate ¶ added in v0.17.0
SetRouteGate installs a gate checked before the middleware chain for every matched route. The argument is the "METHOD /path" key (e.g. "GET /users/{id}") so two modules owning different methods on the same path are gated independently. Returning false produces a plain 404 (not 403 — a disabled module's existence must not leak). The gate is also consulted on the 405 path to exclude gated methods from the Allow header. Framework code uses it to gate routes owned by a disabled module. Pass nil to clear. Must be called on the root router; setting on a child forwards to root.
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