Network.HTTP.Media

A framework for parsing HTTP media type headers.

Media types

data MediaType

An HTTP media type, consisting of the type, subtype, and parameters.

Instances

Eq MediaType

Show MediaType

IsString MediaType

Accept MediaType

(//) :: ByteString -> ByteString -> MediaType

Builds a MediaType without parameters. Can produce an error if either type is invalid.

(/:) :: MediaType -> (ByteString, ByteString) -> MediaType

Adds a parameter to a MediaType. Can produce an error if either string is invalid.

mainType :: MediaType -> ByteString

Retrieves the main type of a MediaType.

subType :: MediaType -> ByteString

Retrieves the sub type of a MediaType.

parameters :: MediaType -> Parameters

Retrieves the parameters of a MediaType.

(/?) :: MediaType -> ByteString -> Bool

Evaluates if a MediaType has a parameter of the given name.

(/.) :: MediaType -> ByteString -> Maybe ByteString

Retrieves a parameter from a MediaType.

Accept matching

matchAccept

Arguments

:: Accept a

=> [a]

The server-side options

-> ByteString

The client-side header value

-> Maybe a

Matches a list of server-side resource options against a quality-marked list of client-side preferences. A result of Nothing means that nothing matched (which should indicate a 406 error). If two or more results arise with the same quality level and specificity, then the first one in the server list is chosen.

The use of the Accept type class allows the application of either MediaType for the standard Accept header or ByteString for any other Accept header which can be marked with a quality value.

 matchAccept ["text/html", "application/json"] <$> getHeader

For more information on the matching process see RFC 2616, section 14.1-4.

mapAccept

Arguments

:: Accept a

=> [(a, b)]

The map of server-side preferences to values

-> ByteString

The client-side header value

-> Maybe b

The equivalent of matchAccept above, except the resulting choice is mapped to another value. Convenient for specifying how to translate the resource into each of its available formats.

 getHeader >>= maybe render406Error renderResource . mapAccept
     [ ("text" // "html",        asHtml)
     , ("application" // "json", asJson)
     ]

mapAcceptMedia

Arguments

:: [(MediaType, b)]

The map of server-side preferences to values

-> ByteString

The client-side header value

-> Maybe b

A specialisation of mapAccept that only takes MediaType as its input, to avoid ambiguous-type errors when using string literal overloading.

 getHeader >>= maybe render406Error renderResource . mapAcceptMedia
     [ ("text/html",        asHtml)
     , ("application/json", asJson)
     ]

mapAcceptBytes

Arguments

:: [(ByteString, b)]

The map of server-side preferences to values

-> ByteString

The client-side header value

-> Maybe b

A specialisation of mapAccept that only takes ByteString as its input, to avoid ambiguous-type errors when using string literal overloading.

 getHeader >>= maybe render406Error encodeResourceWith . mapAcceptBytes
     [ ("compress", compress)
     , ("gzip",     gzip)
     ]

Content matching

matchContent

Arguments

:: Accept a

=> [a]

The server-side response options

-> ByteString

The client's request value

-> Maybe a

Matches a list of server-side parsing options against a the client-side content value. A result of Nothing means that nothing matched (which should indicate a 415 error).

 matchContent ["application/json", "text/plain"] <$> getContentType

For more information on the matching process see RFC 2616, section 14.17.

mapContent

Arguments

:: Accept a

=> [(a, b)]

The map of server-side responses

-> ByteString

The client request's header value

-> Maybe b

The equivalent of matchContent above, except the resulting choice is mapped to another value.

 getContentType >>= maybe send415Error readRequestBodyWith . mapContent
     [ ("application" // "json", parseJson)
     , ("text" // "plain",       parseText)
     ]

mapContentMedia

Arguments

:: [(MediaType, b)]

The map of server-side responses

-> ByteString

The client request's header value

-> Maybe b

A specialisation of mapContent that only takes MediaType as its input, to avoid ambiguous-type errors when using string literal overloading.

 getContentType >>=
     maybe send415Error readRequestBodyWith . mapContentMedia
         [ ("application/json", parseJson)
         , ("text/plain",       parseText)
         ]

Quality values

data Quality a

Attaches a quality value to data.

Instances

Eq a => Eq (Quality a)

Accept a => Show (Quality a)

parseQuality :: Accept a => ByteString -> Maybe [Quality a]

Parses a full Accept header into a list of quality-valued media types.

matchQuality

Arguments

:: Accept a

=> [a]

The server-side options

-> [Quality a]

The pre-parsed client-side header value

-> Maybe a

Matches a list of server-side resource options against a pre-parsed quality-marked list of client-side preferences. A result of Nothing means that nothing matched (which should indicate a 406 error). If two or more results arise with the same quality level and specificity, then the first one in the server list is chosen.

The use of the Accept type class allows the application of either MediaType for the standard Accept header or ByteString for any other Accept header which can be marked with a quality value.

 matchQuality ["text/html", "application/json"] <$> parseQuality header

For more information on the matching process see RFC 2616, section 14.1-4.

mapQuality

Arguments

:: Accept a

=> [(a, b)]

The map of server-side preferences to values

-> [Quality a]

The client-side header value

-> Maybe b

The equivalent of matchQuality above, except the resulting choice is mapped to another value. Convenient for specifying how to translate the resource into each of its available formats.

 parseQuality header >>= maybe render406Error renderResource . mapQuality
     [ ("text" // "html",        asHtml)
     , ("application" // "json", asJson)
     ]

Accept

class Show a => Accept a where

Defines methods for a type whose values can be matched against each other in terms of an HTTP Accept-* header.

This allows functions to work on both the standard Accept header and others such as Accept-Language that still may use quality values.

Methods

parseAccept :: ByteString -> Maybe a

Specifies how to parse an Accept-* header after quality has been handled.

showAccept :: a -> String

Specifies how to show an Accept-* header. Defaults to the standard show method.

Mostly useful just for avoiding quotes when rendering ByteStrings with accompanying quality.

matches :: a -> a -> Bool

Evaluates whether either the left argument matches the right one (order may be important).

moreSpecificThan :: a -> a -> Bool

Evaluates whether the left argument is more specific than the right.

Instances

Accept ByteString

Accept MediaType