# 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](https://github.com/FlavioCFOliveira/MuxMaster/compare/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

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

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

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