| 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))
- acceptMatch :: (ArrowChoice h, ArrowError RouteMismatch h, MIMEType mt) => mt -> Middleware h ts 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 RequestHeader that is required and parsed strictly
type OptionalRequestHeader = RequestHeader Optional Strict Source #
A RequestHeader that is optional 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. 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 ResponseHeader that is required
type OptionalResponseHeader = ResponseHeader Optional Source #
A ResponseHeader that is optional
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)
acceptMatch :: (ArrowChoice h, ArrowError RouteMismatch h, MIMEType mt) => mt -> Middleware h ts ts Source #
Match the Accept header of the incoming request with the specified mediatype. Another handler will be tried if the match fails.
Example usage:
acceptMatch JSON handler