Module Http.Resp

HTTP responses.

Response bodies

type connection = ..

The type for direct response connection. This is connector dependent.

type consumer = (bytes * int * int) option -> unit

The type for response consumers.

Services call consumers with Some (byte, first len) to output the corresponding data and None when they are finished.

Response consumers are provided by the connector to pull the body produced by a response. If you are writing a consumer, the bytes MUST NOT be modified by the consumer and only read from first to first+len.

type body =
| Empty
| Stream of consumer -> unit
| Direct of connection -> unit

The type for response bodies. This is either:

  • An empty body.
  • A stream to which a consumer will be passed by the connector.
  • A direct connection handler, the connector will pass it's connection representation.
val empty_body : body

empty_body s is an empty body.

val stream_body : (consumer -> unit) -> body

stream_body producer is a response body stream produced by producer on the consumer it will be given to.

val direct_body : (connection -> unit) -> body

direct_body producer is a response body produced by producer on the given (backend specific) connection.

val body_of_string : string -> body

body_of_string s is a reponse body made of string s.

val pp_body : Stdlib.Format.formatter -> body -> unit

pp_body ppf b prints an unspecified representation of b's specification on ppf but guarantees not to consume the body.


type t = resp

The type for responses.

val v : ?version:version -> ?explain:string -> ?reason:string -> ?body:body -> ?headers:headers -> status -> resp

v status headers body is a response with given status, headers (defaults to Http.Headers.empty), body (defaults to empty_body, reason (defaults to Http.status_reason_phrase) and version (defaults to (1,1)), explain is a server side reason it is not put on the wire.

FIXME. Maybe make body non-optional to encourage use of empty which is clearer in code.

Note. If body is body_empty (default) a Http.content_length of 0 is automatically added to headers.

val version : resp -> version

version r is r's version.

val status : resp -> status

status r is r's status.

val reason : resp -> string

reason r is r's reason phrase.

val headers : resp -> headers

headers r is r's headers.

val body : resp -> body

body r is r's body.

val explain : resp -> string

explain r is r's explanation. In contrast to reason this remains on the server and can be, for example logged.

val with_status : ?explain:string -> ?reason:string -> status -> resp -> resp

with_status st r is r with status st and reason phrase reason (defaults to Http.status_reason_phrase.

val with_headers : headers -> resp -> resp

with_headers hs r is r with headers hs.

val override_headers : by:headers -> resp -> resp

override_headers by r is r with headers H.override (headers r) ~by.

val with_body : body -> t -> t

with_body b r is r with body b.

val pp : Stdlib.Format.formatter -> t -> unit

pp ppf t prints an unspecified representation of r on ppf but guarantees not to consume the body.

Pre-canned responses

The optional headers argument of the functions below always Http.override those the function computed.

See also request deconstruction combinators.

FIXME. Do a better compositional design, e.g. easily use the error responses with content responses. *

val result : ('a'a) Stdlib.result -> 'a

result r is Result.fold

Content responses

val empty : ?explain:string -> ?reason:string -> ?headers:headers -> int -> resp

empty ?explain ?reason ?headers st is v ?explain ?reason ?headers st.

val content : ?explain:string -> ?reason:string -> ?headers:headers -> mime_type:mime_type -> int -> string -> resp

content ~mime_type st s responds s with content type mime_type and status st. Sets Http.content_type and Http.content_length appropriately.

val text : ?explain:string -> ?reason:string -> ?headers:headers -> int -> string -> resp

text responds with UTF-8 encoded plain text, i.e. content with Http.Mime_type.text_plain.

val html : ?explain:string -> ?reason:string -> ?headers:headers -> int -> string -> resp

html responds with UTF-8 encoded HTML text, i.e. content with Http.Mime_type.text_html.

val json : ?explain:string -> ?reason:string -> ?headers:headers -> int -> string -> resp

json responds with JSON text, i.e. content with Http.Mime_type.application_json.

val octets : ?explain:string -> ?reason:string -> ?headers:headers -> int -> string -> resp

octets responds with octets, i.e. content with Http.Mime_type.application_octet_stream.

Redirect responses

val redirect : ?explain:string -> ?reason:string -> ?headers:headers -> int -> string -> resp

redirect status loc redirects to location loc with status status (defaults to Http.found_302). See also Req.service_redirect.

Client error responses

val bad_request_400 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

bad_request ?explain ?reason () is an empty response with status Http.bad_request_400.

val unauthorized_401 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

unauthorized ?explain ?reason () is an empty response with status Http.unauthorized_401.

val forbidden_403 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

forbidden ?explain ?reason is an empty response with status Http.forbidden_403.

val not_found_404 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

not_found ?explain ?reason is an empty response with status Http.not_found_404.

val method_not_allowed_405 : ?explain:string -> ?reason:string -> ?headers:headers -> allowed:meth list -> unit -> ('at) Stdlib.result

method_not_allowed ~allowed is an empty response with status Http.method_not_allowed_405. It sets the Http.allow header to the allowed methods (which can be empty).

val gone_410 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

not_found ?explain ?reason is an empty response with status Http.gone_410.

Server error responses

val server_error_500 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

server_error ?explain ?reason is an empty response with status Http.server_error_500.

val not_implemented_501 : ?explain:string -> ?reason:string -> ?headers:headers -> unit -> ('aresp) Stdlib.result

server_error ?explain ?reason is an empty response with status Http.not_implemented_501.

Error mapper

val map_errors : only_empty:bool -> (t -> t) -> t -> t

map_errors ~only_empty f r maps r with f if r's status is a 4XX or 5XX. If only_empty is true (defaults to false) it does so only on empty body responses.