
# 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](/releases/v1.1.0) (2026-05-12)
**Comparison:** [v1.1.0...v1.2.0](https://github.com/FlavioCFOliveira/MuxMaster/compare/v1.1.0...v1.2.0)

---

## Executive summary

MuxMaster v1.2.0 adds first-class support for the [HTTP QUERY method (RFC 10008)](/docs/http-query-method), 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](#upgrade-notes) before you upgrade.

---

## Highlights

- **[HTTP QUERY method (RFC 10008)](/docs/http-query-method).** 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`](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/CHANGELOG.md) `[1.2.0]`. Re-measured on 2026-09-26: see [/benchmarks](/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](/changelog#120---2026-09-26). 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`](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/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](/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](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/reports/perf-lab-2026-09-26-docs/README.md). Re-measured on 2026-09-26: see [/benchmarks](/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`](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/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](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/reports/perf-lab-2026-09-26-docs/README.md)). Re-measured on 2026-09-26: see [/benchmarks](/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](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/reports/perf-lab-2026-09-26-docs/README.md) §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`](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.2.0/CHANGELOG.md) `[1.2.0]`). Re-measured on 2026-09-26: see [/benchmarks](/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

```bash
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
