MuxMaster v1.0.0 — Release Notes

Version: v1.0.0 (general availability) Date: 2026-05-08 Type: Major — first stable release Module: github.com/FlavioCFOliveira/MuxMaster Go: 1.26 or newer Previous tag: v1.0.0-rc1 (2026-05-08) Comparison: v1.0.0-rc1...v1.0.0

---

Executive summary

MuxMaster v1.0.0 marks the first general-availability release of the high-performance, zero-dependency HTTP router for Go. The release closes the v1.0.0-rc1 cycle with zero breaking changes, four small but consequential security and operability touchups, an expanded operability documentation set (docs/observability.md), and a canonical graceful-shutdown example. The router is empirically validated at 67 275 RPS sustained over 30 seconds with 1 000 concurrent goroutines and a 0.00 % error rate; nine security agents reran the full audit battery against HEAD and reported zero blocking findings.

This release establishes the public API surface of the 1.x series. From this point forward, all 1.x updates are bound by the SemVer compatibility guarantees documented in COMPATIBILITY.md: no source-incompatible change without a major-version bump, deprecation cycles for any removal, and an apidiff gate enforced on every pull request.

---

What changed since v1.0.0-rc1

The 23 commits between v1.0.0-rc1 and HEAD are CI/CD, documentation, and tooling consolidation only. No exported function signature was modified; no behavioural change is observable to existing consumers. The release-notes-only deltas of the final cycle are:

Security

• OAuth2Introspect: redact endpoint URL in slog warning (TM-2026-005, severity 4). The construction-time slog.Warn issued when AllowInsecureEndpoint=true previously logged the full endpoint URL, which could leak query-string credentials (e.g. ?client_secret=...) to slog sinks. The warning now emits only the resolved host and scheme. The fix is a one-line additive change in middleware/oauth2.go and is fully backward-compatible — only the format of the warning log line changed; no API was modified.
• SECURITY.md "Resolved Findings (v1.0.0)" section enumerates the four S9/S10 findings closed during the rc cycle so that downstream adopters can verify by ID that each issue is resolved: CSA-2026-0060 (severity 8, silent param loss), HPS-2026-0005 (severity 7, open redirect via absolute-form URI), FPE-2026-010 (severity 6, silent middleware skip on root Mux.HandleFast), and TM-2026-005 (severity 4, the OAuth2 redaction above).
• SECURITY.md "Defaults requiring opt-in" matrix documents the three middleware switches that are unsafe by default and must be turned on in production: JWTAuth.RequireExpiry, RealIP() trusted CIDR list, and OAuth2Introspect.AllowInsecureEndpoint=false.

Documentation

• docs/observability.md — a new operability guide describing structured logging with slog, RequestID correlation, the recommended Prometheus metrics-middleware pattern, an OpenTelemetry tracing pattern, health-check endpoints, and pprof integration. The router itself remains zero-dependency; operators bring their own metrics/tracing SDK.
• README "Security defaults" section consolidates the three unsafe-by-default middleware options behind a single hardened-stack snippet.
• README snippet fixes — the Trust X-Forwarded-For example now passes a trusted CIDR; the JWT example now sets RequireExpiry: true.
• JWTAuth.RequireExpiry GoDoc strengthened with an explicit "DO NOT use in production" caveat on the false default and a pointer to RFC 8725 §4.4 (TM-2026-001).
• docs/README.md indexes the new Observability guide.

Examples

• examples/graceful-shutdown/ is a new, self-contained example demonstrating signal-driven srv.Shutdown(ctx) with a bounded drain deadline, the recommended http.Server timeout set (ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout), and a cooperative handler that yields to context cancellation.

Build hygiene

• .gitignore updated to exclude example binaries (examples/oauth2/oauth2, examples/server-side-render/server-side-render, examples/graceful-shutdown/graceful-shutdown).

---

Public API surface

