improve gateway/handler.go comments

gateway/handler.go

@@ -5,7 +5,9 @@
 // LICENSE file                                                              //
 ///////////////////////////////////////////////////////////////////////////////
 
-// Contains callback interface for gateway functionality
+// Contains the top-level initialization for the Gateway comms API.
+// This includes listening on ports, registering GRPC endpoints, and defining
+// the associated callback interface.
 
 package gateway
 
@@ -21,38 +23,30 @@ import (
 	"runtime/debug"
 )
 
-// Handler interface for the Gateway
+// Comms object bundles low-level connect.ProtoComms,
+// the gossip.Manager protocol, and the endpoint Handler interface.
+type Comms struct {
+	*gossip.Manager
+	*connect.ProtoComms
+	handler Handler
+}
+
+// Handler describes the endpoint callbacks for Gateway.
 type Handler interface {
-	// Upload a message to the cMix Gateway (client->Gateway)
+	// PutMessage uploads a message to the cMix Gateway
 	PutMessage(message *pb.GatewaySlot, ipAddr string) (*pb.GatewaySlotResponse, error)
-	// Upload many messages to the cMix Gateway (client->Gateway)
 	PutManyMessages(msgs *pb.GatewaySlots, ipAddr string) (*pb.GatewaySlotResponse, error)
-
-	// Upload a message to the cMix Gateway (gateway -> gateway)
 	PutMessageProxy(message *pb.GatewaySlot, auth *connect.Auth) (*pb.GatewaySlotResponse, error)
-	// Upload many messages to the cMix Gateway (gateway -> gateway)
 	PutManyMessagesProxy(msgs *pb.GatewaySlots, auth *connect.Auth) (*pb.GatewaySlotResponse, error)
-
-	// Client -> Gateway unified polling
 	Poll(msg *pb.GatewayPoll) (*pb.GatewayPollResponse, error)
-	// Client -> Gateway historical round request
 	RequestHistoricalRounds(msg *pb.HistoricalRounds) (*pb.HistoricalRoundsResponse, error)
-	// Client -> Gateway message request
 	RequestMessages(msg *pb.GetMessages) (*pb.GetMessagesResponse, error)
-
 	RequestClientKey(message *pb.SignedClientKeyRequest) (*pb.SignedKeyResponse, error)
 }
 
-// Gateway object used to implement endpoints and top-level comms functionality
-type Comms struct {
-	*gossip.Manager
-	*connect.ProtoComms
-	handler Handler
-}
-
-// Starts a new gateway on the address:port specified by localServer
+// StartGateway starts a new gateway on the address:port specified by localServer
 // and a callback interface for gateway operations
