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 andstableon Linux, macOS, and Windows, plus Linux/arm64. OAuth2Introspectsurvives 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 with401.Group.ServeFilesraw-path guard.Group.ServeFilesrefuses to register in the unsafeUseRawPath+UnescapePathValuesconfiguration, exactly asMux.ServeFilesdoes. Both variants call one shared check.- Working release pipeline. CI and commitlint run on every gitflow branch push, the
CHANGELOG.mdgate no longer fails spuriously, andrelease.ymlpasses 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), thegocommand does not build with an older toolchain. It switches to Go 1.27.1 or newer: it first looks for a matchinggo1.27.1executable inPATH, 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 requiresgo >= 1.27.1. Upgrade the local toolchain, or allow switching. - A consuming module's own
godirective is raised to at least1.27.1bygo 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 customiseshttp.DefaultTransport(for example a proxy or TLS setting). Changes made afterOAuth2Introspectis 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.DefaultTransporthas been replaced with a type other than*http.Transport, it is used as is, as before. - Set
HTTPClientto choose any other settings; a non-nilHTTPClientis 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.
OAuth2Introspectdefault client (rmp #300): own keep-alive transport with a 100-connection bound, built without calling any method ofhttp.DefaultTransport. An earlier revision within this release cycle usedhttp.DefaultTransport.Clone(), which runs the global transport's one-time HTTP/2 set-up and could silently downgradehttp.DefaultClientto HTTP/1.1; it never shipped. A reflection test fails when a Go release adds anhttp.Transportfield 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.gosaturatesmaxParamswith an explicitmath.MaxUint8check (TestMaxParamsSaturatesAtUint8Max); the redirect body escapes its target withhtml.EscapeString, whose output is byte-identical tonet/http.Redirect(TestWriteRedirect_ByteIdenticalToNetHTTPRedirect);Logger's intentionalint64-to-uint64conversion carries a scoped justification. - Test suite (rmp #303): no test outside
reports/andcompetitor/callst.Skip.FuzzTSRRedirectSafetychecks empty, oversized, andhttp.NewRequest-rejected paths; the differential, order-independence, andreqBundletests 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 tomain,develop,release/**, andhotfix/**, and on pull requests againstmain. TheCHANGELOG.md updatedgate runs on push and no longer fails withSIGPIPEunderpipefail.apidiffis advisory on push and blocking on pull requests. gosec v2.29.0 is installed with thego.modtoolchain, 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 fromCHANGELOG.mdto a file and passes it withbody_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 unusedid-tokenpermission.- Actions:
actions/checkoutv7.0.1,actions/setup-gov7.0.0,golangci/golangci-lint-actionv9.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/netv0.59.0 andgolang.org/x/textv0.42.0 (HTTP/2 harness);github.com/go-chi/chi/v5v5.3.2 andgithub.com/stretchr/testifyv1.12.1 (routing-fuzzer harness andcompetitor/, re-vendored). - Branch protection:
.github/branch-protection.mdand the contributing guide now describe a rule compatible with direct gitflow merges: it blocks force pushes and deletion ofmain, 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.mdcorrects rule 6 (aGroupprefix is never validated at creation) and adds rule 45 (invalid UTF-8Mountprefix);static-files.mditem 11 covers bothServeFilesvariants;compatibility.mdspecifies Go 1.27.1 and toolchain switching;middleware-stdlib.mdspecifies theOAuth2Introspectdefault client. - Reference documentation: GoDoc,
api.md, anddocs/middleware.mddescribe the newOAuth2Introspectdefault client;Group.ServeFilesdocuments 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