Documentation ¶
Overview ¶
Package pathrouter is a trie based high performance path request router.
The router matches incoming requests by the request path. If a handle is registered for the path, it is called with the path params.
The registered path, against which the router matches incoming requests, can contain two types of parameters:
Syntax Type :name named parameter *name catch-all parameter
Named parameters are dynamic path segments. They match anything until the next '/' or the path end:
Path: /blog/:category/:post Requests: /blog/go/request-routers match: category="go", post="request-routers" /blog/go/request-routers/ no match, but the router would redirect /blog/go/ no match /blog/go/request-routers/comments no match
Catch-all parameters match anything until the path end, including the directory index (the '/' before the catch-all). Since they match anything until the end, catch-all parameters must always be the final path element.
Path: /files/*filepath Requests: /files/ match: filepath="/" /files/LICENSE match: filepath="/LICENSE" /files/templates/article.html match: filepath="/templates/article.html" /files no match, but the router would redirect
The value of parameters is saved as a slice of the Param struct, consisting each of a key and a value. The slice is passed to the Handle func as a third parameter. There are two ways to retrieve the value of a parameter:
// by the name of the parameter user := ps.ByName("user") // defined by :user or *user // by the index of the parameter. This way you can also get the name (key) thirdKey := ps[2].Key // the name of the 3rd parameter thirdValue := ps[2].Value // the value of the 3rd parameter
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CleanPath ¶
CleanPath is the URL version of path.Clean, it returns a canonical URL path for p, eliminating . and .. elements.
The following rules are applied iteratively until no further processing can be done:
- Replace multiple slashes with a single slash.
- Eliminate each . path name element (the current directory).
- Eliminate each inner .. path name element (the parent directory) along with the non-.. element that precedes it.
- Eliminate .. elements that begin a rooted path: that is, replace "/.." by "/" at the beginning of a path.
If the result of this process is an empty string, "/" is returned
Types ¶
type Handle ¶
Handle is a function that can be registered to a route to handle requests. Returns if the request was handled and any error. If false, nil is returned, assumes the function has returned "not found."
type Params ¶
type Params []Param
Params is a Param-slice, as returned by the router. The slice is ordered, the first URL parameter is also the first slice value. It is therefore safe to read values by the index.
type Router ¶
type Router[W any] struct { // contains filtered or unexported fields }
Router can be used to dispatch URL requests to different handler functions via configurable routes. The request and response types are generic.
R is the request type. W is the response writer type.
func New ¶
New returns a new Router with default configuration. Path auto-correction, including trailing slashes, is enabled by default.
func NewWithConfig ¶
func NewWithConfig[W any](conf RouterConfig[W]) *Router[W]
NewWithConfig constructs a new Router with the given config.
All configuration values are defaulted to false.
func (*Router[W]) AddHandler ¶
AddHandler registers a new request handle with the given path and method.
This function is intended for bulk loading and to allow the usage of less frequently used, non-standardized or custom methods (e.g. for internal communication with a proxy).
NOTE: this function is NOT concurrency safe.
func (*Router[W]) LookupPath ¶
LookupPath allows the manual lookup of a handler with a path. This is e.g. useful to build a framework around this router. If the path was found, it returns the handle function and the path parameter values. Otherwise the third return value indicates whether a redirection to the same path with an extra / without the trailing slash should be performed.
type RouterConfig ¶
type RouterConfig[W any] struct { // Enables automatic redirection if the current route can't be matched but a // handler for the path with (without) the trailing slash exists. // For example if /foo/ is requested but a route only exists for /foo, the // client is redirected to /foo with http status code 301 for GET requests // and 308 for all other request methods. RedirectTrailingSlash bool // RedirectFixedPath configures the router to fix the current request path, if no // handle is registered for it. // First superfluous path elements like ../ or // are removed. // Afterwards the router does a case-insensitive lookup of the cleaned path. // If a handle can be found for this route, the router makes a redirection // to the corrected path. // For example /FOO and /..//Foo could be redirected to /foo. // RedirectTrailingSlash is independent of this option. RedirectFixedPath bool // NotFound is called when no matching route is found. NotFound Handle[W] // Function to handle panics recovered from http handlers. // If nil, no recover() will be called (panics will throw). // The fourth parameter is the error from recover(). PanicHandler func(ctx context.Context, reqPath string, rw W, panicErr interface{}) }
RouterConfig are optional configuration parameters for the Router.
func DefaultConfig ¶
func DefaultConfig[W any]() RouterConfig[W]
DefaultConfig returns the default configuration if none is specified. Path auto-correction, including trailing slashes, is enabled by default.