Documentation
¶
Index ¶
- Constants
- func BloomFilterMatch(filter, sample []byte) bool
- func MakeFullNodeBloom() []byte
- func TopicToBloom(topic TopicType) []byte
- type Criteria
- type EnodeID
- type Envelope
- type EnvelopeError
- type EnvelopeEvent
- type EventType
- type Filter
- type MailServerResponse
- type Message
- type MessagesRequest
- type NegotiatedSecret
- type NewMessage
- type PublicWhisperAPI
- type Subscription
- type SubscriptionOptions
- type SyncEventResponse
- type SyncMailRequest
- type TopicType
- type Whisper
Constants ¶
const ( // EnvelopeTimeNotSynced represents the code passed to notify of a clock skew situation EnvelopeTimeNotSynced uint = 1000 // EnvelopeOtherError represents the code passed to notify of a generic error situation EnvelopeOtherError )
const ( // TopicLength is the expected length of the topic, in bytes TopicLength = 4 // BloomFilterSize is the expected length of a bloom filter byte array, in bytes BloomFilterSize = 64 )
const ( // PubKeyLength represents the length (in bytes) of an uncompressed public key PubKeyLength = 512 / 8 // AesKeyLength represents the length (in bytes) of an private key AesKeyLength = 256 / 8 )
const ( // MaxLimitInMessagesRequest represents the maximum number of messages // that can be requested from the mailserver MaxLimitInMessagesRequest = 1000 )
Variables ¶
This section is empty.
Functions ¶
func BloomFilterMatch ¶
BloomFilterMatch returns true if a sample matches a bloom filter
func MakeFullNodeBloom ¶
func MakeFullNodeBloom() []byte
MakeFullNodeBloom returns a bloom filter which matches all topics
func TopicToBloom ¶
TopicToBloom converts the topic (4 bytes) to the bloom filter (64 bytes)
Types ¶
type Criteria ¶
type Criteria struct { SymKeyID string `json:"symKeyID"` PrivateKeyID string `json:"privateKeyID"` Sig []byte `json:"sig"` MinPow float64 `json:"minPow"` Topics []TopicType `json:"topics"` AllowP2P bool `json:"allowP2P"` }
Criteria holds various filter options for inbound messages.
type Envelope ¶
type Envelope interface { Hash() protocol.Hash // Cached hash of the envelope to avoid rehashing every time. Bloom() []byte }
Envelope represents a clear-text data packet to transmit through the Whisper network. Its contents may or may not be encrypted and signed.
type EnvelopeError ¶
EnvelopeError code and optional description of the error.
type EnvelopeEvent ¶
type EnvelopeEvent struct { Event EventType Hash protocol.Hash Batch protocol.Hash Peer EnodeID Data interface{} }
EnvelopeEvent used for envelopes events.
type EventType ¶
type EventType string
EventType used to define known envelope events.
const ( // EventEnvelopeSent fires when envelope was sent to a peer. EventEnvelopeSent EventType = "envelope.sent" // EventEnvelopeExpired fires when envelop expired EventEnvelopeExpired EventType = "envelope.expired" // EventEnvelopeReceived is sent once envelope was received from a peer. // EventEnvelopeReceived must be sent to the feed even if envelope was previously in the cache. // And event, ideally, should contain information about peer that sent envelope to us. EventEnvelopeReceived EventType = "envelope.received" // EventBatchAcknowledged is sent when batch of envelopes was acknowleged by a peer. EventBatchAcknowledged EventType = "batch.acknowleged" // EventEnvelopeAvailable fires when envelop is available for filters EventEnvelopeAvailable EventType = "envelope.available" // EventMailServerRequestSent fires when such request is sent. EventMailServerRequestSent EventType = "mailserver.request.sent" // EventMailServerRequestCompleted fires after mailserver sends all the requested messages EventMailServerRequestCompleted EventType = "mailserver.request.completed" // EventMailServerRequestExpired fires after mailserver the request TTL ends. // This event is independent and concurrent to EventMailServerRequestCompleted. // Request should be considered as expired only if expiry event was received first. EventMailServerRequestExpired EventType = "mailserver.request.expired" // EventMailServerEnvelopeArchived fires after an envelope has been archived EventMailServerEnvelopeArchived EventType = "mailserver.envelope.archived" // EventMailServerSyncFinished fires when the sync of messages is finished. EventMailServerSyncFinished EventType = "mailserver.sync.finished" )
NOTE: This list of event names is extracted from Geth. It must be kept in sync, or otherwise a mapping layer needs to be created
type MailServerResponse ¶
MailServerResponse is the response payload sent by the mailserver.
type Message ¶
type Message struct { Sig []byte `json:"sig,omitempty"` TTL uint32 `json:"ttl"` Timestamp uint32 `json:"timestamp"` Topic TopicType `json:"topic"` Payload []byte `json:"payload"` Padding []byte `json:"padding"` PoW float64 `json:"pow"` Hash []byte `json:"hash"` Dst []byte `json:"recipientPublicKey,omitempty"` P2P bool `json:"bool,omitempty"` }
Message is the RPC representation of a whisper message.
func (Message) MarshalJSON ¶
MarshalJSON marshals type Message to a json string
func (*Message) UnmarshalJSON ¶
UnmarshalJSON unmarshals type Message to a json string
type MessagesRequest ¶
type MessagesRequest struct { // ID of the request. The current implementation requires ID to be 32-byte array, // however, it's not enforced for future implementation. ID []byte `json:"id"` // From is a lower bound of time range. From uint32 `json:"from"` // To is a upper bound of time range. To uint32 `json:"to"` // Limit determines the number of messages sent by the mail server // for the current paginated request. Limit uint32 `json:"limit"` // Cursor is used as starting point for paginated requests. Cursor []byte `json:"cursor"` // Bloom is a filter to match requested messages. Bloom []byte `json:"bloom"` }
MessagesRequest contains details of a request of historic messages.
func (*MessagesRequest) SetDefaults ¶
func (r *MessagesRequest) SetDefaults(now time.Time)
SetDefaults sets the From and To defaults
type NegotiatedSecret ¶
NegotiatedSecret represents a negotiated secret (both public and private keys)
type NewMessage ¶
type NewMessage struct { SymKeyID string `json:"symKeyID"` PublicKey []byte `json:"pubKey"` SigID string `json:"sig"` TTL uint32 `json:"ttl"` Topic TopicType `json:"topic"` Payload []byte `json:"payload"` Padding []byte `json:"padding"` PowTime uint32 `json:"powTime"` PowTarget float64 `json:"powTarget"` TargetPeer string `json:"targetPeer"` }
NewMessage represents a new whisper message that is posted through the RPC.
type PublicWhisperAPI ¶
type PublicWhisperAPI interface { // AddPrivateKey imports the given private key. AddPrivateKey(ctx context.Context, privateKey protocol.HexBytes) (string, error) // GenerateSymKeyFromPassword derives a key from the given password, stores it, and returns its ID. GenerateSymKeyFromPassword(ctx context.Context, passwd string) (string, error) // DeleteKeyPair removes the key with the given key if it exists. DeleteKeyPair(ctx context.Context, key string) (bool, error) // Post posts a message on the Whisper network. // returns the hash of the message in case of success. Post(ctx context.Context, req NewMessage) ([]byte, error) // NewMessageFilter creates a new filter that can be used to poll for // (new) messages that satisfy the given criteria. NewMessageFilter(req Criteria) (string, error) // GetFilterMessages returns the messages that match the filter criteria and // are received between the last poll and now. GetFilterMessages(id string) ([]*Message, error) }
PublicWhisperAPI provides the whisper RPC service that can be use publicly without security implications.
type Subscription ¶
type Subscription interface { Err() <-chan error // returns the error channel Unsubscribe() // cancels sending of events, closing the error channel }
Subscription represents a stream of events. The carrier of the events is typically a channel, but isn't part of the interface.
Subscriptions can fail while established. Failures are reported through an error channel. It receives a value if there is an issue with the subscription (e.g. the network connection delivering the events has been closed). Only one value will ever be sent.
The error channel is closed when the subscription ends successfully (i.e. when the source of events is closed). It is also closed when Unsubscribe is called.
The Unsubscribe method cancels the sending of events. You must call Unsubscribe in all cases to ensure that resources related to the subscription are released. It can be called any number of times.
type SubscriptionOptions ¶
SubscriptionOptions represents the parameters passed to Whisper.Subscribe to customize the subscription behavior
type SyncEventResponse ¶
SyncEventResponse is a response from the Mail Server form which the peer received envelopes.
type SyncMailRequest ¶
type SyncMailRequest struct { // Lower is a lower bound of time range for which messages are requested. Lower uint32 // Upper is a lower bound of time range for which messages are requested. Upper uint32 // Bloom is a bloom filter to filter envelopes. Bloom []byte // Limit is the max number of envelopes to return. Limit uint32 // Cursor is used for pagination of the results. Cursor []byte }
SyncMailRequest contains details which envelopes should be synced between Mail Servers.
type TopicType ¶
type TopicType [TopicLength]byte
TopicType represents a cryptographically secure, probabilistic partial classifications of a message, determined as the first (left) 4 bytes of the SHA3 hash of some arbitrary data given by the original author of the message.
func BytesToTopic ¶
BytesToTopic converts from the byte array representation of a topic into the TopicType type.
func (TopicType) MarshalText ¶
MarshalText returns the hex representation of t.
func (*TopicType) UnmarshalText ¶
UnmarshalText parses a hex representation to a topic.
type Whisper ¶
type Whisper interface { PublicWhisperAPI() PublicWhisperAPI // Poll must be run periodically on the main thread by the host application Poll() // MinPow returns the PoW value required by this node. MinPow() float64 // BloomFilter returns the aggregated bloom filter for all the topics of interest. // The nodes are required to send only messages that match the advertised bloom filter. // If a message does not match the bloom, it will tantamount to spam, and the peer will // be disconnected. BloomFilter() []byte // SetTimeSource assigns a particular source of time to a whisper object. SetTimeSource(timesource func() time.Time) // GetCurrentTime returns current time. GetCurrentTime() time.Time // SelectedKeyPairID returns the id of currently selected key pair. // It helps distinguish between different users w/o exposing the user identity itself. SelectedKeyPairID() string // GetPrivateKey retrieves the private key of the specified identity. GetPrivateKey(id string) (*ecdsa.PrivateKey, error) SubscribeEnvelopeEvents(events chan<- EnvelopeEvent) Subscription // AddKeyPair imports a asymmetric private key and returns a deterministic identifier. AddKeyPair(key *ecdsa.PrivateKey) (string, error) // DeleteKeyPair deletes the specified key if it exists. DeleteKeyPair(key string) bool // SelectKeyPair adds cryptographic identity, and makes sure // that it is the only private key known to the node. SelectKeyPair(key *ecdsa.PrivateKey) error AddSymKeyDirect(key []byte) (string, error) AddSymKeyFromPassword(password string) (string, error) DeleteSymKey(id string) bool GetSymKey(id string) ([]byte, error) Subscribe(opts *SubscriptionOptions) (string, error) GetFilter(id string) Filter Unsubscribe(id string) error // RequestHistoricMessages sends a message with p2pRequestCode to a specific peer, // which is known to implement MailServer interface, and is supposed to process this // request and respond with a number of peer-to-peer messages (possibly expired), // which are not supposed to be forwarded any further. // The whisper protocol is agnostic of the format and contents of envelope. // A timeout of 0 never expires. RequestHistoricMessagesWithTimeout(peerID []byte, envelope Envelope, timeout time.Duration) error // SendMessagesRequest sends a MessagesRequest. This is an equivalent to RequestHistoricMessages // in terms of the functionality. SendMessagesRequest(peerID []byte, request MessagesRequest) error // SyncMessages can be sent between two Mail Servers and syncs envelopes between them. SyncMessages(peerID []byte, req SyncMailRequest) error }
Whisper represents a dark communication interface through the Ethereum network, using its very own P2P communication layer.