From 87e00e508b83e9dcd414f2a7631ff4bf2490d8c3 Mon Sep 17 00:00:00 2001 From: Vlad Date: Tue, 28 Mar 2017 17:01:02 +0200 Subject: [PATCH] whisper: documenting the API functions --- cmd/wnode/main.go | 2 +- whisper/whisperv5/api.go | 34 +++++++++++++++---------------- whisper/whisperv5/envelope.go | 2 +- whisper/whisperv5/message.go | 2 +- whisper/whisperv5/peer_test.go | 2 +- whisper/whisperv5/whisper.go | 32 ++++++++++++++--------------- whisper/whisperv5/whisper_test.go | 6 +++--- 7 files changed, 40 insertions(+), 40 deletions(-) diff --git a/cmd/wnode/main.go b/cmd/wnode/main.go index 0d824f9ef8..edac824c75 100644 --- a/cmd/wnode/main.go +++ b/cmd/wnode/main.go @@ -358,7 +358,7 @@ func configureNode() { Topics: [][]byte{topic}, AllowP2P: p2pAccept, } - filterID, err = shh.Watch(&filter) + filterID, err = shh.Subscribe(&filter) if err != nil { utils.Fatalf("Failed to install filter: %s", err) } diff --git a/whisper/whisperv5/api.go b/whisper/whisperv5/api.go index e51d2ed1e4..10bbcda878 100644 --- a/whisper/whisperv5/api.go +++ b/whisper/whisperv5/api.go @@ -261,7 +261,7 @@ func (api *PublicWhisperAPI) Subscribe(args WhisperFilterArgs) (string, error) { } } - return api.whisper.Watch(&filter) + return api.whisper.Subscribe(&filter) } // Unsubscribe disables and removes an existing filter. @@ -380,25 +380,25 @@ func (api *PublicWhisperAPI) Post(args PostArgs) error { } type PostArgs struct { - Type string `json:"type"` - TTL uint32 `json:"ttl"` - SignWith string `json:"signWith"` - Key string `json:"key"` - Topic hexutil.Bytes `json:"topic"` - Padding hexutil.Bytes `json:"padding"` - Payload hexutil.Bytes `json:"payload"` - PowTime uint32 `json:"powTime"` - PowTarget float64 `json:"powTarget"` - TargetPeer string `json:"targetPeer"` + Type string `json:"type"` // "sym"/"asym" (symmetric or asymmetric) + TTL uint32 `json:"ttl"` // time-to-live in seconds + SignWith string `json:"signWith"` // id of the signing key + Key string `json:"key"` // id of encryption key + Topic hexutil.Bytes `json:"topic"` // topic (4 bytes) + Padding hexutil.Bytes `json:"padding"` // optional padding bytes + Payload hexutil.Bytes `json:"payload"` // payload to be encrypted + PowTime uint32 `json:"powTime"` // maximal time in seconds to be spent on PoW + PowTarget float64 `json:"powTarget"` // minimal PoW required for this message + TargetPeer string `json:"targetPeer"` // peer id (for p2p message only) } type WhisperFilterArgs struct { - Symmetric bool - Key string - SignedWith string - MinPoW float64 - Topics [][]byte - AllowP2P bool + Symmetric bool // encryption type + Key string // id of the key to be used for decryption + SignedWith string // public key of the sender to be verified + MinPoW float64 // minimal PoW requirement + Topics [][]byte // list of topics (up to 4 bytes each) to match + AllowP2P bool // indicates wheather direct p2p messages are allowed for this filter } // UnmarshalJSON implements the json.Unmarshaler interface, invoked to convert a diff --git a/whisper/whisperv5/envelope.go b/whisper/whisperv5/envelope.go index e61918fcb5..dffa7b2862 100644 --- a/whisper/whisperv5/envelope.go +++ b/whisper/whisperv5/envelope.go @@ -82,7 +82,7 @@ func (e *Envelope) isAsymmetric() bool { } func (e *Envelope) Ver() uint64 { - return bytesToIntLittleEndian(e.Version) + return bytesToUintLittleEndian(e.Version) } // Seal closes the envelope by spending the requested amount of time as a proof diff --git a/whisper/whisperv5/message.go b/whisper/whisperv5/message.go index 98443da131..e28146b86b 100644 --- a/whisper/whisperv5/message.go +++ b/whisper/whisperv5/message.go @@ -327,7 +327,7 @@ func (msg *ReceivedMessage) extractPadding(end int) (int, bool) { paddingSize := 0 sz := int(msg.Raw[0] & paddingMask) // number of bytes containing the entire size of padding, could be zero if sz != 0 { - paddingSize = int(bytesToIntLittleEndian(msg.Raw[1 : 1+sz])) + paddingSize = int(bytesToUintLittleEndian(msg.Raw[1 : 1+sz])) if paddingSize < sz || paddingSize+1 > end { return 0, false } diff --git a/whisper/whisperv5/peer_test.go b/whisper/whisperv5/peer_test.go index cd5153dfd5..a79b6ad144 100644 --- a/whisper/whisperv5/peer_test.go +++ b/whisper/whisperv5/peer_test.go @@ -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.Watch(&f) + node.filerId, err = node.shh.Subscribe(&f) if err != nil { t.Fatalf("failed to install the filter: %s.", err) } diff --git a/whisper/whisperv5/whisper.go b/whisper/whisperv5/whisper.go index 95474550d0..482f7a14b5 100644 --- a/whisper/whisperv5/whisper.go +++ b/whisper/whisperv5/whisper.go @@ -74,7 +74,6 @@ type Whisper struct { } // New creates a Whisper client ready to communicate through the Ethereum P2P network. -// Param s should be passed if you want to implement mail server, otherwise nil. func New() *Whisper { whisper := &Whisper{ privateKeys: make(map[string]*ecdsa.PrivateKey), @@ -147,6 +146,7 @@ func (w *Whisper) SetMinimumPoW(val float64) error { return nil } +// getPeer retrieves peer by ID func (w *Whisper) getPeer(peerID []byte) (*Peer, error) { w.peerMu.Lock() defer w.peerMu.Unlock() @@ -159,8 +159,8 @@ func (w *Whisper) getPeer(peerID []byte) (*Peer, error) { return nil, fmt.Errorf("Could not find peer with ID: %x", peerID) } -// MarkPeerTrusted marks specific peer trusted, which will allow it -// to send historic (expired) messages. +// AllowP2PMessagesFromPeer marks specific peer trusted, +// which will allow it to send historic (expired) messages. func (w *Whisper) AllowP2PMessagesFromPeer(peerID []byte) error { p, err := w.getPeer(peerID) if err != nil { @@ -198,7 +198,7 @@ func (w *Whisper) SendP2PDirect(peer *Peer, envelope *Envelope) error { return p2p.Send(peer.ws, p2pCode, envelope) } -// NewIdentity generates a new cryptographic identity for the client, and injects +// NewKeyPair generates a new cryptographic identity for the client, and injects // it into the known identities for message decryption. Returns ID of the new key pair. func (w *Whisper) NewKeyPair() (string, error) { key, err := crypto.GenerateKey() @@ -227,7 +227,7 @@ func (w *Whisper) NewKeyPair() (string, error) { return id, nil } -// DeleteIdentity deletes the specified key if it exists. +// DeleteKeyPair deletes the specified key if it exists. func (w *Whisper) DeleteKeyPair(key string) bool { w.keyMu.Lock() defer w.keyMu.Unlock() @@ -239,7 +239,7 @@ func (w *Whisper) DeleteKeyPair(key string) bool { return false } -// HasIdentity checks if the the whisper node is configured with the private key +// HasKeyPair checks if the the whisper node is configured with the private key // of the specified public pair. func (w *Whisper) HasKeyPair(id string) bool { w.keyMu.RLock() @@ -247,7 +247,7 @@ func (w *Whisper) HasKeyPair(id string) bool { return w.privateKeys[id] != nil } -// GetIdentity retrieves the private key of the specified identity. +// GetPrivateKey retrieves the private key of the specified identity. func (w *Whisper) GetPrivateKey(id string) (*ecdsa.PrivateKey, error) { w.keyMu.RLock() defer w.keyMu.RUnlock() @@ -370,9 +370,9 @@ func (w *Whisper) GetSymKey(id string) ([]byte, error) { return nil, fmt.Errorf("non-existent key ID") } -// Watch installs a new message handler used for filtering, decrypting +// Subscribe installs a new message handler used for filtering, decrypting // and subsequent storing of incoming messages. -func (w *Whisper) Watch(f *Filter) (string, error) { +func (w *Whisper) Subscribe(f *Filter) (string, error) { return w.filters.Install(f) } @@ -422,7 +422,7 @@ func (w *Whisper) Stop() error { return nil } -// handlePeer is called by the underlying P2P layer when the whisper sub-protocol +// HandlePeer is called by the underlying P2P layer when the whisper sub-protocol // connection is negotiated. func (wh *Whisper) HandlePeer(peer *p2p.Peer, rw p2p.MsgReadWriter) error { // Create the new peer and start tracking it @@ -696,7 +696,7 @@ func (w *Whisper) Stats() string { return result } -// envelopes retrieves all the messages currently pooled by the node. +// Envelopes retrieves all the messages currently pooled by the node. func (w *Whisper) Envelopes() []*Envelope { w.poolMu.RLock() defer w.poolMu.RUnlock() @@ -781,8 +781,8 @@ func containsOnlyZeros(data []byte) bool { return true } -// bytesToIntLittleEndian converts the slice to 64-bit unsigned integer. -func bytesToIntLittleEndian(b []byte) (res uint64) { +// bytesToUintLittleEndian converts the slice to 64-bit unsigned integer. +func bytesToUintLittleEndian(b []byte) (res uint64) { mul := uint64(1) for i := 0; i < len(b); i++ { res += uint64(b[i]) * mul @@ -791,8 +791,8 @@ func bytesToIntLittleEndian(b []byte) (res uint64) { return res } -// BytesToIntBigEndian converts the slice to 64-bit unsigned integer. -func BytesToIntBigEndian(b []byte) (res uint64) { +// BytesToUintBigEndian converts the slice to 64-bit unsigned integer. +func BytesToUintBigEndian(b []byte) (res uint64) { for i := 0; i < len(b); i++ { res *= 256 res += uint64(b[i]) @@ -800,7 +800,7 @@ func BytesToIntBigEndian(b []byte) (res uint64) { return res } -// DeriveSymmetricKey derives symmetric key material from the key or password. +// deriveKeyMaterial derives symmetric key material from the key or password. // pbkdf2 is used for security, in case people use password instead of randomly generated keys. func deriveKeyMaterial(key []byte, version uint64) (derivedKey []byte, err error) { if version == 0 { diff --git a/whisper/whisperv5/whisper_test.go b/whisper/whisperv5/whisper_test.go index ab072d7b43..d5668259e5 100644 --- a/whisper/whisperv5/whisper_test.go +++ b/whisper/whisperv5/whisper_test.go @@ -92,8 +92,8 @@ func TestWhisperBasic(t *testing.T) { } buf := []byte{0xFF, 0xE5, 0x80, 0x2, 0} - le := bytesToIntLittleEndian(buf) - be := BytesToIntBigEndian(buf) + le := bytesToUintLittleEndian(buf) + be := BytesToUintBigEndian(buf) if le != uint64(0x280e5ff) { t.Fatalf("failed bytesToIntLittleEndian: %d.", le) } @@ -565,7 +565,7 @@ func TestCustomization(t *testing.T) { } // check w.messages() - id, err := w.Watch(f) + id, err := w.Subscribe(f) time.Sleep(5 * time.Millisecond) mail := f.Retrieve() if len(mail) > 0 {