-// with given path to public and private key for TLS connection
+// with given path to public and private key for TLS connection.
 func StartGateway(id *id.ID, localServer string, handler Handler,
 	certPem, keyPem []byte, gossipFlags gossip.ManagerFlags) *Comms {
 	pc, lis, err := connect.StartCommServer(id, localServer,
@@ -87,35 +81,25 @@ func StartGateway(id *id.ID, localServer string, handler Handler,
 	return &gatewayServer
 }
 
-// Handler implementation for the Gateway
+// implementationFunctions for the Handler interface.
 type implementationFunctions struct {
-	// Upload a message to the cMix Gateway
 	PutMessage              func(message *pb.GatewaySlot, ipAddr string) (*pb.GatewaySlotResponse, error)
-	// Upload many messages to the cMix Gateway
 	PutManyMessages         func(msgs *pb.GatewaySlots, ipAddr string) (*pb.GatewaySlotResponse, error)
-	// Client -> Gateway unified polling
 	Poll                    func(msg *pb.GatewayPoll) (*pb.GatewayPollResponse, error)
-	// Client -> Gateway historical round request
 	RequestHistoricalRounds func(msg *pb.HistoricalRounds) (*pb.HistoricalRoundsResponse, error)
-	// Client -> Gateway message request
 	RequestMessages         func(msg *pb.GetMessages) (*pb.GetMessagesResponse, error)
-
-	// Pass-through for RequestClientKey Communication
 	RequestClientKey        func(message *pb.SignedClientKeyRequest) (*pb.SignedKeyResponse, error)
-
-	// Upload a message to the cMix Gateway (gateway -> gateway)
 	PutMessageProxy         func(message *pb.GatewaySlot, auth *connect.Auth) (*pb.GatewaySlotResponse, error)
-	// Upload many messages to the cMix Gateway (gateway -> gateway)
 	PutManyMessagesProxy    func(msgs *pb.GatewaySlots, auth *connect.Auth) (*pb.GatewaySlotResponse, error)
 }
 
 // Implementation allows users of the client library to set the
-// functions that implement the node functions
+// functions that implement the node functions.
 type Implementation struct {
 	Functions implementationFunctions
 }
 
-// Creates and returns a new Handler interface
+// NewImplementation creates and returns a new Handler interface for implementing endpoint callbacks.
 func NewImplementation() *Implementation {
 	um := "UNIMPLEMENTED FUNCTION!"
 	warn := func(msg string) {
@@ -132,7 +116,6 @@ func NewImplementation() *Implementation {
 				warn(um)
 				return &pb.GatewaySlotResponse{}, nil
 			},
-
 			Poll: func(msg *pb.GatewayPoll) (*pb.GatewayPollResponse, error) {
 				warn(um)
 				return &pb.GatewayPollResponse{}, nil
@@ -145,18 +128,14 @@ func NewImplementation() *Implementation {
 				warn(um)
 				return &pb.GetMessagesResponse{}, nil
 			},
-
 			RequestClientKey: func(message *pb.SignedClientKeyRequest) (*pb.SignedKeyResponse, error) {
 				warn(um)
 				return new(pb.SignedKeyResponse), nil
 			},
-
-			// Upload a message to the cMix Gateway (gateway -> gateway)
 			PutMessageProxy: func(message *pb.GatewaySlot, auth *connect.Auth) (*pb.GatewaySlotResponse, error) {
 				warn(um)
 				return &pb.GatewaySlotResponse{}, nil
 			},
-			// Upload many messages to the cMix Gateway (gateway -> gateway)
 			PutManyMessagesProxy: func(msgs *pb.GatewaySlots, auth *connect.Auth) (*pb.GatewaySlotResponse, error) {
 				warn(um)
 				return &pb.GatewaySlotResponse{}, nil
@@ -165,43 +144,43 @@ func NewImplementation() *Implementation {
 	}
 }
 
-// Pass-through for RequestClientKey Communication
+// RequestClientKey is a pass-through for RequestClientKey Communication.
 func (s *Implementation) RequestClientKey(message *pb.SignedClientKeyRequest) (
 	*pb.SignedKeyResponse, error) {
 	return s.Functions.RequestClientKey(message)
 }
 
-// Upload a message to the cMix Gateway
+// PutMessage uploads a message to the cMix Gateway.
 func (s *Implementation) PutMessage(message *pb.GatewaySlot, ipAddr string) (*pb.GatewaySlotResponse, error) {
 	return s.Functions.PutMessage(message, ipAddr)
 }
 
-// Upload many messages to the cMix Gateway
+// PutManyMessages uploads many messages to the cMix Gateway.
 func (s *Implementation) PutManyMessages(msgs *pb.GatewaySlots, ipAddr string) (*pb.GatewaySlotResponse, error) {
 	return s.Functions.PutManyMessages(msgs, ipAddr)
 }
 
-// Upload a message to the cMix Gateway
+// PutMessageProxy uploads a message to the cMix Gateway from a proxy gateway.
 func (s *Implementation) PutMessageProxy(message *pb.GatewaySlot, auth *connect.Auth) (*pb.GatewaySlotResponse, error) {
 	return s.Functions.PutMessageProxy(message, auth)
 }
 
-// Upload many messages to the cMix Gateway
+// PutManyMessagesProxy uploads many messages to the cMix Gateway from a proxy gateway.
 func (s *Implementation) PutManyMessagesProxy(msgs *pb.GatewaySlots, auth *connect.Auth) (*pb.GatewaySlotResponse, error) {
 	return s.Functions.PutManyMessagesProxy(msgs, auth)
 }
 
-// Client -> Gateway unified polling
+// Poll provides Client -> Gateway unified polling.
 func (s *Implementation) Poll(msg *pb.GatewayPoll) (*pb.GatewayPollResponse, error) {
 	return s.Functions.Poll(msg)
 }
 
-// Client -> Gateway historical round request
+// RequestHistoricalRounds provides Client -> Gateway historical round requests.
 func (s *Implementation) RequestHistoricalRounds(msg *pb.HistoricalRounds) (*pb.HistoricalRoundsResponse, error) {
 	return s.Functions.RequestHistoricalRounds(msg)
 }
 
-// Client -> Gateway historical round request
+// RequestMessages handles Client -> Gateway requests for message pickup.
 func (s *Implementation) RequestMessages(msg *pb.GetMessages) (*pb.GetMessagesResponse, error) {
 	return s.Functions.RequestMessages(msg)
 }