| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Network.Wai.Middleware.Approot
Description
Middleware for establishing the root of the application.
Many application need the ability to create URLs referring back to the application itself. For example: generate RSS feeds or sitemaps, giving users copy-paste links, or sending emails. In many cases, the approot can be determined correctly from the request headers. However, some things can prevent this, especially reverse proxies. This module provides multiple ways of configuring approot discovery, and functions for applications to get that approot.
Approots are structured such that they can be prepended to a string such as
foobar?baz=bin. For example, if your application is hosted on
example.com using HTTPS, the approot would be https://example.com. Note
the lack of a trailing slash.
Synopsis
- approotMiddleware :: (Request -> IO ByteString) -> Middleware
- envFallback :: IO Middleware
- envFallbackNamed :: String -> IO Middleware
- hardcoded :: ByteString -> Middleware
- fromRequest :: Middleware
- getApproot :: Request -> ByteString
- getApprootMay :: Request -> Maybe ByteString
Middleware
Arguments
| :: (Request -> IO ByteString) | get the approot |
| -> Middleware |
The most generic version of the middleware, allowing you to provide a function to get the approot for each request. For many use cases, one of the helper functions provided by this module will give the necessary functionality more conveniently.
Since 3.0.7
Common providers
envFallback :: IO Middleware Source #
Same as envFallbackNamed APPROOT
The environment variable APPROOT is used by Keter, School of Haskell, and yesod-devel.
Since 3.0.7
envFallbackNamed :: String -> IO Middleware Source #
Produce a middleware that takes the approot from the given environment
variable, falling back to the behavior of fromRequest if the variable is
not set.
Since 3.0.7
hardcoded :: ByteString -> Middleware Source #
Hard-code the given value as the approot.
Since 3.0.7
fromRequest :: Middleware Source #
Get the approot by analyzing the request. This is not a full-proof approach, but in many common cases will work. Situations that can break this are:
- Requests which spoof headers and imply the connection is over HTTPS
- Reverse proxies that change ports in surprising ways
- Invalid Host headers
- Reverse proxies which modify the path info
Normally trusting headers in this way is insecure, however in the case of
approot, the worst that can happen is that the client will get an incorrect
URL. If you are relying on the approot for some security-sensitive purpose,
it is highly recommended to use hardcoded, which cannot be spoofed.
Since 3.0.7
Functions for applications
getApproot :: Request -> ByteString Source #
Get the approot set by the middleware. If the middleware is not in use,
then this function will return an exception. For a total version of the
function, see getApprootMay.
Since 3.0.7
getApprootMay :: Request -> Maybe ByteString Source #
A total version of getApproot, which returns Nothing if the middleware
is not in use.
Since 3.0.7