web-inv-route-0.1.3.2: Composable, reversible, efficient web routing using invertible invariants and bijections
Safe HaskellNone
LanguageHaskell2010

Web.Route.Invertible

Description

This provides a generic, framework-agnostic interface to routing. If you have a RouteMap (see Web.Route.Invertible.Common), make a Request to describe an incoming request, and call lookupRoute or routeRequest to find the route. See RouteRequest for handling errors or the result.

You can also use requestActionRoute to produce a Request from a route endpoint.

Synopsis

Documentation

normRoute :: Route a -> Route a Source #

By default, route predicates are matched in the order they are specified, so each test is done only if all preceding tests succeed. However, in most cases routing rules should be tested in a specific order in order to produce sensible errors (e.g., a 405 error that offers available methods should only apply to other routes with the same path). This re-orders the predicates in a route in order of the constructors in RoutePredicate (i.e., host, secure, path, method, ...), allowing you to construct your routes in any order but still produce sensible matching behavior. Alternatively, since there are cases you may watch to match in a different order (e.g., for routePriority), you can specify your routes in specific order and avoid this function (which would also be more efficient). Note that there are some "de-normalized" cases that this will not correct, such as having duplicate routeMethod specifications (in which case all must match, but each is done independently).

Request representation

type HostString = ByteString Source #

The representation for domain names or domain name segments (after splitHost).

type PathString = Text Source #

A component of a path, such that paths are represented by [PathString] (after splitting on '/'). Paths can be created by decodePath.

normalizePath :: [PathString] -> [PathString] Source #

Remove double- and trailing-slashes (i.e., empty path segments).

data Method Source #

Standard HTTP methods. These are defined a number of places already, but the http-types version (which is the only thing we import by default) is too cumbersome.

data Request Source #

A reduced representation of an HTTP request, sufficient for routing. This lets us both pre-process/parse the request to optimize routing, and be agnostic about the incoming request representation. These can be created with one of the framework-specific layers.

Instances

Instances details
Eq Request Source # 
Instance details

Defined in Web.Route.Invertible.Request

Methods

(==) :: Request -> Request -> Bool #

(/=) :: Request -> Request -> Bool #

Show Request Source # 
Instance details

Defined in Web.Route.Invertible.Request

Semigroup Request Source #

Merge two requests, where non-blank values in the second argument take precedence.

Instance details

Defined in Web.Route.Invertible.Request

Monoid Request Source # 
Instance details

Defined in Web.Route.Invertible.Request

Forward routing

data RouteResult a Source #

The result of looking up a request in a routing map.

Constructors

RouteNotFound

No route was found to handle this request: 404

AllowedMethods [Method]

No route was found to handle this request, but there are routes for other methods: 405

RouteResult a

A route was found to handle this request

MultipleRoutes

Multiple (conflicting) routes were found to handle this request: 500

Instances

Instances details
Functor RouteResult Source # 
Instance details

Defined in Web.Route.Invertible.Result

Methods

fmap :: (a -> b) -> RouteResult a -> RouteResult b #

(<$) :: a -> RouteResult b -> RouteResult a #

Eq a => Eq (RouteResult a) Source # 
Instance details

Defined in Web.Route.Invertible.Result

Show a => Show (RouteResult a) Source # 
Instance details

Defined in Web.Route.Invertible.Result

Semigroup (RouteResult a) Source # 
Instance details

Defined in Web.Route.Invertible.Result

Monoid (RouteResult a) Source # 
Instance details

Defined in Web.Route.Invertible.Result

lookupRoute :: Request -> RouteMap a -> RouteResult a Source #

Lookup a value in a routing table based on a Request. This returns the action returned by the route that can handle this request, wrapped in a RouteResult in case of error.

routeRequest :: Request -> RouteMap a -> Either (Status, ResponseHeaders) a Source #

Lookup a request in a routing table and transform errors to appropriate HTTP status and headers. It is up to the user to provide an appropriate body (if any).

Reverse routing

(!:?) :: RouteAction a b -> a -> BoundRoute infix 1 Source #

Combine (:?) and actionRoute.