Line data    Source code

       1             : #ifndef HEADER_fd_src_discof_restore_utils_fd_sspeer_selector_h
       2             : #define HEADER_fd_src_discof_restore_utils_fd_sspeer_selector_h
       3             : 
       4             : /* The snapshot peer selector (sspeer_selector) continuously selects
       5             :    the most optimal snapshot peer to download snapshots from.  The
       6             :    most optimal peer is defined as the closest peer that serves the
       7             :    most recent snapshot. */
       8             : 
       9             : #include "../../../util/fd_util_base.h"
      10             : #include "../../../util/net/fd_net_headers.h"
      11             : 
      12           3 : #define FD_SSPEER_SELECTOR_MAGIC (0xF17EDA2CE5593350) /* FIREDANCE SSPING V0 */
      13             : 
      14             : /* fd_ssinfo stores the resolved snapshot slot information from a peer. */
      15             : struct fd_ssinfo {
      16             :   struct {
      17             :     ulong slot;
      18             :   } full;
      19             : 
      20             :   struct {
      21             :     ulong base_slot;
      22             :     ulong slot;
      23             :   } incremental;
      24             : };
      25             : typedef struct fd_ssinfo fd_ssinfo_t;
      26             : 
      27             : /* fd_sscluster_slot stores the highest full and incremental slot pair
      28             :    seen in the cluster. */
      29             : struct fd_sscluster_slot {
      30             :   ulong full;
      31             :   ulong incremental;
      32             : };
      33             : 
      34             : typedef struct fd_sscluster_slot fd_sscluster_slot_t;
      35             : 
      36             :  /* fd_sspeer_t represents a selected peer from the snapshot peer
      37             :     selector, including the peer's address, resolved snapshot slots,
      38             :     and selector score. */
      39             : struct fd_sspeer {
      40             :   fd_ip4_port_t addr;   /* address of the peer */
      41             :   fd_ssinfo_t   ssinfo; /* resolved snapshot slot info of the peer */
      42             :   ulong         score;  /* selector score of peer */
      43             : };
      44             : 
      45             : typedef struct fd_sspeer fd_sspeer_t;
      46             : 
      47             : struct fd_sspeer_selector_private;
      48             : typedef struct fd_sspeer_selector_private fd_sspeer_selector_t;
      49             : 
      50             : FD_PROTOTYPES_BEGIN
      51             : 
      52             : FD_FN_CONST ulong
      53             : fd_sspeer_selector_align( void );
      54             : 
      55             : FD_FN_CONST ulong
      56             : fd_sspeer_selector_footprint( ulong max_peers );
      57             : 
      58             : void *
      59             : fd_sspeer_selector_new( void * shmem,
      60             :                         ulong  max_peers,
      61             :                         int    incremental_snapshot_fetch,
      62             :                         ulong  seed );
      63             : 
      64             : fd_sspeer_selector_t *
      65             : fd_sspeer_selector_join( void * shselector );
      66             : 
      67             : void *
      68             : fd_sspeer_selector_leave( fd_sspeer_selector_t * selector );
      69             : 
      70             : void *
      71             : fd_sspeer_selector_delete( void * shselector );
      72             : 
      73             : /* Add a peer to the selector.  If the peer already exists,
      74             :    fd_sspeer_selector_add updates the existing peer's score using the
      75             :    given peer latency and snapshot info.  Returns the updated score. */
      76             : ulong
      77             : fd_sspeer_selector_add( fd_sspeer_selector_t * selector,
      78             :                         fd_ip4_port_t          addr,
      79             :                         ulong                  peer_latency,
      80             :                         fd_ssinfo_t const *    ssinfo );
      81             : 
      82             : /* Remove a peer from the selector.  Peers are removed when they are
      83             :    not reachable or serving corrupted/malformed snapshots.  This is a
      84             :    no-op if the peer does not exist in the selector.  */
      85             : void
      86             : fd_sspeer_selector_remove( fd_sspeer_selector_t * selector,
      87             :                            fd_ip4_port_t          addr );
      88             : 
      89             : /* Select the best peer to download a snapshot from.  incremental
      90             :    indicates to select a peer to download an incremental snapshot.  If
      91             :    incremental is set, base_slot must be a valid full snapshot slot. */
      92             : fd_sspeer_t
      93             : fd_sspeer_selector_best( fd_sspeer_selector_t * selector,
      94             :                          int                    incremental,
      95             :                          ulong                  base_slot );
      96             : 
      97             : /* Updates the selector's internal cluster slot and re-score all peers
      98             :    when the cluster slot updates (moves forward) */
      99             : void
     100             : fd_sspeer_selector_process_cluster_slot( fd_sspeer_selector_t * selector,
     101             :                                          ulong                  full_slot,
     102             :                                          ulong                  incremental_slot );
     103             : 
     104             : /* Obtain the cluster slot from the selector.  It is the highest
     105             :    resolved full/incremental slot pair seen from snapshot hashes or
     106             :    from resolved http peers. */
     107             : fd_sscluster_slot_t
     108             : fd_sspeer_selector_cluster_slot( fd_sspeer_selector_t * selector );
     109             : 
     110             : FD_PROTOTYPES_END
     111             : 
     112             : #endif /* HEADER_fd_src_discof_restore_utils_fd_sspeer_selector_h */