From 371a34d8018b939c5a2bfafb4afd64a690b8827b Mon Sep 17 00:00:00 2001
From: Steven Allen <steven@stebalien.com>
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 <will@cypherpunk.email>
---
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
}