fogfish/http-combinators.md

## http-combinators.md

      
    Raw
  

              http-combinators.md
            
          
Protocol Primitive
Client-side
Server-side


request
writer morphism
reader morphism


HTTP Method
ø.GET
declares the verb of HTTP request
ƒ.GET
 matches the verb of HTTP request and fails with error if the verb does not match the expected one.


URI
ø.URI(string)
specifies target URI for HTTP request. The combinator uses absolute URI to specify target host and endpoint.
ƒ.URI(string)
matches URL path from HTTP request. The combinator considers the URI path as an ordered sequence of segments, which are matched against a given pattern or uses a lens to extract value into the context. It fails if the path does not match the expected one.


URI Query
ø.Params(any)
 ø.Param[T Literals](string, T)
 lifts the flat structure or individual values into query parameters of specified URI.
ƒ.Params[T Lens](T)
 ƒ.Param[T Lens](string, T)
matches the URL query string from an HTTP request. It either matches literal value or uses a lens to extract value.  It fails if the query does not match the expected one.


Headers
ø.Header[T Literals](string, T)
 ø.ContentType.ApplicationJSON
 ø.ContentType.Set(string)
declares headers and its values into HTTP requests. The standard HTTP headers are accomplished by a dedicated combinator making it typesafe.
ƒ.Header[T Lens](string, T)
 ƒ.ContentType.ApplicationJSON
 ƒ.ContentType.Is(string)
 ƒ.ContentType.To(Lens)
matches HTTP headers from the request. It either matches literal value or uses a lens to extract value. The standard HTTP headers are accomplished by a dedicated combinator. It fails if the header does not match the expected one.


Body
ø.Send(any)
transmits the payload to the destination URI. The combinator takes standard data types (e.g. maps, struct, etc) and encodes it to binary using Content-Type header as a hint.
ƒ.Body[T Lens](T)
 ƒ.Bytes([]byte)
 ƒ.Match(Pattern)
consumes payload from HTTP requests and decodes the value into the type associated with the lens using Content-Type header as a hint. It fails if the body cannot be consumed.


response
reader morphism
writer morphism


Status Code
ƒ.Status.OK
 ƒ.Code(200)
 checks the code in HTTP response and fails with error if the status code does not match the expected one. The all well-known HTTP status codes are accomplished by a dedicated combinator making it typesafe.
ø.Status.OK
declares the status of HTTP response.


Headers
ƒ.Header[T Lens](string, T)
 ƒ.ContentType.ApplicationJSON
 ƒ.ContentType.Is(string)
 ƒ.ContentType.To(Lens)
 matches the presence of HTTP header and its value in the response. The matching fails if the response is missing the header or its value does not correspond to the expected one.
ø.Header[T Literals](string, T)
 ø.ContentType.ApplicationJSON
 ø.ContentType.Set(string)
 declares headers and its values into HTTP response.


Payload
ƒ.Body[T Lens](T)
 ƒ.Bytes([]byte)
 ƒ.Match(Pattern)
 consumes payload from HTTP requests and decodes the value into the type associated with the lens using Content-Type header as a hint. It fails if the body cannot be consumed.
ø.Send(any)
transmits the payload as the response on HTTP request. The combinator takes standard data types (e.g. maps, struct, etc) and encodes it to binary using Content-Type header as a hint.
Protocol Primitive	Client-side	Server-side
request	writer morphism	reader morphism
HTTP Method	`ø.GET` declares the verb of HTTP request	`ƒ.GET` matches the verb of HTTP request and fails with error if the verb does not match the expected one.
URI	`ø.URI(string)` specifies target URI for HTTP request. The combinator uses absolute URI to specify target host and endpoint.	`ƒ.URI(string)` matches URL path from HTTP request. The combinator considers the URI path as an ordered sequence of segments, which are matched against a given pattern or uses a lens to extract value into the context. It fails if the path does not match the expected one.
URI Query	`ø.Params(any)` `ø.Param[T Literals](string, T)` lifts the flat structure or individual values into query parameters of specified URI.	`ƒ.Params[T Lens](T)` `ƒ.Param[T Lens](string, T)` matches the URL query string from an HTTP request. It either matches literal value or uses a lens to extract value. It fails if the query does not match the expected one.
Headers	`ø.Header[T Literals](string, T)` `ø.ContentType.ApplicationJSON` `ø.ContentType.Set(string)` declares headers and its values into HTTP requests. The standard HTTP headers are accomplished by a dedicated combinator making it typesafe.	`ƒ.Header[T Lens](string, T)` `ƒ.ContentType.ApplicationJSON` `ƒ.ContentType.Is(string)` `ƒ.ContentType.To(Lens)` matches HTTP headers from the request. It either matches literal value or uses a lens to extract value. The standard HTTP headers are accomplished by a dedicated combinator. It fails if the header does not match the expected one.
Body	`ø.Send(any)` transmits the payload to the destination URI. The combinator takes standard data types (e.g. maps, struct, etc) and encodes it to binary using Content-Type header as a hint.	`ƒ.Body[T Lens](T)` `ƒ.Bytes([]byte)` `ƒ.Match(Pattern)` consumes payload from HTTP requests and decodes the value into the type associated with the lens using Content-Type header as a hint. It fails if the body cannot be consumed.
response	reader morphism	writer morphism
Status Code	`ƒ.Status.OK` `ƒ.Code(200)` checks the code in HTTP response and fails with error if the status code does not match the expected one. The all well-known HTTP status codes are accomplished by a dedicated combinator making it typesafe.	`ø.Status.OK` declares the status of HTTP response.
Headers	`ƒ.Header[T Lens](string, T)` `ƒ.ContentType.ApplicationJSON` `ƒ.ContentType.Is(string)` `ƒ.ContentType.To(Lens)` matches the presence of HTTP header and its value in the response. The matching fails if the response is missing the header or its value does not correspond to the expected one.	`ø.Header[T Literals](string, T)` `ø.ContentType.ApplicationJSON` `ø.ContentType.Set(string)` declares headers and its values into HTTP response.
Payload	`ƒ.Body[T Lens](T)` `ƒ.Bytes([]byte)` `ƒ.Match(Pattern)` consumes payload from HTTP requests and decodes the value into the type associated with the lens using Content-Type header as a hint. It fails if the body cannot be consumed.	`ø.Send(any)` transmits the payload as the response on HTTP request. The combinator takes standard data types (e.g. maps, struct, etc) and encodes it to binary using Content-Type header as a hint.