[P2P] Integrate background router

p2p/README.md

@@ -71,7 +71,22 @@ See [`raintree/router.go`](./raintree/router.go) for the specific implementation
 
 ## Module Architecture
 
+### Architecture Design Language
+
+The architecture design language expressed in this documentation is based on [UML](https://www.uml-diagrams.org/).
+Due to limitations in the current version of mermaid, class diagrams are much more adherant to the UML component specification.
+Component diagrams however are much more loosely inspired by their UML counterparts.
+
+Regardless, each architecture diagram should be accompanied by a legend which covers all the design language features used to provide disambiguation. 
+
+References:
+- [Class Diagrams](https://www.uml-diagrams.org/class-diagrams-overview.html)
+- [Component Diagrams](https://www.uml-diagrams.org/component-diagrams.html)
+
+  _NOTE: mermaid does not support ports, interfaces, ... in component diagrams ("flowcharts)._
+
 ### Legends
+
 ```mermaid
 flowchart
 subgraph Legend
@@ -89,13 +104,13 @@ classDiagram
 class ConcreteType {
   +ExportedField
   -unexportedField
-  +ExportedMethod(argType) returnType
-  -unexportedMethod()
+  +ExportedMethod(...argTypes) (...returnTypes)
+  -unexportedMethod(...argTypes) (...returnTypes)
 }
 
 class InterfaceType {
     <<interface>>
-    +Method(argType) (returnType1, returnType2)
+    +Method(...argTypes) (...returnTypes)
 }
 
 ConcreteType --|> InterfaceType : Interface realization
@@ -106,9 +121,48 @@ ConcreteType --* OtherType : Aggregatation
 ConcreteType ..*  "(cardinality)" OtherType : Indirect (via interface)
 ```
 
+#### Interface Realization
+
+> Realization is a specialized abstraction relationship between two sets of model elements, one representing a specification (the supplier) and the other represents an implementation of the latter (the client).
+
+> Realization can be used to model stepwise refinement, optimizations, transformations, templates, model synthesis, framework composition, etc.
+
+_(see: [UML Realization](https://www.uml-diagrams.org/realization.html))_
+
+#### Direct Usage
+
+> Dependency is a directed relationship which is used to show that some UML element or a set of elements requires, needs or depends on other model elements for specification or implementation. Because of this, dependency is called a supplier - client relationship, where supplier provides something to the client, and thus the client is in some sense incomplete while semantically or structurally dependent on the supplier element(s). Modification of the supplier may impact the client elements.
+
+> Usage is a dependency in which one named element (client) requires another named element (supplier) for its full definition or implementation.
+
+_(see: [UML Dependency](https://www.uml-diagrams.org/dependency.html))_
+
+#### Composition
+
+> A "strong" form of aggregation
+
+> If a composite (whole) is deleted, all of its composite parts are "normally" deleted with it.
+
+_(see: [UML Shared composition](https://www.uml-diagrams.org/composition.html))_
+
+#### Aggregation
+
+> A "weak" form of composition
+
+> Shared part could be included in several composites, and if some or all of the composites are deleted, shared part may still exist.
+
+_(see: [UML Shared aggregation](https://www.uml-diagrams.org/aggregation.html))_
+
+#### Cardinality
+
+Cardinality indicates the number or range of simultaneous instances of the classifier at the "cardinality-side" association end that are associated with the classifier at the other end of the given association type.
+
+_(see: [UML Association](https://www.uml-diagrams.org/association.html#association-end))_
+
+
 ### P2P Module / Router Decoupling
 
-The P2P module encapsulates the `RaiTreeRouter` and `BackgroundRouter` submodules.
+The P2P module encapsulates the `RainTreeRouter` and `BackgroundRouter` submodules.
 The P2P module internally refers to these as the `stakedActorRouter` and `unstakedActorRouter`, respectively.
 
 Depending on the necessary routing scheme (unicast / broadcast) and whether the peers involved are staked actors, a node will use one or both of these routers.
@@ -337,6 +391,8 @@ Messages MUST be deduplicated before broadcasting their respective event over th
 
 The responsibility of deduplication is encapsulated by the P2P module, As such duplicate messages may come from multiple routers in some of these scenarios.
 
+The `NondeDeduper` state is not persisted outside of memory and therefore is cleared during node restarts.
+
 ```mermaid
 classDiagram
     class RainTreeMessage {
@@ -420,7 +476,12 @@ classDiagram
     p2pModule --* NonceDeduper
 ```
 
+#### Configuration
+
+The size of the `NonceDeduper` queue is configurable via the `P2PConfig.MaxNonces` field.
+
 ### Peer Discovery
+
 Peer discovery involves pairing peer IDs to their network addresses (multiaddr).
 This pairing always has an associated TTL (time-to-live), near the end of which it must
 be refreshed.
@@ -489,8 +550,7 @@ flowchart TD
 
 ### Raintree Router Architecture
 
-_DISCUSS(team): If you feel this needs a diagram, please reach out to the team for additional details._
-_TODO(olshansky, BenVan): Link to RainTree visualizations once it is complete._
+_NOTE: If you (the reader) feel this needs a diagram, please reach out to the team for additional details._
 
 ### Code Organization
 

p2p/background/router.go

@@ -49,6 +49,7 @@ type backgroundRouter struct {
 	host libp2pHost.Host
 	// cancelReadSubscription is the cancel function for the context which is
 	// monitored in the `#readSubscription()` go routine. Call to terminate it.
+	// only one read subscription exists per router at any point in time
 	cancelReadSubscription context.CancelFunc
 
 	// Fields below are assigned during creation via `#setupDependencies()`.
@@ -215,6 +216,7 @@ func (rtr *backgroundRouter) setupUnicastRouter() error {
 }
 
 func (rtr *backgroundRouter) setupDependencies(ctx context.Context, cfg *config.BackgroundConfig) error {
+	// NB: The order in which the internal components are setup below is important
 	if err := rtr.setupUnicastRouter(); err != nil {
 		return err
 	}
@@ -237,7 +239,9 @@ func (rtr *backgroundRouter) setupDependencies(ctx context.Context, cfg *config.
 
 	if err := rtr.setupPeerstore(
 		ctx,
-		cfg.PeerstoreProvider, cfg.CurrentHeightProvider); err != nil {
+		cfg.PeerstoreProvider,
+		cfg.CurrentHeightProvider,
+	); err != nil {
 		return fmt.Errorf("setting up peerstore: %w", err)
 	}
 	return nil
@@ -263,6 +267,7 @@ func (rtr *backgroundRouter) setupPeerstore(
 	return nil
 }
 
+// setupPeerDiscovery sets up the Kademlia Distributed Hash Table (DHT)
 func (rtr *backgroundRouter) setupPeerDiscovery(ctx context.Context) (err error) {
 	dhtMode := dht.ModeAutoServer
 	// NB: don't act as a bootstrap node in peer discovery in client debug mode
@@ -274,6 +279,7 @@ func (rtr *backgroundRouter) setupPeerDiscovery(ctx context.Context) (err error)
 	return err
 }
 
+// setupPubsub sets up a new gossip sub topic using libp2p
 func (rtr *backgroundRouter) setupPubsub(ctx context.Context) (err error) {
 	// TECHDEBT(#730): integrate libp2p tracing via `pubsub.WithEventTracer()`.
 
@@ -313,8 +319,8 @@ func (rtr *backgroundRouter) setupSubscription() (err error) {
 }
 
 func (rtr *backgroundRouter) bootstrap(ctx context.Context) error {
-	// CONSIDERATION: add `GetPeers` method to `PeerstoreProvider` interface
-	// to avoid this loop.
+	// CONSIDERATION: add `GetPeers` method, which returns a map,
+	// to the `PeerstoreProvider` interface to simplify this loop.
 	for _, peer := range rtr.pstore.GetPeerList() {
 		if err := utils.AddPeerToLibp2pHost(rtr.host, peer); err != nil {
 			return err
@@ -356,18 +362,21 @@ func (rtr *backgroundRouter) topicValidator(_ context.Context, _ libp2pPeer.ID,
 	}
 
 	if backgroundMsg.Data == nil {
+		rtr.logger.Debug().Msg("no data in Background message")
 		return false
 	}
 
-	networkMessage := messaging.PocketEnvelope{}
-	if err := proto.Unmarshal(backgroundMsg.Data, &networkMessage); err != nil {
-		rtr.logger.Error().Err(err).Msg("Error decoding network message")
+	poktEnvelope := messaging.PocketEnvelope{}
+	if err := proto.Unmarshal(backgroundMsg.Data, &poktEnvelope); err != nil {
+		rtr.logger.Error().Err(err).Msg("Error decoding Background message")
 		return false
 	}
 
 	return true
 }
 
+// readSubscription is a while loop for receiving and handling messages from the
+// subscription. It is intended to be called as a goroutine.
 func (rtr *backgroundRouter) readSubscription(ctx context.Context) {
 	for {
 		if err := ctx.Err(); err != nil {

p2p/event_handler.go

@@ -27,7 +27,7 @@ func (m *p2pModule) HandleEvent(event *anypb.Any) error {
 		if isStaked, err := m.isStakedActor(); err != nil {
 			return err
 		} else if !isStaked {
-			return nil
+			return nil // unstaked actors do not use RainTree and therefore do not need to update this router
 		}
 
 		oldPeerList := m.stakedActorRouter.GetPeerstore().GetPeerList()

p2p/utils_test.go

@@ -120,7 +120,7 @@ func createP2PModules(t *testing.T, busMocks []*mockModules.MockBus, netMock moc
 		p2pMod, err := Create(
 			busMocks[i],
 			WithHost(host),
-			// mock background router to prevent background message propagation.
+			// mock background router to prevent & ignore background message propagation.
 			WithUnstakedActorRouter(noopBackgroundRouterMock),
 		)
 		require.NoError(t, err)
@@ -226,7 +226,7 @@ func createMockBus(
 			if readWriteWaitGroup != nil {
 				readWriteWaitGroup.Done()
 			}
-		}).AnyTimes() // TODO: specific times
+		}).AnyTimes() // TECHDEBT: assert number of times. Consider `waitForEventsInternal` or similar as in consensus.
 	mockBus.EXPECT().PublishEventToBus(gomock.Any()).AnyTimes()
 	return mockBus
 }