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

Safe Haskell | None
Language | Haskell2010

Network.Wai.Middleware.CombineHeaders

Contents

- Adjusting the settings

Description

Sometimes incoming requests don't stick to the "no duplicate headers" invariant, for a number of possible reasons (e.g. proxy servers blindly adding headers), or your application (or other middleware) blindly adds headers.

In those cases, you can use this `Middleware` to make sure that headers that can be combined are combined. (e.g. applications might only check the first "Accept" header and fail, while there might be another one that would match)

Synopsis

- combineHeaders :: CombineSettings -> Middleware
- data CombineSettings
- defaultCombineSettings :: CombineSettings
- type HeaderMap = Map HeaderName HandleType
- data HandleType
- defaultHeaderMap :: HeaderMap
- setHeader :: HeaderName -> HandleType -> CombineSettings -> CombineSettings
- removeHeader :: HeaderName -> CombineSettings -> CombineSettings
- setHeaderMap :: HeaderMap -> CombineSettings -> CombineSettings
- regular :: HandleType
- keepOnly :: ByteString -> HandleType
- setRequestHeaders :: Bool -> CombineSettings -> CombineSettings
- setResponseHeaders :: Bool -> CombineSettings -> CombineSettings

# Documentation

combineHeaders :: CombineSettings -> Middleware #

This middleware will reorganize the incoming and/or outgoing headers in such a way that it combines any duplicates of headers that, on their own, can normally have more than one value, and any other headers will stay untouched.

This middleware WILL change the global order of headers (they will be put in alphabetical order), but keep the order of the same type of header. I.e. if there are 3 "Set-Cookie" headers, the first one will still be first, the second one will still be second, etc. But now they are guaranteed to be next to each other.

N.B. This `Middleware` assumes the headers it combines are correctly formatted. If one of the to-be-combined headers is malformed, the new combined header will also (probably) be malformed.

Since: 3.1.13.0

data CombineSettings #

These settings define which headers should be combined, if the combining should happen on incoming (request) headers and if it should happen on outgoing (response) headers.

Any header you put in the header map *will* be used to combine those headers with commas. There's no check to see if it is a header that allows comma-separated lists, so if you want to combine custom headers, go ahead.

(You can check the documentation of `defaultCombineSettings` to see which standard headers are specified to be able to be combined)

Since: 3.1.13.0

#### Instances

Instances details

Show CombineSettings # |
Instance details Defined in Network.Wai.Middleware.CombineHeaders Methods showsPrec :: Int -> CombineSettings -> ShowS # show :: CombineSettings -> String # showList :: [CombineSettings] -> ShowS #
Eq CombineSettings # |
Instance details Defined in Network.Wai.Middleware.CombineHeaders Methods (==) :: CombineSettings -> CombineSettings -> Bool # (/=) :: CombineSettings -> CombineSettings -> Bool #

defaultCombineSettings :: CombineSettings #

Settings that combine request headers, but don't touch response headers.

All types of headers that can be combined (as defined in the spec) will be combined.

To be exact, this is the list:

- Accept
- Accept-CH
- Accept-Charset
- Accept-Encoding
- Accept-Language
- Accept-Post
- Access-Control-Allow-Headers
- Access-Control-Allow-Methods
- Access-Control-Expose-Headers
- Access-Control-Request-Headers
- Allow
- Alt-Svc `(KeepOnly "clear"")`
- Cache-Control
- Clear-Site-Data `(KeepOnly "*")`
- Connection
- Content-Encoding
- Content-Language
- Digest
- If-Match
- If-None-Match `(KeepOnly "*")`
- Link
- Permissions-Policy
- TE
- Timing-Allow-Origin `(KeepOnly "*")`
- Trailer
- Transfer-Encoding
- Upgrade
- Via
- Vary `(KeepOnly "*")`
- Want-Digest

N.B. Any header name that has "KeepOnly" after it will be combined like normal, unless one of the values is the one mentioned ("*" most of the time), then that value is used and all others are dropped.

Since: 3.1.13.0

type HeaderMap = Map HeaderName HandleType #

The mapping of `HeaderName` to `HandleType`

data HandleType #

Both will concatenate with `,` (commas), but `KeepOnly` will drop all values except the given one if present (e.g. in case of wildcards/special values)

For example: If there are multiple `"Clear-Site-Data"` headers, but one of them is the wildcard `"*"` value, using ``KeepOnly` "*"` will cause all others to be dropped and only the wildcard value to remain. (The `"*"` wildcard in this case means ALL site data should be cleared, so no need to include more)

Since: 3.1.13.0

#### Instances

Instances details

Show HandleType # |
Instance details Defined in Network.Wai.Middleware.CombineHeaders Methods showsPrec :: Int -> HandleType -> ShowS # show :: HandleType -> String # showList :: [HandleType] -> ShowS #
Eq HandleType # |
Instance details Defined in Network.Wai.Middleware.CombineHeaders Methods (==) :: HandleType -> HandleType -> Bool # (/=) :: HandleType -> HandleType -> Bool #

defaultHeaderMap :: HeaderMap #

The default collection of HTTP headers that can be combined in case there are multiples in one request or response.

See the documentation of `defaultCombineSettings` for the exact list.

Since: 3.1.13.0

# Adjusting the settings

setHeader :: HeaderName -> HandleType -> CombineSettings -> CombineSettings #

Convenience function to add a header to the header map or, if it is already in the map, to change the `HandleType`.

Since: 3.1.13.0

removeHeader :: HeaderName -> CombineSettings -> CombineSettings #

Convenience function to remove a header from the header map.

Since: 3.1.13.0

setHeaderMap :: HeaderMap -> CombineSettings -> CombineSettings #

Override the `HeaderMap` of the `CombineSettings` (default: `defaultHeaderMap`)

Since: 3.1.13.0

regular :: HandleType #

Use the regular strategy when combining headers. (i.e. merge into one header and separate values with commas)

Since: 3.1.13.0

keepOnly :: ByteString -> HandleType #

Use the regular strategy when combining headers, but if the exact supplied `ByteString` is encountered then discard all other values and only keep that value.

e.g. `keepOnly "*"` will drop all other encountered values

Since: 3.1.13.0

setRequestHeaders :: Bool -> CombineSettings -> CombineSettings #

Set whether the combining of headers should be applied to the incoming request headers. (default: True)

Since: 3.1.13.0

setResponseHeaders :: Bool -> CombineSettings -> CombineSettings #

Set whether the combining of headers should be applied to the outgoing response headers. (default: False)

Since: 3.1.13.0