From 371a34d8018b939c5a2bfafb4afd64a690b8827b Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Fri, 6 Mar 2020 17:18:54 -0800 Subject: [PATCH] doc(event): document network events (#129) Add extensive documentation to network events to explain the edge-cases. Co-authored-by: Will --- event/network.go | 51 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/event/network.go b/event/network.go index 05b435d..15f9f6c 100644 --- a/event/network.go +++ b/event/network.go @@ -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 } -- GitLab