(** Effectful operations using Unix for pure TLS.

    The pure TLS is state and buffer in, state and buffer out. This module uses
    the Unix layer for communication over the network. *)

exception Tls_alert of Tls.Packet.alert_type
exception Tls_failure of Tls.Engine.failure
exception Closed_by_peer

type t
(** Abstract type of a session. *)

val file_descr : t -> Unix.file_descr
(** [file_descr] returns the underlying file-descriptor used by the given
    TLS {i socket}. *)

val read : t -> ?off:int -> ?len:int -> bytes -> int
(** [read fd buf ~off ~len] reads up to [len] bytes (defaults to
    [Bytes.length buf - off] from the given TLS {i socket} [fd], storing them in
    byte sequence [buf], starting at position [off] in [buf] (defaults to [0]).
    It returns the actual number of characters read, between 0 and [len]
    (inclusive).

    @raise Unix_error raised by the system call {!val:Unix.read}. The function
    handles {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK}
    exceptions and redo the system call.

    @raise Invalid_argument if [off] and [len] do not designate a valid range of
    [buf]. *)

val really_read : t -> ?off:int -> ?len:int -> bytes -> unit
(** [really_read fd buf ~off ~len] reads [len] bytes (defaults to
    [Bytes.length buf - off]) from the given TLS {i socket} [fd], storing them
    in byte sequence [buf], starting at position [off] in [buf] (defaults to
    [0]). If [len = 0], [really_read] does nothing.

    @raise Unix_error raised by the system call {!val:Unix.read}. The function
    handles {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK}
    exceptions and redo the system call.

    @raise End_of_file if {!val:Unix.read} returns [0] before [len] characters
    have been read.

    @raise Invalid_argument if [off] and [len] do not designate a valid range of
    [buf]. *)

val write : t -> ?off:int -> ?len:int -> string -> unit
(** [write t str ~off ~len] writes [len] bytes (defaults to
    [String.length str - off]) from byte sequence [str], starting at offset
    [off] (defaults to [0]), to the given TLS {i socket} [fd].

    @raise Unix_error raised by the syscall call {!val:Unix.write}. The function
    handles {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK}
    exceptions and redo the system call.

    @raise Closed_by_peer if [t] is connected to a peer whose reading end is
    closed. Similar to the {!val:EPIPE} error for pipe/socket connected.

    @raise Invalid_argument if [off] and [len] do not designate a valid range of
    [buf]. *)

val close : t -> unit
(** [close flow] closes the TLS session and the underlying file-descriptor. *)

val shutdown : t -> [ `read | `write | `read_write ] -> unit
(** [shutdown t direction] closes the direction of the TLS session [t]. If
    [`read_write] or [`write] is closed, a TLS close-notify is sent to the other
    endpoint. If this results in a fully-closed session (or an errorneous
    session), the underlying file descriptor is closed. *)

val client_of_fd :
  Tls.Config.client ->
  ?read_buffer_size:int ->
  ?host:[ `host ] Domain_name.t ->
  Unix.file_descr ->
  t
(** [client_of_flow client ~host fd] is [t], after client-side TLS handshake of
    [fd] using [client] configuration and [host].

    @raise End_of_file if we are not able to complete the handshake. *)

val server_of_fd :
  Tls.Config.server -> ?read_buffer_size:int -> Unix.file_descr -> t
(** [server_of_fd server fd] is [t], after server-side TLS handshake of [fd]
    using [server] configuration.

    @raise End_of_file if we are not able to complete the handshake. *)

val connect : X509.Authenticator.t -> string * int -> t
(** [connect authenticator (host, port)] is [t], a connected TLS connection
    to [host] on [port] using the default configuration and the
    [authenticator]. *)

val epoch : t -> Tls.Core.epoch_data option
(** [epoch t] returns [epoch], which contains information of the active
    session. *)