WebGear.Core.Trait.Header

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.

Traits

data RequestHeader (e :: Existence) (p :: ParseStyle) (name :: Symbol) (val :: Type)

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)

Defined in WebGear.Core.Trait.Header

type Absence (RequestHeader 'Optional 'Lenient name val) = Void

type Absence (RequestHeader 'Optional 'Strict name val)

Defined in WebGear.Core.Trait.Header

type Absence (RequestHeader 'Optional 'Strict name val) = HeaderParseError

type Absence (RequestHeader 'Required 'Lenient name val)

Defined in WebGear.Core.Trait.Header

type Absence (RequestHeader 'Required 'Lenient name val) = HeaderNotFound

type Absence (RequestHeader 'Required 'Strict name val)

Defined in WebGear.Core.Trait.Header

type Absence (RequestHeader 'Required 'Strict name val) = Either HeaderNotFound HeaderParseError

type Attribute (RequestHeader 'Optional 'Lenient name val) Request

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Optional 'Lenient name val) Request = Maybe (Either Text val)

type Attribute (RequestHeader 'Optional 'Strict name val) Request

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Optional 'Strict name val) Request = Maybe val

type Attribute (RequestHeader 'Required 'Lenient name val) Request

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Required 'Lenient name val) Request = Either Text val

type Attribute (RequestHeader 'Required 'Strict name val) Request

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Required 'Strict name val) Request = val

type Prerequisite (RequestHeader e p name val) ts

Defined in WebGear.Core.Trait.Header

type Prerequisite (RequestHeader e p name val) ts = ()

data HeaderNotFound

Indicates a missing header

Constructors

HeaderNotFound

Instances

Read HeaderNotFound

Defined in WebGear.Core.Trait.Header

Methods

readsPrec :: Int -> ReadS HeaderNotFound

readList :: ReadS [HeaderNotFound]

readPrec :: ReadPrec HeaderNotFound

readListPrec :: ReadPrec [HeaderNotFound]

Show HeaderNotFound

Defined in WebGear.Core.Trait.Header

Methods

showsPrec :: Int -> HeaderNotFound -> ShowS

show :: HeaderNotFound -> String

showList :: [HeaderNotFound] -> ShowS

Eq HeaderNotFound

Defined in WebGear.Core.Trait.Header

Methods

(==) :: HeaderNotFound -> HeaderNotFound -> Bool

(/=) :: HeaderNotFound -> HeaderNotFound -> Bool

newtype HeaderParseError

Error in converting a header

Constructors

HeaderParseError Text

Instances

Read HeaderParseError

Defined in WebGear.Core.Trait.Header

Methods

readsPrec :: Int -> ReadS HeaderParseError

readList :: ReadS [HeaderParseError]

readPrec :: ReadPrec HeaderParseError

readListPrec :: ReadPrec [HeaderParseError]

Show HeaderParseError

Defined in WebGear.Core.Trait.Header

Methods

showsPrec :: Int -> HeaderParseError -> ShowS

show :: HeaderParseError -> String

showList :: [HeaderParseError] -> ShowS

Eq HeaderParseError

Defined in WebGear.Core.Trait.Header

Methods

(==) :: HeaderParseError -> HeaderParseError -> Bool

(/=) :: HeaderParseError -> HeaderParseError -> Bool

type RequiredRequestHeader = RequestHeader Required Strict

A RequestHeader that is required and parsed strictly

type OptionalRequestHeader = RequestHeader Optional Strict

A RequestHeader that is optional and parsed strictly

data ResponseHeader (e :: Existence) (name :: Symbol) (val :: Type)

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

Defined in WebGear.Core.Trait.Header

type Attribute (ResponseHeader 'Optional name val) Response = Maybe val

type Attribute (ResponseHeader 'Required name val) Response

Defined in WebGear.Core.Trait.Header

type Attribute (ResponseHeader 'Required name val) Response = val

type RequiredResponseHeader = ResponseHeader Required

A ResponseHeader that is required

type OptionalResponseHeader = ResponseHeader Optional

A ResponseHeader that is optional

Middlewares

header

Arguments

:: forall name val h ts. (Get h (RequestHeader Required Strict name val), ArrowChoice h)

=> h (Request `With` 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

optionalHeader

Arguments

:: forall name val h ts. (Get h (RequestHeader Optional Strict name val), ArrowChoice h)

=> h (Request `With` 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

lenientHeader

Arguments

:: forall name val h ts. (Get h (RequestHeader Required Lenient name val), ArrowChoice h)

=> h (Request `With` 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 val h ts. (Get h (RequestHeader Optional Lenient name val), ArrowChoice h) => Middleware h ts (RequestHeader Optional Lenient name val : ts)

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 val h ts. Set h (ResponseHeader Required name val) => h (Response `With` ts, val) (Response `With` (ResponseHeader Required name val : ts))

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) => h (Response `With` ts, Maybe val) (Response `With` (ResponseHeader Optional name val : ts))

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

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