| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
WebGear.Core.Trait.Header
Contents
Description
Traits and middlewares to handle request and response headers.
There are a number of ways to extract a header value from a request:
The header middleware can extract a header value trait and invoke
another handler. An error handler is invoked if the header is missing
or the parsing fails.
The optionalHeader middleware is similar but will not invoke the
error handling in case the header is missing. Instead, the trait
value will be set to Nothing in that case.
The lenientHeader middleware requires the header to be present. But
the trait attribute will be set to Left msg if an error occurs
while parsing it to a Haskell value. Here msg will indicate the
error in parsing.
Finally, we have optionalLenientHeader which combines the behaviors
of optionalHeader and lenientHeader. In this case, the header
extraction never fails. Missing headers and parse errors are
indicated in the trait attribute passed to next handler.
A response header can be set using setHeader or setOptionalHeader
arrows. They accept a witnessed response and a header value and sets
the header in the response. You can generate an input response object
using functions from WebGear.Core.Trait.Status module.
Synopsis
- data RequestHeader (e :: Existence) (p :: ParseStyle) (name :: Symbol) (val :: Type) = RequestHeader
- data HeaderNotFound = HeaderNotFound
- newtype HeaderParseError = HeaderParseError Text
- type RequiredRequestHeader = RequestHeader Required Strict
- type OptionalRequestHeader = RequestHeader Optional Strict
- data ResponseHeader (e :: Existence) (name :: Symbol) (val :: Type) = ResponseHeader
- type RequiredResponseHeader = ResponseHeader Required
- type OptionalResponseHeader = ResponseHeader Optional
- header :: forall name val h ts. (Get h (RequestHeader Required Strict name val) Request, ArrowChoice h) => h (Request `With` ts, Either HeaderNotFound HeaderParseError) Response -> Middleware h ts (RequestHeader Required Strict name val ': ts)
- optionalHeader :: forall name val h ts. (Get h (RequestHeader Optional Strict name val) Request, ArrowChoice h) => h (Request `With` ts, HeaderParseError) Response -> Middleware h ts (RequestHeader Optional Strict name val ': ts)
- lenientHeader :: forall name val h ts. (Get h (RequestHeader Required Lenient name val) Request, ArrowChoice h) => h (Request `With` ts, HeaderNotFound) Response -> Middleware h ts (RequestHeader Required Lenient name val ': ts)
- optionalLenientHeader :: forall name val h ts. (Get h (RequestHeader Optional Lenient name val) Request, ArrowChoice h) => Middleware h ts (RequestHeader Optional Lenient name val ': ts)
- setHeader :: forall name val h ts. Set h (ResponseHeader Required name val) Response => h (Response `With` ts, val) (Response `With` (ResponseHeader Required name val ': ts))
- setOptionalHeader :: forall name val h ts. Set h (ResponseHeader Optional name val) Response => h (Response `With` ts, Maybe val) (Response `With` (ResponseHeader Optional name val ': ts))
Traits
data RequestHeader (e :: Existence) (p :: ParseStyle) (name :: Symbol) (val :: Type) Source #
A Trait for capturing an HTTP header of specified name and
converting it to some type val. The modifiers e and p determine
how missing headers and parsing errors are handled. The header name
is compared case-insensitively.
Constructors
| RequestHeader |
Instances
data HeaderNotFound Source #
Indicates a missing header
Constructors
| HeaderNotFound |
Instances
| Read HeaderNotFound Source # | |
Defined in WebGear.Core.Trait.Header Methods readsPrec :: Int -> ReadS HeaderNotFound # readList :: ReadS [HeaderNotFound] # | |
| Show HeaderNotFound Source # | |
Defined in WebGear.Core.Trait.Header Methods showsPrec :: Int -> HeaderNotFound -> ShowS # show :: HeaderNotFound -> String # showList :: [HeaderNotFound] -> ShowS # | |
| Eq HeaderNotFound Source # | |
Defined in WebGear.Core.Trait.Header Methods (==) :: HeaderNotFound -> HeaderNotFound -> Bool # (/=) :: HeaderNotFound -> HeaderNotFound -> Bool # | |
newtype HeaderParseError Source #
Error in converting a header
Constructors
| HeaderParseError Text |
Instances
| Read HeaderParseError Source # | |
Defined in WebGear.Core.Trait.Header Methods readsPrec :: Int -> ReadS HeaderParseError # readList :: ReadS [HeaderParseError] # | |
| Show HeaderParseError Source # | |
Defined in WebGear.Core.Trait.Header Methods showsPrec :: Int -> HeaderParseError -> ShowS # show :: HeaderParseError -> String # showList :: [HeaderParseError] -> ShowS # | |
| Eq HeaderParseError Source # | |
Defined in WebGear.Core.Trait.Header Methods (==) :: HeaderParseError -> HeaderParseError -> Bool # (/=) :: HeaderParseError -> HeaderParseError -> Bool # | |
type RequiredRequestHeader = RequestHeader Required Strict Source #
A Header that is required in the request and parsed strictly
type OptionalRequestHeader = RequestHeader Optional Strict Source #
A Header that is optional in the request and parsed strictly
data ResponseHeader (e :: Existence) (name :: Symbol) (val :: Type) Source #
A Trait for setting a header in the HTTP response. It has a
specified name and a value of type val which can be converted to
a ByteString. The header name is compared case-insensitively. The
modifier e determines whether the header is mandatory or optional.
Constructors
| ResponseHeader |
Instances
| Trait (ResponseHeader 'Optional name val) Response Source # | |
Defined in WebGear.Core.Trait.Header | |
| Trait (ResponseHeader 'Required name val) Response Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Attribute (ResponseHeader 'Optional name val) Response Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Attribute (ResponseHeader 'Required name val) Response Source # | |
Defined in WebGear.Core.Trait.Header | |
type RequiredResponseHeader = ResponseHeader Required Source #
A Header that is required in the response
type OptionalResponseHeader = ResponseHeader Optional Source #
A Header that is optional in the response
Middlewares
Arguments
| :: forall name val h ts. (Get h (RequestHeader Required Strict name val) Request, ArrowChoice h) | |
| => h (Request `With` ts, Either HeaderNotFound HeaderParseError) Response | Error handler |
| -> Middleware h ts (RequestHeader Required Strict name val ': ts) |
Extract a header value and convert it to a value of type val.
The associated trait attribute has type val.
Example usage:
header @"Content-Length" @Integer errorHandler okHandler
Arguments
| :: forall name val h ts. (Get h (RequestHeader Optional Strict name val) Request, ArrowChoice h) | |
| => h (Request `With` ts, HeaderParseError) Response | Error handler |
| -> Middleware h ts (RequestHeader Optional Strict name val ': ts) |
Extract an optional header value and convert it to a value of type
val.
The associated trait attribute has type Maybe val; a Nothing
value indicates that the header is missing from the request.
Example usage:
optionalHeader @"Content-Length" @Integer errorHandler okHandler
Arguments
| :: forall name val h ts. (Get h (RequestHeader Required Lenient name val) Request, ArrowChoice h) | |
| => h (Request `With` ts, HeaderNotFound) Response | Error handler |
| -> Middleware h ts (RequestHeader Required Lenient name val ': ts) |
Extract a header value and convert it to a value of type val.
The associated trait attribute has type Either Text val. The
parsing is done leniently and any errors are reported in the trait
attribute.
Example usage:
lenientHeader @"Content-Length" @Integer errorHandler okHandler
optionalLenientHeader :: forall name val h ts. (Get h (RequestHeader Optional Lenient name val) Request, ArrowChoice h) => Middleware h ts (RequestHeader Optional Lenient name val ': ts) Source #
Extract a header value and convert it to a value of type val.
The associated trait attribute has type Maybe (Either Text
val). The parsing is done leniently. Any parsing errors and
missing header are reported in the trait attribute.
Example usage:
optionalLenientHeader @"Content-Length" @Integer handler
setHeader :: forall name val h ts. Set h (ResponseHeader Required name val) Response => h (Response `With` ts, val) (Response `With` (ResponseHeader Required name val ': ts)) Source #
Set a header value in a response.
Example usage:
response' <- setHeader @"Content-Length" -< (response, 42)
setOptionalHeader :: forall name val h ts. Set h (ResponseHeader Optional name val) Response => h (Response `With` ts, Maybe val) (Response `With` (ResponseHeader Optional name val ': ts)) Source #
Set an optional header value in a response.
Setting the header to Nothing will remove it from the response if
it was previously set. The header will be considered as optional in
all relevant places (such as documentation).
Example usage:
response' <- setOptionalHeader @"Content-Length" -< (response, Just 42)