Response (webs.Webs.Http.Response)

Responses

type t

The type for HTTP responses.

val make : 
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  ?version:Version.t ->
  Status.t ->
  Body.t ->
  t

make status body is a response with given status and body and:

explain, see explain. Defaults to "".
headers, the response headers. Defaults to Http.Headers.empty. Note that in general it is better to let bodies define the content type and content length headers. See the service response conventions.
reason, the status reason phrase. Defaults to Http.Status.reason_phrase status.
version, the HTTP version, see version. Defaults to Version.v11.

val empty : 
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  Status.t ->
  t

empty status is make status Body.empty.

val is_empty : t -> bool

is_empty response is Body.is_empty (body response).

val with_body : Body.t -> t -> t

with_body b response is response with body b.

val with_explain : string -> t -> t

with_explain response is response with explanation explain.

val with_headers : Headers.t -> t -> t

with_headers hs response is response with headers hs.

val override_headers : by:Headers.t -> t -> t

override_headers ~by response is response with headers Headers.override (headers response) ~by.

val with_status : ?explain:string -> ?reason:string -> Status.t -> t -> t

with_status status response is response with status status, reason phrase reason (defaults to Http.Status.reason_phrasestatus, use reason response to keep the previous reason) and explanation explain (defaults to explain response).

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

pp formats responses for inspection. Guarantees not consume the body.

val encode_http11 : include_body:bool -> t -> (string, string) Stdlib.result

encode_http11 ~include_body response encodes response to an HTTP/1.1 response. If include_body is true the body is consumed and included in the result. If false the body is left untouched and the encoding stops after the header final double CRLF.

Properties

val body : t -> Body.t

body response is the body of response.

val explain : t -> string

explain response is the explanation of response. The explanation is a server-side reason not meant to be sent to the client. It can be used to log further details about the answer that one may not want to disclose to the client.

val headers : t -> Headers.t

headers response are the headers of response.

val reason : t -> string

reason response is the reason phrase of response.

val status : t -> Status.t

status response is the status of response.

val version : t -> Version.t

version response is the version of response.

For service connectors this is mostly irrelevant: the connector decides how it wants to send the response to the client. But it can be used as a hint for which HTTP version to use.
For client connectors this should be the HTTP version of the response read by the connector.

Responding

See also request deconstruction combinators.

Simple content

val content : 
  ?explain:string ->
  ?reason:string ->
  ?headers:Headers.t ->
  ?content_type:Media_type.t ->
  Status.t ->
  string ->
  t

content status s is make status (Body.of_string ?content_type s).

val text : 
  ?explain:string ->
  ?reason:string ->
  ?headers:Headers.t ->
  Status.t ->
  string ->
  t

text responds with UTF-8 encoded plain text: content with Media_type.text_plain.

val html : 
  ?explain:string ->
  ?reason:string ->
  ?headers:Headers.t ->
  Status.t ->
  string ->
  t

html responds with UTF-8 encoded HTML text: content with Media_type.text_html.

val json : 
  ?explain:string ->
  ?reason:string ->
  ?headers:Headers.t ->
  Status.t ->
  string ->
  t

json responds with JSON text: content with Media_type.application_json.

Redirections

val redirect : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  Status.t ->
  string ->
  t

redirect status loc is a response with status status and Http.Headers.location set to loc on headers. body defaults to Body.empty.

Client errors

val bad_request_400 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

bad_request_400 () is Error r with r a response with status Status.bad_request_400. body defaults to Body.empty.

val unauthorized_401 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

unauthorized_401 () is Error r with r a response with status Status.unauthorized_401. body defaults to Body.empty.

val forbidden_403 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

forbidden_403 () is Error r with r a response with status Status.forbidden_403. body defaults to Body.empty.

val not_found_404 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

not_found_404 () is Error r with r a response with status Status.not_found_404. body defaults to Body.empty.

val method_not_allowed_405 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  allowed:Method.t list ->
  unit ->
  ('a, t) Stdlib.result

method_not_allowed_450 ~allowed () is Error r with r a response with status Status.method_not_allowed_405 and Http.Headers.allow set on headers with the allowed methods (which can be empty). body defaults to Body.empty.

val gone_410 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

gone_410 () is Error r with r a response with status Status.gone_410. body defaults to Body.empty.

Server errors

val server_error_500 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

server_error_500 () is Error r with r a response with status Status.server_error_500. body defaults to Body.empty.

val not_implemented_501 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

not_implemented_501 () is Error r with r a response with status Status.not_implemented_501. body defaults to Body.empty.

val service_unavailable_503 : 
  ?body:Body.t ->
  ?explain:string ->
  ?headers:Headers.t ->
  ?reason:string ->
  unit ->
  ('a, t) Stdlib.result

service_unavailable_503 () is Error r with r a response with status Status.service_unavailable_503. body defaults to Body.empty.

Error handling

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

result r is Result.fold ~ok:Fun.id ~error:Fun.id. It retracts the result type.

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

map_errors ~only_empty f response maps reponse response with f if r's status is a 4XX or 5XX. If only_empty is true it does so only whenever is_empty response is true.

The idea of map_errors is that service and service building blocks define their errors as responses with empty bodies. This function is then called just before handing over the reponse to the connector to define a page content for response with with_body.