github.com/ethersphere/bee/v2@v2.2.0/pkg/topology/topology.go (about)

     1  // Copyright 2020 The Swarm Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package topology exposes abstractions needed in
     6  // topology-aware components.
     7  package topology
     8  
     9  import (
    10  	"errors"
    11  	"io"
    12  	"time"
    13  
    14  	"github.com/ethersphere/bee/v2/pkg/p2p"
    15  	"github.com/ethersphere/bee/v2/pkg/swarm"
    16  )
    17  
    18  var (
    19  	ErrNotFound      = errors.New("no peer found")
    20  	ErrWantSelf      = errors.New("node wants self")
    21  	ErrOversaturated = errors.New("oversaturated")
    22  )
    23  
    24  type Driver interface {
    25  	p2p.Notifier
    26  	PeerAdder
    27  	ClosestPeerer
    28  	PeerIterator
    29  	SubscribeTopologyChange() (c <-chan struct{}, unsubscribe func())
    30  	io.Closer
    31  	Halter
    32  	Snapshot() *KadParams
    33  	IsReachable() bool
    34  	SetStorageRadiuser
    35  	UpdatePeerHealth(addr swarm.Address, h bool, t time.Duration)
    36  }
    37  
    38  type PeerAdder interface {
    39  	// AddPeers is called when peers are added to the topology backlog
    40  	AddPeers(addr ...swarm.Address)
    41  }
    42  
    43  type ClosestPeerer interface {
    44  	// ClosestPeer returns the closest connected peer we have in relation to a
    45  	// given chunk address.
    46  	// This function will ignore peers with addresses provided in skipPeers.
    47  	// Returns topology.ErrWantSelf in case base is the closest to the address.
    48  	ClosestPeer(addr swarm.Address, includeSelf bool, f Select, skipPeers ...swarm.Address) (peerAddr swarm.Address, err error)
    49  }
    50  
    51  // PeerIterator is an interface that allows iteration over peers.
    52  type PeerIterator interface {
    53  	// EachConnectedPeer iterates through connected
    54  	// peers from the closest bin to the farthest.
    55  	EachConnectedPeer(EachPeerFunc, Select) error
    56  	// EachConnectedPeerRev iterates through connected
    57  	// peers from the farthest bin to the closest.
    58  	EachConnectedPeerRev(EachPeerFunc, Select) error
    59  }
    60  
    61  // Select defines the different filters that can be used with the Peer iterators.
    62  // The fields only take effect if set to true. The logical AND operator is applied to multiple selected fields.
    63  type Select struct {
    64  	Reachable bool
    65  	Healthy   bool
    66  }
    67  
    68  // EachPeerFunc is a callback that is called with a peer and its PO
    69  type EachPeerFunc func(addr swarm.Address, bin uint8) (stop, jumpToNext bool, err error)
    70  
    71  // PeerInfo is a view of peer information exposed to a user.
    72  type PeerInfo struct {
    73  	Address swarm.Address       `json:"address"`
    74  	Metrics *MetricSnapshotView `json:"metrics,omitempty"`
    75  }
    76  
    77  // MetricSnapshotView represents snapshot of metrics counters in more human readable form.
    78  type MetricSnapshotView struct {
    79  	LastSeenTimestamp          int64   `json:"lastSeenTimestamp"`
    80  	SessionConnectionRetry     uint64  `json:"sessionConnectionRetry"`
    81  	ConnectionTotalDuration    float64 `json:"connectionTotalDuration"`
    82  	SessionConnectionDuration  float64 `json:"sessionConnectionDuration"`
    83  	SessionConnectionDirection string  `json:"sessionConnectionDirection"`
    84  	LatencyEWMA                int64   `json:"latencyEWMA"`
    85  	Reachability               string  `json:"reachability"`
    86  	Healthy                    bool    `json:"healthy"`
    87  }
    88  
    89  type BinInfo struct {
    90  	BinPopulation     uint        `json:"population"`
    91  	BinConnected      uint        `json:"connected"`
    92  	DisconnectedPeers []*PeerInfo `json:"disconnectedPeers"`
    93  	ConnectedPeers    []*PeerInfo `json:"connectedPeers"`
    94  }
    95  
    96  type KadBins struct {
    97  	Bin0  BinInfo `json:"bin_0"`
    98  	Bin1  BinInfo `json:"bin_1"`
    99  	Bin2  BinInfo `json:"bin_2"`
   100  	Bin3  BinInfo `json:"bin_3"`
   101  	Bin4  BinInfo `json:"bin_4"`
   102  	Bin5  BinInfo `json:"bin_5"`
   103  	Bin6  BinInfo `json:"bin_6"`
   104  	Bin7  BinInfo `json:"bin_7"`
   105  	Bin8  BinInfo `json:"bin_8"`
   106  	Bin9  BinInfo `json:"bin_9"`
   107  	Bin10 BinInfo `json:"bin_10"`
   108  	Bin11 BinInfo `json:"bin_11"`
   109  	Bin12 BinInfo `json:"bin_12"`
   110  	Bin13 BinInfo `json:"bin_13"`
   111  	Bin14 BinInfo `json:"bin_14"`
   112  	Bin15 BinInfo `json:"bin_15"`
   113  	Bin16 BinInfo `json:"bin_16"`
   114  	Bin17 BinInfo `json:"bin_17"`
   115  	Bin18 BinInfo `json:"bin_18"`
   116  	Bin19 BinInfo `json:"bin_19"`
   117  	Bin20 BinInfo `json:"bin_20"`
   118  	Bin21 BinInfo `json:"bin_21"`
   119  	Bin22 BinInfo `json:"bin_22"`
   120  	Bin23 BinInfo `json:"bin_23"`
   121  	Bin24 BinInfo `json:"bin_24"`
   122  	Bin25 BinInfo `json:"bin_25"`
   123  	Bin26 BinInfo `json:"bin_26"`
   124  	Bin27 BinInfo `json:"bin_27"`
   125  	Bin28 BinInfo `json:"bin_28"`
   126  	Bin29 BinInfo `json:"bin_29"`
   127  	Bin30 BinInfo `json:"bin_30"`
   128  	Bin31 BinInfo `json:"bin_31"`
   129  }
   130  
   131  type KadParams struct {
   132  	Base                string    `json:"baseAddr"`            // base address string
   133  	Population          int       `json:"population"`          // known
   134  	Connected           int       `json:"connected"`           // connected count
   135  	Timestamp           time.Time `json:"timestamp"`           // now
   136  	NNLowWatermark      int       `json:"nnLowWatermark"`      // low watermark for depth calculation
   137  	Depth               uint8     `json:"depth"`               // current depth
   138  	Reachability        string    `json:"reachability"`        // current reachability status
   139  	NetworkAvailability string    `json:"networkAvailability"` // network availability
   140  	Bins                KadBins   `json:"bins"`                // individual bin info
   141  	LightNodes          BinInfo   `json:"lightNodes"`          // light nodes bin info
   142  }
   143  
   144  type Halter interface {
   145  	// Halt the topology from initiating new connections
   146  	// while allowing it to still run.
   147  	Halt()
   148  }
   149  
   150  type SetStorageRadiuser interface {
   151  	SetStorageRadius(uint8)
   152  }
   153  
   154  type PeersCounter interface {
   155  	PeersCount(Select) int
   156  }