| Safe Haskell | None |
|---|---|
| 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 = 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 = ResponseHeader
- type RequiredResponseHeader = ResponseHeader 'Required
- type OptionalResponseHeader = ResponseHeader 'Optional
- header :: forall (name :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Required 'Strict name val), ArrowChoice h) => h (With Request ts, Either HeaderNotFound HeaderParseError) Response -> Middleware h ts (RequestHeader 'Required 'Strict name val ': ts)
- optionalHeader :: forall (name :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Optional 'Strict name val), ArrowChoice h) => h (With Request ts, HeaderParseError) Response -> Middleware h ts (RequestHeader 'Optional 'Strict name val ': ts)
- lenientHeader :: forall (name :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Required 'Lenient name val), ArrowChoice h) => h (With Request ts, HeaderNotFound) Response -> Middleware h ts (RequestHeader 'Required 'Lenient name val ': ts)
- optionalLenientHeader :: forall (name :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Optional 'Lenient name val), ArrowChoice h) => Middleware h ts (RequestHeader 'Optional 'Lenient name val ': ts)
- setHeader :: forall (name :: Symbol) val h (ts :: [Type]). Set h (ResponseHeader 'Required name val) => h (With Response ts, val) (With Response (ResponseHeader 'Required name val ': ts))
- setOptionalHeader :: forall (name :: Symbol) val h (ts :: [Type]). Set h (ResponseHeader 'Optional name val) => h (With Response ts, Maybe val) (With Response (ResponseHeader 'Optional name val ': ts))
- acceptMatch :: forall h mt (ts :: [Type]). (ArrowChoice h, ArrowError RouteMismatch h, MIMEType mt) => mt -> Middleware h ts ts
Traits
data RequestHeader (e :: Existence) (p :: ParseStyle) (name :: Symbol) val Source #
A trait for capturing an HTTP request header of specified name
and converting it to some type val. The modifiers e and p
determine how the missing headers and parsing errors are handled. The
header name is compared case-insensitively.
Constructors
| RequestHeader |
Instances
| type Absence (RequestHeader 'Optional 'Lenient name val) Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Absence (RequestHeader 'Optional 'Strict name val) Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Absence (RequestHeader 'Required 'Lenient name val) Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Absence (RequestHeader 'Required 'Strict name val) Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Attribute (RequestHeader 'Optional 'Lenient name val) Request Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Attribute (RequestHeader 'Optional 'Strict name val) Request Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Attribute (RequestHeader 'Required 'Lenient name val) Request Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Attribute (RequestHeader 'Required 'Strict name val) Request Source # | |
Defined in WebGear.Core.Trait.Header | |
| type Prerequisite (RequestHeader e p name val) ts Source # | |
Defined in WebGear.Core.Trait.Header | |
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 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
| 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 :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Required 'Strict name val), ArrowChoice h) | |
| => h (With Request ts, Either HeaderNotFound HeaderParseError) Response | Error handler |
| -> Middleware h ts (RequestHeader 'Required 'Strict name val ': ts) |
Extract a request 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 :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Optional 'Strict name val), ArrowChoice h) | |
| => h (With Request ts, HeaderParseError) Response | Error handler |
| -> Middleware h ts (RequestHeader 'Optional 'Strict name val ': ts) |
Extract an optional request 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 :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Required 'Lenient name val), ArrowChoice h) | |
| => h (With Request ts, HeaderNotFound) Response | Error handler |
| -> Middleware h ts (RequestHeader 'Required 'Lenient name val ': ts) |
Extract a request 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 :: Symbol) val h (ts :: [Type]). (Get h (RequestHeader 'Optional 'Lenient name val), ArrowChoice h) => Middleware h ts (RequestHeader 'Optional 'Lenient name val ': ts) Source #
Extract a request 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 :: Symbol) val h (ts :: [Type]). Set h (ResponseHeader 'Required name val) => h (With Response ts, val) (With Response (ResponseHeader 'Required name val ': ts)) Source #
Set a header value in a response.
Example usage:
response' <- setHeader @"Content-Length" -< (response, 42)
setOptionalHeader :: forall (name :: Symbol) val h (ts :: [Type]). Set h (ResponseHeader 'Optional name val) => h (With Response ts, Maybe val) (With Response (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 :: forall h mt (ts :: [Type]). (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