h2 0.8.0 · OCaml Package

type t

type error = [

| `Bad_request
| `Internal_server_error
| `Exn of exn

]

type request_handler = Reqd.t -> unit

type error_handler =
  ?request:Request.t ->
  error ->
  (Headers.t -> [ `write ] Body.t) ->
  unit

val create : 
  ?config:Config.t ->
  ?error_handler:error_handler ->
  request_handler ->
  t

create ?config ?error_handler ~request_handler creates a connection handler that will service individual requests with request_handler.

val create_h2c : 
  ?config:Config.t ->
  ?error_handler:error_handler ->
  http_request:Httpaf.Request.t ->
  ?request_body:Bigstringaf.t IOVec.t list ->
  request_handler ->
  (t, string) Stdlib.result

create ?config ?error_handler ~http_request ~request_handler creates a connection handler that will take over the communication channel from a HTTP/1.1 connection, and service individual HTTP/2.0 requests with request_handler. Upon successful creation, it returns the connection, otherwise an error message is returned with an explanation of the failure that caused the connection setup to not succeed.

This function is intended to be used in HTTP/1.1 upgrade handlers to set up a new h2c (HTTP/2.0 over TCP) connection without prior knowledge.

See RFC7540§3.2 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 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.

error_code t returns the error_code that caused the connection to close, if one exists.

package h2