# MuxMaster

> MuxMaster is a high-performance, zero-dependency HTTP router for Go. It provides a radix-tree implementation with O(k) lookups, zero allocations on static routes, and 100% compatibility with `net/http`. Since v1.1.0 the opt-in `Mux.PoolRequestBundle` flag drives parameterised routes to 45 ns / 0 B / 0 allocs on a single parameter — 20 % faster than `httprouter`, and the only stdlib-compatible router that achieves zero allocations on parameterised routes. It supports the minimum Go version stated on /compatibility.

## Documentation

- [Documentation](https://muxmaster.net/docs/): Index of MuxMaster documentation: getting started, routing, groups, middleware, error handling, configuration, performance, observability, and the cookbook.
- [Configuration](https://muxmaster.net/docs/configuration): RedirectTrailingSlash, RedirectFixedPath, HandleMethodNotAllowed, CaseInsensitive, NotFound, MethodNotAllowed, and the security-relevant defaults.
- [Cookbook](https://muxmaster.net/docs/cookbook): Recipes for the patterns that come up most often: graceful shutdown, file uploads, server-sent events, static files, and more.
- [Error handling](https://muxmaster.net/docs/error-handling): HandlerFuncE, HTTPError, and the typed error pipeline. How errors are surfaced, logged, rendered, and turned into HTTP responses.
- [Getting started](https://muxmaster.net/docs/getting-started): Install MuxMaster, register a route, run the server, and verify the response. The shortest path to a running router.
- [Groups](https://muxmaster.net/docs/groups): Compose route prefixes, scoped middleware, and nested groups with mux.Group. Includes the With, Route, and Mount idioms with worked examples.
- [Maximum performance](https://muxmaster.net/docs/max-performance): Zero-allocation hot path with PoolRequestBundle and PoolFastParams: the lifetime contract, the failure modes, and four recipes. 45 ns / 0 B / 0 allocs on a 1-param route.
- [Middleware](https://muxmaster.net/docs/middleware): The 17 bundled middleware constructors covering request lifecycle (RequestID, Recoverer, Logger), transport (Compress, RealIP, CleanPath, StripSlashes, NoCache, SetHeader), throughput (Timeout, Throttle), and authentication (BasicAuth, APIKey, JWTAuth, OAuth2Introspect, CORS).
- [Migration](https://muxmaster.net/docs/migration): Mapping idioms from net/http, gorilla/mux, chi, gin, and httprouter onto MuxMaster. Side-by-side examples for the most common migration paths.
- [Observability](https://muxmaster.net/docs/observability): Structured logging with slog, RequestID correlation, custom Prometheus metrics middleware, OpenTelemetry tracing, health checks, and pprof.
- [Performance](https://muxmaster.net/docs/performance): Allocation profile, FastHandler, the radix-tree lookup cost model, and the benchmarks that back the documented latency and throughput numbers.
- [Response helpers](https://muxmaster.net/docs/response-helpers): JSON, XML, Text, Redirect, NoContent, and the typed Params accessors that read URL parameters without reflection or per-request allocation.
- [Routing](https://muxmaster.net/docs/routing): Define static, parametric, and catch-all routes; pattern syntax; match precedence; and the trade-offs the MuxMaster radix tree makes.

## API

- [API reference](https://muxmaster.net/api): Complete API reference for MuxMaster: every exported type, function, method, and field, with signatures and behavioural notes.

## Examples

- [Examples](https://muxmaster.net/examples/): Thirteen runnable MuxMaster examples: REST API, maximum-performance opt-ins, versioning, SSE, file upload, reverse proxy, auth (Basic/JWT/OAuth2), cache, SSR, more.
- [Authentication example](https://muxmaster.net/examples/authn): HTTP Basic Authentication via the BasicAuth middleware, paired with ThrottlePerIP to defend against credential-stuffing attacks.
- [Cache example](https://muxmaster.net/examples/cache): An in-memory TTL cache that avoids re-computing identical responses within a configurable horizon. For expensive, idempotent handlers.
- [Graceful shutdown example](https://muxmaster.net/examples/graceful-shutdown): Production graceful shutdown: signal handling, srv.Shutdown with a bounded drain deadline, and the recommended Server timeout set for real deployments.
- [JWT example](https://muxmaster.net/examples/jwt): Bearer-token authentication via the JWTAuth middleware. Configures RequireExpiry: true (RFC 8725 §4.4) and shows the canonical OIDC integration shape.
- [Maximum-performance example](https://muxmaster.net/examples/max-performance): Every v1.1.0 opt-in combined: PoolRequestBundle, PoolFastParams, HandleFast, UseFast, Mounted pprof, plus an in-process /bench endpoint that reports the live 2.4x speed-up.
- [OAuth2 example](https://muxmaster.net/examples/oauth2): OAuth 2.0 token introspection (RFC 7662) via the OAuth2Introspect middleware. Tokens are validated against an authorisation server, not locally.
- [REST API example](https://muxmaster.net/examples/rest-api): A complete REST API built with MuxMaster: route grouping, JSON responses, parameter parsing, and a small in-memory store. CRUD over a single resource.
- [Reverse-proxy example](https://muxmaster.net/examples/reverse-proxy): HTTP gateway with httputil.ReverseProxy on MuxMaster: catch-all routing, lock-free round-robin load balancing, per-route gating, and pool-safe synchronous dispatch.
- [Server-sent events example](https://muxmaster.net/examples/server-sent-events): Pool-safe SSE streaming on MuxMaster: topic-hub fan-out, drop-on-slow-subscriber backpressure, periodic server tick, and an in-browser demo page.
- [Server-side render example](https://muxmaster.net/examples/server-side-render): A multi-page guestbook rendered by Go's html/template. The same SSR pattern that powers this documentation website you are reading now.
- [Static site example](https://muxmaster.net/examples/static-site): Conditional GET (304 via ETag and Last-Modified) and range requests (206) on top of MuxMaster's ServeFiles primitive. Production static-asset semantics.
- [Upload-file example](https://muxmaster.net/examples/upload-file): Multipart upload with PoolRequestBundle: single + multi + async handlers, the body-drain-before-spawn pattern, 32 MiB caps, path-traversal guard, streaming SHA-256.
- [Versioning example](https://muxmaster.net/examples/versioning): Path-based (/v1, /v2) and header-based (Accept: ...;v=N) API versioning on the same router, with nested admin groups and PoolRequestBundle for zero-alloc dispatch.

## Reference

- [Benchmarks](https://muxmaster.net/benchmarks): MuxMaster v1.1.0 benchmarks: 25 ns static, 45 ns / 0 alloc one-parameter Pooled, with a competitor table vs httprouter, Fiber v3, bunrouter, chi v5, gorilla/mux.
- [Changelog](https://muxmaster.net/changelog): The full upstream changelog: every released version of MuxMaster with one section per release, ordered newest-first. Mirrors CHANGELOG.md.
- [Release notes — v1.0.0](https://muxmaster.net/releases/v1.0.0): Release notes for MuxMaster v1.0.0, the first general-availability release. Public API frozen, security guarantees stated, performance baseline established.
- [Release notes — v1.1.0](https://muxmaster.net/releases/v1.1.0): MuxMaster v1.1.0 release notes: 45 ns / 0 B / 0 allocs Pooled hot path, five new examples, /docs/max-performance guide. Backward-compatible with v1.0.x.
- [Security](https://muxmaster.net/security): MuxMaster's security policy, threat model, resolved findings, and the operator-facing defaults that require explicit opt-in.
- [Compatibility](https://muxmaster.net/compatibility): Supported Go versions, the four-tier SemVer guarantee policy, and the net/http interoperability contract that MuxMaster preserves end-to-end.
- [Contributing](https://muxmaster.net/contributing): How to contribute to MuxMaster: branch policy, tests, security-review expectations, and the gatekeeper-agent workflow that gates every merge.

## Optional

- [GitHub repository](https://github.com/FlavioCFOliveira/MuxMaster): canonical source for MuxMaster.