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

IsString MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

fromString :: String -> MediaType

Show MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

showsPrec :: Int -> MediaType -> ShowS

show :: MediaType -> String

showList :: [MediaType] -> ShowS

Eq MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

(==) :: MediaType -> MediaType -> Bool

(/=) :: MediaType -> MediaType -> Bool

Ord MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

compare :: MediaType -> MediaType -> Ordering

(<) :: MediaType -> MediaType -> Bool

(<=) :: MediaType -> MediaType -> Bool

(>) :: MediaType -> MediaType -> Bool

(>=) :: MediaType -> MediaType -> Bool

max :: MediaType -> MediaType -> MediaType

min :: MediaType -> MediaType -> MediaType

Accept MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

parseAccept :: ByteString -> Maybe MediaType

matches :: MediaType -> MediaType -> Bool

moreSpecificThan :: MediaType -> MediaType -> Bool

hasExtensionParameters :: Proxy MediaType -> Bool

RenderHeader MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

renderHeader :: MediaType -> ByteString

(//) :: 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 -> CI ByteString

Retrieves the main type of a MediaType.

subType :: MediaType -> CI 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 (CI ByteString)

Retrieves a parameter from a MediaType.

Charsets

data Charset

Suitable for HTTP charset as defined in RFC7231.

Specifically:

charset = token / "*"

Instances

IsString Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

fromString :: String -> Charset

Show Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

showsPrec :: Int -> Charset -> ShowS

show :: Charset -> String

showList :: [Charset] -> ShowS

Eq Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

(==) :: Charset -> Charset -> Bool

(/=) :: Charset -> Charset -> Bool

Ord Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

compare :: Charset -> Charset -> Ordering

(<) :: Charset -> Charset -> Bool

(<=) :: Charset -> Charset -> Bool

(>) :: Charset -> Charset -> Bool

(>=) :: Charset -> Charset -> Bool

max :: Charset -> Charset -> Charset

min :: Charset -> Charset -> Charset

Accept Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

parseAccept :: ByteString -> Maybe Charset

matches :: Charset -> Charset -> Bool

moreSpecificThan :: Charset -> Charset -> Bool

hasExtensionParameters :: Proxy Charset -> Bool

RenderHeader Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

renderHeader :: Charset -> ByteString

Encodings

data Encoding

Suitable for HTTP encoding as defined in RFC7231.

Specifically:

codings = content-coding / "identity" / "*"

Instances

IsString Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

fromString :: String -> Encoding

Show Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

showsPrec :: Int -> Encoding -> ShowS

show :: Encoding -> String

showList :: [Encoding] -> ShowS

Eq Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

(==) :: Encoding -> Encoding -> Bool

(/=) :: Encoding -> Encoding -> Bool

Ord Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

compare :: Encoding -> Encoding -> Ordering

(<) :: Encoding -> Encoding -> Bool

(<=) :: Encoding -> Encoding -> Bool

(>) :: Encoding -> Encoding -> Bool

(>=) :: Encoding -> Encoding -> Bool

max :: Encoding -> Encoding -> Encoding

min :: Encoding -> Encoding -> Encoding

Accept Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

parseAccept :: ByteString -> Maybe Encoding

matches :: Encoding -> Encoding -> Bool

moreSpecificThan :: Encoding -> Encoding -> Bool

hasExtensionParameters :: Proxy Encoding -> Bool

RenderHeader Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

renderHeader :: Encoding -> ByteString

Languages

data Language

Suitable for HTTP language-ranges as defined in RFC4647.

Specifically:

language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*"

Instances

IsString Language

Defined in Network.HTTP.Media.Language.Internal

Methods

fromString :: String -> Language

Show Language

Defined in Network.HTTP.Media.Language.Internal

Methods

showsPrec :: Int -> Language -> ShowS

show :: Language -> String

showList :: [Language] -> ShowS

Eq Language

Defined in Network.HTTP.Media.Language.Internal

Methods

(==) :: Language -> Language -> Bool

(/=) :: Language -> Language -> Bool

Ord Language

Defined in Network.HTTP.Media.Language.Internal

Methods

compare :: Language -> Language -> Ordering

(<) :: Language -> Language -> Bool

(<=) :: Language -> Language -> Bool

(>) :: Language -> Language -> Bool

(>=) :: Language -> Language -> Bool

max :: Language -> Language -> Language

min :: Language -> Language -> Language

Accept Language

Defined in Network.HTTP.Media.Language.Internal

Methods

parseAccept :: ByteString -> Maybe Language

matches :: Language -> Language -> Bool

moreSpecificThan :: Language -> Language -> Bool

hasExtensionParameters :: Proxy Language -> Bool

RenderHeader Language

Defined in Network.HTTP.Media.Language.Internal

Methods

renderHeader :: Language -> ByteString

toParts :: Language -> [CI ByteString]

Converts Language to a list of its language parts. The wildcard produces an empty list.

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)
    ]

