webgear-core-1.1.1: Composable, type-safe library to build HTTP APIs
Safe HaskellSafe-Inferred
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 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

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

Associated Types

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

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

Defined in WebGear.Core.Trait.Header

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

Defined in WebGear.Core.Trait.Header

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

Defined in WebGear.Core.Trait.Header

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

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

type Attribute (RequestHeader 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

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

Instances details
Trait (ResponseHeader 'Optional name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (ResponseHeader 'Optional name val) Response Source #

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

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (ResponseHeader 'Required name val) Response Source #

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

Defined in WebGear.Core.Trait.Header

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

Defined in WebGear.Core.Trait.Header

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

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

header Source #

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

optionalHeader Source #

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

lenientHeader Source #

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)