Network.HTTP.Media

http-media-0.8.1.1: Processing HTTP Content-Type and Accept headers

Safe Haskell | Safe-Inferred
Language | Haskell2010

Network.HTTP.Media

Contents

- Media types
- Charsets
- Encodings
- Languages
- Accept matching
- Content matching
- Quality values
- Accept
- Rendering

Description

A framework for parsing HTTP media type headers.

Synopsis

- data MediaType
- (//) :: ByteString -> ByteString -> MediaType
- (/:) :: MediaType -> (ByteString, ByteString) -> MediaType
- mainType :: MediaType -> CI ByteString
- subType :: MediaType -> CI ByteString
- parameters :: MediaType -> Parameters
- (/?) :: MediaType -> ByteString -> Bool
- (/.) :: MediaType -> ByteString -> Maybe (CI ByteString)
- data Charset
- data Encoding
- data Language
- toParts :: Language -> [CI ByteString]
- matchAccept :: Accept a => [a] -> ByteString -> Maybe a
- mapAccept :: Accept a => [(a, b)] -> ByteString -> Maybe b
- mapAcceptMedia :: [(MediaType, b)] -> ByteString -> Maybe b
- mapAcceptCharset :: [(Charset, b)] -> ByteString -> Maybe b
- mapAcceptEncoding :: [(Encoding, b)] -> ByteString -> Maybe b
- mapAcceptLanguage :: [(Language, b)] -> ByteString -> Maybe b
- mapAcceptBytes :: [(ByteString, b)] -> ByteString -> Maybe b
- matchContent :: Accept a => [a] -> ByteString -> Maybe a
- mapContent :: Accept a => [(a, b)] -> ByteString -> Maybe b
- mapContentMedia :: [(MediaType, b)] -> ByteString -> Maybe b
- mapContentCharset :: [(Charset, b)] -> ByteString -> Maybe b
- mapContentEncoding :: [(Encoding, b)] -> ByteString -> Maybe b
- mapContentLanguage :: [(Language, b)] -> ByteString -> Maybe b
- data Quality a
- quality :: a -> ByteString -> Quality a
- data QualityOrder
- qualityOrder :: Quality a -> QualityOrder
- isAcceptable :: Quality a -> Bool
- maxQuality :: a -> Quality a
- minQuality :: a -> Quality a
- parseQuality :: Accept a => ByteString -> Maybe [Quality a]
- matchQuality :: Accept a => [a] -> [Quality a] -> Maybe a
- mapQuality :: Accept a => [(a, b)] -> [Quality a] -> Maybe b
- class Show a => Accept a where
  - parseAccept :: ByteString -> Maybe a
  - matches :: a -> a -> Bool
  - moreSpecificThan :: a -> a -> Bool
  - hasExtensionParameters :: Proxy a -> Bool
- class RenderHeader h where
  - renderHeader :: h -> ByteString

# Media types

data MediaType #

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

#### Instances

Instances details

IsString MediaType # |
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods fromString :: String -> MediaType #
Show MediaType # |
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods showsPrec :: Int -> MediaType -> ShowS # show :: MediaType -> String # showList :: [MediaType] -> ShowS #
Eq MediaType # |
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods (==) :: MediaType -> MediaType -> Bool # (/=) :: MediaType -> MediaType -> Bool #
Ord MediaType # |
Instance details 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 # |
Instance details 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 # |
Instance details 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

Instances details

IsString Charset # |
Instance details Defined in Network.HTTP.Media.Charset.Internal Methods fromString :: String -> Charset #
Show Charset # |
Instance details Defined in Network.HTTP.Media.Charset.Internal Methods showsPrec :: Int -> Charset -> ShowS # show :: Charset -> String # showList :: [Charset] -> ShowS #
Eq Charset # |
Instance details Defined in Network.HTTP.Media.Charset.Internal Methods (==) :: Charset -> Charset -> Bool # (/=) :: Charset -> Charset -> Bool #
Ord Charset # |
Instance details 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 # |
Instance details 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 # |
Instance details 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

Instances details

IsString Encoding # |
Instance details Defined in Network.HTTP.Media.Encoding.Internal Methods fromString :: String -> Encoding #
Show Encoding # |
Instance details Defined in Network.HTTP.Media.Encoding.Internal Methods showsPrec :: Int -> Encoding -> ShowS # show :: Encoding -> String # showList :: [Encoding] -> ShowS #
Eq Encoding # |
Instance details Defined in Network.HTTP.Media.Encoding.Internal Methods (==) :: Encoding -> Encoding -> Bool # (/=) :: Encoding -> Encoding -> Bool #
Ord Encoding # |
Instance details 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 # |
Instance details 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 # |
Instance details 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

Instances details

IsString Language # |
Instance details Defined in Network.HTTP.Media.Language.Internal Methods fromString :: String -> Language #
Show Language # |
Instance details Defined in Network.HTTP.Media.Language.Internal Methods showsPrec :: Int -> Language -> ShowS # show :: Language -> String # showList :: [Language] -> ShowS #
Eq Language # |
Instance details Defined in Network.HTTP.Media.Language.Internal Methods (==) :: Language -> Language -> Bool # (/=) :: Language -> Language -> Bool #
Ord Language # |
Instance details 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 # |
Instance details 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 # |
Instance details 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

Instances details

Functor Quality # |
Instance details Defined in Network.HTTP.Media.Quality Methods fmap :: (a -> b) -> Quality a -> Quality b # (<$) :: a -> Quality b -> Quality a #
RenderHeader a => Show (Quality a) # |
Instance details 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) # |
Instance details Defined in Network.HTTP.Media.Quality Methods (==) :: Quality a -> Quality a -> Bool # (/=) :: Quality a -> Quality a -> Bool #
Ord a => Ord (Quality a) # |
Instance details 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) # |
Instance details 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

Instances details

Eq QualityOrder # |
Instance details Defined in Network.HTTP.Media.Quality Methods (==) :: QualityOrder -> QualityOrder -> Bool # (/=) :: QualityOrder -> QualityOrder -> Bool #
Ord QualityOrder # |
Instance details 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

Instances details

Accept ByteString # |
Instance details 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 # |
Instance details 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 # |
Instance details 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 # |
Instance details 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 # |
Instance details 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

Instances details

RenderHeader ByteString # |
Instance details Defined in Network.HTTP.Media.RenderHeader Methods renderHeader :: ByteString -> ByteString #
RenderHeader Charset # |
Instance details Defined in Network.HTTP.Media.Charset.Internal Methods renderHeader :: Charset -> ByteString #
RenderHeader Encoding # |
Instance details Defined in Network.HTTP.Media.Encoding.Internal Methods renderHeader :: Encoding -> ByteString #
RenderHeader Language # |
Instance details Defined in Network.HTTP.Media.Language.Internal Methods renderHeader :: Language -> ByteString #
RenderHeader MediaType # |
Instance details Defined in Network.HTTP.Media.MediaType.Internal Methods renderHeader :: MediaType -> ByteString #
RenderHeader h => RenderHeader (Quality h) # |
Instance details Defined in Network.HTTP.Media.Quality Methods renderHeader :: Quality h -> ByteString #
RenderHeader h => RenderHeader [h] # |
Instance details Defined in Network.HTTP.Media.RenderHeader Methods renderHeader :: [h] -> ByteString #