Document p2p package (#2254)

Signed-off-by: Joshua Kim <[email protected]>
Co-authored-by: Stephen Buttolph <[email protected]>

network/p2p/handler.go

@@ -50,6 +50,7 @@ type Handler interface {
 	) ([]byte, error)
 }
 
+// NoOpHandler drops all messages
 type NoOpHandler struct{}
 
 func (NoOpHandler) AppGossip(context.Context, ids.NodeID, []byte) error {
@@ -94,6 +95,7 @@ type responder struct {
 	sender    common.AppSender
 }
 
+// AppRequest calls the underlying handler and sends back the response to nodeID
 func (r *responder) AppRequest(ctx context.Context, nodeID ids.NodeID, requestID uint32, deadline time.Time, request []byte) error {
 	appResponse, err := r.handler.AppRequest(ctx, nodeID, deadline, request)
 	if err != nil {
@@ -122,6 +124,8 @@ func (r *responder) AppGossip(ctx context.Context, nodeID ids.NodeID, msg []byte
 	}
 }
 
+// CrossChainAppRequest calls the underlying handler and sends back the response
+// to chainID
 func (r *responder) CrossChainAppRequest(ctx context.Context, chainID ids.ID, requestID uint32, deadline time.Time, request []byte) error {
 	appResponse, err := r.handler.CrossChainAppRequest(ctx, chainID, deadline, request)
 	if err != nil {

network/p2p/router.go

@@ -49,6 +49,7 @@ type pendingCrossChainAppRequest struct {
 	CrossChainAppResponseCallback
 }
 
+// meteredHandler emits metrics for a Handler
 type meteredHandler struct {
 	*responder
 	*metrics
@@ -198,6 +199,11 @@ func (r *Router) RegisterAppProtocol(handlerID uint64, handler Handler, nodeSamp
 	}, nil
 }
 
+// AppRequest routes an AppRequest to a Handler based on the handler prefix. The
+// message is dropped if no matching handler can be found.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) AppRequest(ctx context.Context, nodeID ids.NodeID, requestID uint32, deadline time.Time, request []byte) error {
 	start := time.Now()
 	parsedMsg, handler, ok := r.parse(request)
@@ -212,6 +218,7 @@ func (r *Router) AppRequest(ctx context.Context, nodeID ids.NodeID, requestID ui
 		return nil
 	}
 
+	// call the corresponding handler and send back a response to nodeID
 	if err := handler.AppRequest(ctx, nodeID, requestID, deadline, parsedMsg); err != nil {
 		return err
 	}
@@ -220,10 +227,16 @@ func (r *Router) AppRequest(ctx context.Context, nodeID ids.NodeID, requestID ui
 	return nil
 }
 
+// AppRequestFailed routes an AppRequestFailed message to the callback
+// corresponding to requestID.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) AppRequestFailed(ctx context.Context, nodeID ids.NodeID, requestID uint32) error {
 	start := time.Now()
 	pending, ok := r.clearAppRequest(requestID)
 	if !ok {
+		// we should never receive a timeout without a corresponding requestID
 		return ErrUnrequestedResponse
 	}
 
@@ -232,10 +245,16 @@ func (r *Router) AppRequestFailed(ctx context.Context, nodeID ids.NodeID, reques
 	return nil
 }
 
+// AppResponse routes an AppResponse message to the callback corresponding to
+// requestID.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) AppResponse(ctx context.Context, nodeID ids.NodeID, requestID uint32, response []byte) error {
 	start := time.Now()
 	pending, ok := r.clearAppRequest(requestID)
 	if !ok {
+		// we should never receive a timeout without a corresponding requestID
 		return ErrUnrequestedResponse
 	}
 
@@ -244,6 +263,11 @@ func (r *Router) AppResponse(ctx context.Context, nodeID ids.NodeID, requestID u
 	return nil
 }
 
+// AppGossip routes an AppGossip message to a Handler based on the handler
+// prefix. The message is dropped if no matching handler can be found.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) AppGossip(ctx context.Context, nodeID ids.NodeID, gossip []byte) error {
 	start := time.Now()
 	parsedMsg, handler, ok := r.parse(gossip)
@@ -262,6 +286,12 @@ func (r *Router) AppGossip(ctx context.Context, nodeID ids.NodeID, gossip []byte
 	return nil
 }
 
+// CrossChainAppRequest routes a CrossChainAppRequest message to a Handler
+// based on the handler prefix. The message is dropped if no matching handler
+// can be found.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) CrossChainAppRequest(
 	ctx context.Context,
 	chainID ids.ID,
@@ -290,10 +320,16 @@ func (r *Router) CrossChainAppRequest(
 	return nil
 }
 
+// CrossChainAppRequestFailed routes a CrossChainAppRequestFailed message to
+// the callback corresponding to requestID.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) CrossChainAppRequestFailed(ctx context.Context, chainID ids.ID, requestID uint32) error {
 	start := time.Now()
 	pending, ok := r.clearCrossChainAppRequest(requestID)
 	if !ok {
+		// we should never receive a timeout without a corresponding requestID
 		return ErrUnrequestedResponse
 	}
 
@@ -302,10 +338,16 @@ func (r *Router) CrossChainAppRequestFailed(ctx context.Context, chainID ids.ID,
 	return nil
 }
 
+// CrossChainAppResponse routes a CrossChainAppResponse message to the callback
+// corresponding to requestID.
+//
+// Any error condition propagated outside Handler application logic is
+// considered fatal
 func (r *Router) CrossChainAppResponse(ctx context.Context, chainID ids.ID, requestID uint32, response []byte) error {
 	start := time.Now()
 	pending, ok := r.clearCrossChainAppRequest(requestID)
 	if !ok {
+		// we should never receive a timeout without a corresponding requestID
 		return ErrUnrequestedResponse
 	}