servant-0.20.2: A family of combinators for defining webservices APIs

Safe Haskell | None
Language | Haskell2010

Servant.API.ResponseHeaders

Description

This module provides facilities for adding headers to a response.

    >>> let headerVal = addHeader "some-url" 5 :: Headers '[Header "Location" String] Int

The value is added to the header specified by the type (`Location` in the example above).

Synopsis

- data Headers (ls :: [Type]) a = Headers {
  - getResponse :: a
  - getHeadersHList :: HList ls
  }
- data ResponseHeader (sym :: Symbol) a
  - = Header a
  - | MissingHeader
  - | UndecodableHeader ByteString
- class AddHeader (mods :: [Type]) (h :: Symbol) v orig new | mods h v orig -> new, new -> mods, new -> h, new -> v, new -> orig
- addHeader :: forall (h :: Symbol) v orig new. AddHeader '[Optional, Strict] h v orig new => v -> orig -> new
- addHeader' :: forall (mods :: [Type]) (h :: Symbol) v orig new. AddHeader mods h v orig new => v -> orig -> new
- noHeader :: forall (h :: Symbol) v orig new. AddHeader '[Optional, Strict] h v orig new => orig -> new
- noHeader' :: forall (mods :: [Type]) (h :: Symbol) v orig new. AddHeader mods h v orig new => orig -> new
- class HasResponseHeader (h :: Symbol) a (headers :: [Type])
- lookupResponseHeader :: forall (h :: Symbol) a (headers :: [Type]) r. HasResponseHeader h a headers => Headers headers r -> ResponseHeader h a
- class BuildHeadersTo (hs :: [Type]) where
  - buildHeadersTo :: [Header] -> HList hs
- class GetHeaders ls where
  - getHeaders :: ls -> [Header]
