router

router is an explicit, immutable HTTP router built on Go's net/http programming model. It adds deterministic composition, groups, names, safe URL generation, metadata, introspection, mounts, and route-scoped middleware while keeping handlers as ordinary http.Handler values.

The published v2.0.1 release retains the fail-closed inherited middleware and mount defaults introduced in v2.0.0. The minimum supported toolchain is Go 1.27.0. The package has no runtime dependencies and no global router, reflection discovery, controller resolver, container, session, template, or application lifecycle.

See the versioned Golib ecosystem index and its service-edge package guidance for the shared design language and related packages.

Installation

Install the published v2.0.1 release:

go get github.com/faustbrian/go-router/v2@v2.0.1

Existing v2 applications can retain released v2.0.0 while planning an upgrade. Legacy consumers can retain github.com/faustbrian/go-router@v1.0.0; do not bypass publication with a local replacement or pseudo-version.

Five-minute start

builder := router.New()
err := builder.Register(router.Route{
    Name:    "users.show",
    Methods: []string{http.MethodGet},
    Path:    "/users/{id}",
    Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, r.PathValue("id"))
    }),
})
if err != nil {
    return err
}

handler, err := builder.Compile()
if err != nil {
    return err
}
return http.ListenAndServe(":8080", handler)

Registration is single-owner and startup-time. The compiled router is an immutable http.Handler safe for concurrent serving and introspection.

Contracts

• Semantics
• Specification decisions
• Pinned conformance matrix
• Compatibility
• Behavior matrices
• Resource limits
• Security
• Support
• Vulnerability reporting
• Architecture
• Five-minute quickstarts
• API reference
• Adoption guides
• Migration guides
• Cookbook
• Performance
• FAQ
• Troubleshooting
• Release process

Development

Use ordinary Go tests and a focused two-second fuzz smoke as described in CONTRIBUTING.md. make check and make ci use bounded local assurance with the public verifier; make ci checks the specification register offline. make check-full retains full assurance and explicit online authoritative-source validation. NilAway remains advisory.

License

MIT. See LICENSE and NOTICE.

Documentation

Use the documentation index for package-owned guides, operational contracts, examples, and maintainer references.