package protocol_version_header

  1. Overview
  2. Docs

This library offers a lightweight way for applications protocols to version themselves. The more protocols that add themselves to Known_protocol, the nicer error messages we will get when connecting to a service while using the wrong protocol.

The library also offers a mechanism for some data to be shared in the connection header. A header can contain additional_magic_numbers that are not used in the version negotiation but can be used in some way by the peer (e.g. the kerberos rpc library could use this to indicate whether the server is doing any form of authorization).

type t
include Core.Bin_prot.Binable.S with type t := t
include Bin_prot.Binable.S_only_functions with type t := t
val bin_size_t : t Bin_prot.Size.sizer
val bin_write_t : t Bin_prot.Write.writer
val bin_read_t : t Bin_prot.Read.reader
val __bin_read_t__ : (int -> t) Bin_prot.Read.reader

This function only needs implementation if t exposed to be a polymorphic variant. Despite what the type reads, this does *not* produce a function after reading; instead it takes the constructor tag (int) before reading and reads the rest of the variant t afterwards.

val bin_shape_t : Bin_prot.Shape.t
val bin_writer_t : t Bin_prot.Type_class.writer
val bin_reader_t : t Bin_prot.Type_class.reader
include Sexplib0.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
val create_exn : ?additional_magic_numbers:int list -> protocol:Known_protocol.t -> supported_versions:int list -> unit -> t

create_exn raises if one of the following is true:

  • List.length supported_versions + List.length additional_magic_numbers >= 100
  • supported_versions containing version number greater than max_supported_version
  • additional_magic_numbers containing version numbers not greater than max_supported_version
  • additional_magic_numbers overlaps with potential magic values for protocols.
val negotiate : allow_legacy_peer:bool -> us:t -> peer:t -> int Core.Or_error.t

negotiate ~allow_legacy_peer ~us ~peer inspects the magic numbers of us and peer. If the magic numbers match, the highest shared version number is returned.

If allow_legacy_peer then the magic number of peer is assumed to be us if no magic number exists.

val contains_magic_prefix : protocol:Known_protocol.t -> bool Core.Bin_prot.Type_class.reader

contains_magic_prefix reads a bin_protted value of type t and returns a boolean saying whether this magic number was observed.

any_magic_prefix and any_magic_prefix_from_six_bytes read the magic number for one of the known protocols. They differ in how many bytes they read.

any_magic_prefix reads the entire Protocol_version_header.t and then checks if there's any magic prefix in there. The number of bytes in the bin_io representation of a Protocol_version_header.t is not fixed because it depends on the supported versions of the protocol.

any_magic_prefix_from_six_bytes reads exactly 6 bytes to check magic prefix.

any_magic_prefix_from_six_bytes_bin_size is 6: the number of bytes that any_magic_prefix_from_six_bytes reads.

val any_magic_prefix_from_six_bytes : Known_protocol.t option Core.Bin_prot.Type_class.reader

See any_magic_prefix

val any_magic_prefix_from_six_bytes_bin_size : int

See any_magic_prefix

module Known_protocol : sig ... end
module Expert : sig ... end
module For_test : sig ... end