mte/unikernel/duniverse/ocaml-h1/lib/h1.mli

(*----------------------------------------------------------------------------
    Copyright (c) 2017 Inhabited Type LLC.
    Copyright (c) 2025 Robur Cooperative

    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

    3. Neither the name of the author nor the names of his contributors
       may be used to endorse or promote products derived from this software
       without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS
    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
  ----------------------------------------------------------------------------*)

(** H1 is a high-performance, memory-efficient, and scalable web server
    for OCaml. It implements the HTTP 1.1 specification with respect to
    parsing, serialization, and connection pipelining. For compatibility,
    H1 respects the imperatives of the [Server_connection] header when handling
    HTTP 1.0 connections.

    To use this library effectively, the user must be familiar with the HTTP
    1.1 specification, and the basic principles of memory management and
    vectorized IO. *)

(** {2 Basic HTTP Types} *)

module Version : module type of Httpun_types.Version
module Method : module type of Httpun_types.Method
module Status : module type of Httpun_types.Status
module Headers : module type of Httpun_types.Headers

(** {2 Message Body} *)

module Body : sig
  module Reader : sig
    type t

    val schedule_read
      :  t
      -> on_eof  : (unit -> unit)
      -> on_read : (Bstr.t -> off:int -> len:int -> unit)
      -> unit
    (** [schedule_read t ~on_eof ~on_read] will setup [on_read] and [on_eof] as
        callbacks for when bytes are available in [t] for the application to
        consume, or when the input channel has been closed and no further bytes
        will be received by the application.

        Once either of these callbacks have been called, they become inactive.
        The application is responsible for scheduling subsequent reads, either
        within the [on_read] callback or by some other mechanism. *)

    val close : t -> unit
    (** [close t] closes [t], indicating that any subsequent input
        received should be discarded. *)

    val is_closed : t -> bool
    (** [is_closed t] is [true] if {!close} has been called on [t] and [false]
        otherwise. A closed [t] may still have bytes available for reading. *)
  end

  module Writer : sig
    type t

    val write_char : t -> char -> unit
    (** [write_char w char] copies [char] into an internal buffer. If possible,
        this write will be combined with previous and/or subsequent writes
        before transmission. *)

    val write_string : t -> ?off:int -> ?len:int -> string -> unit
    (** [write_string w ?off ?len str] copies [str] into an internal buffer. If
        possible, this write will be combined with previous and/or subsequent
        writes before transmission. *)

    val write_bigstring : t -> ?off:int -> ?len:int -> Bstr.t -> unit
    (** [write_bigstring w ?off ?len bs] copies [bs] into an internal buffer. If
        possible, this write will be combined with previous and/or subsequent
        writes before transmission. *)

    val schedule_bigstring : t -> ?off:int -> ?len:int -> Bstr.t -> unit
    (** [schedule_bigstring w ?off ?len bs] schedules [bs] to be transmitted at
        the next opportunity without performing a copy. [bs] should not be
        modified until a subsequent call to {!flush} has successfully
        completed. *)

    val flush_with_reason : t -> ([ `Written | `Closed ] -> unit) -> unit
    (** [flush_with_reason t f] makes all bytes in [t] available for writing to the awaiting output
        channel. Once those bytes have reached that output channel, [f `Written] will be
        called. If instead, the output channel is closed before all of those bytes are
        successfully written, [f `Closed] will be called.

        The type of the output channel is runtime-dependent, as are guarantees
        about whether those packets have been queued for delivery or have
        actually been received by the intended recipient. *)

    val flush: t -> (unit -> unit) -> unit
    (** [flush t f] is identical to [flush_with_reason t], except ignoring the result of the flush.
        In most situations, you should use flush_with_reason and properly handle a closed output channel. *)

    val close : t -> unit
    (** [close t] closes [t], causing subsequent write calls to raise. If
        [t] is writable, this will cause any pending output to become available
        to the output channel. *)

    val is_closed : t -> bool
    (** [is_closed t] is [true] if {!close} has been called on [t], or if the attached
        output channel is closed (e.g. because [report_write_result `Closed] has been
        called). A closed [t] may still have pending output. *)
  end

end


(** {2 Message Types} *)

(** Request

    A client-initiated HTTP message. *)
module Request : sig
  type t =
    { meth    : Method.t
    ; target  : string
    ; version : Version.t
    ; headers : Headers.t }

  val create
    :  ?version:Version.t (** default is HTTP 1.1 *)
    -> ?headers:Headers.t (** default is {!Headers.empty} *)
    -> Method.t
    -> string
    -> t

  module Body_length : sig
    type t = [
      | `Fixed of Int64.t
      | `Chunked
      | `Error of [`Bad_request]
    ]

    val pp_hum : Format.formatter -> t -> unit
  end

  val body_length : t -> Body_length.t
  (** [body_length t] is the length of the message body accompanying [t]. It is
      an error to generate a request with a close-delimited message body.

      See {{:https://tools.ietf.org/html/rfc7230#section-3.3.3} RFC7230§3.3.3}
      for more details. *)

  val persistent_connection : ?proxy:bool -> t -> bool
  (** [persistent_connection ?proxy t] indicates whether the connection for [t]
      can be reused for multiple requests and responses. If the calling code
      is acting as a proxy, it should pass [~proxy:true].

      See {{:https://tools.ietf.org/html/rfc7230#section-6.3} RFC7230§6.3 for
      more details. *)

  val pp_hum : Format.formatter -> t -> unit [@@ocaml.toplevel_printer]

  val is_upgrade : t -> bool
  (** [is_upgrade t] returns true if the request has the "Connection: upgrade"
      header. *)
end


(** Response

    A server-generated message to a {Request}. *)
module Response : sig
  type t =
    { version : Version.t
    ; status  : Status.t
    ; reason  : string
    ; headers : Headers.t }

  val create
    :  ?reason:string     (** default is determined by {!Status.default_reason_phrase} *)
    -> ?version:Version.t (** default is HTTP 1.1 *)
    -> ?headers:Headers.t (** default is {!Headers.empty} *)
    -> Status.t
    -> t
  (** [create ?reason ?version ?headers status] creates an HTTP response with
      the given parameters. For typical use cases, it's sufficient to provide
      values for [headers] and [status]. *)

  module Body_length : sig
    type t = [
      | `Fixed of Int64.t
      | `Chunked
      | `Close_delimited
      | `Error of [ `Bad_gateway | `Internal_server_error ]
    ]

    val pp_hum : Format.formatter -> t -> unit
  end

  val body_length : ?proxy:bool -> request_method:Method.standard -> t -> Body_length.t
  (** [body_length ?proxy ~request_method t] is the length of the message body
      accompanying [t] assuming it is a response to a request whose method was
      [request_method]. If the calling code is acting as a proxy, it should
      pass [~proxy:true]. This optional parameter only affects error reporting.

      See {{:https://tools.ietf.org/html/rfc7230#section-3.3.3} RFC7230§3.3.3}
      for more details. *)

  val persistent_connection : ?proxy:bool -> t -> bool
  (** [persistent_connection ?proxy t] indicates whether the connection for [t]
      can be reused for multiple requests and responses. If the calling code
      is acting as a proxy, it should pass [~proxy:true].

      See {{:https://tools.ietf.org/html/rfc7230#section-6.3} RFC7230§6.3 for
      more details. *)

  val pp_hum : Format.formatter -> t -> unit [@@ocaml.toplevel_printer]
end


(** IOVec *)
module IOVec : module type of Httpun_types.IOVec

(** {2 Request Descriptor} *)
module Reqd : sig
  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]. Depending on the state of the current connection, and the
      header values of the response, this may cause the connection to close or
      to persist for reuse by the client.

      See {{:https://tools.ietf.org/html/rfc7230#section-6.3} RFC7230§6.3} for
      more details. *)

  val respond_with_string    : t -> Response.t -> string -> unit
  val respond_with_bigstring : t -> Response.t -> Bstr.t -> unit
  val respond_with_streaming : ?flush_headers_immediately:bool -> t -> Response.t -> Body.Writer.t

  val respond_with_upgrade : ?reason:string -> t -> Headers.t -> unit
  (** Initiate an HTTP upgrade. [Server_connection.next_write_request] and
      [next_read_request] will begin returning [`Upgrade] once the response
      headers have been written, which indicates that the runtime should take
      over direct control of the socket rather than shuttling bytes through H1.

      The headers must indicate a valid upgrade message, e.g. must include
      "Connection: upgrade". See [Request.is_upgrade]. *)

  (** {3 Exception Handling} *)

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

(** {2 Buffer Size Configuration} *)
module Config : sig
  type t =
    { read_buffer_size          : int (** Default is [4096] *)
    ; request_body_buffer_size  : int (** Default is [4096] *)
    ; response_buffer_size      : int (** Default is [1024] *)
    ; response_body_buffer_size : int (** Default is [4096] *)
    }

  val default : t
  (** [default] is a configuration record with all parameters set to their
      default values. *)
end

(** {2 Server Connection} *)

module Server_connection : sig
  type t

  type error =
    [ `Bad_request | `Bad_gateway | `Internal_server_error | `Exn of exn ]

  type request_handler = Reqd.t -> unit

  type error_handler =
    ?request:Request.t -> error -> (Headers.t -> Body.Writer.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 next_read_operation : t -> [ `Read | `Yield | `Close | `Upgrade ]
  (** [next_read_operation t] returns a value describing the next operation
      that the caller should conduct on behalf of the connection. *)

  val read : t -> Bstr.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 -> Bstr.t -> off:int -> len:int -> int
  (** [read_eof 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_eof} 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 yield_reader : t -> (unit -> unit) -> unit
  (** [yield_reader t continue] registers with the connection to call
      [continue] when reading should resume. {!yield_reader} should be called
      after {next_read_operation} returns a [`Yield] value. *)

  val next_write_operation : t -> [
    | `Write of Bstr.t IOVec.t list
    | `Yield
    | `Upgrade
    | `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.

        {ul
        {- [`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 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 return [`Write _] until all
      buffered output has been flushed. *)

  val error_code : t -> error option
  (** [error_code t] returns the [error_code] that caused the connection to
      close, if one exists. *)

  (**/**)
  val shutdown : t -> unit
  (**/**)
end

(** {2 Client Connection} *)

module Client_connection : sig

  type t

  type error =
    [ `Malformed_response of string | `Invalid_response_body_length of Response.t | `Exn of exn ]

  type response_handler = Response.t -> Body.Reader.t  -> unit

  type error_handler = error -> unit

  val request
    :  ?config:Config.t
    -> Request.t
    -> error_handler:error_handler
    -> response_handler:response_handler
    -> Body.Writer.t * t

  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 -> Bstr.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 -> Bstr.t -> off:int -> len:int -> int
  (** [read_eof 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_eof} 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 Bstr.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.

        {ul
        {- [`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 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

  (**/**)
  val shutdown : t -> unit
  (**/**)
end

(**/**)

(** Websocket *)
module Websocket : sig
  module Opcode : sig
    type standard_non_control = [ `Continuation | `Text | `Binary ]
    type standard_control = [ `Connection_close | `Ping | `Pong ]
    type standard = [ standard_non_control | standard_control ]
    type t = [ standard | `Other of int ]

    val code : t -> int
    val of_code : int -> t option
    val of_code_exn : int -> t
    val to_int : t -> int
    val of_int : int -> t option
    val of_int_exn : int -> t
    val pp_hum : Format.formatter -> t -> unit
  end

  module Close_code : sig
    type standard =
      [ `Normal_closure
      | `Going_away
      | `Protocol_error
      | `Unsupported_data
      | `No_status_rcvd
      | `Abnormal_closure
      | `Invalid_frame_payload_data
      | `Policy_violation
      | `Message_too_big
      | `Mandatory_ext
      | `Internal_server_error
      | `TLS_handshake ]

    type t = [ standard | `Other of int ]

    val code : t -> int
    val of_code : int -> t option
    val of_code_exn : int -> t
    val to_int : t -> int
    val of_int : int -> t option
    val of_int_exn : int -> t
  end

  module Frame : sig
    type t

    val is_fin : t -> bool
    val rsv : t -> int
    val opcode : t -> Opcode.t
    val has_mask : t -> bool
    val mask : t -> int32 option
    val mask_exn : t -> int32
    val mask_inplace : t -> unit
    val unmask_inplace : t -> unit
    val length : t -> int
    val payload_length : t -> int
    val parse : t Angstrom.t

    (* does not allocate a bigstring, but instead returns a
       new view into the frame payload *)
    val payload_view : t -> Bstr.t

    val serialize_control :
      Faraday.t -> mask:int32 option -> opcode:Opcode.standard_control -> unit

    val schedule_serialize :
      Faraday.t ->
      mask:int32 option ->
      is_fin:bool ->
      opcode:Opcode.t ->
      payload:Bstr.t ->
      off:int ->
      len:int ->
      unit

    val schedule_serialize_bytes :
      Faraday.t ->
      mask:int32 option ->
      is_fin:bool ->
      opcode:Opcode.t ->
      payload:Bytes.t ->
      off:int ->
      len:int ->
      unit

    val serialize_bytes :
      Faraday.t ->
      mask:int32 option ->
      is_fin:bool ->
      opcode:Opcode.t ->
      payload:Bytes.t ->
      off:int ->
      len:int ->
      unit
  end

  type frame_handler =
    opcode:Opcode.t -> is_fin:bool -> Bstr.t -> off:int -> len:int -> unit

  type input_handlers = { frame_handler : frame_handler; eof : unit -> unit }

  module Wsd : sig
    type mode = [ `Client of unit -> int32 | `Server ]
    type t

    val create : mode -> t

    val schedule :
      t ->
      kind:Opcode.standard_non_control ->
      is_fin:bool ->
      Bstr.t ->
      off:int ->
      len:int ->
      unit

    val send_bytes :
      t ->
      kind:Opcode.standard_non_control ->
      is_fin:bool ->
      Bytes.t ->
      off:int ->
      len:int ->
      unit

    val send_ping : t -> unit
    val send_pong : t -> unit
    val flushed : t -> (unit -> unit) -> unit
    val close : t -> unit
    val next : t -> [ `Write of Bstr.t IOVec.t list | `Yield | `Close of int ]
    val report_result : t -> [ `Ok of int | `Closed ] -> unit
    val is_closed : t -> bool
    val when_ready_to_write : t -> (unit -> unit) -> unit
  end

  module Handshake : sig
    val get_nonce : Request.t -> string option

    val server_headers : sha1:(string -> string) -> nonce:string -> Headers.t
  end

  module Client_connection : sig
    type t

    type error =
      [ Client_connection.error
      | `Handshake_failure of Response.t * Body.Reader.t ]

    val create :
      nonce:string ->
      host:string ->
      port:int ->
      resource:string ->
      sha1:(string -> string) ->
      error_handler:(error -> unit) ->
      websocket_handler:(Wsd.t -> input_handlers) ->
      t

    val next_read_operation : t -> [ `Read | `Close ]

    val next_write_operation :
      t -> [ `Write of Bstr.t IOVec.t list | `Yield | `Close of int ]

    val read : t -> Bstr.t -> off:int -> len:int -> int
    val read_eof : t -> Bstr.t -> off:int -> len:int -> int
    val report_write_result : t -> [ `Ok of int | `Closed ] -> unit
    val yield_writer : t -> (unit -> unit) -> unit
    val close : t -> unit
  end

  module Server_connection : sig
    type t
    type error = [ `Exn of exn ]

    val create : websocket_handler:(Wsd.t -> input_handlers) -> t
    val next_read_operation : t -> [ `Read | `Close ]

    val next_write_operation :
      t -> [ `Write of Bstr.t IOVec.t list | `Yield | `Close of int ]

    val read : t -> Bstr.t -> off:int -> len:int -> int
    val read_eof : t -> Bstr.t -> off:int -> len:int -> int
    val report_write_result : t -> [ `Ok of int | `Closed ] -> unit
    val yield_writer : t -> (unit -> unit) -> unit
    val is_closed : t -> bool
    val close : t -> unit
  end
end

(**/**)

module H1_private : sig
  module Parse : sig
    val request : Request.t Angstrom.t
    val response : Response.t Angstrom.t
  end

  module Serialize : sig
    val write_request  : Faraday.t -> Request.t  -> unit
    val write_response : Faraday.t -> Response.t -> unit
  end
end