mapAcceptCharset

Arguments

:: [(Charset, b)]

The map of server-side preferences to values

-> ByteString

The client-side header value

-> Maybe b

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

getHeader >>= maybe render406Error renderResource . mapAcceptCharset
    [ ("utf-8",    inUtf8)
    , ("us-ascii", inAscii)
    ]

mapAcceptEncoding

Arguments

:: [(Encoding, b)]

The map of server-side preferences to values

-> ByteString

The client-side header value

-> Maybe b

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

getHeader >>= maybe render406Error renderResource . mapAcceptEncoding
    [ ("compress", compress)
    , ("identity", id)
    ]

mapAcceptLanguage

Arguments

:: [(Language, b)]

The map of server-side preferences to values

-> ByteString

The client-side header value

-> Maybe b

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

getHeader >>= maybe render406Error renderResource . mapAcceptLanguage
    [ ("en-gb", inBritishEnglish)
    , ("fr",    inFrench)
    ]

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
    [ ("abc", abc)
    , ("xyz", xyz)
    ]

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)
        ]

mapContentCharset

Arguments

:: [(Charset, b)]

The map of server-side responses

-> ByteString

The client request's header value

-> Maybe b

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

getContentCharset >>=
    maybe send415Error readRequestBodyWith . mapContentCharset
        [ ("utf-8",    parseUtf8)
        , ("us-ascii", parseAscii)
        ]

mapContentEncoding

Arguments

:: [(Encoding, b)]

The map of server-side responses

-> ByteString

The client request's header value

-> Maybe b

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

getContentEncoding >>=
    maybe send415Error readRequestBodyWith . mapContentEncoding
        [ ("compress", decompress)
        , ("identity", id)
        ]

mapContentLanguage

Arguments

:: [(Language, b)]

The map of server-side responses

-> ByteString

The client request's header value

-> Maybe b

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

getContentLanguage >>=
    maybe send415Error readRequestBodyWith . mapContentLanguage
        [ ("en-gb", parseBritishEnglish)
        , ("fr",    parseFrench)
        ]

Quality values

data Quality a

Attaches a quality value to data.

Instances

Functor Quality

Defined in Network.HTTP.Media.Quality

Methods

fmap :: (a -> b) -> Quality a -> Quality b

(<$) :: a -> Quality b -> Quality a

RenderHeader a => Show (Quality a)

Defined in Network.HTTP.Media.Quality

Methods

showsPrec :: Int -> Quality a -> ShowS

show :: Quality a -> String

showList :: [Quality a] -> ShowS

Eq a => Eq (Quality a)

Defined in Network.HTTP.Media.Quality

Methods

(==) :: Quality a -> Quality a -> Bool

(/=) :: Quality a -> Quality a -> Bool

Ord a => Ord (Quality a)

Defined in Network.HTTP.Media.Quality

Methods

compare :: Quality a -> Quality a -> Ordering

(<) :: Quality a -> Quality a -> Bool

(<=) :: Quality a -> Quality a -> Bool

(>) :: Quality a -> Quality a -> Bool

(>=) :: Quality a -> Quality a -> Bool

max :: Quality a -> Quality a -> Quality a

min :: Quality a -> Quality a -> Quality a

RenderHeader h => RenderHeader (Quality h)

Defined in Network.HTTP.Media.Quality

Methods

renderHeader :: Quality h -> ByteString

quality :: a -> ByteString -> Quality a

Manually construct a quality value.

data QualityOrder

An opaque ordered representation of quality values without attached data.

Instances

Eq QualityOrder

Defined in Network.HTTP.Media.Quality

Methods

(==) :: QualityOrder -> QualityOrder -> Bool

(/=) :: QualityOrder -> QualityOrder -> Bool

Ord QualityOrder

Defined in Network.HTTP.Media.Quality

Methods

