package tezos-p2p

You can search for identifiers within the package.

in-package search v0.2.0

On This Page

Pool management
Connections management
Functions on Peer_id
Functions on Points
Misc functions

tezos-p2p
- Tezos_p2p
  - P2p
  - P2p_acl
    
    IPBlacklist
    
    IPGreylist
    
    IpTable
    
    Legacy
    
    PeerBlacklist
    
    PeerFIFOCache
    
    PeerGreylist
  - P2p_answerer
  - P2p_conn
  - P2p_connect_handler
  - P2p_directory
  - P2p_discovery
  - P2p_events
    
    Discovery
    
    P2p
    
    P2p_conn
    
    P2p_connect_handler
    
    P2p_fd
    
    P2p_io_scheduler
    
    P2p_maintainance
    
    P2p_pool
    
    P2p_protocol
    
    P2p_socket
    
    P2p_welcome
  - P2p_fd
    
    Table
    
    Legacy
  - P2p_io_scheduler
    
    Internal
  - P2p_maintenance
  - P2p_message
  - P2p_params
  - P2p_peer_state
    
    Info
    
    File
  - P2p_point_state
    
    Info
  - P2p_pool
    
    Connection
    
    Peers
    
    Points
  - P2p_protocol
  - P2p_socket
  - P2p_trigger
  - P2p_welcome

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 = {

identity : Tezos_base.P2p_identity.t;
(*
Our identity.
*)
trusted_points : (Tezos_base.P2p_point.Id.t * Tezos_base.P2p_peer.Id.t option) list;
(*
List of hard-coded known peers to bootstrap the network from.
*)
peers_file : string;
(*
The path to the JSON file where the metadata associated to peer_ids are loaded / stored.
*)
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.
*)
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.
*)
max_known_peer_ids : (int * int) option;
(*
Like max_known_points, but for known peer_ids.
*)
peer_greylist_size : int;
(*
The number of peer_ids kept in the peer_id greylist.
*)
ip_greylist_size_in_kilobytes : int;
(*
The size of the IP address greylist.
*)
ip_greylist_cleanup_delay : Tezos_base.Time.System.Span.t;
(*
The time an IP address is kept in the greylist.
*)

}

val create : 
  config ->
  'peer P2p_params.peer_meta_config ->
  P2p_trigger.t ->
  log:(Tezos_base.P2p_connection.P2p_event.t -> unit) ->
  ('msg, 'peer, 'conn) t Lwt.t

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 : ('msg, 'peer, 'conn) t -> unit Lwt.t

tear_down_connections 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.P2p_peer.Id.t ->
  ('msg, 'peer, 'conn) t ->
  Tezos_base.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.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.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.P2p_peer.Id.t ->
  ('msg, 'peer, 'conn) t ->
  Tezos_base.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.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.P2p_addr.t -> unit

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

val greylist_peer : ('msg, 'peer, 'conn) t -> Tezos_base.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.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.

raises [Invalid_argument]
if size < 0

val connected_peer_ids : 
  ('msg, 'peer, 'conn) t ->
  (('msg, 'peer, 'conn) P2p_conn.t, 'peer, 'conn) P2p_peer_state.Info.t
    Tezos_base.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.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.P2p_point.Id.t ->
  Tezos_base.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.