webgear-core-1.0.1: Composable, type-safe library to build HTTP APIs
Safe HaskellNone
LanguageHaskell2010

WebGear.Core.Trait.Header

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 linked 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

Traits

data Header (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

Header 

Instances

Instances details
TraitAbsence (Header 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Required 'Strict name val) Request Source #

TraitAbsence (Header 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Required 'Lenient name val) Request Source #

TraitAbsence (Header 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Optional 'Strict name val) Request Source #

TraitAbsence (Header 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Optional 'Lenient name val) Request Source #

Trait (Header 'Required 'Strict name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Required 'Strict name val) Response Source #

Trait (Header 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Required 'Strict name val) Request Source #

Trait (Header 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Required 'Lenient name val) Request Source #

Trait (Header 'Optional 'Strict name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Optional 'Strict name val) Response Source #

Trait (Header 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Optional 'Strict name val) Request Source #

Trait (Header 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Optional 'Lenient name val) Request Source #

type Absence (Header 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Absence (Header 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Absence (Header 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Absence (Header 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (Header 'Required 'Strict name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (Header 'Required 'Strict name val) Response = val
type Attribute (Header 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (Header 'Required 'Strict name val) Request = val
type Attribute (Header 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (Header 'Optional 'Strict name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (Header 'Optional 'Strict name val) Response = Maybe val
type Attribute (Header 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (Header 'Optional 'Strict name val) Request = Maybe val
type Attribute (Header 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type RequiredHeader = Header Required Strict Source #

A Header that is required and parsed strictly

type OptionalHeader = Header Optional Strict Source #

A Header that is optional and parsed strictly

Middlewares

header Source #

Arguments

:: forall name val h req. (Get h (Header Required Strict name val) Request, ArrowChoice h) 
=> h (Linked req Request, Either HeaderNotFound HeaderParseError) Response

Error handler

-> Middleware h req (Header Required Strict name val ': req) 

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

optionalHeader Source #

Arguments

:: forall name val h req. (Get h (Header Optional Strict name val) Request, ArrowChoice h) 
=> h (Linked req Request, HeaderParseError) Response

Error handler

-> Middleware h req (Header Optional Strict name val ': req) 

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

lenientHeader Source #

Arguments

:: forall name val h req. (Get h (Header Required Lenient name val) Request, ArrowChoice h) 
=> h (Linked req Request, HeaderNotFound) Response

Error handler

-> Middleware h req (Header Required Lenient name val ': req) 

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 req. (Get h (Header Optional Lenient name val) Request, ArrowChoice h) => Middleware h req (Header Optional Lenient name val ': req) 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 a h res. Set h (Header Required Strict name val) Response => h a (Linked res Response) -> h (val, a) (Linked (Header Required Strict name val ': res) Response) Source #

Set a header value in a response.

Example usage:

response' <- setHeader @"Content-Length" -< (response, 42)

setOptionalHeader :: forall name val a h res. Set h (Header Optional Strict name val) Response => h a (Linked res Response) -> h (Maybe val, a) (Linked (Header Optional Strict name val ': res) Response) 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)