compare :: QualityOrder -> QualityOrder -> Ordering

(<) :: QualityOrder -> QualityOrder -> Bool

(<=) :: QualityOrder -> QualityOrder -> Bool

(>) :: QualityOrder -> QualityOrder -> Bool

(>=) :: QualityOrder -> QualityOrder -> Bool

max :: QualityOrder -> QualityOrder -> QualityOrder

min :: QualityOrder -> QualityOrder -> QualityOrder

qualityOrder :: Quality a -> QualityOrder

Remove the attached data from a quality value, retaining only the priority of the quality parameter.

isAcceptable :: Quality a -> Bool

Whether the quality value is greater than zero; otherwise the value should never be accepted, even when no other options are available.

maxQuality :: a -> Quality a

Attaches the quality value '1'.

minQuality :: a -> Quality a

Attaches the quality value '0'.

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.

Minimal complete definition

parseAccept, matches, moreSpecificThan

Methods

parseAccept :: ByteString -> Maybe a

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

matches :: a -> a -> Bool

Evaluates whether either the left argument matches the right one.

This relation must be a total order, where more specific terms on the left can produce a match, but a less specific term on the left can never produce a match. For instance, when matching against media types it is important that if the client asks for a general type then we can choose a more specific offering from the server, but if a client asks for a specific type and the server only offers a more general form, then we cannot generalise. In this case, the server types will be the left argument, and the client types the right.

For types with no concept of specificity, this operation is just equality.

moreSpecificThan :: a -> a -> Bool

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

This relation must be irreflexive and transitive. For types with no concept of specificity, this is the empty relation (always false).

hasExtensionParameters :: Proxy a -> Bool

Indicates whether extension parameters are permitted after the weight parameter when this type appears in an Accept header. Defaults to false.

Instances

Accept ByteString

Defined in Network.HTTP.Media.Accept

Methods

parseAccept :: ByteString -> Maybe ByteString

matches :: ByteString -> ByteString -> Bool

moreSpecificThan :: ByteString -> ByteString -> Bool

hasExtensionParameters :: Proxy ByteString -> Bool

Accept Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

parseAccept :: ByteString -> Maybe Charset

matches :: Charset -> Charset -> Bool

moreSpecificThan :: Charset -> Charset -> Bool

hasExtensionParameters :: Proxy Charset -> Bool

Accept Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

parseAccept :: ByteString -> Maybe Encoding

matches :: Encoding -> Encoding -> Bool

moreSpecificThan :: Encoding -> Encoding -> Bool

hasExtensionParameters :: Proxy Encoding -> Bool

Accept Language

Defined in Network.HTTP.Media.Language.Internal

Methods

parseAccept :: ByteString -> Maybe Language

matches :: Language -> Language -> Bool

moreSpecificThan :: Language -> Language -> Bool

hasExtensionParameters :: Proxy Language -> Bool

Accept MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

parseAccept :: ByteString -> Maybe MediaType

matches :: MediaType -> MediaType -> Bool

moreSpecificThan :: MediaType -> MediaType -> Bool

hasExtensionParameters :: Proxy MediaType -> Bool

Rendering

class RenderHeader h where

A class for header values, so they may be rendered to their ByteString representation. Lists of header values and quality-marked header values will render appropriately.

Methods

renderHeader :: h -> ByteString

Render a header value to a UTF-8 ByteString.

Instances

RenderHeader ByteString

Defined in Network.HTTP.Media.RenderHeader

Methods

renderHeader :: ByteString -> ByteString

RenderHeader Charset

Defined in Network.HTTP.Media.Charset.Internal

Methods

renderHeader :: Charset -> ByteString

RenderHeader Encoding

Defined in Network.HTTP.Media.Encoding.Internal

Methods

renderHeader :: Encoding -> ByteString

RenderHeader Language

Defined in Network.HTTP.Media.Language.Internal

Methods

renderHeader :: Language -> ByteString

RenderHeader MediaType

Defined in Network.HTTP.Media.MediaType.Internal

Methods

renderHeader :: MediaType -> ByteString

RenderHeader h => RenderHeader (Quality h)

Defined in Network.HTTP.Media.Quality

Methods

renderHeader :: Quality h -> ByteString

RenderHeader h => RenderHeader [h]

Defined in Network.HTTP.Media.RenderHeader

Methods

renderHeader :: [h] -> ByteString