On this page

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 (2026-09-26) Comparison: 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, 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 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 (requirement 4) and follows the Go toolchain documentation.

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.

  • 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 and the contributing guide 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 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 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

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