# Public API The public API of MuxMaster: every exported type, function, method, and field, with the signatures and short behavioural notes the compiler sees. The package implements an `http.Handler`-compatible HTTP router built on a radix tree, plus typed parameter accessors, response helpers, and an introspection API. For the SemVer tier policy that governs which symbols below are stable, see the [Compatibility](/compatibility) page. ## github.com/FlavioCFOliveira/MuxMaster ```go package muxmaster // import "github.com/FlavioCFOliveira/MuxMaster" Package muxmaster is a high-performance HTTP router for Go that is 100% compatible with the standard net/http package, requires zero external dependencies, and is built on a radix tree (compressed prefix trie) that delivers O(k) route lookup — where k is the length of the URL path, not the number of registered routes. ### Quick start mux := muxmaster.New() mux.GET("/users/:id", func(w http.ResponseWriter, r *http.Request) { id := muxmaster.PathParam(r, "id") fmt.Fprintf(w, "user=%s", id) }) http.ListenAndServe(":8080", mux) ### Route patterns Static segments match literally; dynamic segments use one of three forms: - Named parameter: /users/:id — single non-slash segment - Regex parameter: /items/{id:[0-9]+} — Go regexp restricted match - Catch-all: /static/*filepath — matches the rest of the path ### Middleware Three orthogonal middleware scopes are supported: - Mux.Use: stdlib http.Handler middleware applied at registration time; wraps Mux.Handle routes only. Registering a HandleFast route after Use panics (FPE-2026-010). - Mux.UseFast: FastMiddleware that wraps HandleFast routes only. - Mux.Pre: pre-dispatch middleware that wraps BOTH Handle and HandleFast routes; ideal for cross-cutting policy (auth, logging, request_id). See the SECURITY.md "Pre vs Use security boundary" section for the full matrix. ### Performance On AMD Ryzen 9 5900HX (Go 1.26.2): - Static route: 25 ns / 0 alloc - 1-param route: 112 ns / 1 alloc / 416 B - HandleFast 1-p: 49 ns / 1 alloc / 32 B (parity with httprouter) HandleFast routes bypass the requestCtx allocation by passing Params directly as the third handler argument; they trade off stdlib middleware compatibility for raw throughput. ### Compatibility See COMPATIBILITY.md for the SemVer scheme, tier classification of the public API surface, deprecation policy, and Go version policy. Package muxmaster is a high-performance HTTP request multiplexer for Go. Routes are matched with a radix (compressed prefix) tree, giving O(k) lookup where k is the path length. Zero external dependencies; pure standard library. Usage: mux := muxmaster.New() mux.Use(logger, auth) // middleware applied to every route below mux.GET("/users", listUsers) mux.GET("/users/:id", getUser) mux.GET("/static/*filepath", serveFiles) api := mux.Group("/api/v1") api.Use(apiKeyCheck) api.POST("/items", createItem) http.ListenAndServe(":8080", mux) Middleware must be registered (via Use) before the routes it should wrap. Dynamic route registration after the server starts serving is not supported. FUNCTIONS func JSON(w http.ResponseWriter, code int, v any) error JSON marshals v to JSON and writes it with the given status code. Returns any marshalling or write error. func NoContent(w http.ResponseWriter) NoContent writes a 204 No Content response. func PathParam(r *http.Request, name string) string PathParam returns the value of the named path parameter from the request. func Redirect(w http.ResponseWriter, r *http.Request, code int, url string) Redirect sends an HTTP redirect to url with the given status code. func RoutePattern(r *http.Request) string RoutePattern returns the registered route pattern that matched the request, or "" if none has been stored in the context. func Text(w http.ResponseWriter, code int, s string) error Text writes s as plain text with the given status code. func XML(w http.ResponseWriter, code int, v any) error XML marshals v to XML and writes it with the given status code. Returns any marshalling or write error. TYPES type FastHandler func(http.ResponseWriter, *http.Request, Params) FastHandler is a high-performance request handler that receives path parameters as a direct argument, bypassing the context allocation overhead of http.Handler routes. Params is valid only for the lifetime of the handler call. If a goroutine is spawned that outlives the handler, copy the Params slice before the handler returns: func myHandler(w http.ResponseWriter, r *http.Request, ps muxmaster.Params) { ps2 := make(muxmaster.Params, len(ps)) copy(ps2, ps) go func() { use(ps2) }() } FastHandler routes do not support stdlib middleware (func(http.Handler) http.Handler). Use FastMiddleware instead, or register the route with Handle for full stdlib compatibility. type FastMiddleware func(FastHandler) FastHandler FastMiddleware wraps a FastHandler, following the same composition model as stdlib middleware but for FastHandler routes only. type Group struct { // Has unexported fields. } Group is a set of routes sharing a common path prefix and middleware stack. Create one via Mux.Group; nest further via Group.Group. func (g *Group) ANY(path string, h http.HandlerFunc) ANY registers h for all standard HTTP methods on path. func (g *Group) CONNECT(path string, h http.HandlerFunc) CONNECT registers a HandlerFunc for CONNECT requests on path. func (g *Group) DELETE(path string, h http.HandlerFunc) DELETE registers a HandlerFunc for DELETE requests on path. func (g *Group) DELETEE(path string, h HandlerFuncE) DELETEE registers a HandlerFuncE for DELETE requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) GET(path string, h http.HandlerFunc) GET registers a HandlerFunc for GET requests on path. func (g *Group) GETE(path string, h HandlerFuncE) GETE registers a HandlerFuncE for GET requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) Group(prefix string) *Group Group returns a sub-group sharing the same mux with an extended prefix. The sub-group starts with a copy of the parent group's middleware stacks. func (g *Group) HEAD(path string, h http.HandlerFunc) HEAD registers a HandlerFunc for HEAD requests on path. func (g *Group) HEADE(path string, h HandlerFuncE) HEADE registers a HandlerFuncE for HEAD requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) Handle(method, path string, handler http.Handler) Handle registers handler under this group with the given method and path. The full path is g.prefix + path. Group middleware is applied after mux-level middleware. func (g *Group) HandleE(method, path string, h HandlerFuncE) HandleE registers a HandlerFuncE under this group. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. The error handler is read from the frozen muxConfig at request time — see Mux.HandleE for the rationale (CSA-2026-0052). func (g *Group) HandleFast(method, path string, h FastHandler) HandleFast registers a FastHandler under this group with the given method and path. The full path is g.prefix + path. Group FastMiddleware is applied before dispatch. SECURITY: panics if the group has stdlib middleware registered via Use(). Stdlib middleware is incompatible with the FastHandler dispatch path — silently mixing them would let HandleFast routes bypass authentication, authorisation, logging or any other Use()-registered middleware. Operators must use UseFast() for FastHandler routes, or Handle() for routes that should run through the stdlib middleware chain. func (g *Group) HandleFunc(method, path string, h http.HandlerFunc) HandleFunc registers a HandlerFunc under this group. func (g *Group) Match(methods []string, path string, handler http.Handler) Match registers handler for each of the listed methods on path. func (g *Group) Mount(prefix string, h http.Handler) Mount attaches h at g.prefix+prefix, stripping the full prefix before forwarding. The group's stdlib middleware (registered via Use) wraps the mounted handler so authentication, logging, etc. apply to every request reaching h — without this wrapping a Group with BasicAuth/JWTAuth would silently leave the mounted handler unprotected (MSR-2026-0062). func (g *Group) OPTIONS(path string, h http.HandlerFunc) OPTIONS registers a HandlerFunc for OPTIONS requests on path. func (g *Group) OPTIONSE(path string, h HandlerFuncE) OPTIONSE registers a HandlerFuncE for OPTIONS requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) PATCH(path string, h http.HandlerFunc) PATCH registers a HandlerFunc for PATCH requests on path. func (g *Group) PATCHE(path string, h HandlerFuncE) PATCHE registers a HandlerFuncE for PATCH requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) POST(path string, h http.HandlerFunc) POST registers a HandlerFunc for POST requests on path. func (g *Group) POSTE(path string, h HandlerFuncE) POSTE registers a HandlerFuncE for POST requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) PUT(path string, h http.HandlerFunc) PUT registers a HandlerFunc for PUT requests on path. func (g *Group) PUTE(path string, h HandlerFuncE) PUTE registers a HandlerFuncE for PUT requests on path. Errors are passed to g.mux.ErrorHandler if set, otherwise a 500 is returned. func (g *Group) Route(prefix string, fn func(*Group)) Route creates a sub-group at prefix and calls fn with it. func (g *Group) ServeFiles(prefix string, root http.FileSystem) ServeFiles serves static files from root under the given prefix pattern. prefix must end with "/*name" (relative to the group prefix). func (g *Group) TRACE(path string, h http.HandlerFunc) TRACE registers a HandlerFunc for TRACE requests on path. func (g *Group) Use(middleware ...func(http.Handler) http.Handler) Use appends middleware to this group's chain. Must be called before registering routes on the group. func (g *Group) UseFast(mw ...FastMiddleware) UseFast appends FastMiddleware to this group's fast-route chain. Must be called before registering HandleFast routes on the group. func (g *Group) With(mw ...func(http.Handler) http.Handler) *Group With returns a copy of this group with additional middleware appended. type HTTPError interface { error StatusCode() int } HTTPError is an error that carries an HTTP status code. func Error(code int, err error) HTTPError Error constructs an HTTPError wrapping err with the given HTTP status code. Panics if err is nil. type HandlerFuncE func(http.ResponseWriter, *http.Request) error HandlerFuncE is a handler that returns an error, allowing centralised error handling. type Mux struct { // RedirectTrailingSlash redirects /foo/ → /foo (or /foo → /foo/) when a // handler exists at the alternate path. RedirectTrailingSlash bool // RedirectFixedPath redirects requests whose cleaned path has a handler. RedirectFixedPath bool // HandleMethodNotAllowed returns 405 with an Allow header when the path // exists but not for the requested method. HandleMethodNotAllowed bool // HandleOPTIONS replies to OPTIONS requests with the Allow header set to // all registered methods for the matched path. HandleOPTIONS bool // CaseInsensitive enables case-insensitive route matching for static segments. CaseInsensitive bool // UseRawPath uses r.URL.RawPath for matching when set and non-empty. UseRawPath bool // UnescapePathValues percent-decodes path parameter values before storing // them. Only takes effect when UseRawPath is also true: when UseRawPath is // false (the default) net/http already decodes the URL path during parsing // and a second decode would corrupt values containing literal '%XX' (the // PRF-2026-0006 double-decode that let %2520 bypass space-blocking input // validators). Set both UseRawPath and UnescapePathValues to retrieve // decoded values from the original raw path bytes. // // SECURITY (PRF-2026-0002): when UseRawPath=true AND UnescapePathValues=true, // `%2f` inside a single segment is matched as one path segment by the radix // tree (because `/` is preserved as separator only via literal slash) and // then DECODED in the captured param value. A request such as // `/files/..%2fetc%2fpasswd` binds `:filepath` to the literal string // `..\x2fetc\x2fpasswd` — i.e. the captured value contains a real slash. // Handlers that pass `ParamsFromContext(...).ByName("filepath")` to // `os.Open`, `http.FileServer`, or any URL/file API WITHOUT calling // `path.Clean` (and rejecting values that contain `..`) are vulnerable to // directory traversal. The `clean_path` middleware does NOT normalise // post-decode values; it only canonicalises the request path before // dispatch. See SECURITY.md "UseRawPath traversal" and // examples/static-site/ for the safe pattern. UnescapePathValues bool // RedirectCode overrides the default redirect status code (301/307). // Zero means use the default. RedirectCode int // PoolRequestBundle, when true, recycles the per-request reqBundle // (the fused requestCtx + *http.Request copy) through three // tier-matched sync.Pools (1 / 2 / 3+ parameters). Eliminates the // 384 / 416 / 480 B allocation on the stdlib http.Handler path. // Introduced in v1.1.0 (Opt O13). Default: false. // // CONTRACT: handlers must NOT retain *http.Request past return. // Capturing r in a goroutine that outlives the handler observes // either a zeroed bundle or another concurrent request's state. // See docs/max-performance.md for the audit checklist and the // four real-world recipes. // // FORWARD-COMPATIBILITY: if a future Go release renames the // unexported ctx field of http.Request, MuxMaster detects the // absence via reflection at init (hasReqCtxField) and silently // falls back to the non-pooled r.WithContext(...) path. PoolRequestBundle bool // PoolFastParams, when true, recycles the Params slice handed to // FastHandler routes through three tier-matched sync.Pools // (1 / 2 / 3 parameters). Introduced in v1.1.0 (Opt O9). // Default: false. // // CONTRACT: FastHandler callbacks must NOT retain the Params // slice (or any Param element) past return. PoolFastParams bool // NotFound is called when no route matches (default: http.NotFound). NotFound http.Handler // MethodNotAllowed is called on 405 (default: plain-text response). MethodNotAllowed http.Handler // GlobalOPTIONS is called for auto-handled OPTIONS requests instead of // the default 204 No Content response. GlobalOPTIONS http.Handler // ErrorHandler handles errors returned by HandlerFuncE handlers. // Default: 500 Internal Server Error. ErrorHandler func(http.ResponseWriter, *http.Request, error) // PanicHandler recovers from panics in handlers and receives the // ResponseWriter, Request, and recovered value. // // SECURITY (CSA-2026-0058 / H8-30): PanicHandler implementations MUST // NOT themselves panic. MuxMaster's recover frame catches the FIRST // panic and dispatches into PanicHandler; if PanicHandler panics again // the secondary panic is NOT recovered by MuxMaster. It propagates up // to the per-connection recover in net/http (server.go), which logs // "http: panic serving ..." and closes the TCP connection. There is // no goroutine leak and no process crash, but the connection is // terminated mid-response, which can confuse clients and HTTP/2 // stream multiplexing. See SECURITY.md "Layered panic recovery". PanicHandler func(http.ResponseWriter, *http.Request, any) // Has unexported fields. } Mux is a high-performance HTTP request multiplexer. Configuration fields (RedirectTrailingSlash, CaseInsensitive, etc.) are read once and frozen on the first ServeHTTP call. Use Rebuild to reset the snapshot when changing flags after the server has started serving. func New() *Mux New returns a Mux with production-safe defaults enabled. func (m *Mux) ANY(pattern string, h http.HandlerFunc) ANY registers handler for all standard HTTP methods on pattern. func (m *Mux) CONNECT(pattern string, h http.HandlerFunc) CONNECT registers a HandlerFunc for CONNECT requests on pattern. func (m *Mux) CONNECTFast(pattern string, h FastHandler) CONNECTFast registers a FastHandler for CONNECT requests on pattern. func (m *Mux) DELETE(pattern string, h http.HandlerFunc) DELETE registers a HandlerFunc for DELETE requests on pattern. func (m *Mux) DELETEE(pattern string, h HandlerFuncE) DELETEE registers a HandlerFuncE for DELETE requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) DELETEFast(pattern string, h FastHandler) DELETEFast registers a FastHandler for DELETE requests on pattern. func (m *Mux) GET(pattern string, h http.HandlerFunc) GET registers a HandlerFunc for GET requests on pattern. func (m *Mux) GETE(pattern string, h HandlerFuncE) GETE registers a HandlerFuncE for GET requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) GETFast(pattern string, h FastHandler) GETFast registers a FastHandler for GET requests on pattern. func (m *Mux) Group(prefix string) *Group Group returns a RouteGroup whose routes share the given path prefix. func (m *Mux) HEAD(pattern string, h http.HandlerFunc) HEAD registers a HandlerFunc for HEAD requests on pattern. func (m *Mux) HEADE(pattern string, h HandlerFuncE) HEADE registers a HandlerFuncE for HEAD requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) HEADFast(pattern string, h FastHandler) HEADFast registers a FastHandler for HEAD requests on pattern. func (m *Mux) Handle(method, pattern string, handler http.Handler) Handle registers handler for the given HTTP method and path pattern. Path parameters use the ':name' syntax (/users/:id). Regex params use '{name:expr}' (/users/{id:[0-9]+}). Catch-all parameters use '*name' and must end the path (/static/*filepath). Panics on empty method, non-absolute path, nil handler, or route conflict. func (m *Mux) HandleE(method, pattern string, h HandlerFuncE) HandleE registers a HandlerFuncE for the given method and path. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. The error handler is read from the frozen muxConfig snapshot at request time, eliminating the data race against post-startup mutation of m.ErrorHandler (CSA-2026-0052). func (m *Mux) HandleFast(method, pattern string, h FastHandler) HandleFast registers a FastHandler for the given HTTP method and path. FastHandler routes bypass the context allocation overhead of http.Handler routes. Params are passed as a direct argument — see FastHandler for lifetime guarantees. SECURITY: stdlib middleware (registered via Use) does NOT apply to fast routes. This includes the Recoverer middleware — a panic in a FastHandler is NOT recovered by middleware.Recoverer, regardless of the order Use was called. Set Mux.PanicHandler to recover panics on the FastHandler path: PanicHandler is invoked from dispatchWithRecover and covers both http.Handler and FastHandler routes. Use UseFast to attach FastMiddleware to fast routes; FastMiddleware runs on the FastHandler dispatch path. Panics on empty method, non-absolute path, nil handler, or route conflict. func (m *Mux) HandleFunc(method, pattern string, h http.HandlerFunc) HandleFunc registers a HandlerFunc for the given method and path. func (m *Mux) Lookup(method, path string) (http.Handler, Params, bool) Lookup performs a route lookup without dispatching a request. Returns (nil, nil, false) if path is empty or does not begin with '/'. For FastHandler routes the returned http.Handler is nil; use LookupFast when you need to distinguish fast routes. func (m *Mux) Match(methods []string, pattern string, handler http.Handler) Match registers handler for each of the listed methods on pattern. func (m *Mux) Mount(prefix string, h http.Handler) Mount attaches h at prefix, stripping the prefix before forwarding the request. The catch-all parameter is named "mux_mount". func (m *Mux) OPTIONS(pattern string, h http.HandlerFunc) OPTIONS registers a HandlerFunc for OPTIONS requests on pattern. func (m *Mux) OPTIONSE(pattern string, h HandlerFuncE) OPTIONSE registers a HandlerFuncE for OPTIONS requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) OPTIONSFast(pattern string, h FastHandler) OPTIONSFast registers a FastHandler for OPTIONS requests on pattern. func (m *Mux) PATCH(pattern string, h http.HandlerFunc) PATCH registers a HandlerFunc for PATCH requests on pattern. func (m *Mux) PATCHE(pattern string, h HandlerFuncE) PATCHE registers a HandlerFuncE for PATCH requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) PATCHFast(pattern string, h FastHandler) PATCHFast registers a FastHandler for PATCH requests on pattern. func (m *Mux) POST(pattern string, h http.HandlerFunc) POST registers a HandlerFunc for POST requests on pattern. func (m *Mux) POSTE(pattern string, h HandlerFuncE) POSTE registers a HandlerFuncE for POST requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) POSTFast(pattern string, h FastHandler) POSTFast registers a FastHandler for POST requests on pattern. func (m *Mux) PUT(pattern string, h http.HandlerFunc) PUT registers a HandlerFunc for PUT requests on pattern. func (m *Mux) PUTE(pattern string, h HandlerFuncE) PUTE registers a HandlerFuncE for PUT requests on pattern. Errors are passed to m.ErrorHandler if set, otherwise a 500 is returned. func (m *Mux) PUTFast(pattern string, h FastHandler) PUTFast registers a FastHandler for PUT requests on pattern. func (m *Mux) Pre(mw ...func(http.Handler) http.Handler) Pre registers middleware that runs before dispatch (e.g. before routing). Calling Pre rebuilds the pre-dispatch handler chain. SECURITY (CSA-2026-0059): Pre wraps the entire ServeHTTP dispatch and covers BOTH Handle (stdlib) and HandleFast routes. This makes Pre the correct registration point for cross-cutting policies that must apply uniformly — auth gates, CleanPath, RealIP, RecovererWithLogger, request IDs. See SECURITY.md "Pre vs Use security boundary". func (m *Mux) Rebuild() Rebuild resets the frozen configuration snapshot and the lazy NotFound / MethodNotAllowed / OPTIONS handler caches so the next ServeHTTP call re-reads every configuration field and rebuilds the wrapped handlers. Safe to call concurrently with ServeHTTP: every reset is a single atomic operation, and the next config() / lazyNotFound() / lazyMethodNotAllowed() / lazyOPTIONS() call re-initialises via CompareAndSwap or sync.Map re-population. Intended for tests and dynamic reconfiguration scenarios. func (m *Mux) Route(prefix string, fn func(*Group)) Route creates a sub-group at prefix and calls fn with it. func (m *Mux) Routes() []RouteInfo Routes returns a slice of RouteInfo for every registered route, including both http.Handler and FastHandler routes. func (m *Mux) ServeFiles(prefix string, root http.FileSystem) ServeFiles serves static files from root under the given prefix pattern. prefix must end with "/*name" (e.g. "/static/*filepath"). SECURITY (CDX-S8-002): http.FileServer applies path.Clean internally, so a request like /static/../etc/passwd cannot escape root. However, when the Mux is configured with UseRawPath=true AND UnescapePathValues=true the captured filepath param contains decoded slashes (PRF-2026-0002) and http.FileServer's clean step happens AFTER the param has already been re-set as r2.URL.Path — the decoded slashes act as path separators inside FileServer's tree. Registration with that combination panics so the misconfiguration is caught at boot. Disable one of UseRawPath / UnescapePathValues, or write a custom handler that calls path.Clean on the captured value and rejects ".." segments before dispatch. func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request) ServeHTTP implements http.Handler, dispatching through pre-middleware if set. The fast path (no PanicHandler, no pre-middleware) avoids the defer frame overhead entirely by going straight to dispatch. Deferred paths are isolated in dispatchWithRecover to keep this function inlineable. func (m *Mux) TRACE(pattern string, h http.HandlerFunc) TRACE registers a HandlerFunc for TRACE requests on pattern. func (m *Mux) TRACEFast(pattern string, h FastHandler) TRACEFast registers a FastHandler for TRACE requests on pattern. func (m *Mux) Use(middleware ...func(http.Handler) http.Handler) Use appends one or more middleware to the chain. Each middleware wraps all handlers registered after this call. The first middleware added is outermost. SECURITY (CSA-2026-0059): Use does NOT wrap HandleFast routes — registering a fast route after Use(authMiddleware) panics at HandleFast call time on BOTH the root Mux (FPE-2026-010) and Groups (CSA-2026-0054), so the bypass cannot occur silently regardless of where the operator places the route. To apply policy to both stdlib and fast routes, use Pre(...) (outermost, route-type agnostic) or UseFast(...) for FastMiddleware. See SECURITY.md "Pre vs Use security boundary". func (m *Mux) UseFast(mw ...FastMiddleware) UseFast appends one or more FastMiddleware to the chain applied to all HandleFast routes registered after this call. The first middleware added is outermost. Has no effect on routes registered via Handle. SECURITY (CSA-2026-0059): UseFast is the FastHandler counterpart of Use; together with Pre (which covers BOTH route types) it forms the route-type matrix documented in SECURITY.md "Pre vs Use security boundary". An auth gate applied only via Use(...) does NOT cover HandleFast routes. func (m *Mux) Walk(fn func(method, pattern string, handler http.Handler) error) error Walk calls fn for each registered http.Handler route. FastHandler routes are skipped — use WalkFast to visit them. Stops iteration and returns the error if fn returns non-nil. func (m *Mux) WalkFast(fn func(method, pattern string, handler FastHandler) error) error WalkFast calls fn for each registered FastHandler route. http.Handler routes are skipped — use Walk to visit them. Stops iteration and returns the error if fn returns non-nil. func (m *Mux) With(mw ...func(http.Handler) http.Handler) *Group With returns a Group with the given middleware applied and an empty prefix. type Param struct { Key string Value string } Param is a single URL path parameter (key + value). type Params []Param Params is an ordered list of path parameters extracted from a URL. func ParamsFromContext(ctx context.Context) Params ParamsFromContext returns the path parameters stored in ctx. func (ps Params) Bool(name string) (bool, error) Bool returns the named parameter parsed as bool. func (ps Params) Float64(name string) (float64, error) Float64 returns the named parameter parsed as float64. func (ps Params) Get(name string) string Get returns the value for the named parameter, or "" if not present. func (ps Params) Int(name string) (int, error) Int returns the named parameter parsed as int. Returns errParamNotFound if the key is absent, or a strconv error on parse failure. func (ps Params) Int64(name string) (int64, error) Int64 returns the named parameter parsed as int64 (base 10). func (ps Params) Lookup(name string) (value string, ok bool) Lookup returns the value and a presence flag for the named parameter. func (ps Params) Map() map[string]string Map returns a copy of the parameters as a string map. func (ps Params) Uint64(name string) (uint64, error) Uint64 returns the named parameter parsed as uint64 (base 10). type RouteInfo struct { Method string Pattern string Handler string } RouteInfo describes a single registered route. ``` ## github.com/FlavioCFOliveira/MuxMaster/middleware ```go package middleware // import "github.com/FlavioCFOliveira/MuxMaster/middleware" Package middleware provides common HTTP middleware handlers for use with MuxMaster or any net/http-compatible router. Each middleware is a function that takes an http.Handler and returns an http.Handler, following the standard Go middleware pattern: func(next http.Handler) http.Handler Usage with MuxMaster: import "github.com/FlavioCFOliveira/MuxMaster/middleware" mux := muxmaster.New() mux.Use(middleware.Logger(os.Stdout)) mux.Use(middleware.Recoverer) mux.Use(middleware.CORS(middleware.CORSOptions{ AllowedOrigins: []string{"https://example.com"}, })) CONSTANTS const DefaultThrottlePerIPMaxTableSize = 100_000 DefaultThrottlePerIPMaxTableSize is the default upper bound on the number of distinct keys ThrottlePerIP will track concurrently. When the table is full, requests for NEW keys are rejected with 503 to bound memory under IP-churn attacks (MSR-2026-0068). Existing keys keep working. FUNCTIONS func APIKey(opts APIKeyOptions) func(http.Handler) http.Handler APIKey authenticates requests by matching an extracted key against a pre-hashed set of valid keys. All keys are SHA-256 hashed at construction time; per-request cost is one SHA-256 hash plus a [32]byte map lookup — no iteration, no string comparison. On success, the identity string associated with the key is injected into the request context and retrievable via GetAPIKeyIdentity. Panics if opts.Keys is nil or empty. func BasicAuth(realm string, creds map[string]string) func(http.Handler) http.Handler BasicAuth enforces HTTP Basic Authentication using constant-time credential comparison. Passwords are SHA-256 hashed at construction time so that subtle.ConstantTimeCompare always operates on equal-length inputs, eliminating both user-enumeration timing (MM-2026-0009) and password-length oracle (MM-2026-0020). Panics if creds is nil. func CORS(opts CORSOptions) func(http.Handler) http.Handler CORS handles Cross-Origin Resource Sharing. Panics on invalid configuration. SECURITY: AllowedOrigins must be set explicitly. Passing nil or an empty slice is a misconfiguration trap (HPS-2026-0003): the middleware would silently let cross-origin requests through with no ACAO header, hiding the issue from the operator. We panic at construction time so the misconfiguration is caught at boot. ORDERING (MSR-2026-0070): CORS sets `Access-Control-Allow-Origin` (and related Access-Control-* + Vary headers) when its frame runs. If another middleware that calls `Header().Set(...)` runs AFTER CORS in the request flow (innermost in the Use() chain), the late Set will OVERWRITE the CORS-managed values, silently bypassing the configured whitelist. To keep CORS authoritative, register CORS as the INNERMOST middleware that touches these headers (i.e. last in the Use() chain that handles them) or avoid calling SetHeader on CORS-managed names. See SetHeader for the composition rule. func CleanPath() func(http.Handler) http.Handler CleanPath normalises r.URL.Path via path.Clean before routing. When r.URL.RawPath is set, it is also cleaned; if the cleaned RawPath differs from what path.Clean produces for the percent-decoded Path, RawPath is zeroed to prevent encoded path-traversal bypass (MM-2026-0018). func Compress(level int) func(http.Handler) http.Handler Compress compresses responses with gzip when the client accepts it. Responses smaller than 1024 bytes are passed through uncompressed. Uses streaming compression — memory usage is bounded regardless of response size. Panics on invalid compression level. OPERATIONAL (DOS-2026-0007): the compress middleware buffers up to 8 KiB per stalled connection while sniffing whether the response is large enough to compress. Operators MUST configure http.Server.ReadHeaderTimeout and http.Server.WriteTimeout (and a connection cap via a Listener limit) to bound the total memory held by N stalled connections; the middleware itself does not enforce a per-connection timeout. SECURITY (BREACH / DOS-2026-0006): do NOT echo user-controlled input alongside a secret (OAuth2 scope, CSRF token, session ID, JWT) inside a gzip-compressed response body. Compression amplifies tiny size differences that depend on whether the user's input matches a prefix of the secret — this is the BREACH oracle (Cohen's d > 10 measured in reports/dos-resilience-tester/harness/breach_oracle_test.go), letting an attacker recover the secret character-by-character with ~2 requests per character. Mitigations, in order of preference: 1. Do not compress endpoints that echo user input near secrets — wrap them with a different middleware chain that excludes Compress. 2. Move secrets out of the response body (set them in headers, cookies, or separate API endpoints not reachable via attacker-controlled input). 3. Add variable-length random padding (>= 256 bytes, length randomised per request) to the response body. Validated by TestBREACHOracleWithRandomPadding (Cohen's d drops below 0.03). MuxMaster cannot apply these mitigations on the operator's behalf because they require knowledge of which fields are secret vs user-controlled. See SECURITY.md "BREACH mitigation" for the full pattern. func GetAPIKeyIdentity(ctx context.Context) (string, bool) GetAPIKeyIdentity returns the identity string associated with the validated API key, as injected by the APIKey middleware. func GetRequestID(ctx context.Context) string GetRequestID returns the request ID stored in ctx, or "" if absent. func JWTAuth(opts JWTOptions) func(http.Handler) http.Handler JWTAuth validates JWT Bearer tokens from the Authorization header. Signature is always verified before claims are parsed to prevent payload manipulation. On success, claims are injected into the request context via GetJWTClaims. Panics if Algorithms is empty or if the required key material is missing for any listed algorithm. func Logger(out io.Writer) func(http.Handler) http.Handler Logger logs each request after it completes. Panics if out is nil. func NoCache() func(http.Handler) http.Handler NoCache sets response headers to prevent caching at every layer: browsers (Cache-Control / Pragma / Expires), CDNs (Surrogate-Control) and nginx-style reverse proxies (X-Accel-Expires). All headers are harmless to deployments that do not run an intermediate cache. func OAuth2Introspect(opts OAuth2Options) func(http.Handler) http.Handler OAuth2Introspect validates Bearer tokens via RFC 7662 token introspection. Active tokens are cached (keyed by sha256(token)) to avoid per-request network calls. On success, the IntrospectResponse is available via GetOAuth2Claims. Panics if opts.Endpoint is empty, malformed, or non-HTTPS (unless opts.AllowInsecureEndpoint is true). Bearer tokens transmitted over plaintext are exposed to passive observers (MSR-2026-0067 / RFC 7662 §4). func RealIP(trustedCIDRs ...*netip.Prefix) func(http.Handler) http.Handler RealIP overwrites r.RemoteAddr with the client IP derived from the X-Forwarded-For or X-Real-IP header. Only mutates RemoteAddr when the direct peer is within one of the trusted CIDR prefixes. XFF selection (MSR-2026-0065): the header is parsed as a comma-separated list and walked from RIGHTMOST toward leftmost, skipping entries that lie inside any trustedCIDRs. The first entry NOT inside a trusted CIDR is the real client IP. This rejects attacker-injected leftmost values: in a multi-hop chain (proxy1 + proxy2), if only proxy2 is trusted, the leftmost-XFF approach would pick a forged `client_ip` injected by the attacker, but the rightmost walk stops at proxy1 (the first untrusted hop) and falls back to its address. When the entire chain consists of trusted CIDRs, the leftmost entry is used as a last resort. With a single trusted proxy stripping inbound XFF (the documented baseline) the behaviour is identical to picking the leftmost. SECURITY (MSR-2026-0055): calling RealIP() with no CIDRs trusts every peer — any client can spoof the X-Forwarded-For / X-Real-IP header and the router will accept it as the real client IP. This is only safe behind a single trusted proxy that strips inbound XFF; in any other deployment it is a trivial spoofing primitive that defeats ThrottlePerIP and IP-based access controls. The middleware emits a slog.Warn at construction time when called without CIDRs so the misconfiguration is visible in startup logs. ALWAYS pass the proxy CIDR list explicitly in production. Proxy depth: each additional trusted proxy in the forwarding chain MUST be covered by a trustedCIDRs entry, otherwise the rightmost-walk stops too early and the proxy IP (rather than the real client) becomes RemoteAddr. IP values are validated via netip.ParseAddr, which rejects CRLF injection and malformed addresses, and IPv6 zone IDs are stripped via WithZone("") (FPE-2026-003 / FPE-2026-003b). func Recoverer() func(http.Handler) http.Handler Recoverer recovers from panics and writes a 500 response. Logs via slog.Default() — use RecovererWithLogger for a custom logger. Deprecated: use RecovererWithLogger(slog.Default()) for explicit control. func RecovererWithLogger(logger *slog.Logger) func(http.Handler) http.Handler RecovererWithLogger recovers from panics, logs the panic value and stack trace at Error level via logger, and writes a plain 500 response. The panic value is never written to the response body, preventing information leakage to clients (MM-2026-0023). func RequestID() func(http.Handler) http.Handler RequestID generates or propagates a request ID via X-Request-ID header. Incoming X-Request-ID values are validated; invalid or oversized values are replaced with a freshly generated random ID (MM-2026-0011). func SetHeader(key, value string) func(http.Handler) http.Handler SetHeader sets a fixed response header before calling the next handler. Panics at construction time if key or value contains CR or LF, as those bytes can reach downstream middleware in raw form even though Go's wire serialiser strips them before writing to the network. ORDERING (MSR-2026-0070): SetHeader runs Header().Set on the response at the START of its frame, BEFORE calling next. Middleware composition in MuxMaster wraps from outermost to innermost — the first Use() call is outermost. So if Use(CORS, SetHeader(...)) is registered, SetHeader runs LAST in the request flow (innermost) and its Set() will OVERWRITE any header CORS already wrote. Specifically, Use(CORS, SetHeader( "Access-Control-Allow-Origin", "*")) silently bypasses the CORS allowed origins whitelist for every request. To preserve CORS guarantees, register SetHeader BEFORE CORS in the Use() chain (so SetHeader is the outermost frame and CORS overwrites it for the headers it manages), or omit any SetHeader call that targets a CORS-managed header (Access-Control-Allow-Origin, -Methods, -Headers, -Credentials, -Max-Age, -Expose-Headers, Vary). func StripSlashes() func(http.Handler) http.Handler StripSlashes removes all trailing slashes from r.URL.Path before routing. Idempotent: "/a///" becomes "/a" (not "/a//"). When r.URL.RawPath is set (the original raw form is preserved by net/http only when it differs from the decoded Path), StripSlashes also strips trailing '/' bytes from RawPath. Without this the dispatch path would diverge between Path and RawPath when Mux.UseRawPath is true (HPS-2026-0004). func ThrottleAllBacklog(limit int, backlog int, timeout time.Duration) func(http.Handler) http.Handler ThrottleAllBacklog is the renamed ThrottleBacklog — limits concurrency globally across ALL clients combined. Use ThrottlePerIP for per-client rate limiting. Deprecated: Use ThrottleAllBacklog. ThrottleBacklog remains for compatibility. func ThrottleBacklog(limit int, backlog int, timeout time.Duration) func(http.Handler) http.Handler ThrottleBacklog limits concurrent handler execution with a backlog queue. Panics if limit <= 0 or backlog < 0. func ThrottlePerIP(limit int, timeout time.Duration, keyFn func(*http.Request) string) func(http.Handler) http.Handler ThrottlePerIP limits concurrent handler executions per client key. keyFn extracts the rate-limit key from the request; if nil, the host part of r.RemoteAddr is used. limit is the maximum concurrent requests per key; timeout is how long a request waits for a slot before receiving 503. SECURITY (DOS-2026-0002): when keyFn is nil, ThrottlePerIP keys on r.RemoteAddr — which is whatever the TCP peer's address is unless RealIP has previously rewritten it. Behind a load balancer that does not strip the LB's own address from RemoteAddr, every request appears to come from the LB and the per-IP limit degrades to a global rate limit. RealIP (with explicit trusted-proxy CIDRs) MUST be registered BEFORE ThrottlePerIP for per-client limits to be effective. See SECURITY.md "RealIP + ThrottlePerIP ordering". SECURITY (MSR-2026-0068): the internal per-key table is capped at DefaultThrottlePerIPMaxTableSize. When full, requests for NEW keys (those not already in the table) receive 503 immediately to bound memory under IP-churn attacks. Use ThrottlePerIPCapped to override the cap. Panics if limit <= 0. func ThrottlePerIPCapped(limit int, timeout time.Duration, maxTableSize int, keyFn func(*http.Request) string) func(http.Handler) http.Handler ThrottlePerIPCapped is ThrottlePerIP with an explicit cap on the number of distinct keys tracked. maxTableSize <= 0 disables the cap (legacy unbounded behaviour, NOT recommended in production). SATURATION BEHAVIOUR (TM-2026-013, DOS-2026-0057): when the table reaches maxTableSize and every slot has refs > 0 (i.e. all entries are in active use), new client IPs receive 503 immediately until at least one slot drains. An attacker controlling N >= maxTableSize distinct IPs can sustain this state for as long as their requests stay open. Mitigations: - deploy upstream DDoS scrubbing (Cloudflare, AWS Shield, etc.); - configure http.Server{ReadHeaderTimeout, IdleTimeout, ReadTimeout} so slow-handler connections cannot hold slots indefinitely; - lower maxTableSize for sensitive endpoints. Panics if limit <= 0. func Timeout(d time.Duration) func(http.Handler) http.Handler Timeout applies a context deadline to each request. Panics if d <= 0. SECURITY (DOS-2026-0003): Timeout cancels the request context after d, but it does NOT preempt the handler goroutine — Go has no preemption primitive for blocked syscalls. Handlers MUST observe ctx.Done() on every blocking call (DB, network, file I/O); a handler that ignores ctx.Done() will run to completion regardless of the timeout, accumulating goroutines under load and exhausting memory or upstream connections. Co-design Timeout with handler-level cooperation (use the *Context variants of the stdlib — sql.DB.QueryContext, net/http with http.Request, etc.). func WithValue(key, val any) func(http.Handler) http.Handler WithValue injects a value into the request context. To avoid context key collisions between packages, always use an unexported type as the key: type ctxKey struct{} mux.Use(middleware.WithValue(ctxKey{}, myValue)) MSR-2026-0059: passing a string (or any built-in type) as the key is a CWE-1021 cross-package collision risk — any package that uses the same string literal can read or overwrite this value. WithValue emits a slog.Warn at construction time when called with a string-kind key. TYPES type APIKeyOptions struct { // Keys maps raw API key values to identity strings injected into the request context. // Panics if nil or empty. Keys map[string]string // Header is the request header name to read when ExtractFn is nil. Default: "X-API-Key". Header string // ExtractFn overrides key extraction. If nil, the Header field is used. ExtractFn func(*http.Request) string } APIKeyOptions configures the APIKey middleware. type CORSOptions struct { AllowedOrigins []string AllowedMethods []string AllowedHeaders []string ExposedHeaders []string AllowCredentials bool MaxAge int } CORSOptions configures CORS behaviour. type IntrospectResponse struct { Active bool Subject string Scope string ClientID string Username string TokenType string ExpiresAt time.Time IssuedAt time.Time NotBefore time.Time Issuer string Audience []string } IntrospectResponse holds the RFC 7662 token introspection response fields. func GetOAuth2Claims(ctx context.Context) (*IntrospectResponse, bool) GetOAuth2Claims returns the IntrospectResponse injected by the OAuth2Introspect middleware. type JWTClaims struct { Subject string Issuer string Audience []string ExpiresAt time.Time IssuedAt time.Time NotBefore time.Time // RawPayload is the decoded JSON payload bytes, available for extracting custom claims. RawPayload []byte } JWTClaims holds the standard JWT claims extracted from a validated token. Custom claims can be unmarshalled from RawPayload. func GetJWTClaims(ctx context.Context) (*JWTClaims, bool) GetJWTClaims returns the JWT claims injected by the JWTAuth middleware. type JWTOptions struct { // Secret is the HMAC signing key, required for HS256, HS384, HS512. Secret []byte // PublicKey is the RSA or ECDSA public key, required for RS*/ES* algorithms. PublicKey crypto.PublicKey // Algorithms lists accepted signing algorithms. Must be non-empty. // Supported: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512. // SEE the SECURITY note on JWTOptions about mixing families. Algorithms []string // Issuers, if non-empty, restricts accepted "iss" claim values. Issuers []string // Audiences, if non-empty, requires at least one "aud" entry to match. Audiences []string // ClockSkew is the permitted clock drift applied to exp and nbf checks. Default: 0. ClockSkew time.Duration // RequireExpiry, when true, rejects any token whose payload has no "exp" // claim. RFC 8725 §4.4 recommends rejecting tokens without expiry unless // there is a compelling reason: a stolen token without "exp" is valid // indefinitely (TM-2026-001). // // SECURITY: production deployments SHOULD set RequireExpiry: true. The // default is false ONLY for backward compatibility with code written // before this option existed. JWTAuth emits a slog.Warn at construction // time when this option is left at the unsafe default so the // misconfiguration is visible in startup logs. // // Default: false (backward compatible — DO NOT use in production). RequireExpiry bool } JWTOptions configures the JWTAuth middleware. SECURITY (TSC-2026-0003): mixing algorithm families (HS* with RS* or ES*) in Algorithms leaks the algorithm path via response latency. HMAC verifies in ~1 µs, RSA-2048 verifies in ~300 µs, and an attacker submitting tokens with different alg labels can determine which path the server runs from the response time alone — narrowing the attack surface for algorithm-confusion attacks (RFC 8725 §3.1). Configure each endpoint with a single algorithm family. JWTAuth emits a slog.Warn at construction time when a mixed-family Algorithms list is detected. type OAuth2Options struct { // Endpoint is the RFC 7662 introspection URL. Required. // MUST use the https:// scheme — bearer tokens transmitted over plaintext // are exposed to passive observers and MITM attackers (RFC 7662 §4 / RFC // 6749 §1.6). Construction panics on a non-HTTPS endpoint unless // AllowInsecureEndpoint is explicitly set to true (testing/localhost only). Endpoint string // AllowInsecureEndpoint disables the HTTPS-only enforcement on Endpoint. // Set to true ONLY for testing or trusted-local-loopback deployments — // production traffic must always use HTTPS. When true, a one-time slog // warning is emitted at construction time. Default: false. AllowInsecureEndpoint bool // ClientID and ClientSecret authenticate to the introspection endpoint via HTTP Basic. ClientID string ClientSecret string // CacheTTL is how long active tokens are cached. Default: 60s. // Set to -1 (or any negative value) to disable caching entirely — every // request hits the introspection endpoint, eliminating the cache-poisoning // blast radius (MSR-2026-0063) at the cost of higher IDP load. Use // disabled caching for high-security endpoints; the singleflight group // (DOS-OAUTH2-001 fix) still coalesces concurrent introspection calls // for the same token. // Cache respects the token's own exp: effective TTL = min(CacheTTL, token.exp - now). // Note: caching means revoked tokens remain valid until TTL expires. CacheTTL time.Duration // MaxCacheSize caps the number of cached active tokens. Default: 10000. MaxCacheSize int // HTTPClient is used for introspection requests. Default: 10s timeout. HTTPClient *http.Client // ExtractFn overrides token extraction. Default: "Authorization: Bearer ". ExtractFn func(*http.Request) string } OAuth2Options configures the OAuth2Introspect middleware. ``` ## Common questions
### What does `mux.New()` return? `mux.New()` returns a `*mux.Mux` — the value that holds the radix tree, the middleware stack, and the configuration options. It implements `http.Handler`, so any standard-library construct that consumes a handler (`http.Server`, `httptest.NewServer`, `http.StripPrefix`, etc.) accepts it directly.
### How do I register a route on a method other than GET? Call the matching helper on the mux: `m.POST`, `m.PUT`, `m.PATCH`, `m.DELETE`, `m.HEAD`, `m.OPTIONS`. Each takes the same `(pattern, handler)` arguments as `m.GET` and registers the handler against the same radix tree under the corresponding method bucket. ### How do I declare a path parameter? Prefix the path segment with a colon — for example `/users/:id`. Read the matched value inside the handler with `muxmaster.PathParam(r, "id")`. Catch-all parameters use the `*` prefix and must be the last segment of the pattern.
### How do I attach middleware to every route on a router? Call `m.Use(middleware)` before registering routes. The middleware wraps every handler the router dispatches; attach it in the order you want it to run on the request path (the first `Use` call is the outermost layer). ### What's the difference between `Use` and `Pre`? `Pre` middleware runs before the radix-tree lookup — it sees the raw URL and can rewrite it (the canonical use case is `RealIP` and `CleanPath`). `Use` middleware runs after route resolution — it sees the matched handler and can short-circuit, log, or wrap the response.
### How do I create a route group with a shared prefix? Call `m.Group("/api/v1")`. The returned `*Group` exposes the same routing methods as the mux; routes registered on the group inherit the prefix and any group-scoped middleware. ### Can I attach middleware to only the routes inside a group? Yes — call `g.Use(middleware)` on the group. The middleware wraps every handler registered on the group (including nested sub-groups) and does not affect routes outside the group.
### How do I return an error from a handler instead of writing the response manually? Register the handler with `m.HandleFuncE(method, pattern, handler)` where the handler signature is `func(http.ResponseWriter, *http.Request) error`. A non-nil return invokes the configured `ErrorHandler`, which translates the error to an HTTP response. ### How do I customise the default error response? Set `mux.Config.ErrorHandler` (or pass `mux.WithErrorHandler` at construction). The handler receives the original error plus the response writer and request; it is responsible for writing the final status, headers, and body.
### How do I write a JSON response from a handler? Call `mux.JSON(w, status, value)` — the helper sets `Content-Type: application/json; charset=utf-8`, encodes `value` with the standard library's encoder, writes the status, and returns any encoder error so the caller can decide whether to log it. ### How do I serve a conditional-GET response? Call `mux.IfNoneMatch(w, r, etag)` (or `IfModifiedSince`) before writing the body. The helper returns true and writes the 304 short-circuit when the request's conditional header matches; on false, the handler proceeds to write the full response.
### When should I use `FastHandler` instead of `http.HandlerFunc`? Use `mux.FastHandler` only on routes that need to bypass the standard `http.ResponseWriter` allocation cost on the hottest paths (typical use case: a health probe or a synthetic load endpoint). For ordinary application code, prefer `http.HandlerFunc` so middleware composition stays straightforward.
### How do I list every registered route at runtime? Call `m.Routes()`. The result is a slice of `RouteInfo` values describing each method/pattern pair, the registration order, and the middleware stack the handler sees. Suitable for an admin endpoint or a startup audit. ### How do I read request counters from a live router? Call `m.Stats()`. The map is keyed by route pattern and exposes hit counters, plus the global request total and the count of 404s. Suitable for scraping into a metrics endpoint.