Core.Webserver.Router

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.

Setup

data Route τ

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 τ)

Defined in Core.Webserver.Router

Methods

fromString :: String -> Route τ

type Prefix = Rope

type Remainder = Rope

literalRoute :: Prefix -> Route τ

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 τ

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 τ

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 τ

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 Routes listed as children.

Since: 0.2.0

Compile

prepareRoutes :: [Route τ] -> Program τ Application

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

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