Network.HTTP.Kinder.Header.Serialization

HeaderNames define semantics for Text values seen in HTTP headers over the wire. This module provides classes to map both to and from these reprsentations.

Classes for encoding and decoding

class HeaderEncode n a where

Determines a Text representation for some value to be encoded as a value of a given HeaderName. Any proxy can be passed as the first argument, although Sing is a nice one to choose. Encodings may choose to not be represented on the wire at all as desired by returning Nothing. This implies default behavior.

Methods

headerEncode :: sing n -> a -> Maybe Text

Instances

HeaderEncode ContentType MediaType

HeaderEncode AccessControlAllowOrigin Text

HeaderEncode AccessControlMaxAge NominalDiffTime

HeaderEncode AccessControlAllowCredentials Bool

HeaderEncode h t => HeaderEncode h (Maybe t)

Any value can be forced as optional if desired

HeaderEncode n (Raw Text)

Reports a "raw" value without interpretation

HeaderEncode AccessControlExposeHeaders [SomeHeaderName]

HeaderEncode AccessControlExposeHeaders (Set SomeHeaderName)

HeaderEncode AccessControlAllowMethods [Verb]

HeaderEncode AccessControlAllowMethods (Set Verb)

HeaderEncode AccessControlAllowHeaders [SomeHeaderName]

HeaderEncode AccessControlAllowHeaders (Set SomeHeaderName)

HeaderEncode Allow [Verb]

HeaderEncode Allow (Set Verb)

class HeaderDecode n a where

Interprets a (possibly missing) Text representation for some value taking semantics at a given HeaderName. Any proxy can be passed as the first argument, although Sing is a nice one to choose. If a value is expected and no representation is provided then Nothing can be passed seeking a default value (should one exist).

Methods

headerDecode :: sing n -> Maybe Text -> Either String a

Instances

HeaderDecode ContentType MediaType

HeaderDecode h t => HeaderDecode h (Maybe t)

Any value may be only optionally captured as desired

HeaderDecode n (Raw Text)

Returns the raw header value

HeaderDecode Accept [Quality MediaType]

Listing constraints to type-level lists

type family AllHeaderEncodes hs :: Constraint

For a given concrete type a, a list of pairs ts satisfies AllHeaderEncode a ts if each (n, a) in ts has HeaderEncode n a.

Equations

AllHeaderEncodes `[]` = ()

AllHeaderEncodes (`(n, a)` : hs) = (HeaderEncode n a, AllHeaderEncodes hs)

type family AllHeaderDecodes hs :: Constraint

For a given concrete type a, a list of pairs ts satisfies AllHeaderDecode a ts if each (n, a) in ts has HeaderDecode n a.

Equations

AllHeaderDecodes `[]` = ()

AllHeaderDecodes (`(n, a)` : hs) = (HeaderDecode n a, AllHeaderDecodes hs)

Extra serialization utilities

headerEncodePair :: forall a n. HeaderEncode n a => Sing n -> a -> Maybe (CI ByteString, ByteString)

Encode a HeaderName singleton and a HeaderEncode-represented value as a pair of name and representation, ready to be sent over the wire.

headerEncodeBS :: HeaderEncode n a => sing n -> a -> Maybe ByteString

While the semantics of HTTP headers are built off of Text-like values, usually we require a ByteString for emission. This helper function converts a header value directly to a ByteString.

headerDecodeBS :: HeaderDecode n a => sing n -> Maybe ByteString -> Either String a

While HTTP header semantics are built off of Text-like values, we usually read a raw ByteString from the wire. This helper function combines a HeaderDecode with a UTF-8 decode so as to attempt to deserialize header values directly from a ByteString.

Utilities for writing serialization instances

displaySetOpt :: Set Text -> Maybe Text

Output a set of text items as a comma-delimited list OR return nothing if the set is empty

uniqueSet :: (Ord v, HeaderEncode n (Set v)) => sing n -> [v] -> Maybe Text

Extend a HeaderEncode instance on Set v to [v].

required :: (Text -> Either String a) -> Maybe Text -> Either String a

Fail to decode if there is no header. For headers which lack default values. If a header lacks a natural default then avoiding failure should be explicitly requested in the types by wrapping it with a Maybe.

withDefault :: a -> (Text -> Either String a) -> Maybe Text -> Either String a

For headers with natural notions of default values.