Skip to main content

Router

type Router​

type Router interface {
    MiddlewareRegistrar
    MiddlewareComposer
    ErrorHandlerRegistrar
    RouteRegistrar
    RouteMatcher
    // Add registers a request handler and returns the corresponding route interface instance
    Add([]string, string, HandlerFunc) (Route, error)
    // Remove removes a route
    Remove(methods []string, path string) error
    // Routes returns registered routes
    Routes() []Route
    // URI generates a URI from a handler.
    URI(h HandlerFunc, params ...any) string
    // Reverse generates a URL from a route name and provided parameters.
    Reverse(name string, params ...any) string
}

Router is an interface that routes requests to registered routes.

type RouteMatcher​

type RouteMatcher interface {
    // Match matches a route
    Match(r *http.Request, p *PathParams) RouteMatch
}

Route matcher interface.

type RouterConfig​

type RouterConfig struct {
    AllowOverwritingRoute    bool
    UnescapePathParamValues  bool
    UseEscapedPathForRouting bool
    RoutingTrailingSlash     bool
    RouteCollector           RouteCollector
}

type func NewRouter​

func NewRouter(config RouterConfig) Router

type RouteCollector​

type RouteCollector interface {
    MiddlewareRegistrar
    MiddlewareComposer
    ErrorHandlerRegistrar
    RouteRegistrar
    // Prefix returns the common route prefix
    Prefix() string
    // Parent returns the parent route collector
    Parent() RouteCollector
    // Router returns the router to which it belongs
    Router() Router
}

Route collector interface

func NewRouteCollector​

func NewRouteCollector(prefix string, parent RouteCollector, router Router) RouteCollector

type RouteRegistrar​

type RouteRegistrar interface {
    // Group implements route grouping registration, actually calls `RouteCollector.Route` to implement
    Group(fn func(sub RouteCollector))
    // Route implements route grouping registration with a specified prefix
    Route(prefix string, fn func(sub RouteCollector))
    // Some registers a new route for multiple HTTP methods and path, matching handlers in the router. Panics if an error occurs.
    Some(methods []string, pattern string, h HandlerFunc) Route
    // Any registers a new route for all supported HTTP methods and path, matching handlers in the router. Panics if an error occurs.
    Any(pattern string, h HandlerFunc) Route
    // CONNECT registers a new CONNECT route for the path, matching handlers in the router. Panics if an error occurs.
    CONNECT(pattern string, h HandlerFunc) Route
    // DELETE registers a new DELETE route for the path, matching handlers in the router. Panics if an error occurs.
    DELETE(pattern string, h HandlerFunc) Route
    // GET registers a new GET route for the path, matching handlers in the router. Panics if an error occurs.
    GET(pattern string, h HandlerFunc) Route
    // HEAD registers a new HEAD route for the path, matching handlers in the router. Panics if an error occurs.
    HEAD(pattern string, h HandlerFunc) Route
    // OPTIONS registers a new OPTIONS route for the path, matching handlers in the router. Panics if an error occurs.
    OPTIONS(pattern string, h HandlerFunc) Route
    // PATCH registers a new PATCH route for the path, matching handlers in the router. Panics if an error occurs.
    PATCH(pattern string, h HandlerFunc) Route
    // POST registers a new POST route for the path, matching handlers in the router. Panics if an error occurs.
    POST(pattern string, h HandlerFunc) Route
    // PUT registers a new PUT route for the path, matching handlers in the router. Panics if an error occurs.
    PUT(pattern string, h HandlerFunc) Route
    // TRACE registers a new TRACE route for the path, matching handlers in the router. Panics if an error occurs.
    TRACE(pattern string, h HandlerFunc) Route
    // Handle registers a route that supports the specified request method
    Handle(method, pattern string, h HandlerFunc) Route
    // Static registers a new route with a path prefix to serve static files from the provided root directory. Panics if an error occurs.
    Static(prefix, root string) Route
    // File registers a new route with a path to serve a static file. Panics if an error occurs.
    File(pattern, file string) Route
}

Route registrar interface

type Route​

type Route interface {
    MiddlewareRegistrar
    MiddlewareComposer
    // Router returns the router to which it belongs
    Router() Router
    // Collector returns the collector to which it belongs
    Collector() RouteCollector
    // Name returns the route name
    Name() string
    // SetName sets the route name
    SetName(name string) Route
    // Title returns the route title
    Title() string
    // SetTitle sets the route title
    SetTitle(name string) Route
    // Pattern returns the route path expression
    Pattern() string
    // Methods returns the supported HTTP request methods
    Methods() []string
    // Handler returns the registered request handler function
    Handler() HandlerFunc
    // Params returns the list of supported route parameters
    Params() []string
    // RouteInfo returns the route description interface implementation
    RouteInfo() RouteInfo
}

Route interface.

type RouteInfo​

type RouteInfo interface {
    // Router returns the router to which it belongs
    Router() Router
    // Collector returns the collector to which it belongs
    Collector() RouteCollector
    // Name returns the route name
    Name() string
    // Title returns the route title
    Title() string
    // Methods returns the list of supported request methods
    Methods() []string
    // Pattern returns the route path expression
    Pattern() string
    // Params returns the list of supported route parameters
    Params() []string
    // Reverse reverses the route expression to an actual request path using provided parameters.
    // If parameters are empty or nil, it tries to use default values. If parameters cannot be resolved,
    // it will panic with an error
    Reverse(params ...any) string
    // String returns the string form
    String() string
}

Route description interface.

type RouteMatchType​

type RouteMatchType uint8

Describes the possible states of a request from the routing perspective.

const (
    // RouteMatchUnknown is the state before routing is completed. Default state for a fresh context.
    RouteMatchUnknown RouteMatchType = iota
    // RouteMatchNotFound is the state when the router found no matching route for the current request
    RouteMatchNotFound
    // RouteMatchMethodNotAllowed is the state when the router found no route with matching path + method.
    // Although the router has a route matching the path, the method is different.
    RouteMatchMethodNotAllowed
    // RouteMatchFound is the state when the router found an exact match for the path + method combination
    RouteMatchFound
)

type RouteMatch​

type RouteMatch struct {
    // Type contains the enumerated result of Router.Match, helping to understand whether the router
    // truly matched a route, or what kind of error case we have at the end of the handler chain (404/405).
    Type RouteMatchType
    // AllowMethods is the list of request methods that can be handled, mainly
    // used when Type value is RouteMatchMethodNotAllowed.
    AllowMethods []string
    // Handler is the function (chain) matched by the router. If there's no match, it may result in ErrNotFound or ErrMethodNotAllowed.
    Handler HandlerFunc
    // RouteInfo is the information of the route we just matched
    RouteInfo RouteInfo
}

RouteMatch is the result object of Router.Match. Its main purpose is to avoid allocating memory for PathParams inside the router.