package octez-shell-libs

  1. Overview
  2. Docs
package octez-shell-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

This module maintains several pools of points/peers needed by the P2P layer.

Recall a *point id* (or point) is a couple (addr, port). A *peer id* (or peer) is a hash uniquely identifying a peer. An address may host several peers.

Pool functions can trigger two types of events. They can *log* P2p_connection.P2p_event.t (for the upper layer), and they can trigger condition variables defined in P2p_trigger.t, for inter-modules synchronization.

Pool management

type ('msg, 'peer, 'conn) t

The type of a pool of connections, parametrized by, resp., the type of messages and the meta-information associated to an identity and a connection.

type config = {
  1. identity : Tezos_base.TzPervasives.P2p_identity.t;
    (*

    Our identity.

    *)
  2. trusted_points : (Tezos_base.TzPervasives.P2p_point.Id.t * Tezos_base.TzPervasives.P2p_peer.Id.t option) list;
    (*

    List of hard-coded known peers to bootstrap the network from.

    *)
  3. peers_file : string;
    (*

    The path to the JSON file where the metadata associated to peer_ids are loaded / stored.

    *)
  4. private_mode : bool;
    (*

    If true, only open outgoing/accept incoming connections to/from peers whose addresses are in trusted_peers, and inform these peers that the identity of this node should not be revealed to the rest of the network.

    *)
  5. max_known_points : (int * int) option;
    (*

    Parameters for the garbage collection of known points. If None, no garbage collection is performed. Otherwise, the first integer of the couple limits the size of the "known points" table. When this number is reached, the table is purged off of disconnected points, older first, to try to reach the amount of connections indicated by the second integer.

    *)
  6. max_known_peer_ids : (int * int) option;
    (*

    Like max_known_points, but for known peer_ids.

    *)
  7. peer_greylist_size : int;
    (*

    The number of peer_ids kept in the peer_id greylist.

    *)
  8. ip_greylist_size_in_kilobytes : int;
    (*

    The size of the IP address greylist.

    *)
  9. ip_greylist_cleanup_delay : Tezos_base.TzPervasives.Time.System.Span.t;
    (*

    The time an IP address is kept in the greylist.

    *)
}
val save_peers : ('msg, 'peer, 'conn) t -> unit Lwt.t

save_peers pool save all peer currently known by the node on disk

val tear_down_connections : reason:P2p_disconnection_reason.t -> ('msg, 'peer, 'conn) t -> unit Lwt.t

tear_down_connections ~reason pool close all connections, and returns when member connections are either disconnected or canceled.

val destroy : ('msg, 'peer, 'conn) t -> unit Lwt.t

destroy pool calls tear_down_connections and save the known peers list on the disk

val config : (_, _, _) t -> config

config pool is the config argument passed to pool at creation.

Connections management

val active_connections : ('msg, 'peer, 'conn) t -> int

active_connections pool is the number of connections inside pool.

val register_point : ?trusted:bool -> ?expected_peer_id:Tezos_base.TzPervasives.P2p_peer.Id.t -> ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_point.Id.t -> ('msg, 'peer, 'conn) P2p_conn.t P2p_point_state.Info.t

If point doesn't belong to the table of known points, register_point ?expected_peer_id t point creates a P2p_point_state.Info.t, triggers a `New_point` event and signals the `new_point` condition. If table capacity is exceeded, a GC of the table is triggered.

If point is already known, the P2p_point_state.Info.t from the table is returned. In either case, the trusted status of the returned P2p_point_state.Info.t is set to trusted. If an expected_peer_id is given, it will be used during the next connection attempt. If the provided peer_id is different the connection will be refused. If we are already connected to a peer, we check whether the current peer_id is the expected one otherwise we disconnect from this point.

val unregister_point : ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_point.Id.t -> unit

Remove a point from the table of known points if it is already known..

val register_new_point : ?trusted:bool -> ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_point.Id.t -> ('msg, 'peer, 'conn) P2p_conn.t P2p_point_state.Info.t option

register_new_point pool point returns None if point is a point for this peer. Otherwise it behaves as register_point.

val register_list_of_new_points : ?trusted:bool -> medium:string -> source:Tezos_base.TzPervasives.P2p_peer.Id.t -> ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_point.Id.t list -> unit Lwt.t

register_list_of_new_point ?trusted medium source pool point_list o registers all points of the list as new points. medium and source are for logging purpose. medium should indicate through which medium the points have been acquired ( advertisement, Nack, ..) and source is the id of the peer which sent the list.

val register_peer : ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_peer.Id.t -> (('msg, 'peer, 'conn) P2p_conn.t, 'peer, 'conn) P2p_peer_state.Info.t

If peer doesn't belong to the table of known peers, register_peer t peer creates a P2p_peer.Info.t, triggers a `New_peer` event, and signals a `new_peer` condition. If table capacity is exceeded, a GC of the table is triggered. If peer is already known, the P2p_peer.Info.t from the table is returned.

module Connection : sig ... end

Functions on Peer_id

module Peers : sig ... end

Functions on Points

module Points : sig ... end

Misc functions

val greylist_addr : ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_addr.t -> unit

greylist_addr pool addr adds addr to pool's IP greylist.

val greylist_peer : ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_peer.Id.t -> unit

greylist_peer pool peer adds peer to pool's peer greylist and peer's address to pool's addr greylist.

val clear_greylist : ('msg, 'peer, 'conn) t -> unit

clear_greylist removes all addresses from the greylist.

val gc_greylist : ('msg, 'peer, 'conn) t -> unit

gc_greylist removes some addresses from the greylist (the oldest have a higher probability to be removed, yet due to the underlying probabilistic structure, recent greylistings can be dropped).

val acl_clear : ('msg, 'peer, 'conn) t -> unit

acl_clear pool clears ACL tables.

val list_known_points : ignore_private:bool -> ?size:int -> ('msg, 'peer, 'coon) t -> Tezos_base.TzPervasives.P2p_point.Id.t list Lwt.t

list_known_points ~ignore_private ?size t returns a list of point ids, which are not banned, and if ignore_private is true, public.

It returns at most size point ids (default is 50) based on a heuristic that selects a mix of 3/5 "good" and 2/5 random points.

val connected_peer_ids : ('msg, 'peer, 'conn) t -> (('msg, 'peer, 'conn) P2p_conn.t, 'peer, 'conn) P2p_peer_state.Info.t Tezos_base.TzPervasives.P2p_peer.Table.t
val score : ('msg, 'peer, 'conn) t -> 'peer -> float

score t peer_meta returns the score of peer_meta.

val add_to_id_points : ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_point.Id.t -> unit

add_to_id_points t point adds point to the list of points for this peer. point is removed from the list of known points.

val set_expected_peer_id : ('msg, 'peer, 'conn) t -> Tezos_base.TzPervasives.P2p_point.Id.t -> Tezos_base.TzPervasives.P2p_peer.Id.t -> unit Lwt.t

set_expected_peer_id t point peer sets peer as an expected peer_id to point. For any future connection with this point, there is a check that the peer_id announced is the expected one. As a side effect, if there is an active connection with point with another peer_id, we disconnect from this point and the point is greylisted. If the connection is not active but accepted, the point is greylisted.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct