wai-extra-3.1.13.0: Provides some basic WAI handlers and middleware.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Network.Wai.Middleware.CombineHeaders

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

Documentation

combineHeaders :: CombineSettings -> Middleware Source #

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 Source #

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

defaultCombineSettings :: CombineSettings Source #

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

data HandleType Source #

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 Source # 
Instance details

Defined in Network.Wai.Middleware.CombineHeaders

Eq HandleType Source # 
Instance details

Defined in Network.Wai.Middleware.CombineHeaders

defaultHeaderMap :: HeaderMap Source #

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 Source #

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 Source #

Convenience function to remove a header from the header map.

Since: 3.1.13.0

regular :: HandleType Source #

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 Source #

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 Source #

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 Source #

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

Since: 3.1.13.0