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

Methods

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

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

Ord 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

Methods

readsPrec :: Int -> ReadS Method

readList :: ReadS [Method]

readPrec :: ReadPrec Method

readListPrec :: ReadPrec [Method]

Show Method

Methods

showsPrec :: Int -> Method -> ShowS

show :: Method -> String

showList :: [Method] -> ShowS

IsMethod Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

Parameter ByteString Method

Methods

parseParameter :: ByteString -> Maybe Method

renderParameter :: Method -> ByteString

class IsMethod m where

Any types that represent an HTTP method.

Minimal complete definition

toMethod, fromMethod

Methods

toMethod :: m -> Method

fromMethod :: Method -> Maybe m

Instances

IsMethod ByteString

Methods

toMethod :: ByteString -> Method

fromMethod :: Method -> Maybe ByteString

IsMethod Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

IsMethod StdMethod

Methods

toMethod :: StdMethod -> Method

fromMethod :: Method -> Maybe StdMethod

IsMethod Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

IsMethod Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

IsMethod (Either ByteString StdMethod)

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

Methods

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

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

Show Request

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

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

Methods

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

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

Eq a => Eq (RouteResult a)

Methods

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

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

Show a => Show (RouteResult a)

Methods

showsPrec :: Int -> RouteResult a -> ShowS

show :: RouteResult a -> String

showList :: [RouteResult a] -> ShowS

Monoid (RouteResult a)

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.