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