On this page

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 MethodQuery constant and Mux.QUERY, Mux.QUERYE, Mux.QUERYFast, Group.QUERY, and Group.QUERYE. ANY now registers QUERY, the Allow header lists it, and the router's own redirects on QUERY routes use 307 so the method and body are preserved. Go's net/http does not yet define http.MethodQuery (golang/go#80058); MethodQuery is guaranteed to equal "QUERY".
  • Mount works correctly with nested routers. An inner *Mux's own trailing-slash and fixed-path redirects now keep the mount prefix in Location; RawPath is 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 is nil.
  • Redirect and middleware behaviour. Redirect targets percent-encode \ as %5C and control bytes per RFC 9110; BasicAuth compares credentials in constant time across all users; CORS adds Vary: Origin to every response; OAuth2Introspect redacts credentials in construction-time panics and keeps request-scoped context values in shared introspection calls; Recoverer writes 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, and OAuth2Introspect cost 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 -count are not recorded upstream; source: upstream CHANGELOG.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 ServeHTTP receives a *http.Request built as a struct literal (nil context).
  • An inner *Mux's own redirect through Mount now keeps the mount prefix (/api/users → /api/users/, previously /users/).
  • StripSlashes keeps RawPath consistent with Path for 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 with muxmaster: 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 Mount prefix 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:

  • Compress and Logger implement http.Flusher and Unwrap(); Logger also implements io.ReaderFrom, so sendfile stays 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-proxy no longer fails under PoolRequestBundle = 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, and Handle("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