
# MuxMaster v1.3.0 — Release Notes

**Version:** v1.3.0
**Date:** 2026-09-26
**Type:** Minor — minimum Go version raised to 1.27.1; bug fixes and a stricter `Group.ServeFiles` registration check
**Module:** `github.com/FlavioCFOliveira/MuxMaster`
**Go:** 1.27.1 or newer (was 1.26)
**Previous release:** [v1.2.0](/releases/v1.2.0) (2026-09-26)
**Comparison:** [v1.2.0...v1.3.0](https://github.com/FlavioCFOliveira/MuxMaster/compare/v1.2.0...v1.3.0)

---

## Executive summary

MuxMaster v1.3.0 raises the minimum Go version to 1.27.1, fixes ephemeral-port exhaustion in the default `OAuth2Introspect` introspection client, makes `Group.ServeFiles` apply the same raw-path guard as `Mux.ServeFiles`, and repairs the CI, commitlint, and release workflows. It is the product of sprint 22.

Raising the minimum Go version is a MINOR change under the project's [Go version policy](/compatibility#go-version-policy), which follows the Go core team's guidance; this is why the release is v1.3.0 rather than v1.2.1.

The exported API is identical to v1.2.0: `apidiff` against the v1.2.0 tag reports no change, compatible or incompatible, in the root package or in the `middleware` package. The module still has zero external dependencies. Three changes can be observed by existing programs; read [Upgrade notes](#upgrade-notes) before you upgrade.

---

## Highlights

- **Go 1.27.1 minimum.** Every module now declares `go 1.27.1`. CI tests Go 1.27.1 and `stable` on Linux, macOS, and Windows, plus Linux/arm64.
- **`OAuth2Introspect` survives concurrent load with the default client.** The default client keeps connections alive and allows at most 100 connections to the introspection host, so a burst of cache misses no longer exhausts ephemeral ports and rejects valid tokens with `401`.
- **`Group.ServeFiles` raw-path guard.** `Group.ServeFiles` refuses to register in the unsafe `UseRawPath` + `UnescapePathValues` configuration, exactly as `Mux.ServeFiles` does. Both variants call one shared check.
- **Working release pipeline.** CI and commitlint run on every gitflow branch push, the `CHANGELOG.md` gate no longer fails spuriously, and `release.yml` passes the release notes by file, fixing the empty v1.2.0 GitHub Release body.

---

## Upgrade notes

### Go 1.27.1 or newer is required

`go.mod` now declares `go 1.27.1` (previously `go 1.26`). Go 1.26 and Go 1.27.0 are no longer supported.

- With the default `GOTOOLCHAIN=auto` (Go 1.21 or newer), the `go` command does not build with an older toolchain. It switches to Go 1.27.1 or newer: it first looks for a matching `go1.27.1` executable in `PATH`, and otherwise downloads and caches that toolchain.
- With `GOTOOLCHAIN=local`, or any setting that prevents switching, the build fails with an error stating that the module requires `go >= 1.27.1`. Upgrade the local toolchain, or allow switching.
- A consuming module's own `go` directive is raised to at least `1.27.1` by `go get github.com/FlavioCFOliveira/MuxMaster@v1.3.0`.

The precise behaviour is specified in [`specification/compatibility.md`](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.3.0/specification/compatibility.md) (requirement 4) and follows the [Go toolchain documentation](https://go.dev/doc/toolchain).

### `OAuth2Introspect` default client (only when `HTTPClient` is nil)

In v1.2.0, the default client was `&http.Client{Timeout: 10 * time.Second}`, which uses `http.DefaultTransport` directly. That transport keeps only two idle connections per host, so concurrent introspection calls opened and closed a new TCP connection each; the resulting `TIME_WAIT` sockets could exhaust the ephemeral port range (notably on Windows) and every failed dial rejected a valid token with `401`.

In v1.3.0, the default client still has a 10-second timeout, but uses its own transport:

| Behaviour | v1.2.0 | v1.3.0 |
|---|---|---|
| Transport | `http.DefaultTransport` itself | A new `*http.Transport` that copies `http.DefaultTransport`'s settings (proxy, dialers, TLS configuration, timeouts, protocol selection) once, when `OAuth2Introspect` is called |
| Connections to the introspection host | Unbounded; 2 idle connections kept | At most 100, all kept alive (`MaxConnsPerHost` = `MaxIdleConnsPerHost` = `MaxIdleConns` = 100). The bound is exact for HTTP/1.1; over HTTP/2 the transport may open more |
| Calls beyond the limit | Open a new connection | Wait for a free connection; the wait counts toward the 10-second timeout |
| Later changes to `http.DefaultTransport` | Seen by the middleware | **Not seen**: the settings are copied at construction |
| Effect on `http.DefaultTransport` | — | None: it is neither modified nor initialised |

What to check:

- **Construct the middleware at startup**, before the process issues HTTP requests concurrently through `http.DefaultTransport`, and after any code that customises `http.DefaultTransport` (for example a proxy or TLS setting). Changes made after `OAuth2Introspect` is called do not reach the middleware.
- **Throughput above 100 concurrent introspection calls** to one host now queues instead of dialling. Size the cache (`CacheTTL`, `MaxCacheSize`) or supply your own client if a higher bound is needed.
- If `http.DefaultTransport` has been replaced with a type other than `*http.Transport`, it is used as is, as before.
- **Set `HTTPClient`** to choose any other settings; a non-nil `HTTPClient` is used unchanged, as in v1.2.0.

### `Group.ServeFiles` panics in the unsafe raw-path configuration

`Group.ServeFiles` now panics at registration when the owning `Mux` has both `UseRawPath` and `UnescapePathValues` set to `true` at the time of the call, with the same message as `Mux.ServeFiles`. A program that starts successfully on v1.2.0 with this combination panics at startup on v1.3.0. In that configuration the captured path can contain decoded `/` characters that `http.FileServer` treats as separators; disable one of the two options, or serve the files with a custom handler that cleans and confines the captured value.

---

## Fixes

The complete list is in the [`[1.3.0]` entry of CHANGELOG.md](/changelog#130---2026-09-26).

- **`OAuth2Introspect` default client** (rmp #300): own keep-alive transport with a 100-connection bound, built without calling any method of `http.DefaultTransport`. An earlier revision within this release cycle used `http.DefaultTransport.Clone()`, which runs the global transport's one-time HTTP/2 set-up and could silently downgrade `http.DefaultClient` to HTTP/1.1; it never shipped. A reflection test fails when a Go release adds an `http.Transport` field that the copy does not classify. Tests: `TestOAuth2Introspect_DefaultClient_BoundsConnectionsUnderConcurrency`, `middleware/oauth2_transport_test.go`, `middleware/oauth2_transport_internal_test.go`.
- **gosec reports** (rmp #301): three false positives resolved without weakening the scan and without behaviour change. `tree.go` saturates `maxParams` with an explicit `math.MaxUint8` check (`TestMaxParamsSaturatesAtUint8Max`); the redirect body escapes its target with `html.EscapeString`, whose output is byte-identical to `net/http.Redirect` (`TestWriteRedirect_ByteIdenticalToNetHTTPRedirect`); `Logger`'s intentional `int64`-to-`uint64` conversion carries a scoped justification.
- **Test suite** (rmp #303): no test outside `reports/` and `competitor/` calls `t.Skip`. `FuzzTSRRedirectSafety` checks empty, oversized, and `http.NewRequest`-rejected paths; the differential, order-independence, and `reqBundle` tests assert instead of skipping, which also fixes a latent integer-negation overflow in the order-independence test.

---

## CI and tooling

- **`ci.yml`** (rmp #304): runs on pushes to `main`, `develop`, `release/**`, and `hotfix/**`, and on pull requests against `main`. The `CHANGELOG.md updated` gate runs on push and no longer fails with `SIGPIPE` under `pipefail`. `apidiff` is advisory on push and blocking on pull requests. gosec v2.29.0 is installed with the `go.mod` toolchain, because the gosec action images cannot load a Go 1.27.1 module.
- **`commitlint.yml`**: validates pushed commit ranges as well as pull requests; merge commits are exempt by parent count.
- **`release.yml`**: writes the release notes extracted from `CHANGELOG.md` to a file and passes it with `body_path`, because GitHub masked the job output and left the v1.2.0 release body empty; tests the requested tag on manual runs; drops the unused `id-token` permission.
- **Actions**: `actions/checkout` v7.0.1, `actions/setup-go` v7.0.0, `golangci/golangci-lint-action` v9.3.0; golangci-lint v2.14.0 in CI and in the pre-push hook.
- **`dependabot.yml`**: covers the three security-harness modules that have third-party dependencies, and emits commit prefixes that pass commitlint.
- **Auxiliary modules** (not part of the published module): `golang.org/x/net` v0.59.0 and `golang.org/x/text` v0.42.0 (HTTP/2 harness); `github.com/go-chi/chi/v5` v5.3.2 and `github.com/stretchr/testify` v1.12.1 (routing-fuzzer harness and `competitor/`, re-vendored).
- **Branch protection**: [`.github/branch-protection.md`](https://github.com/FlavioCFOliveira/MuxMaster/blob/v1.3.0/.github/branch-protection.md) and the [contributing guide](/contributing) now describe a rule compatible with direct gitflow merges: it blocks force pushes and deletion of `main`, and cannot require pull requests, status checks, or linear history.

---

## Documentation and specification

- **Specification** (rmp #305): `routing.md` §16 (rules 110–114) specifies the remaining registration panics and that a panicking registration leaves the route tree unchanged; `groups.md` corrects rule 6 (a `Group` prefix is never validated at creation) and adds rule 45 (invalid UTF-8 `Mount` prefix); `static-files.md` item 11 covers both `ServeFiles` variants; `compatibility.md` specifies Go 1.27.1 and toolchain switching; `middleware-stdlib.md` specifies the `OAuth2Introspect` default client.
- **Reference documentation**: GoDoc, `api.md`, and `docs/middleware.md` describe the new `OAuth2Introspect` default client; `Group.ServeFiles` documents its panic; README, CONTRIBUTING, COMPATIBILITY, the guides, and the issue template state the Go 1.27.1 minimum.

---

## Performance

No change on the request hot path is expected: the only non-test changes to the root package are registration-time code (`maxParams` saturation, the `ServeFiles` guard) and the HTML escaping of the redirect body, whose output is byte-identical. No benchmark suite was run for this release; the v1.2.0 figures in the [v1.2.0 release notes](/releases/v1.2.0#performance) remain the latest measurements.

> **Website note.** The sentence above describes the upstream measurements available when v1.3.0 was released. This website ran its own benchmark campaign on v1.3.0 (2026-09-26, AMD Ryzen 9 5900HX, go1.27.1, `-count=10`), which compares v1.1.0 with v1.3.0 and v1.3.0 with other Go routers. Its results are on the [Benchmarks](/benchmarks) page.

---

## Test evidence summary

All checks ran on `release/1.3.0` at `4e6f9e5` on 2026-09-26 (the release edits that follow change Markdown files only): Linux 6.8, AMD Ryzen 9 5900HX, Go 1.27.1 linux/amd64, the version declared in `go.mod`.

| Check | Command | Result |
|---|---|---|
| Build | `go build ./...` | pass |
| Vet | `make vet` | clean |
| Lint | `make lint` (`golangci-lint run` 2.14.0, `staticcheck` 2026.2.1) | pass: 0 issues in both |
| SAST | `gosec -quiet -exclude-dir=reports -exclude-dir=competitor -severity=medium ./...` | 0 issues |
| Go advisory database | `govulncheck ./...` (v1.8.0) | no advisories found |
| API reference | `make api`, then `git diff --exit-code api.md` | no diff |
| API compatibility | `apidiff` against v1.2.0 (root and `middleware`) | no changes |
| Tests with race detector | `make test-race` (the same command as the `release.yml` test gate) | pass: 2 packages; 1 575 tests, subtests, and fuzz seeds passed, 0 failed, 0 skipped |
| Coverage | `go test -coverprofile … $(go list ./... \| grep -v /reports/)` | 92.0 % total (root 90.0 %, `middleware` 94.6 %); CI gate ≥ 80 % |
| Examples | `go build ./... && go vet ./...` in each of the 13 example modules | 13/13 pass |
| Workflows | `actionlint` | no issues |
| Release notes extraction | the `release.yml` `awk` script for `1.3.0`, run locally | 40 lines, identical to the `[1.3.0]` section of `CHANGELOG.md` |

---

## Acknowledgements

This release is the product of sprint 22.

---

## Verifying this release

```bash
go get github.com/FlavioCFOliveira/MuxMaster@v1.3.0
go mod download -json github.com/FlavioCFOliveira/MuxMaster@v1.3.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