The 1.x series locks in the API as documented in api.md and COMPATIBILITY.md. The full surface includes:

Core router

• Mux (with New() *Mux, ServeHTTP)
• Mux.GET, Mux.POST, Mux.PUT, Mux.PATCH, Mux.DELETE, Mux.HEAD, Mux.OPTIONS, Mux.CONNECT, Mux.TRACE
• Mux.Handle, Mux.Match, Mux.ANY
• Mux.HandleE, Mux.GETE, Mux.POSTE, Mux.PUTE, Mux.PATCHE, Mux.DELETEE
• Mux.HandleFast and the per-method fast variants (GETFast, POSTFast, PUTFast, PATCHFast, DELETEFast, HEADFast, OPTIONSFast, CONNECTFast, TRACEFast)
• Mux.Use, Mux.UseFast, Mux.Pre, Mux.With
• Mux.Group, Mux.Route, Mux.Mount, Mux.ServeFiles
• Mux.Lookup, Mux.Walk, Mux.Routes, Mux.Rebuild
• Configuration flags: RedirectTrailingSlash, RedirectFixedPath, HandleMethodNotAllowed, HandleOPTIONS, CaseInsensitive, UseRawPath, UnescapePathValues, RedirectCode
• Custom handlers: NotFound, MethodNotAllowed, GlobalOPTIONS, PanicHandler, ErrorHandler

Path parameters

• Param, Params types
• PathParam(r, name), ParamsFromContext(ctx), RoutePattern(r)
• Typed parsers: Params.Int, Params.Int64, Params.Uint64, Params.Float64, Params.Bool

Response helpers

• JSON, XML, Text, Redirect, NoContent

Middleware sub-package (middleware)

• Logger, Recoverer, RecovererWithLogger, CORS, BasicAuth, Compress, Throttle, ThrottleBacklog, Timeout, RequestID, RealIP, CleanPath, StripSlashes, NoCache, SetHeader, WithValue
• Authentication: APIKey (SHA-256 hashed key lookup), JWTAuth (HS*/RS*/ES* token validation), OAuth2Introspect (RFC 7662 introspection with caching)

Compatibility tier

• Tier 1 (locked): Mux, Param, Params, PathParam, ParamsFromContext, all HTTP-method registration helpers, the standard http.Handler dispatch path.
• Tier 2 (frozen for 1.x): HandleFast, FastHandler, FastMiddleware, UseFast.
• Tier 3 (stable, may add fields): all middleware constructors and option structs.
• Tier 4 (experimental): listed under // Experimental: GoDoc in the source — currently empty.

apidiff is run on every pull request against the previous tag; any breaking change without an explicit breaking-change-allowed label fails CI.

---

Migration notes (rc1 → 1.0.0)

No migration is required. The release is source-compatible and binary-compatible with v1.0.0-rc1. The only behavioural change is the redaction of the OAuth2 endpoint URL in the construction-time slog.Warn for AllowInsecureEndpoint=true; this affects only log output, and only when the deliberately-insecure flag is used. Production stacks should not be using AllowInsecureEndpoint=true in the first place.

If you depended on the previous log line format (e.g. for log-shipping rules that parse the full URL), update the pattern to match host= and scheme= fields instead of a full endpoint= URL.

---

Test evidence summary

All checks were re-run against HEAD immediately before this release.

Functional and static analysis

Check	Tool	Command	Result
Vet	go vet	go vet ./...	clean
Linter	golangci-lint v2.12.2	golangci-lint run ./...	0 issues
Static analysis	staticcheck 2026.1	staticcheck ./...	0 issues (production scope)
Security SAST	gosec	gosec -severity medium -confidence medium ./...	0 issues
Vulnerability scan	govulncheck	govulncheck ./...	0 reachable vulnerabilities
Errcheck	errcheck	included in golangci-lint	clean
Ineffassign	ineffassign	included in golangci-lint	clean

Tests

