MuxMaster v1.2.0 — Release Notes
Version: v1.2.0
Date: 2026-09-26
Type: Minor — backward-compatible additions, bug fixes, and behaviour changes to redirects and middleware
Module: github.com/FlavioCFOliveira/MuxMaster
Go: 1.26 or newer (unchanged)
Previous release: v1.1.0 (2026-05-12)
Comparison: v1.1.0...v1.2.0
Executive summary
MuxMaster v1.2.0 adds first-class support for the HTTP QUERY method (RFC 10008), fixes a set of routing, Mount, Group, and middleware defects, changes the behaviour of redirects and of four middleware (BasicAuth, CORS, OAuth2Introspect, and Recoverer), and removes waste from route registration and several middleware. It is the product of sprints 18 to 21: 88 commits since v1.1.0.
The exported API is a strict superset of v1.1.0. apidiff against the v1.1.0 tag reports six compatible additions and no incompatible change in the root package, and no change at all in the middleware package. The module still has zero external dependencies.
Several fixes change observable behaviour. Most of them turn a panic, a wrong status, or a silently corrupted response into the documented result, but some programs can notice the difference. Read Upgrade notes before you upgrade.
Highlights
- HTTP QUERY method (RFC 10008). New
MethodQueryconstant andMux.QUERY,Mux.QUERYE,Mux.QUERYFast,Group.QUERY, andGroup.QUERYE.ANYnow registers QUERY, theAllowheader lists it, and the router's own redirects on QUERY routes use307so the method and body are preserved. Go'snet/httpdoes not yet definehttp.MethodQuery(golang/go#80058);MethodQueryis guaranteed to equal"QUERY". Mountworks correctly with nested routers. An inner*Mux's own trailing-slash and fixed-path redirects now keep the mount prefix inLocation;RawPathis propagated through parameterised prefixes; a prefix that ends in an optional parameter panics at registration with a message that names the cause.- Routing correctness. A named or regex parameter no longer captures an empty path segment; a static route can be registered next to a parameter sibling in either order; a request that does not match a static branch falls back to its parameter sibling; an unclosed
{panics instead of silently overwriting a route; parameter routes no longer panic on a request whose context isnil. - Redirect and middleware behaviour. Redirect targets percent-encode
\as%5Cand control bytes per RFC 9110;BasicAuthcompares credentials in constant time across all users;CORSaddsVary: Originto every response;OAuth2Introspectredacts credentials in construction-time panics and keeps request-scoped context values in shared introspection calls;Recovererwrites its 500 response only when the handler has not started one. - Faster registration and leaner middleware. Registration copies O(depth) instead of O(tree size) (5 000 routes: 2.86 s → 4.7 ms).
ThrottlePerIP,Logger,Compress,JWTAuth,RealIP,APIKey,RequestID, andOAuth2Introspectcost less time or fewer allocations. The request hot path allocates exactly as much as in v1.1.0. The registration figures are upstream measurements from the sprint 18 waste-hunt campaign on an AMD Ryzen 9 5900HX with go1.27.0; their measurement date and-countare not recorded upstream; source: upstreamCHANGELOG.md[1.2.0]. Re-measured on 2026-09-26: see /benchmarks.
Upgrade notes
The list below covers every change a program written for v1.1.0 can observe. Each item was reproduced by running the same probe program against the v1.1.0 tag and against the release commit (Go 1.27.0, linux/amd64).
Changes that can make a working v1.1.0 program behave differently
| Change | v1.1.0 | v1.2.0 | What to check |
|---|---|---|---|
Group prefix join (rmp #282). Group("/api/") followed by GET("/users") |
Registers /api//users (plain concatenation, as the v1.1.0 specification stated) |
Registers /api/users; exactly one / is dropped at the join |
Groups whose prefix ends in /. If the program also registers the joined path directly (for example mux.GET("/api/users")), registration now panics with a duplicate-route error. Applies to Group.Handle, Group.HandleFast, Group.Group, Group.Mount, and Group.ServeFiles. |
ANY includes QUERY |
A QUERY request to an ANY route gets 405 (or 404) |
The ANY handler receives it |
ANY handlers that assume a fixed method set. |
Empty segments no longer match parameters (rmp #283). /:id/posts against //posts |
200, id = "" |
404 (or the ordinary redirect sequence) |
Clients that relied on a doubled / reaching a parameter route. |
Static-to-parameter fallback (rmp #259). /users/list and /users/:id, request /users/listx |
404 |
200, id = "listx" |
Parameter handlers must validate values that begin with a static sibling's name. |
CORS sends Vary: Origin on every response |
Only on a matched, non-wildcard origin | Always, including requests without Origin and CORS's own 400/403 responses |
Caches and tests that assert exact Vary values. Cost: +1 allocation (112 B) and about +45 ns on the no-Origin path. |
Recoverer after a started response |
Appends Internal Server Error\n to the body already written |
Leaves the started response untouched; the panic is still logged | Tests that assert the appended text. |
Mount, ServeFiles, CleanPath, StripSlashes build a shallow request copy (rmp #250) |
r.Clone(): the inner handler received its own header map |
The copy shares the header map and context with the original, as http.StripPrefix does |
A mounted handler that mutates r.Header is now visible to outer middleware that reads r.Header after next.ServeHTTP returns. |
Trailing-slash redirect for catch-all routes and bare Mount prefixes (rmp #255) |
/api for Mount("/api", h) and /s for GET("/s/*fp") return 404 |
301 to /api/ and /s/ (when RedirectTrailingSlash is true, the default) |
Clients that call the bare prefix. |
Redirect Location encoding |
\ and control bytes copied verbatim |
\ becomes %5C; bytes 0x00–0x1F and 0x7F are percent-encoded |
Redirect targets that contain those bytes. |
Changes that turn a failure into success
- A static route registered after a parameter sibling (
/books/:id, then/books/featured) no longer panics. - A parameter route no longer panics when
ServeHTTPreceives a*http.Requestbuilt as a struct literal (nil context). - An inner
*Mux's own redirect throughMountnow keeps the mount prefix (/api/users→/api/users/, previously/users/). StripSlasheskeepsRawPathconsistent withPathfor an encoded trailing slash (/a%2f).
Changes that turn silent corruption into a registration panic
- A pattern with an unclosed
{(for example/a/{id) panics withmuxmaster: regex param '{' in path '<pattern>' is missing its closing '}'. In v1.1.0 it silently replaced the handler of an existing route. Programs that start successfully on v1.1.0 but contain such a pattern will panic at startup on v1.2.0; the pattern was never routable as intended. - A
Mountprefix that ends in an optional parameter still panics, but the message now names the prefix and the cause.
Fixes
The complete list, with rationale, specification references, and regression tests, is in the [1.2.0] entry of CHANGELOG.md. Beyond the items above, it covers:
CompressandLoggerimplementhttp.FlusherandUnwrap();Loggeralso implementsio.ReaderFrom, sosendfilestays available behind it.- Registration rollback: a registration that panics mid-insert leaves the live tree untouched.
- Five examples that panicked at startup (
authn,cache,jwt,static-site,rest-api) now start;reverse-proxyno longer fails underPoolRequestBundle = true. - Documentation, GoDoc,
api.md, and the specification were checked against the code and corrected (sprint 21), including the statement that custom HTTP methods are not supported: the method set is closed, andHandle("PURGE", ...)panics, as it already did in v1.1.0.
Performance
Source: reports/perf-lab-2026-09-26-docs/README.md. Host: AMD Ryzen 9 5900HX (8 cores, 16 threads), Linux 6.8, Go 1.27.0, CPU governor powersave, -count=3 for every suite. Date: 2026-09-26. Measured commit: bc4edb7, which precedes the v1.2.0 tag.
Website note. The figures in this section are the upstream measurements quoted in the release notes (
-count=3, Go 1.27.0). This website's own benchmark campaign (2026-09-26, AMD Ryzen 9 5900HX, go1.27.1,-count=10) measured v1.1.0 against v1.3.0 with significance tests; its results are on the Benchmarks page.
Request hot path: unchanged
The 18 routing benchmarks shared by v1.1.0 and v1.2.0 have identical B/op and allocs/op. With three samples per side, benchstat marks every ns/op delta as not significant; read the ns/op columns as point estimates, not as a regression or an improvement.
Figures: upstream measurements, AMD Ryzen 9 5900HX, Go 1.27.0, 2026-09-26, -count=3; source: perf-lab report. Re-measured on 2026-09-26: see /benchmarks.
| Benchmark | v1.1.0 ns/op | v1.2.0 ns/op | B/op | allocs/op |
|---|---|---|---|---|
| Static route | 26.95 | 28.63 | 0 | 0 |
| 1 parameter | 119.5 | 118.5 | 384 | 1 |
| Catch-all | 109.5 | 132.4 | 384 | 1 |
| Fast, 1 parameter | 43.31 | 46.15 | 32 | 1 |
| Pooled, 1 parameter | 42.20 | 48.51 | 0 | 0 |
| Pooled, parallel parameter | 6.347 | 6.901 | 0 | 0 |
The report notes that a few rows (static, catch-all, fast two-parameter) read slightly higher on v1.2.0 in all three samples; confirming or refuting that needs a -count=10 run on a host pinned to the performance governor.
Sprint 18 gains, re-measured on the release code
All 18 verifiable sprint 18 claims reproduced on 2026-09-26; several measure better than first recorded.
Figures: the "Before" and "Recorded after" columns are upstream sprint 18 measurements on an AMD Ryzen 9 5900HX with go1.27.0, whose measurement date and -count are not recorded upstream (source: upstream CHANGELOG.md [1.2.0]); the "Re-measured" column is the upstream run of 2026-09-26 on an AMD Ryzen 9 5900HX with Go 1.27.0, -count=3 (source: perf-lab report). Re-measured on 2026-09-26: see /benchmarks.
| Change | Before | Recorded after | Re-measured |
|---|---|---|---|
| Registration, 5 000 routes | 2.86 s | 4.7 ms | 4.70 ms |
| Registration, 1 000 routes | 90.6 ms | 0.65 ms | 0.693 ms |
Mount request copy |
1 024 ns, 9 allocs | 243 ns, 3 allocs | 237.5 ns, 2 allocs |
CleanPath (dirty path) |
810 ns, 7 allocs | 132 ns, 2 allocs | 145.4 ns, 2 allocs |
ThrottlePerIP |
4 051 ns, 5 allocs | 118 ns, 0 allocs | 115.0 ns, 0 allocs |
Logger |
7.5 µs, 5 allocs | 5.7 µs, 0 allocs | 5.67 µs, 0 allocs |
Compress, chunked 12 KiB |
14.6 µs, 16 allocs | 8.1 µs, 3 allocs | 7.77 µs, 3 allocs |
JWTAuth HS256 |
5.16 µs, 10 allocs | 4.44 µs, 7 allocs | 4.35 µs, 7 allocs |
Automatic OPTIONS |
124 ns, 3 allocs | 61 ns, 1 alloc | 61.9 ns, 1 alloc |
Costs of the behaviour changes
Figures: upstream measurements on an AMD Ryzen 9 5900HX. The BasicAuth figures and the re-measured Recoverer value come from the upstream run of 2026-09-26 with Go 1.27.0, -count=3 (source: perf-lab report §2). The CORS and Recoverer before and after values use -count=10; their Go version and measurement date are not recorded upstream (source: upstream CHANGELOG.md [1.2.0]). Re-measured on 2026-09-26: see /benchmarks.
| Change | Measured cost | Source |
|---|---|---|
BasicAuth constant-time scan |
Hit ≈ 320 / 550 / 2 836 ns and miss ≈ 733 / 959 / 3 232 ns for 1 / 10 / 100 users (O(users) per request) | perf-lab 2026-09-26 §2 |
CORS Vary: Origin |
No-Origin path 25.7 → 71.0 ns, 0 → 1 allocation (112 B); other paths unchanged |
CHANGELOG, benchstat -count=10 |
Recoverer response tracking |
No-panic path 8.4 → 19.4 ns, 0 allocations before and after (≈ 20 ns re-measured) | CHANGELOG, -count=10; perf-lab 2026-09-26 §2 |
Test evidence summary
All checks ran on develop at da64afd on 2026-09-26 (the release edits that follow change Markdown files only): Linux 6.8, AMD Ryzen 9 5900HX, Go 1.27.0. CI runs the same gates with the Go version declared in go.mod (1.26).
| Check | Command | Result |
|---|---|---|
| Build | go build ./... |
pass |
| Vet | make vet |
clean |
| Lint | make lint (golangci-lint run 2.14.0, staticcheck 2026.2.1) |
0 issues |
| Go advisory database | govulncheck ./... (v1.7.0) |
no advisories found |
| API reference | make api, then git diff --exit-code api.md |
no diff |
| API compatibility | apidiff against v1.1.0 (root and middleware) |
6 compatible additions, 0 incompatible |
| Tests with race detector | make test-race (the same command as the release.yml test gate) |
pass: 2 packages; 1 533 tests, subtests, and fuzz seeds passed, 0 failed, 2 fuzz seed inputs skipped by the target's input filter |
| Coverage | go test -coverprofile … $(go list ./... | grep -v /reports/) |
91.9 % total (root 89.9 %, middleware 94.5 %); CI gate ≥ 80 % |
| Examples | go build ./... && go vet ./... in each of the 13 example modules |
13/13 pass |
Acknowledgements
This release is the product of sprints 18 (performance and efficiency laboratory), 19 (QUERY method), 20 (backlog clearance), and 21 (documentation truth pass), and of the specialised performance agents whose measurements are archived under reports/.
Verifying this release
go get github.com/FlavioCFOliveira/MuxMaster@v1.2.0
go mod download -json github.com/FlavioCFOliveira/MuxMaster@v1.2.0 | jq -r .Sum
The GitHub Release carries a CycloneDX SBOM (sbom.json) generated by release.yml.
Maintainer: flavio cf oliveira
License: see LICENSE at the repository root
Issue tracker: https://github.com/FlavioCFOliveira/MuxMaster/issues