Web.Route.Invertible

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.

Documentation

module Web.Route.Invertible.Common

normRoute :: Route a -> Route a

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

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

type PathString = Text

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

normalizePath :: [PathString] -> [PathString]

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

data Method

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.

Constructors

OPTIONS

GET

HEAD

POST

PUT

DELETE

TRACE

CONNECT

PATCH

ExtensionMethod !ByteString

Instances

Eq Method

Defined in Web.Route.Invertible.Method

Methods

(==) :: Method -> Method -> Bool

(/=) :: Method -> Method -> Bool

Ord Method

Defined in Web.Route.Invertible.Method

Methods

compare :: Method -> Method -> Ordering

(<) :: Method -> Method -> Bool

(<=) :: Method -> Method -> Bool

(>) :: Method -> Method -> Bool

(>=) :: Method -> Method -> Bool

max :: Method -> Method -> Method

min :: Method -> Method -> Method

Read Method

Defined in Web.Route.Invertible.Method

Methods

readsPrec :: Int -> ReadS Method

readList :: ReadS [Method]

readPrec :: ReadPrec Method

readListPrec :: ReadPrec [Method]

Show Method

Defined in Web.Route.Invertible.Method

Methods

showsPrec :: Int -> Method -> ShowS

show :: Method -> String

showList :: [Method] -> ShowS

IsMethod Method

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

Parameter ByteString Method

Defined in Web.Route.Invertible.Method

Methods

parseParameter :: ByteString -> Maybe Method

renderParameter :: Method -> ByteString

class IsMethod m where

Any types that represent an HTTP method.

Methods

toMethod :: m -> Method

fromMethod :: Method -> Maybe m

Instances

IsMethod ByteString

Defined in Web.Route.Invertible.Method

Methods

toMethod :: ByteString -> Method

fromMethod :: Method -> Maybe ByteString

IsMethod Method

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Method -> Method0

fromMethod :: Method0 -> Maybe Method

IsMethod StdMethod

Defined in Web.Route.Invertible.Method

Methods

toMethod :: StdMethod -> Method

fromMethod :: Method -> Maybe StdMethod

IsMethod Method

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Method -> Method0

fromMethod :: Method0 -> Maybe Method

IsMethod Method

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

IsMethod (Either ByteString StdMethod)

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Either ByteString StdMethod -> Method

fromMethod :: Method -> Maybe (Either ByteString StdMethod)

data Request

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.

Constructors

Request

Fields

• requestSecure :: Bool
• requestHost :: [HostString]
• requestMethod :: Method
• requestPath :: [PathString]
• requestQuery :: QueryParams
• requestContentType :: ContentType

Instances

Eq Request

Defined in Web.Route.Invertible.Request

Methods

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

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

Show Request

Defined in Web.Route.Invertible.Request

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

Semigroup Request

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

Defined in Web.Route.Invertible.Request

Methods

(<>) :: Request -> Request -> Request

sconcat :: NonEmpty Request -> Request

stimes :: Integral b => b -> Request -> Request

Monoid Request

Defined in Web.Route.Invertible.Request

Methods

mempty :: Request

mappend :: Request -> Request -> Request

mconcat :: [Request] -> Request

Forward routing

data RouteResult a

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

Functor RouteResult

Defined in Web.Route.Invertible.Result

Methods

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

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

Eq a => Eq (RouteResult a)

Defined in Web.Route.Invertible.Result

Methods

(==) :: RouteResult a -> RouteResult a -> Bool

(/=) :: RouteResult a -> RouteResult a -> Bool

Show a => Show (RouteResult a)

Defined in Web.Route.Invertible.Result

Methods

showsPrec :: Int -> RouteResult a -> ShowS

show :: RouteResult a -> String

showList :: [RouteResult a] -> ShowS

Semigroup (RouteResult a)

Defined in Web.Route.Invertible.Result

Methods

(<>) :: RouteResult a -> RouteResult a -> RouteResult a

sconcat :: NonEmpty (RouteResult a) -> RouteResult a

stimes :: Integral b => b -> RouteResult a -> RouteResult a

Monoid (RouteResult a)

Defined in Web.Route.Invertible.Result

Methods

mempty :: RouteResult a

mappend :: RouteResult a -> RouteResult a -> RouteResult a

mconcat :: [RouteResult a] -> RouteResult a

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

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

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

requestActionRoute :: RouteAction a b -> a -> Request

Apply requestRoute to actionRoute.

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

Combine (:?) and actionRoute.

requestBoundRoute :: BoundRoute -> Request

Apply requestRoute on a BoundRoute.