wai-extra-3.0.10: Provides some basic WAI handlers and middleware.

Safe HaskellNone
LanguageHaskell98

Network.Wai.Middleware.Approot

Contents

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

Middleware

approotMiddleware Source

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