Line data    Source code

       1             : #ifndef HEADER_fd_src_discof_restore_utils_fd_ssping_h
       2             : #define HEADER_fd_src_discof_restore_utils_fd_ssping_h
       3             : 
       4             : /* The snapshot pinger (ssping) is responsible for maintaining a list of
       5             :    peers that are reachable for snapshot download, and returning the
       6             :    "best" such peer at any time.
       7             : 
       8             :    The "best" peer is defined as the one with the lowest combined score
       9             :    of TCP connection latency and snapshot age (slots behind the
      10             :    cluster), as computed by the peer selector.
      11             : 
      12             :    The snapshot pinger works on the assumption that there is a maximum
      13             :    size of peers that will ever be added, as we expect from the gossip
      14             :    system.  Peers can be added and removed arbitrarily outside of this
      15             :    maximum restriction. */
      16             : 
      17             : #include "../../../util/fd_util_base.h"
      18             : #include "../../../util/net/fd_net_headers.h"
      19             : 
      20             : struct fd_sspeer_selector_private;
      21             : typedef struct fd_sspeer_selector_private fd_sspeer_selector_t;
      22             : 
      23           0 : #define FD_SSPING_FD_MIN 20000
      24           0 : #define FD_SSPING_FD_CNT   247 /* Limit to how many pings can be
      25             :                                   inflight.  Chosen so that it doesn't
      26             :                                   overflow the tile limit (256 allowed
      27             :                                   fds, less the workspace fd, stderr,
      28             :                                   logfile, snapshot dir + 2 output
      29             :                                   fds, the 2 netdb fds for DNS, and
      30             :                                   the adns UDP socket). */
      31             : 
      32           0 : #define FD_SSPING_MAGIC (0xF17EDA2CE55A1A60) /* FIREDANCE SSPING V0 */
      33             : 
      34             : struct fd_ssping_private;
      35             : typedef struct fd_ssping_private fd_ssping_t;
      36             : 
      37             : typedef void
      38             : (* fd_ssping_on_ping_fn_t)( void *        _ctx,
      39             :                             fd_ip4_port_t addr,
      40             :                             ulong         latency );
      41             : 
      42             : FD_PROTOTYPES_BEGIN
      43             : 
      44             : FD_FN_CONST ulong
      45             : fd_ssping_align( void );
      46             : 
      47             : FD_FN_CONST ulong
      48             : fd_ssping_footprint( ulong max_peers );
      49             : 
      50             : void *
      51             : fd_ssping_new( void *                 shmem,
      52             :                ulong                  max_peers,
      53             :                ulong                  seed,
      54             :                fd_ssping_on_ping_fn_t on_ping_cb,
      55             :                void *                 cb_arg,
      56             :                int                    epoll_fd );
      57             : 
      58             : fd_ssping_t *
      59             : fd_ssping_join( void * shping );
      60             : 
      61             : void *
      62             : fd_ssping_leave( fd_ssping_t * ssping );
      63             : 
      64             : void *
      65             : fd_ssping_delete( void * shping );
      66             : 
      67             : /* Add a peer to be tracked by the snapshot pinger, which will from here
      68             :    until it is removed, constantly ping the node to maintain its
      69             :    status.
      70             : 
      71             :    An address can be added multiple times, and the addresses are
      72             :    internally reference counted, so it will need a corresponding number
      73             :    of releases to be removed from ping tracking.
      74             : 
      75             :    The ping tracker cannot be overflowed, and if too many peers are
      76             :    being tracked, trying to add a new peer is a no-op. */
      77             : 
      78             : void
      79             : fd_ssping_add( fd_ssping_t * ssping,
      80             :                fd_ip4_port_t addr );
      81             : 
      82             : /* Remove a peer from tracking by the snapshot pinger.  Peers are
      83             :    reference counted, so this will only remove the peer only if the
      84             :    count goes to zero.  If the peer is not tracked, this is a no-op.
      85             :    Returns whether the peer was removed. */
      86             : 
      87             : int
      88             : fd_ssping_remove( fd_ssping_t * ssping,
      89             :                   fd_ip4_port_t addr );
      90             : 
      91             : /* Mark the peer as invalid for selection for a period of time, probably
      92             :    if they refused a connection or served us a bad snapshot. */
      93             : 
      94             : void
      95             : fd_ssping_invalidate( fd_ssping_t * ssping,
      96             :                       fd_ip4_port_t addr,
      97             :                       long          now );
      98             : 
      99             : /* Returns 1 if the peer at addr is currently in the INVALID state
     100             :    (i.e. temporarily banned), 0 otherwise.  Safe to call with a NULL
     101             :    ssping (returns 0). */
     102             : 
     103             : int
     104             : fd_ssping_is_invalidated( fd_ssping_t * ssping,
     105             :                           fd_ip4_port_t addr );
     106             : 
     107             : /* Advance the ping tracker forward in time until "now".  This should be
     108             :    called periodically to refresh pings and service networking to
     109             :    maintain ping states.  Takes a handle to the peer selector to
     110             :    invalidate peers from both the pinger and the selector. */
     111             : 
     112             : void
     113             : fd_ssping_advance( fd_ssping_t *          ssping,
     114             :                    long                   now,
     115             :                    fd_sspeer_selector_t * selector);
     116             : 
     117             : /* fd_ssping_next_deadline returns the earliest wallclock at which
     118             :    advance has timer work: a ping times out, a valid peer is due a
     119             :    refresh, or an invalid one a retry.  LONG_MAX if none. */
     120             : 
     121             : long
     122             : fd_ssping_next_deadline( fd_ssping_t const * ssping );
     123             : 
     124             : FD_PROTOTYPES_END
     125             : 
     126             : #endif /* HEADER_fd_src_discof_restore_utils_fd_ssping_h */