Suite	Command	Result
Core	go test -race -count=1 .	PASS — 1.06 s
Middleware	go test -race -count=1 ./middleware	PASS — 1.21 s
Examples (×8)	go build ./... && go vet ./... per example	8/8 PASS

Coverage

Package	Coverage
Core (github.com/FlavioCFOliveira/MuxMaster)	83.3 %
Middleware (./middleware)	85.4 %
Total	84.2 % (CI gate ≥ 80 %)

Concurrency

The race detector was active in every test run. Sprint S10-PreCSA executed 23 stress tests over 94 seconds at -race -count=3 against the nine concurrency-related TM hypotheses (TM-007/008/019/025/027/028/036/037/045) and reported 9/9 REFUTED with zero data races.

---

Benchmark evidence summary

All numbers were captured on the same machine: AMD Ryzen 9 5900HX (16 logical cores), Linux 6.8, Go 1.26.2.

Internal hot-path benchmarks (bench_test.go)

Case	ns/op	B/op	allocs/op
Static route	25.81	0	0
1 parameter	115.4	416	1
2 parameters	135.9	448	1
3 parameters	138.9	480	1
Wildcard / catch-all	118.2	416	1
Parallel static	3.575	0	0
Parallel 1-param	106.9	416	1
FastStatic	25.20	0	0
FastParam 1	48.81	32	1
FastParam 2	66.03	64	1
FastParam 3	74.22	96	1

Competitive context

Numbers below are the medians over count=10 runs against httprouter, bunrouter (via HTTPHandlerFunc adapter), and chi v5 on the same host.

Case	MuxMaster Handle	MuxMaster HandleFast	httprouter	bunrouter	chi v5
Static	25 ns / 0 allocs	25 ns / 0 allocs	35 ns / 0 allocs	198 ns / 3 allocs	1981 ns / 2 allocs
1 parameter	115 ns / 1 alloc	50 ns / 1 alloc	59 ns / 1 alloc	182 ns / 3 allocs	3449 ns / 4 allocs
2 parameters	134 ns / 1 alloc	68 ns / 1 alloc	72 ns / 1 alloc	202 ns / 3 allocs	2301 ns / 4 allocs
3 parameters	139 ns / 1 alloc	78 ns / 1 alloc	80 ns / 1 alloc	214 ns / 3 allocs	2992 ns / 4 allocs
Catch-all	118 ns / 1 alloc	—	56 ns / 1 alloc	1636 ns / 3 allocs	2333 ns / 4 allocs
Parallel param	110 ns / 1 alloc	17 ns / 1 alloc	24 ns / 1 alloc	748 ns / 3 allocs	943 ns / 4 allocs
Not found	253 ns / 3 allocs	—	493 ns / 3 allocs	1949 ns / 4 allocs	1658 ns / 5 allocs

Reading. MuxMaster Handle beats every tested competitor on static routes and on Not found. On parameterised routes, it trails httprouter by 1.5–2× — this is a structural cost of preserving 100 % net/http compatibility without race conditions (see params.go → tiered reqBundle design). For workloads where this matters, HandleFast beats httprouter on every parameterised case; the trade-off is documented in CLAUDE.md and SECURITY.md.

Sustained-load resilience (reports/dos-resilience-tester/2026-05-08-production-loadtest.md)

Metric	Result	Threshold	Status
Duration	30.0 s	≥ 30 s	PASS
Workers	1 000 goroutines	—	—
Total requests	2 019 062	—	—
RPS sustained	67 275	≥ 1 000	PASS
Error rate	0.00 %	≤ 1 %	PASS
Heap net (post-GC)	3.56 MB	bounded	STEADY-STATE
GC cycles	477	—	INFO
Max GC pause	2.948 ms	≤ 50 ms	PASS
Goroutine delta after drain	−1 (2 → 1)	≤ 50	PASS

