Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
type error = [
| `Malformed_response of string
| `Invalid_response_body_length of Response.t
| `Protocol_error of Error_code.t * string
| `Exn of exn
]
type response_handler = Response.t -> [ `read ] Body.t -> unit
type error_handler = error -> unit
val create :
?config:Config.t ->
?push_handler:(Request.t -> (response_handler, unit) result) ->
error_handler:error_handler ->
t
create ?config ?push_handler ~error_handler
creates a connection that can be used to interact with servers over the HTTP/2 protocol.
error_handler
will be called for connection-level errors. HTTP/2 is multiplexed over a single TCP connection and distinguishes connection-level errors from stream-level errors. See See RFC7540§5.4 for more details.
If present, push_handler
will be called upon the receipt of PUSH_PROMISE frames with the request promised by the server. This function should return Ok response_handler
if the client wishes to accept the pushed request. In this case, response_handler
will be called once the server respondes to the pushed request. Returning Error ()
will signal to h2 that the client is choosing to reject the request that the server is pushing, and its stream will be closed, as per the following excerpt from the HTTP/2 specification:
From RFC7540§6.6: Recipients of PUSH_PROMISE frames can choose to reject promised streams by returning a RST_STREAM referencing the promised stream identifier back to the sender of the PUSH_PROMISE.
val create_h2c :
?config:Config.t ->
?push_handler:(Request.t -> (response_handler, unit) result) ->
http_request:Httpaf.Request.t ->
error_handler:error_handler ->
(response_handler * error_handler) ->
(t, string) result
val request :
t ->
Request.t ->
error_handler:error_handler ->
response_handler:response_handler ->
[ `write ] Body.t
request connection req ~error_handler ~response_handler
opens a new HTTP/2 stream with req
and returns a request body that can be written to. Once a response arrives, response_handler
will be called with its headers and body. error_handler
will be called for stream-level errors.
HTTP/2 is multiplexed over a single TCP connection and distinguishes connection-level errors from stream-level errors. See RFC7540§5.4 for more details.
val ping : t -> ?payload:Bigstringaf.t -> ?off:int -> (unit -> unit) -> unit
ping connection ?payload ?off f
sends an HTTP/2 PING frame and registers f
to be called when the server has sent an acknowledgement for it. A custom payload
(and offset into that payload) for the PING frame may also be provided. If not, a payload with all bytes set to zero will be used. Note that a PING frame's payload must be 8 octets in length.
In HTTP/2, the PING frame is a mechanism for measuring a minimal round-trip time from the sender, as well as determining whether an idle connection is still functional. See RFC7540§5.4 for more details.
val shutdown : t -> unit
shutdown connection
initiates the graceful shutdown of connection
, and sends an HTTP/2 GOAWAY frame with NO_ERROR on the output channel (See RFC7540§6.8 for more details).
val next_read_operation : t -> [> `Read | `Close ]
next_read_operation t
returns a value describing the next operation that the caller should conduct on behalf of the connection.
val read : t -> Bigstringaf.t -> off:int -> len:int -> int
read t bigstring ~off ~len
reads bytes of input from the provided range of bigstring
and returns the number of bytes consumed by the connection. read
should be called after next_read_operation
returns a `Read
value and additional input is available for the connection to consume.
val read_eof : t -> Bigstringaf.t -> off:int -> len:int -> int
read t bigstring ~off ~len
reads bytes of input from the provided range of bigstring
and returns the number of bytes consumed by the connection. read
should be called after next_read_operation
returns a `Read
and an EOF has been received from the communication channel. The connection will attempt to consume any buffered input and then shutdown the HTTP parser for the connection.
val next_write_operation :
t ->
[ `Write of Bigstringaf.t IOVec.t list | `Yield | `Close of int ]
next_write_operation t
returns a value describing the next operation that the caller should conduct on behalf of the connection.
val report_write_result : t -> [ `Ok of int | `Closed ] -> unit
report_write_result t result
reports the result of the latest write attempt to the connection. report_write_result
should be called after a call to next_write_operation
that returns a `Write buffer
value.
`Ok n
indicates that the caller successfully wrote n
bytes of output from the buffer that the caller was provided by next_write_operation
.`Closed
indicates that the output destination will no longer accept bytes from the write processor.val yield_writer : t -> (unit -> unit) -> unit
yield_writer t continue
registers with the connection to call continue
when writing should resume. yield_writer
should be called after next_write_operation
returns a `Yield
value.
val yield_reader : t -> (unit -> unit) -> unit
yield_reader t continue
immediately calls continue
. This function * shouldn't generally be called and it's only here to simplify adhering * to the Gluten RUNTIME
module type.
val report_exn : t -> exn -> unit
report_exn t exn
reports that an error exn
has been caught and that it has been attributed to t
. Calling this function will switch t
into an error state. Depending on the state t
is transitioning from, it may call its (connection-level) error handler before terminating the connection.
val is_closed : t -> bool
is_closed t
is true
if both the read and write processors have been shutdown. When this is the case next_read_operation
will return `Close _
and next_write_operation
will do the same will return a `Write _
until all buffered output has been flushed, at which point it will return `Close
.