Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Machinery for routing HTTP requests to appropriate handler functions.
Most of the time when writing a webserver or backend service for an application we need to handle multiple different request paths. Even if the process handles a only single primary endpoint there is often still a requirement to respond to requests for status and to have simple health checks that can be used to inform load balancers that the service is available in addition to that primary endpoint. Sending different requests to different functions is called routing.
Usage
This module provides a simple mechanism for declaring routes and their
corresponding targets. You do this by creating a list of "handlers", one for
each context path prefix you want to route requests to, then using the
prepareRoutes
function to compile this list into a WAI Application
that
can be passed to launchWebserver
.
application <-prepareRoutes
[ "api"</>
[ "check" `handleRoute
` checkHandler , "servicename"</>
[ "v3"</>
[ "status" `handleRoute
` statusHandler , "update" `captureRoute
` updateHandler ] ] ] ]launchWebserver
80 application
This results in an HTTP server responding to the following routes:
- http://www.example.com/api/check
- http://www.example.com/api/servicename/v3/status
- http://www.example.com/api/servicename/v3/update
- http://www.example.com/api/servicename/v3/update/12345678/field
Requests to any other paths (for example /api
and
/api/servicename/v3
) will result in a 404 Not Found
response.
Synopsis
- data Route τ
- type Prefix = Rope
- type Remainder = Rope
- literalRoute :: Prefix -> Route τ
- handleRoute :: Prefix -> (Request -> Program τ Response) -> Route τ
- captureRoute :: Prefix -> (Prefix -> Remainder -> Request -> Program τ Response) -> Route τ
- (</>) :: Route τ -> [Route τ] -> Route τ
- prepareRoutes :: [Route τ] -> Program τ Application
- notFoundHandler :: Request -> Program τ Response
Setup
Component of a context path in a URL request that can be routed to a hander in
the Program
τ
monad. Routes can be nested under other routes, building up
the familiar tree structure commonly used by webservers.
Since: 0.2.0
Instances
IsString (Route τ) Source # | |
Defined in Core.Webserver.Router fromString :: String -> Route τ # |
literalRoute :: Prefix -> Route τ Source #
A segment of a route that is to be matched exactly. For example,
literalRoute
"api"
will match the context path /api
.
This is the used for the definition of the IsString
instance enabling use of
OverloadedStrings
, so
"api"
will also match the context path /api
and makes for cleaner routing
specifications when building up nested paths with (</>)
.
Since: 0.2.0
handleRoute :: Prefix -> (Request -> Program τ Response) -> Route τ Source #
Route a given prefix to the supplied handler. You specify the prefix that you want covered, and if the request path a matches the handler function will be invoked.
handleRoute
"status" statusHandler
will match the context path /status
and invoke your function called
statusHandler
when requests for this path come in.
Since: 0.2.0
captureRoute :: Prefix -> (Prefix -> Remainder -> Request -> Program τ Response) -> Route τ Source #
Route a given prefix to the supplied handler, passing any following components of the path to that handler.
This is a more general variation of handleRoute
which allows you to
"capture" the part of the context path that came after the route prefix,
if there is one (and an empty string otherwise).
For example,
captureRoute
"person"
will match the context paths in the URLs like these:
- http://www.example.com/person
- http://www.example.com/person/U37gcRTh
- http://www.example.com/person/U37gcRTh/name
In the case of the third example the result of matching on this Route
would
have a prefix of /person
and a remainder of /U37gcRTh/name
.
Since: 0.2.0
(</>) :: Route τ -> [Route τ] -> Route τ Source #
Nest a set of routes below a parent. This will take the prefix inherited to
this point and insert it in front of the prefixes of each of the Route
s
listed as children.
Since: 0.2.0
Compile
prepareRoutes :: [Route τ] -> Program τ Application Source #
Compile a list of route handlers into a WAI Application
suitable to be
passed to launchWebserver
.
Internally this builds up a patricia tree of the different route prefixes.
Incoming requests are matched against these possibilities, and either the
corresponding handler is invoked or 404 Not Found
is returned.
Since: 0.2.0
Internal
notFoundHandler :: Request -> Program τ Response Source #
A default handler for routes that are encountered that don't have actual
handlers defined. This is what is served if the user requests an endpoint that
is defined by a literalRoute
or if the user requests a path that does not
route successfully..
Since: 0.2.0