Stack tested: ThrottleBacklog(2000, 5000, 5s) + RealIP(127.0.0.1/32) + RequestID() + Recoverer() plus three routes (one static, one 1-parameter, one catch-all). The result extrapolates linearly with GOMAXPROCS up to the network/file-descriptor limit; on a 16-vCPU box this is approximately 4 200 RPS per core, or ~1.6 M RPS at full saturation.

Algorithmic complexity (radix tree)

Stress vector	Measured slope	Theoretical bound	Status
Path depth (10 → 1 000)	0.022 ns/depth	O(k)	PASS (sub-linear)
Common prefix (10 → 1 000 routes)	0.0145 ns/route	O(1) at fixed k	PASS
Wide fan-out (10 → 62 children)	0.535 ns/branch	O(B)	PASS
Many parameters (1 → 10)	63.9 ns/param	O(1) amortised	PASS
1 MB path through catch-all	464 B router-allocs	constant	PASS (no amplification)

---

Security notes

Findings closed in v1.0.0 (with verifiable IDs)

ID	Severity	Type	Fix location	Validation
CSA-2026-0060	8	Silent params loss via context wrap on slow path	params.go:357-378 (hasReqCtxField slow path)	S10-PreCSA — TM-007/008/036/037/045 all REFUTED
HPS-2026-0005	7	Open redirect via absolute-form URI	mux.go:945, 960 (path-only Location URL)	code review + manual repro
FPE-2026-010	6	Silent middleware skip on root Mux.HandleFast	mux.go:435-442 (panic guard)	CSA: Group.HandleFast delegates → guard covers transitively
TM-2026-005	4	OAuth2 endpoint URL leak in slog warning	middleware/oauth2.go:229	code review
TM-2026-001	4 (doc)	JWT RequireExpiry default-false caveat	GoDoc + README hardened-stack snippet	doc audit
TM-2026-044	4 (doc)	RealIP without trusted CIDR list	README "Security defaults" callout	doc audit

Sprint S10 pre-release closure

Four security agents reran their full hypothesis batteries against the release HEAD:

• concurrency-security-auditor — 9/9 TM-CSA hypotheses REFUTED. -race -count=3 clean across 23 stress tests in 94 seconds. Evidence: reports/concurrency-security-auditor/{evidence,harness}/2026-05-08-S10-PreCSA/.
• middleware-security-reviewer — 6/6 TM-MSR domains covered (logger, JWT, OAuth2, BasicAuth, RealIP, APIKey). One one-line fix (TM-005) and two documentation reinforcements (TM-001, TM-044) applied. Evidence: reports/middleware-security-reviewer/harness/2026-05-08-S10-PreMSR/.
• path-routing-fuzzer — prerelease_v100_test.go fuzz harness 10 M+ executions, zero crashes; CL-PATH-1 cluster CLOSED for v1.0.0. Evidence: reports/path-routing-fuzzer/harness/prerelease_v100_test.go.
• go-sast-and-memory-auditor — full SAST (vet + staticcheck + golangci-lint + gosec + govulncheck + errcheck + ineffassign) reports zero issues over 4 862 LOC across 26 production files. Evidence: reports/go-sast-and-memory-auditor/{2026-05-08-v1.0.0-prerelease.md, evidence/2026-05-08/}.

Maturity verdict

Cross-agent consolidation: GO — production-ready for high load, stress, and concurrency. Aggregate maturity score 8.7 / 10 (reports/overview/2026-05-08-final-maturity-verdict.md). Five dimensions that were below 7 in the morning assessment moved above 7; the only remaining gap below 7 is the operability/metrics-export dimension, which is partially addressed by the new docs/observability.md and is not a release blocker.

---

Upgrade instructions

go get github.com/FlavioCFOliveira/MuxMaster@v1.0.0

For projects already on v1.0.0-rc1, this is a drop-in upgrade: no code change is required. Run go mod tidy after the upgrade to refresh go.sum (note: MuxMaster itself ships with zero dependencies, so the only entries in your go.sum will be from your own consumers).

