Documentation
¶
Overview ¶
Package router matches HTTP requests to OpenAPI operations without running validation.
A Router returns the effective server, path template, path item, operation, decoded server variables, and raw and decoded path parameters. Standalone routers enforce OpenAPI server precedence by default; WithPathOnlyMatching provides the validator's backward-compatible path-only behavior.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrPathNotFound identifies requests that do not match an effective server and path. ErrPathNotFound = errors.New("openapi path not found") // ErrMethodNotAllowed identifies requests whose path exists but method does not. // FindRoute returns a partial Route alongside this error. ErrMethodNotAllowed = errors.New("openapi operation not found") )
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*options)
Option configures Router construction.
func WithPathLookup ¶
func WithPathLookup(lookup PathLookup) Option
WithPathLookup borrows a path lookup. The router never releases it.
func WithPathOnlyMatching ¶
func WithPathOnlyMatching() Option
WithPathOnlyMatching preserves validator-compatible document base-path matching.
func WithRegexCache ¶
func WithRegexCache(cache RegexCache) Option
WithRegexCache borrows a compiled-regex cache. The router never releases it.
type PathLookup ¶
type PathLookup interface {
// Lookup returns the matched path item, its OpenAPI path template, and whether a match was found.
Lookup(string) (*v3.PathItem, string, bool)
}
PathLookup performs fast standard-template lookup. radix.PathLookup satisfies this contract.
type RegexCache ¶
type RegexCache interface {
// Load returns a previously cached value for key.
Load(key any) (value any, ok bool)
// Store associates value with key.
Store(key, value any)
}
RegexCache stores compiled path expressions. config.RegexCache satisfies this contract. Values stored by the router are *regexp.Regexp instances.
type Route ¶
type Route struct {
Document *v3.Document // Document is the OpenAPI document used for matching.
Server *v3.Server // Server is the matched server, or nil for the implicit relative server.
Path string // Path is the matched OpenAPI path template.
PathItem *v3.PathItem // PathItem is the matched OpenAPI path item.
Method string // Method is the request method, including additional methods.
Operation *v3.Operation // Operation is nil on a method mismatch.
// RawPathParams contains escaped parameter values exactly as matched in the URL path.
RawPathParams map[string]string
// PathParams contains URL-decoded operation path parameter values.
PathParams map[string]string
// ServerParams contains URL-decoded server variable values.
ServerParams map[string]string
}
Route describes the OpenAPI operation selected for a request.
type RouteError ¶
type RouteError struct {
Kind error // Kind is ErrPathNotFound or ErrMethodNotAllowed.
Route *Route // Route is populated for method mismatches and nil for path misses.
}
RouteError retains partial match context while supporting errors.Is.
func (*RouteError) Error ¶
func (e *RouteError) Error() string
Error returns the stable error message for the route failure kind.
func (*RouteError) Unwrap ¶
func (e *RouteError) Unwrap() error
Unwrap exposes the stable route error kind.
type Router ¶
type Router interface {
// FindRoute returns the route selected for a request.
//
// A method mismatch returns a non-nil partial Route and an error matching
// ErrMethodNotAllowed. A server or path mismatch returns a nil Route and an
// error matching ErrPathNotFound.
FindRoute(*http.Request) (*Route, error)
// Release drops document and router-owned lookup references. Injected lookups
// and regex caches are borrowed and are never released by the router.
Release()
}
Router locates an OpenAPI route for a request.
Source Files