http-reverse-proxy-0.6.2.0: Reverse proxy HTTP requests, either over raw sockets or with WAI

Safe Haskell | None
Language | Haskell2010

Network.HTTP.ReverseProxy

Contents

- Types
- Raw
- WAI + http-conduit
  - Settings
    - Local settings

Synopsis

- data ProxyDest = ProxyDest {
  - pdHost :: !ByteString
  - pdPort :: !Int
  }
- rawProxyTo :: MonadUnliftIO m => (RequestHeaders -> m (Either (AppData -> m ()) ProxyDest)) -> AppData -> m ()
- rawTcpProxyTo :: MonadIO m => ProxyDest -> AppData -> m ()
- waiProxyTo :: (Request -> IO WaiProxyResponse) -> (SomeException -> Application) -> Manager -> Application
- defaultOnExc :: SomeException -> Application
- waiProxyToSettings :: (Request -> IO WaiProxyResponse) -> WaiProxySettings -> Manager -> Application
- data WaiProxyResponse
  - = WPRResponse Response
  - | WPRProxyDest ProxyDest
  - | WPRProxyDestSecure ProxyDest
  - | WPRModifiedRequest Request ProxyDest
  - | WPRModifiedRequestSecure Request ProxyDest
  - | WPRApplication Application
- data WaiProxySettings
- defaultWaiProxySettings :: WaiProxySettings
- wpsOnExc :: WaiProxySettings -> SomeException -> Application
- wpsTimeout :: WaiProxySettings -> Maybe Int
- wpsSetIpHeader :: WaiProxySettings -> SetIpHeader
- wpsProcessBody :: WaiProxySettings -> Request -> Response () -> Maybe (ConduitT ByteString (Flush Builder) IO ())
- wpsUpgradeToRaw :: WaiProxySettings -> Request -> Bool
- wpsGetDest :: WaiProxySettings -> Maybe (Request -> IO (LocalWaiProxySettings, WaiProxyResponse))
- wpsLogRequest :: WaiProxySettings -> Request -> IO ()
- wpsModifyResponseHeaders :: WaiProxySettings -> Request -> Response () -> ResponseHeaders -> ResponseHeaders
- data SetIpHeader
  - = SIHNone
  - | SIHFromSocket
  - | SIHFromHeader
- data LocalWaiProxySettings
- defaultLocalWaiProxySettings :: LocalWaiProxySettings
- setLpsTimeBound :: Maybe Int -> LocalWaiProxySettings -> LocalWaiProxySettings

# Types

data ProxyDest Source #

Host/port combination to which we want to proxy.

Constructors

ProxyDest |

Fields

- pdHost :: !ByteString
- pdPort :: !Int

#### Instances

Instances details

Generic ProxyDest Source # |

Instance details

Defined in Network.HTTP.ReverseProxy

Associated Types

type Rep ProxyDest |

Instance details

Defined in Network.HTTP.ReverseProxy

