Reqd (docs.findlib-1.h2.H2.Reqd)

Request Descriptor

type error = [

| `Bad_request
| `Internal_server_error
| `Exn of exn

]

type t

val request : t -> Request.t

val request_body : t -> Body.Reader.t

val response : t -> Response.t option

val response_exn : t -> Response.t

Responding

The following functions will initiate a response for the corresponding request in t. When the response is fully transmitted to the wire, the stream completes.

From RFC7540§8.1: An HTTP request/response exchange fully consumes a single stream.

val respond_with_string : t -> Response.t -> string -> unit

val respond_with_bigstring : t -> Response.t -> Bigstringaf.t -> unit

val respond_with_streaming : 
  t ->
  ?flush_headers_immediately:bool ->
  Response.t ->
  Body.Writer.t

val schedule_trailers : t -> Headers.t -> unit

schedule_trailers reqd trailers schedules a list of trailers to be sent before the stream is closed, concluding the HTTP message. Should only be used after respond_with_streaming. Raises Failure if trailers have already been scheduled. See RFC7540§8.1 for more information

Pushing

HTTP/2 allows a server to pre-emptively send (or "push") responses (along with corresponding "promised" requests) to a client in association with a previous client-initiated request. This can be useful when the server knows the client will need to have those responses available in order to fully process the response to the original request.

An additional note regarding server push:

In HTTP/2, PUSH_PROMISE frames must only be sent in the open or half-closed ("remote") stream states. In practice, this means that calling Reqd.push must happen before the entire response body for the associated client-initiated request has been written to the wire. As such, it is dangerous to start a server pushed response in association with either Reqd.respond_with_string or Reqd.respond_with_bigstring, as the entire body for the response that they produce is sent to the output channel immediately, causing the corresponding stream to enter the closed state.

See RFC7540§8.2 for more details.

val push : 
  t ->
  Request.t ->
  (t, [ `Push_disabled | `Stream_cant_push | `Stream_ids_exhausted ]) result

push reqd request creates a new ("pushed") request descriptor that allows responding to the "promised" request. As per the HTTP/2 specification, request must be cacheable, safe, and must not include a request body (see RFC7540§8.2 for more details). Note: h2 will not validate request against these assumptions.

This function returns Error `Push_disabled when the value of SETTINGS_ENABLE_PUSH is set to 0 (see RFC7540§8.2 for more details), Error `Stream_cant_push when trying to initiate a push stream from a stream that has been obtained from pushing, or Error `Stream_ids_exhausted when the connection has exhausted the range of identifiers available for pushed streams and cannot push on that connection anymore.

Exception Handling

val error_code : t -> error option

val report_exn : t -> exn -> unit

val try_with : t -> (unit -> unit) -> (unit, exn) result