Req (webs.Webs.Req)

Request bodies

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

The type for request bodies.

Bodies are blocking functions pulled by services to yield byte chunks of data of the request body as Some (bytes, first, len) values. The bytes value must not be modified and is readable from first to first+len until the next call to the function. The function returns None at the end of stream.

val empty_body : body

empty_body is an empty body.

val body_to_string : body -> string

body_to_string b accumulates the body to a string.

HTTP Requests

type t

The type for HTTP requests.

val v : ?service_root:Http.path -> ?version:Http.version -> ?body_length:int option -> ?body:body -> ?headers:Http.headers
-> Http.meth -> string -> t

v meth request_target is an HTTP request with method meth, request target request_target, headers (defaults to Http.H.empty), body (defaults to empty_body), body_length (defaults to None or Some 0 if body is empty_body) and version (defaults to (1,1)).

val service_root : t -> Http.path

service_root r is the root path on which the service is served. Consult the documentation of connectors to understand how this is derived (usually from the gateway via a x-service-root header).

val version : t -> Http.version

version r is r's HTTP version.

val meth : t -> Http.meth

meth r is r's HTTP method.

val request_target : t -> string

request_target is r's request target. This should be the raw request, still percent encoded. Note that you usually rather want to use the convenience path and query which are derived from this value.

val path : t -> Http.path

path r is the absolute path of request_target. This is as a list of path segments or the empty list if the request target has no path. See the Http.path representation for details.

val query : t -> string option

query r is the query (without the '?') of request_target. Note that query string may be the empty string which is different from None (no '?' in the request target). To decode the query (and handle those that are POSTed) see to_query.

val headers : t -> Http.headers

headers r is r's HTTP headers. Includes at least the Http.H.host header.

val body_length : t -> int option

body_length r is r's request body length (if known).

val body : t -> body

body r is r's body.

val with_headers : Http.headers -> t -> t

with_headers hs r is r with headers hs.

val with_body : body_length:int option -> body -> t -> t

with_body blen b r is r with body length blen and body b.

val with_path : Http.path -> t -> t

with_path p r is r with path p.

val with_service_root : Http.path -> t -> t

with_service_root p r is r with service root r.

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

pp ppf req prints and unspecified representation of req on ppf but guarantees not to consume the body.

Request responses

Service redirect

val service_redirect : ?explain:string -> int -> Http.path -> t -> Resp.t

service_redirect status p r redirects r to the service path p (this means r's service_root is prefixed to p) with status status. See also Resp.redirect.

Echo

val echo : ?status:Http.status -> t -> Resp.t

echo r returns r as a 404 text/plain document (and by doing so violates numerous HTTP's musts). This includes the request body, which is consumed by the service.

Request deconstruction

Request deconstruction helpers. These functions directly error with responses that have the right statuses and empty bodies.

Header decoding

val decode_header : Http.name -> (string -> ('a, string) Stdlib.result) -> t -> ('a option, Resp.t) Stdlib.result

decode_header h dec r decodes header h (if any) in r. Errors with Http.s400_bad_request in case of decoding errors.

Method constraints

val allow : [< Http.meth as 'a ] list -> t -> ('a, Resp.t) Stdlib.result

allow ms r is:

Ok (Req.meth r) if List.mem (Req.meth r) ms
Error _ with a Http.s405_method_not_allowed response otherwise.

FIXME. The type restriction doesn't work.

Service forwarding

val forward_service : strip:Http.path -> t -> (t, Resp.t) Stdlib.result

forward_service ~strip r is:

Ok r' with r' the request r with a path made of r's path stripped by strip and a service_root made of r's service root concatenated with strip.
Error _ with a Http.s404_not_found if stripping results in None.

Absolute file paths

val to_absolute_filepath : ?strip:Http.path -> root:Http.fpath -> t -> (Http.fpath, Resp.t) Stdlib.result

absolute_filepath ~strip ~root r determines an absolute file path strictly rooted in root by stripping strip (defaults to []) from r's path, converting the result to an absolute filepath and prefixing it with docroot.

Errors with Http.s404_not_found if stripping strip results in None and Http.s400_bad_request if the absolute path conversion fails.

Queries

Warning. Http.Query.t values are untrusted, you need to properly validate their data.

val to_query : t -> (Http.Query.t, Resp.t) Stdlib.result

to_query r extracts a query from r. This is

Ok q with q parsed from Req.query r if r's method is `GET.
Ok q with q parsed from the request body if r is `POST with a content type of Http.Mime_type.application_x_www_form_urlencoded or TODO multipart. The Req.query is ignored.
Error _ with a:
- Http.s405_method_not_allowed reponse on other methods
- Http.s415_unsupported_media_type response if the content-type is unsupported
- Http.s400_bad_request reponse on decoding errors.

Service routing

val to_service : strip:Http.path -> t -> (t, Resp.t) Stdlib.result

to_service ~strip r strips strip from r's path and appends it to the service root. Errors with Http.s404_not_found if stripping strip results in None.