type Rep ProxyDest = D1 ('MetaData "ProxyDest" "Network.HTTP.ReverseProxy" "http-reverse-proxy-0.6.2.0-3lK9yPr9Jc94mSE1U1XrCV" 'False) (C1 ('MetaCons "ProxyDest" 'PrefixI 'True) (S1 ('MetaSel ('Just "pdHost") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString) :*: S1 ('MetaSel ('Just "pdPort") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)))

Methods

from :: ProxyDest -> Rep ProxyDest x Source #

to :: Rep ProxyDest x -> ProxyDest Source #

Read ProxyDest Source # |
Instance details Defined in Network.HTTP.ReverseProxy Methods readsPrec :: Int -> ReadS ProxyDest Source # readList :: ReadS [ProxyDest] Source # readPrec :: ReadPrec ProxyDest Source # readListPrec :: ReadPrec [ProxyDest] Source #
Show ProxyDest Source # |
Instance details Defined in Network.HTTP.ReverseProxy Methods showsPrec :: Int -> ProxyDest -> ShowS Source # show :: ProxyDest -> String Source # showList :: [ProxyDest] -> ShowS Source #
Eq ProxyDest Source # |
Instance details Defined in Network.HTTP.ReverseProxy Methods (==) :: ProxyDest -> ProxyDest -> Bool Source # (/=) :: ProxyDest -> ProxyDest -> Bool Source #
Ord ProxyDest Source # |

Instance details

Defined in Network.HTTP.ReverseProxy

Methods

compare :: ProxyDest -> ProxyDest -> Ordering Source #

(<) :: ProxyDest -> ProxyDest -> Bool Source #

(<=) :: ProxyDest -> ProxyDest -> Bool Source #

(>) :: ProxyDest -> ProxyDest -> Bool Source #

(>=) :: ProxyDest -> ProxyDest -> Bool Source #

max :: ProxyDest -> ProxyDest -> ProxyDest Source #

min :: ProxyDest -> ProxyDest -> ProxyDest Source #

type Rep ProxyDest Source # |

Instance details

Defined in Network.HTTP.ReverseProxy

type Rep ProxyDest = D1 ('MetaData "ProxyDest" "Network.HTTP.ReverseProxy" "http-reverse-proxy-0.6.2.0-3lK9yPr9Jc94mSE1U1XrCV" 'False) (C1 ('MetaCons "ProxyDest" 'PrefixI 'True) (S1 ('MetaSel ('Just "pdHost") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString) :*: S1 ('MetaSel ('Just "pdPort") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)))

# Raw

rawProxyTo Source #

Arguments

:: MonadUnliftIO m |
=> (RequestHeaders -> m (Either (AppData -> m ()) ProxyDest)) | How to reverse proxy. A `Left` result will run the given `Application`, whereas a `Right` will reverse proxy to the given host/port.
-> AppData |
-> m () |

Set up a reverse proxy server, which will have a minimal overhead.

This function uses raw sockets, parsing as little of the request as possible. The workflow is:

1. Parse the first request headers.
2. Ask the supplied function to specify how to reverse proxy.
3. Open up a connection to the given host/port.
4. Pass all bytes across the wire unchanged.

If you need more control, such as modifying the request or response, use `waiProxyTo`.

rawTcpProxyTo :: MonadIO m => ProxyDest -> AppData -> m () Source #

Set up a reverse tcp proxy server, which will have a minimal overhead.

This function uses raw sockets, parsing as little of the request as possible. The workflow is:

1. Open up a connection to the given host/port.
2. Pass all bytes across the wire unchanged.

If you need more control, such as modifying the request or response, use `waiProxyTo`.

Since: 0.4.4

# WAI + http-conduit

waiProxyTo Source #

Arguments

:: (Request -> IO WaiProxyResponse) | How to reverse proxy.
-> (SomeException -> Application) | How to handle exceptions when calling remote server. For a simple 502 error page, use `defaultOnExc`.
-> Manager | connection manager to utilize
-> Application |

Creates a WAI `Application` which will handle reverse proxies.

Connections to the proxied server will be provided via http-conduit. As such, all requests and responses will be fully processed in your reverse proxy. This allows you much more control over the data sent over the wire, but also incurs overhead. For a lower-overhead approach, consider `rawProxyTo`.

Most likely, the given application should be run with Warp, though in theory other WAI handlers will work as well.

Note: This function will use chunked request bodies for communicating with the proxied server. Not all servers necessarily support chunked request bodies, so please confirm that yours does (Warp, Snap, and Happstack, for example, do).

defaultOnExc :: SomeException -> Application Source #

Sends a simple 502 bad gateway error message with the contents of the exception.

waiProxyToSettings :: (Request -> IO WaiProxyResponse) -> WaiProxySettings -> Manager -> Application Source #

data WaiProxyResponse Source #

The different responses that could be generated by a `waiProxyTo` lookup function.

Since: 0.2.0

Constructors

WPRResponse Response | Respond with the given WAI Response. Since: 0.2.0
WPRProxyDest ProxyDest | Send to the given destination. Since: 0.2.0
WPRProxyDestSecure ProxyDest | Send to the given destination via HTTPS.
WPRModifiedRequest Request ProxyDest | Send to the given destination, but use the given modified Request for computing the reverse-proxied request. This can be useful for reverse proxying to a different path than the one specified. By the user. The path will be taken from rawPathInfo while the queryString from rawQueryString of the request. Since: 0.2.0
WPRModifiedRequestSecure Request ProxyDest | Same as WPRModifiedRequest but send to the given destination via HTTPS.
WPRApplication Application | Respond with the given WAI Application. Since: 0.4.0

## Settings

data WaiProxySettings Source #

defaultWaiProxySettings :: WaiProxySettings Source #

Default value for `WaiProxySettings`

Since: 0.6.0

wpsOnExc :: WaiProxySettings -> SomeException -> Application Source #

wpsTimeout :: WaiProxySettings -> Maybe Int Source #

wpsSetIpHeader :: WaiProxySettings -> SetIpHeader Source #

Set the X-Real-IP request header with the client's IP address.

Default: SIHFromSocket

Since: 0.2.0

wpsProcessBody :: WaiProxySettings -> Request -> Response () -> Maybe (ConduitT ByteString (Flush Builder) IO ()) Source #

Post-process the response body returned from the host. The API for this function changed to include the extra `Request` parameter in version 0.5.0.

Since: 0.2.1

wpsUpgradeToRaw :: WaiProxySettings -> Request -> Bool Source #

Determine if the request should be upgraded to a raw proxy connection, as is needed for WebSockets. Requires WAI 2.1 or higher and a WAI handler with raw response support (e.g., Warp) to work.

Default: check if the upgrade header is websocket.

Since: 0.3.1

wpsGetDest :: WaiProxySettings -> Maybe (Request -> IO (LocalWaiProxySettings, WaiProxyResponse)) Source #

Allow to override proxy settings for each request. If you supply this field it will take precedence over getDest parameter in waiProxyToSettings

Default: have one global setting

Since: 0.4.2

wpsLogRequest :: WaiProxySettings -> Request -> IO () Source #

Function provided to log the `Request` that is constructed.

Default: no op

Since: 0.6.0.1

wpsModifyResponseHeaders :: WaiProxySettings -> Request -> Response () -> ResponseHeaders -> ResponseHeaders Source #

Allow to override the response headers before the response is returned upstream. Useful for example to override overly-strict 'Content-Security-Policy' when the source is known to be trustworthy.

Default: no op

Since: 0.6.1.0

data SetIpHeader Source #

How to set the X-Real-IP request header.

Since: 0.2.0

Constructors

SIHNone | Do not set the header
SIHFromSocket | Set it from the socket's address.
SIHFromHeader | Set it from either X-Real-IP or X-Forwarded-For, if present

### Local settings

data LocalWaiProxySettings Source #

defaultLocalWaiProxySettings :: LocalWaiProxySettings Source #

Default value for `LocalWaiProxySettings`, same as `def` but with a more explicit name.

Since: 0.4.2

setLpsTimeBound :: Maybe Int -> LocalWaiProxySettings -> LocalWaiProxySettings Source #

Allows to specify the maximum time allowed for the conection on per request basis.

Default: no timeouts

Since: 0.4.2