- class GetHeaders' (hs :: [Type])
- type family HeaderValMap (f :: Type -> Type) (xs :: [Type]) :: [Type] where ...
- data HList (a :: [Type]) where
  - HNil :: HList ('[] :: [Type])
  - HCons :: forall (h :: Symbol) x (xs :: [Type]) (mods :: [Type]). ResponseHeader h x -> HList xs -> HList (Header' mods h x ': xs)

# Documentation

data Headers (ls :: [Type]) a #

Response Header objects. You should never need to construct one directly. Instead, use `addOptionalHeader`.

Constructors

Headers |

Fields

- getResponse :: a

  The underlying value of a `Headers`

- getHeadersHList :: HList ls

  HList of headers.

#### Instances

Instances details

(KnownSymbol h, ToHttpApiData v) => AddHeader mods h v (Headers (fst ': rest) a) (Headers (Header' mods h v ': (fst ': rest)) a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers (Header' mods h v ': (fst ': rest)) a
Functor (Headers ls) # |
Instance details Defined in Servant.API.ResponseHeaders Methods fmap :: (a -> b) -> Headers ls a -> Headers ls b # (<$) :: a -> Headers ls b -> Headers ls a #
(NFDataHList ls, NFData a) => NFData (Headers ls a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods rnf :: Headers ls a -> () #
GetHeaders' hs => GetHeaders (Headers hs a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods getHeaders :: Headers hs a -> [Header] #
HasStatus a => HasStatus (Headers ls a) # |

Instance details

Defined in Servant.API.UVerb

Associated Types

type StatusOf (Headers ls a) |
Instance details Defined in Servant.API.UVerb type StatusOf (Headers ls a) = StatusOf a

type StatusOf (Headers ls a) # |
Instance details Defined in Servant.API.UVerb type StatusOf (Headers ls a) = StatusOf a

data ResponseHeader (sym :: Symbol) a #

Constructors

Header a |
MissingHeader |
UndecodableHeader ByteString |

#### Instances

Instances details

Functor (ResponseHeader sym) # |
Instance details Defined in Servant.API.ResponseHeaders Methods fmap :: (a -> b) -> ResponseHeader sym a -> ResponseHeader sym b # (<$) :: a -> ResponseHeader sym b -> ResponseHeader sym a #
NFData a => NFData (ResponseHeader sym a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods rnf :: ResponseHeader sym a -> () #
Show a => Show (ResponseHeader sym a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods showsPrec :: Int -> ResponseHeader sym a -> ShowS # show :: ResponseHeader sym a -> String # showList :: [ResponseHeader sym a] -> ShowS #
Eq a => Eq (ResponseHeader sym a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods (==) :: ResponseHeader sym a -> ResponseHeader sym a -> Bool # (/=) :: ResponseHeader sym a -> ResponseHeader sym a -> Bool #

class AddHeader (mods :: [Type]) (h :: Symbol) v orig new | mods h v orig -> new, new -> mods, new -> h, new -> v, new -> orig #

Minimal complete definition

addOptionalHeader

#### Instances

Instances details

(KnownSymbol h, ToHttpApiData v, new ~ Headers '[Header' mods h v] a) => AddHeader mods h v a new # |
Instance details Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> a -> new
(AddHeader mods h v old new, AddHeader mods h v (Union oldrest) (Union newrest), oldrest ~ (a ': as), newrest ~ (b ': bs)) => AddHeader mods h v (Union (old ': (a ': as))) (Union (new ': (b ': bs))) # |
Instance details Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Union (old ': (a ': as)) -> Union (new ': (b ': bs))
AddHeader mods h v old new => AddHeader mods h v (Union '[old]) (Union '[new]) # |
Instance details Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Union '[old] -> Union '[new]
(KnownSymbol h, ToHttpApiData v) => AddHeader mods h v (Headers (fst ': rest) a) (Headers (Header' mods h v ': (fst ': rest)) a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers (Header' mods h v ': (fst ': rest)) a

addHeader :: forall (h :: Symbol) v orig new. AddHeader '[Optional, Strict] h v orig new => v -> orig -> new #

`addHeader` adds a header to a response. Note that it changes the type of the value in the following ways:

1. A simple value is wrapped in "Headers '[hdr]":

    >>> let example0 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;
    >>> getHeaders example0
    [("someheader","5")]

1. A value that already has a header has its new header *prepended* to the existing list:

    >>> let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;
    >>> let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String
    >>> getHeaders example2
    [("1st","true"),("someheader","5")]

Note that while in your handlers type annotations are not required, since the type can be inferred from the API type, in other cases you may find yourself needing to add annotations.

addHeader' :: forall (mods :: [Type]) (h :: Symbol) v orig new. AddHeader mods h v orig new => v -> orig -> new #

Same as `addHeader` but works with `Header'`, so it's possible to use any `mods`.

noHeader :: forall (h :: Symbol) v orig new. AddHeader '[Optional, Strict] h v orig new => orig -> new #

Deliberately do not add a header to a value.

    >>> let example1 = noHeader "hi" :: Headers '[Header "someheader" Int] String
    >>> getHeaders example1
    []

noHeader' :: forall (mods :: [Type]) (h :: Symbol) v orig new. AddHeader mods h v orig new => orig -> new #

Same as `noHeader` but works with `Header'`, so it's possible to use any `mods`.

class HasResponseHeader (h :: Symbol) a (headers :: [Type]) #

Minimal complete definition

hlistLookupHeader

#### Instances

Instances details

HasResponseHeader h a (Header' mods h a ': rest) # |
Instance details Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList (Header' mods h a ': rest) -> ResponseHeader h a
HasResponseHeader h a rest => HasResponseHeader h a (first ': rest) # |
Instance details Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList (first ': rest) -> ResponseHeader h a

lookupResponseHeader :: forall (h :: Symbol) a (headers :: [Type]) r. HasResponseHeader h a headers => Headers headers r -> ResponseHeader h a #

Look up a specific ResponseHeader, without having to know what position it is in the HList.

    >>> let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String
    >>> let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String
    >>> lookupResponseHeader example2 :: ResponseHeader "someheader" Int
    Header 5

    >>> lookupResponseHeader example2 :: ResponseHeader "1st" Bool
    Header True

Usage of this function relies on an explicit type annotation of the header to be looked up. This can be done with type annotations on the result, or with an explicit type application. In this example, the type of header value is determined by the type-inference, we only specify the name of the header:

    >>> :set -XTypeApplications
    >>> case lookupResponseHeader @"1st" example2 of { Header b -> b ; _ -> False }
    True

Since: 0.15

class BuildHeadersTo (hs :: [Type]) where #

Methods

buildHeadersTo :: [Header] -> HList hs #

#### Instances

Instances details

BuildHeadersTo ('[] :: [Type]) # |
Instance details Defined in Servant.API.ResponseHeaders Methods buildHeadersTo :: [Header] -> HList ('[] :: [Type]) #
(FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo (Header' mods h v ': xs) # |
Instance details Defined in Servant.API.ResponseHeaders Methods buildHeadersTo :: [Header] -> HList (Header' mods h v ': xs) #

class GetHeaders ls where #

Methods

getHeaders :: ls -> [Header] #

#### Instances

Instances details

GetHeadersFromHList hs => GetHeaders (HList hs) # |
Instance details Defined in Servant.API.ResponseHeaders Methods getHeaders :: HList hs -> [Header] #
GetHeaders' hs => GetHeaders (Headers hs a) # |
Instance details Defined in Servant.API.ResponseHeaders Methods getHeaders :: Headers hs a -> [Header] #

class GetHeaders' (hs :: [Type]) #

Auxiliary class for ``GetHeaders` (`Headers` hs a)` instance

Minimal complete definition

getHeaders'

#### Instances

Instances details

GetHeaders' ('[] :: [Type]) # | This instance is an optimisation
Instance details Defined in Servant.API.ResponseHeaders Methods getHeaders' :: Headers ('[] :: [Type]) a -> [Header]
(KnownSymbol h, GetHeadersFromHList rest, ToHttpApiData v) => GetHeaders' (Header' mods h v ': rest) # |
Instance details Defined in Servant.API.ResponseHeaders Methods getHeaders' :: Headers (Header' mods h v ': rest) a -> [Header]

type family HeaderValMap (f :: Type -> Type) (xs :: [Type]) :: [Type] where ... #

Equations

HeaderValMap f ('[] :: [Type]) = '[] :: [Type] |
HeaderValMap f (Header' mods h x ': xs) = Header' mods h (f x) ': HeaderValMap f xs |

data HList (a :: [Type]) where #

Constructors

HNil :: HList ('[] :: [Type]) |
HCons :: forall (h :: Symbol) x (xs :: [Type]) (mods :: [Type]). ResponseHeader h x -> HList xs -> HList (Header' mods h x ': xs) |

#### Instances

Instances details

NFDataHList xs => NFData (HList xs) # |
Instance details Defined in Servant.API.ResponseHeaders Methods rnf :: HList xs -> () #
GetHeadersFromHList hs => GetHeaders (HList hs) # |
Instance details Defined in Servant.API.ResponseHeaders Methods getHeaders :: HList hs -> [Header] #