happstack-server-7.1.7: Web related tools and services.

Safe Haskell | None

Happstack.Server.Routing

Contents

- Route by scheme
- Route by request method
- Route by pathInfo
- Route by host
- Route by (Request -> Bool)

Description

Route an incoming `Request` to a handler. For more in-depth documentation see this section of the Happstack Crash Course: http://happstack.com/docs/crashcourse/RouteFilters.html

Synopsis

- http :: (ServerMonad m, MonadPlus m) => m ()
- https :: (ServerMonad m, MonadPlus m) => m ()
- methodM :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()
- methodOnly :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()
- methodSP :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m b -> m b
- method :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()
- class MatchMethod m where
  - matchMethod :: m -> Method -> Bool
- dir :: (ServerMonad m, MonadPlus m) => String -> m a -> m a
- dirs :: (ServerMonad m, MonadPlus m) => FilePath -> m a -> m a
- nullDir :: (ServerMonad m, MonadPlus m) => m ()
- trailingSlash :: (ServerMonad m, MonadPlus m) => m ()
- noTrailingSlash :: (ServerMonad m, MonadPlus m) => m ()
- anyPath :: (ServerMonad m, MonadPlus m) => m r -> m r
- path :: (FromReqURI a, MonadPlus m, ServerMonad m) => (a -> m b) -> m b
- uriRest :: ServerMonad m => (String -> m a) -> m a
- host :: (ServerMonad m, MonadPlus m) => String -> m a -> m a
- withHost :: (ServerMonad m, MonadPlus m) => (String -> m a) -> m a
- guardRq :: (ServerMonad m, MonadPlus m) => (Request -> Bool) -> m ()

# Route by scheme

http :: (ServerMonad m, MonadPlus m) => m ()

guard which checks that an insecure connection was made via http://

Example:

     handler :: ServerPart Response
     handler =
         do https
            ...

https :: (ServerMonad m, MonadPlus m) => m ()

guard which checks that a secure connection was made via https://

Example:

     handler :: ServerPart Response
     handler =
         do https
            ...

# Route by request method

methodM :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()

Guard against the method. This function also guards against *any remaining path segments*. See `method` for the version that guards only by method.

Example:

     handler :: ServerPart Response
     handler =
         do methodM [GET, HEAD]
            ...

NOTE: This function is largely retained for backwards compatibility. The fact that implicitly calls `nullDir` is often forgotten and leads to confusion. It is probably better to just use `method` and call `nullDir` explicitly.

This function will likely be deprecated in the future.

methodOnly :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()

Deprecated: this function is just an alias for method now

Guard against the method only (as opposed to `methodM`).

Example:

     handler :: ServerPart Response
     handler =
         do methodOnly [GET, HEAD]
            ...

methodSP :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m b -> m b

Deprecated: use method instead.

Guard against the method. Note, this function also guards against any remaining path segments. Similar to `methodM` but with a different type signature.

Example:

     handler :: ServerPart Response
     handler = methodSP [GET, HEAD] $ subHandler

NOTE: This style of combinator is going to be deprecated in the future. It is better to just use `method`.

     handler :: ServerPart Response
     handler = method [GET, HEAD] >> nullDir >> subHandler

method :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()

Guard against the method only (as opposed to `methodM`).

Example:

     handler :: ServerPart Response
     handler =
         do methodOnly [GET, HEAD]
            ...

class MatchMethod m where

instances of this class provide a variety of ways to match on the `Request` method.

Examples:

     method GET                  -- match GET or HEAD
     method [GET, POST]          -- match GET, HEAD or POST
     method HEAD                 -- match HEAD /but not/ GET
     method (== GET)             -- match GET or HEAD
     method (not . (==) DELETE)  -- match any method except DELETE
     method ()                   -- match any method

As you can see, GET implies that HEAD should match as well. This is to make it harder to write an application that uses HTTP incorrectly. Happstack handles HEAD requests automatically, but we still need to make sure our handlers don't mismatch or a HEAD will result in a 404.

If you must, you can still do something like this to match GET without HEAD:

     guardRq ((== GET) . rqMethod)

Methods

matchMethod :: m -> Method -> Bool

Instances

MatchMethod () |
MatchMethod Method |
MatchMethod [Method] |
MatchMethod (Method -> Bool) |

# Route by pathInfo

dir :: (ServerMonad m, MonadPlus m) => String -> m a -> m a

Pop a path element and run the supplied handler if it matches the given string.

     handler :: ServerPart Response
     handler = dir "foo" $ dir "bar" $ subHandler

The path element can not contain '/'. See also `dirs`.

dirs :: (ServerMonad m, MonadPlus m) => FilePath -> m a -> m a

Guard against a `FilePath`. Unlike `dir` the `FilePath` may contain '/'. If the guard succeeds, the matched elements will be popped from the directory stack.

     dirs "foo/bar" $ ...

See also: `dir`.

nullDir :: (ServerMonad m, MonadPlus m) => m ()

guard which only succeeds if there are no remaining path segments

Often used if you want to explicitly assign a route for `/`

trailingSlash :: (ServerMonad m, MonadPlus m) => m ()

Guard which checks that the Request URI ends in `'/'`. Useful for distinguishing between `foo` and `foo/`

noTrailingSlash :: (ServerMonad m, MonadPlus m) => m ()

The opposite of `trailingSlash`.

anyPath :: (ServerMonad m, MonadPlus m) => m r -> m r

Pop any path element and run the handler.

Succeeds if a path component was popped. Fails is the remaining path was empty.

path :: (FromReqURI a, MonadPlus m, ServerMonad m) => (a -> m b) -> m b

Pop a path element and parse it using the `fromReqURI` in the `FromReqURI` class.

uriRest :: ServerMonad m => (String -> m a) -> m a

Grab the rest of the URL (dirs + query) and passes it to your handler.

# Route by host

host :: (ServerMonad m, MonadPlus m) => String -> m a -> m a

Guard against the host.

This matches against the `host` header specified in the incoming `Request`.

Can be used to support virtual hosting, http://en.wikipedia.org/wiki/Virtual_hosting

Note that this matches against the value of the `Host` header which may include the port number.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.23

see also: `withHost`

withHost :: (ServerMonad m, MonadPlus m) => (String -> m a) -> m a

Lookup the `host` header in the incoming request and pass it to the handler.

see also: `host`

# Route by (Request -> Bool)

guardRq :: (ServerMonad m, MonadPlus m) => (Request -> Bool) -> m ()

Guard using an arbitrary function on the `Request`.