libp2p/go-libp2p-core
1
0
Fork 0
mirror of https://github.com/libp2p/go-libp2p-core.git synced 2025-01-27 04:20:06 +08:00
Code Issues Projects Releases Wiki Activity

doc(event): document network events (#129)

Browse Source 
Add extensive documentation to network events to explain the edge-cases.

Co-authored-by: Will <will@cypherpunk.email>
This commit is contained in:
Steven Allen 2020-03-06 17:18:54 -08:00 committed by GitHub
parent ab2bf16021
commit 371a34d801
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 45 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
event/network.go
View File

@ -5,12 +5,51 @@ import (
"github.com/libp2p/go-libp2p-core/peer"
)
// EvtPeerConnectednessChanged should be emitted every time we form a connection with a peer or drop our last
// connection with the peer. Essentially, it is emitted in two cases:
// a) We form a/any connection with a peer.
// b) We go from having a connection/s with a peer to having no connection with the peer.
// It contains the Id of the remote peer and the new connectedness state.
// EvtPeerConnectednessChanged should be emitted every time the "connectedness" to a
// given peer changes. Specifically, this event is emitted in the following
// cases:
//
// * Connectedness = Connected: Every time we transition from having no
// connections to a peer to having at least one connection to the peer.
// * Connectedness = NotConnected: Every time we transition from having at least
// one connection to a peer to having no connections to the peer.
//
// Additional connectedness states may be added in the future. This list should
// not be considered exhaustive.
//
// Take note:
//
// * It's possible to have _multiple_ connections to a given peer.
// * Both libp2p and networks are asynchronous.
//
// This means that all of the following situations are possible:
//
// A connection is cut and is re-established:
//
// * Peer A observes a transition from Connected -> NotConnected -> Connected
// * Peer B observes a transition from Connected -> NotConnected -> Connected
//
// Explanation: Both peers observe the connection die. This is the "nice" case.
//
// A connection is cut and is re-established.
//
// * Peer A observes a transition from Connected -> NotConnected -> Connected.
// * Peer B observes no transition.
//
// Explanation: Peer A re-establishes the dead connection. Peer B observes the
// new connection form before it observes the old connection die.
//
// A connection is cut:
//
// * Peer A observes no transition.
// * Peer B observes no transition.
//
// Explanation: There were two connections and one was cut. This connection
// might have been in active use but neither peer will observe a change in
// "connectedness". Peers should always make sure to re-try network requests.
type EvtPeerConnectednessChanged struct {
Peer peer.ID
// Peer is the remote peer who's connectedness has changed.
Peer peer.ID
// Connectedness is the new connectedness state.
Connectedness network.Connectedness
}