Merge 82d8b40bda into 8c4a7fa8d3

params/version.go

@@ -20,6 +20,7 @@ import (
 	"fmt"
 )
 
+// Version components of the current release.
 const (
 	VersionMajor = 1          // Major version component of the current release
 	VersionMinor = 8          // Minor version component of the current release

whisper/mailserver/mailserver.go

@@ -29,6 +29,8 @@ import (
 	"github.com/syndtr/goleveldb/leveldb/util"
 )
 
+// WMailServer stores the leveldb instance containing an archive of messages
+// as well as the whisper instance.
 type WMailServer struct {
 	db  *leveldb.DB
 	w   *whisper.Whisper
@@ -42,6 +44,7 @@ type DBKey struct {
 	raw       []byte
 }
 
+// NewDbKey creates a new DBKey with a new raw hash based on the current time.
 func NewDbKey(t uint32, h common.Hash) *DBKey {
 	const sz = common.HashLength + 4
 	var k DBKey
@@ -53,6 +56,7 @@ func NewDbKey(t uint32, h common.Hash) *DBKey {
 	return &k
 }
 
+// Init assigns initial values for the WMailServer.
 func (s *WMailServer) Init(shh *whisper.Whisper, path string, password string, pow float64) error {
 	var err error
 	if len(path) == 0 {
@@ -82,12 +86,14 @@ func (s *WMailServer) Init(shh *whisper.Whisper, path string, password string, p
 	return nil
 }
 
+// Close shutdowns the connection to the levelDB instance of s
 func (s *WMailServer) Close() {
 	if s.db != nil {
 		s.db.Close()
 	}
 }
 
+// Archive maps the message in bytes to a new raw key hash.
 func (s *WMailServer) Archive(env *whisper.Envelope) {
 	key := NewDbKey(env.Expiry-env.TTL, env.Hash())
 	rawEnvelope, err := rlp.EncodeToBytes(env)
@@ -101,6 +107,7 @@ func (s *WMailServer) Archive(env *whisper.Envelope) {
 	}
 }
 
+// DeliverMail will send a message via the p2p protocol.
 func (s *WMailServer) DeliverMail(peer *whisper.Peer, request *whisper.Envelope) {
 	if peer == nil {
 		log.Error("Whisper peer is nil")
@@ -177,15 +184,16 @@ func (s *WMailServer) validateRequest(peerID []byte, request *whisper.Envelope)
 
 	var bloom []byte
 	payloadSize := len(decrypted.Payload)
-	if payloadSize < 8 {
+	switch {
+	case (payloadSize < 8):
 		log.Warn(fmt.Sprintf("Undersized p2p request"))
 		return false, 0, 0, nil
-	} else if payloadSize == 8 {
+	case (payloadSize == 8):
 		bloom = whisper.MakeFullNodeBloom()
-	} else if payloadSize < 8+whisper.BloomFilterSize {
+	case (payloadSize < 8+whisper.BloomFilterSize):
 		log.Warn(fmt.Sprintf("Undersized bloom filter in p2p request"))
 		return false, 0, 0, nil
-	} else {
+	default:
 		bloom = decrypted.Payload[8 : 8+whisper.BloomFilterSize]
 	}
 

whisper/whisperv5/api.go

@@ -32,6 +32,7 @@ import (
 	"github.com/ethereum/go-ethereum/rpc"
 )
 
+// Variables that specify custom error messages.
 var (
 	ErrSymAsym              = errors.New("specify either a symmetric or an asymmetric key")
 	ErrInvalidSymmetricKey  = errors.New("invalid symmetric key")

whisper/whisperv5/config.go

@@ -16,11 +16,13 @@
 
 package whisperv5
 
+// Config is used to map unambiguously to values in the doc.go file.
 type Config struct {
 	MaxMessageSize     uint32  `toml:",omitempty"`
 	MinimumAcceptedPOW float64 `toml:",omitempty"`
 }
 
+// DefaultConfig values are set by the doc.go file within this package.
 var DefaultConfig = Config{
 	MaxMessageSize:     DefaultMaxMessageSize,
 	MinimumAcceptedPOW: DefaultMinimumPoW,

whisper/whisperv5/doc.go

@@ -34,6 +34,7 @@ import (
 	"time"
 )
 
+// Constants here define the configuration for the current release.
 const (
 	EnvelopeVersion    = uint64(0)
 	ProtocolVersion    = uint64(5)
@@ -53,7 +54,7 @@ const (
 	signatureLength = 65
 	aesKeyLength    = 32
 	AESNonceLength  = 12
-	keyIdSize       = 32
+	keyIDSize       = 32
 
 	MaxMessageSize        = uint32(10 * 1024 * 1024) // maximum accepted size of a message.
 	DefaultMaxMessageSize = uint32(1024 * 1024)

whisper/whisperv5/envelope.go

@@ -82,14 +82,17 @@ func NewEnvelope(ttl uint32, topic TopicType, aesNonce []byte, msg *sentMessage)
 	return &env
 }
 
+// IsSymmetric confirms the AESNonce has length greater than 0.
 func (e *Envelope) IsSymmetric() bool {
 	return len(e.AESNonce) > 0
 }
 
+// isAsymmetric confirms the AESNonce does not have a length greater than 0.
 func (e *Envelope) isAsymmetric() bool {
 	return !e.IsSymmetric()
 }
 
+//Ver converts the version to 64-bit unsigned integer.
 func (e *Envelope) Ver() uint64 {
 	return bytesToUintLittleEndian(e.Version)
 }
@@ -223,7 +226,7 @@ func (e *Envelope) Open(watcher *Filter) (msg *ReceivedMessage) {
 		if msg != nil {
 			msg.Dst = &watcher.KeyAsym.PublicKey
 		}
-	} else if e.IsSymmetric() {
+	} else {
 		msg, _ = e.OpenSymmetric(watcher.KeySym)
 		if msg != nil {
 			msg.SymKeyHash = crypto.Keccak256Hash(watcher.KeySym)

whisper/whisperv5/filter.go

@@ -45,6 +45,7 @@ type Filters struct {
 	mutex    sync.RWMutex
 }
 
+// NewFilters initiliazes the Filterse struct with w.
 func NewFilters(w *Whisper) *Filters {
 	return &Filters{
 		watchers: make(map[string]*Filter),
@@ -52,6 +53,8 @@ func NewFilters(w *Whisper) *Filters {
 	}
 }
 
+// Install hashes the Topic's key and sets the watcher to a random ID
+// inside fs.watchers.
 func (fs *Filters) Install(watcher *Filter) (string, error) {
 	if watcher.Messages == nil {
 		watcher.Messages = make(map[common.Hash]*ReceivedMessage)
@@ -77,6 +80,7 @@ func (fs *Filters) Install(watcher *Filter) (string, error) {
 	return id, err
 }
 
+// Uninstall deletes values associated with id from fs.watchers, if one exists.
 func (fs *Filters) Uninstall(id string) bool {
 	fs.mutex.Lock()
 	defer fs.mutex.Unlock()
@@ -87,12 +91,15 @@ func (fs *Filters) Uninstall(id string) bool {
 	return false
 }
 
+// Get returns the watcher with the associated id.
 func (fs *Filters) Get(id string) *Filter {
 	fs.mutex.RLock()
 	defer fs.mutex.RUnlock()
 	return fs.watchers[id]
 }
 
+// NotifyWatchers validates that messages are allowed to be read before
+// mapping the msg to fs Messages map.
 func (fs *Filters) NotifyWatchers(env *Envelope, p2pMessage bool) {
 	var msg *ReceivedMessage
 
@@ -136,9 +143,8 @@ func (f *Filter) processEnvelope(env *Envelope) *ReceivedMessage {
 		msg := env.Open(f)
 		if msg != nil {
 			return msg
-		} else {
-			log.Trace("processing envelope: failed to open", "hash", env.Hash().Hex())
 		}
+		log.Trace("processing envelope: failed to open", "hash", env.Hash().Hex())
 	} else {
 		log.Trace("processing envelope: does not match", "hash", env.Hash().Hex())
 	}
@@ -153,6 +159,8 @@ func (f *Filter) expectsSymmetricEncryption() bool {
 	return f.KeySym != nil
 }
 
+// Trigger will assign the msg to Filter's Messages map if the
+// EnvelopeHash has not already been used to set a msg.
 func (f *Filter) Trigger(msg *ReceivedMessage) {
 	f.mutex.Lock()
 	defer f.mutex.Unlock()
@@ -162,6 +170,7 @@ func (f *Filter) Trigger(msg *ReceivedMessage) {
 	}
 }
 
+// Retrieve will return a slice of all messages the Filter stores.
 func (f *Filter) Retrieve() (all []*ReceivedMessage) {
 	f.mutex.Lock()
 	defer f.mutex.Unlock()
@@ -201,6 +210,7 @@ func (f *Filter) MatchEnvelope(envelope *Envelope) bool {
 	return false
 }
 
+// MatchTopic checks whether param topic exists in the f receiver.
 func (f *Filter) MatchTopic(topic TopicType) bool {
 	if len(f.Topics) == 0 {
 		// any topic matches
@@ -232,6 +242,8 @@ func matchSingleTopic(topic TopicType, bt []byte) bool {
 	return true
 }
 
+// IsPubKeyEqual checks the format of the given public keys a and b,
+// and compares where each sits on an elliptical curve.
 func IsPubKeyEqual(a, b *ecdsa.PublicKey) bool {
 	if !ValidatePublicKey(a) {
 		return false

whisper/whisperv5/filter_test.go

@@ -109,7 +109,7 @@ func TestInstallFilters(t *testing.T) {
 			t.Fatalf("seed %d: failed to install filter: %s", seed, err)
 		}
 		tst[i].id = j
-		if len(j) != keyIdSize*2 {
+		if len(j) != keyIDSize*2 {
 			t.Fatalf("seed %d: wrong filter id size [%d]", seed, len(j))
 		}
 	}

whisper/whisperv5/gen_criteria_json.go

@@ -10,6 +10,7 @@ import (
 
 var _ = (*criteriaOverride)(nil)
 
+// MarshalJSON implements the json.Marshaller interface.
 func (c Criteria) MarshalJSON() ([]byte, error) {
 	type Criteria struct {
 		SymKeyID     string        `json:"symKeyID"`
@@ -29,6 +30,7 @@ func (c Criteria) MarshalJSON() ([]byte, error) {
 	return json.Marshal(&enc)
 }
 
+// UnmarshalJSON implements json.Unmarshaler interface and maps input to C.
 func (c *Criteria) UnmarshalJSON(input []byte) error {
 	type Criteria struct {
 		SymKeyID     *string        `json:"symKeyID"`

whisper/whisperv5/gen_message_json.go

@@ -10,6 +10,7 @@ import (
 
 var _ = (*messageOverride)(nil)
 
+// MarshalJSON implements the json.Marshaller interface.
 func (m Message) MarshalJSON() ([]byte, error) {
 	type Message struct {
 		Sig       hexutil.Bytes `json:"sig,omitempty"`
@@ -35,6 +36,7 @@ func (m Message) MarshalJSON() ([]byte, error) {
 	return json.Marshal(&enc)
 }
 
+// UnmarshalJSON implements json.Unmarshaler interface and maps input to m.
 func (m *Message) UnmarshalJSON(input []byte) error {
 	type Message struct {
 		Sig       *hexutil.Bytes `json:"sig,omitempty"`

whisper/whisperv5/gen_newmessage_json.go

@@ -10,6 +10,7 @@ import (
 
 var _ = (*newMessageOverride)(nil)
 
+// MarshalJSON implements the json.Marshaller interface.
 func (n NewMessage) MarshalJSON() ([]byte, error) {
 	type NewMessage struct {
 		SymKeyID   string        `json:"symKeyID"`
@@ -37,6 +38,7 @@ func (n NewMessage) MarshalJSON() ([]byte, error) {
 	return json.Marshal(&enc)
 }
 
+// UnmarshalJSON implements json.Unmarshaler interface and maps input to n.
 func (n *NewMessage) UnmarshalJSON(input []byte) error {
 	type NewMessage struct {
 		SymKeyID   *string        `json:"symKeyID"`

whisper/whisperv5/peer.go

@@ -156,10 +156,9 @@ func (peer *Peer) broadcast() error {
 			err := p2p.Send(peer.ws, messagesCode, envelope)
 			if err != nil {
 				return err
-			} else {
-				peer.mark(envelope)
-				cnt++
 			}
+			peer.mark(envelope)
+			cnt++
 		}
 	}
 	if cnt > 0 {
@@ -168,6 +167,7 @@ func (peer *Peer) broadcast() error {
 	return nil
 }
 
+// ID returns the peers peer.ID in a byte slice.
 func (peer *Peer) ID() []byte {
 	id := peer.peer.ID()
 	return id[:]

whisper/whisperv5/peer_test.go

@@ -79,13 +79,13 @@ type TestNode struct {
 	shh     *Whisper
 	id      *ecdsa.PrivateKey
 	server  *p2p.Server
-	filerId string
+	filerID string
 }
 
 var result TestData
 var nodes [NumNodes]*TestNode
 var sharedKey = []byte("some arbitrary data here")
-var sharedTopic TopicType = TopicType{0xF, 0x1, 0x2, 0}
+var sharedTopic = TopicType{0xF, 0x1, 0x2, 0}
 var expectedMessage = []byte("per rectum ad astra")
 
 // This test does the following:
@@ -120,7 +120,7 @@ func initialize(t *testing.T) {
 		topics = append(topics, sharedTopic)
 		f := Filter{KeySym: sharedKey}
 		f.Topics = [][]byte{topics[0][:]}
-		node.filerId, err = node.shh.Subscribe(&f)
+		node.filerID, err = node.shh.Subscribe(&f)
 		if err != nil {
 			t.Fatalf("failed to install the filter: %s.", err)
 		}
@@ -133,9 +133,9 @@ func initialize(t *testing.T) {
 		name := common.MakeName("whisper-go", "2.0")
 		var peers []*discover.Node
 		if i > 0 {
-			peerNodeId := nodes[i-1].id
+			peerNodeID := nodes[i-1].id
 			peerPort := uint16(port - 1)
-			peerNode := discover.PubkeyID(&peerNodeId.PublicKey)
+			peerNode := discover.PubkeyID(&peerNodeID.PublicKey)
 			peer := discover.NewNode(peerNode, ip, peerPort, peerPort)
 			peers = append(peers, peer)
 		}
@@ -167,7 +167,7 @@ func stopServers() {
 	for i := 0; i < NumNodes; i++ {
 		n := nodes[i]
 		if n != nil {
-			n.shh.Unsubscribe(n.filerId)
+			n.shh.Unsubscribe(n.filerID)
 			n.shh.Stop()
 			n.server.Stop()
 		}
@@ -186,9 +186,9 @@ func checkPropagation(t *testing.T) {
 		time.Sleep(cycle * time.Millisecond)
 
 		for i := 0; i < NumNodes; i++ {
-			f := nodes[i].shh.GetFilter(nodes[i].filerId)
+			f := nodes[i].shh.GetFilter(nodes[i].filerID)
 			if f == nil {
-				t.Fatalf("failed to get filterId %s from node %d.", nodes[i].filerId, i)
+				t.Fatalf("failed to get filterId %s from node %d.", nodes[i].filerID, i)
 			}
 
 			mail := f.Retrieve()

whisper/whisperv5/topic.go

@@ -28,6 +28,7 @@ import (
 // SHA3 hash of some arbitrary data given by the original author of the message.
 type TopicType [TopicLength]byte
 
+// BytesToTopic will return passed parameters as a TopicType.
 func BytesToTopic(b []byte) (t TopicType) {
 	sz := TopicLength
 	if x := len(b); x < TopicLength {

whisper/whisperv5/whisper.go

@@ -37,6 +37,7 @@ import (
 	set "gopkg.in/fatih/set.v0"
 )
 
+// Statistics is used to store useful information regarding whisper node usage.
 type Statistics struct {
 	messagesCleared      int
 	memoryCleared        int
@@ -121,6 +122,7 @@ func New(cfg *Config) *Whisper {
 	return whisper
 }
 
+// MinPow returns the minimal PoW required by this node.
 func (w *Whisper) MinPow() float64 {
 	val, _ := w.settings.Load(minPowIdx)
 	return val.(float64)
@@ -842,7 +844,7 @@ func deriveKeyMaterial(key []byte, version uint64) (derivedKey []byte, err error
 
 // GenerateRandomID generates a random string, which is then returned to be used as a key id
 func GenerateRandomID() (id string, err error) {
-	buf := make([]byte, keyIdSize)
+	buf := make([]byte, keyIDSize)
 	_, err = crand.Read(buf)
 	if err != nil {
 		return "", err

whisper/whisperv6/peer.go

@@ -242,6 +242,8 @@ func (peer *Peer) setBloomFilter(bloom []byte) {
 	}
 }
 
+// MakeFullNodeBloom returns a bloom object with all entries
+// representing a single byte with the value of 255.
 func MakeFullNodeBloom() []byte {
 	bloom := make([]byte, BloomFilterSize)
 	for i := 0; i < BloomFilterSize; i++ {

whisper/whisperv6/whisper.go

@@ -1025,6 +1025,7 @@ func isFullNode(bloom []byte) bool {
 	return true
 }
 
+// BloomFilterMatch compares the values of filter and sample, returning a boolean.
 func BloomFilterMatch(filter, sample []byte) bool {
 	if filter == nil {
 		return true