Recommended hardened stack

For new adopters, the recommended production stack is:

package main

import (
    "log/slog"
    "net/http"
    "time"

    muxmaster "github.com/FlavioCFOliveira/MuxMaster"
    mw "github.com/FlavioCFOliveira/MuxMaster/middleware"
)

func main() {
    mux := muxmaster.New()

    mux.Use(
        mw.RealIP("127.0.0.1/32", "10.0.0.0/8"), // explicit trusted CIDRs
        mw.RequestID(),
        mw.Logger(slog.Default()),
        mw.RecovererWithLogger(slog.Default()),
        mw.ThrottleBacklog(1000, 5000, 5*time.Second),
    )

    mux.GET("/healthz", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       30 * time.Second,
        WriteTimeout:      30 * time.Second,
        IdleTimeout:       120 * time.Second,
    }

    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        slog.Error("server failed", "err", err)
    }
}

For the canonical graceful-shutdown wrapper around this server, see examples/graceful-shutdown/main.go.

---

Documentation index

• README.md — installation, quickstart, all features at a glance, security defaults.
• COMPATIBILITY.md — SemVer policy, API tiers, deprecation timelines, support matrix.
• SECURITY.md — threat model, hardened-stack defaults, resolved findings.
• CONTRIBUTING.md — fork/branch/PR workflow, test commands, deprecation convention.
• api.md — generated API reference (kept fresh by CI's make api gate).
• docs/observability.md — slog, RequestID correlation, Prometheus, OpenTelemetry, pprof.
• docs/ — per-feature documentation pages indexed by docs/README.md.
• examples/ — eight self-contained example modules (authn, cache, graceful-shutdown, jwt, oauth2, rest-api, server-side-render, static-site).

---

CI/CD pipeline

Every pull request triggers:

• go build ./..., go test -race -count=1 ./..., go vet ./...
• golangci-lint run, staticcheck, gosec, govulncheck
• Coverage gate (≥ 80 %)
• apidiff breaking-change gate
• make api freshness gate
• CHANGELOG update gate
• Conventional Commits validator
• Multi-OS matrix (Linux, macOS, Windows) and linux/arm64 via QEMU
• Benchmark regression gate (±10 %)
• CodeQL security analysis with security-extended queries

The release.yml workflow fires on git push --tags v*; it validates the SemVer tag, reruns the test suite, generates a CycloneDX SBOM, extracts the matching CHANGELOG section, and creates the GitHub Release. Nothing further is required beyond cutting the tag.

---

Acknowledgements

This release is the product of nine sprints of cross-disciplinary auditing (S1–S9) plus the S10-PreCSA and S10-PreMSR pre-release closures. The audit harnesses, evidence, and per-finding write-ups are archived under /reports/ and ship with this release for full traceability.

Particular thanks to the specialised agent battery — go-perf-optimizer, benchmark-elite-tester, path-routing-fuzzer, dos-resilience-tester, concurrency-security-auditor, middleware-security-reviewer, go-sast-and-memory-auditor, timing-and-sidechannel-analyst, fuzzing-and-property-engineer, and threat-modeler-and-zero-day-researcher — whose evidence underpins the maturity verdict.

---

Verifying this release

# Verify the published checksum
go install github.com/FlavioCFOliveira/MuxMaster@v1.0.0
go mod download -json github.com/FlavioCFOliveira/MuxMaster@v1.0.0 | jq -r .Sum

# Verify against the provided SBOM (attached to the GitHub Release)
cyclonedx-cli validate --input-file muxmaster-v1.0.0.cdx.json

The SBOM (CycloneDX JSON) is generated automatically by release.yml and attached as a release asset.

---

Maintainer: flavio cf oliveira License: see LICENSE at the repository root Issue tracker: https://github.com/FlavioCFOliveira/MuxMaster/issues