discv5

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2019 License: GPL-3.0 Imports: 35 Imported by: 0

Documentation

Overview

Package discv5 implements the Msgpx v5 Topic Discovery Protocol.

The Topic Discovery protocol provides a way to find Msgpx nodes that can be connected to. It uses a Kademlia-like protocol to maintain a distributed database of the IDs and endpoints of all listening nodes.

Index

Examples

Constants

View Source 
const NodeIDBits = 512
View Source 
const NodeIDBytes = NodeIDBits / 8
View Source 
const Version = 4

Variables

This section is empty.

Functions

This section is empty.

Types

type Findnode 

type Findnode struct {
	Target     NodeID `msg:",extension"` // doesn't need to be an actual public key
	Expiration uint64
	// Ignore additional fields (for forward compatibility).
	Rest []byte `msg:"-"`
}

Findnode is a query for nodes close to the given target.

func (*Findnode) DecodeMsg 

func (z *Findnode) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*Findnode) EncodeMsg 

func (z *Findnode) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Findnode) MarshalMsg 

func (z *Findnode) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Findnode) Msgsize 

func (z *Findnode) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Findnode) UnmarshalMsg 

func (z *Findnode) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type FindnodeHash 

type FindnodeHash struct {
	Target     types.Hash `msg:",extension"`
	Expiration uint64
	// Ignore additional fields (for forward compatibility).
	Rest []byte `msg:"-"`
}

FindnodeHash is a query for nodes close to the given target.

func (*FindnodeHash) DecodeMsg 

func (z *FindnodeHash) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*FindnodeHash) EncodeMsg 

func (z *FindnodeHash) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*FindnodeHash) MarshalMsg 

func (z *FindnodeHash) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*FindnodeHash) Msgsize 

func (z *FindnodeHash) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*FindnodeHash) UnmarshalMsg 

func (z *FindnodeHash) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type Neighbors 

type Neighbors struct {
	Nodes      []RpcNode
	Expiration uint64
	// Ignore additional fields (for forward compatibility).
	Rest []byte `msg:"-"`
}

reply to Findnode

func (*Neighbors) DecodeMsg 

func (z *Neighbors) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*Neighbors) EncodeMsg 

func (z *Neighbors) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Neighbors) MarshalMsg 

func (z *Neighbors) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Neighbors) Msgsize 

func (z *Neighbors) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Neighbors) UnmarshalMsg 

func (z *Neighbors) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type Network 

type Network struct {
	// contains filtered or unexported fields
}

Network manages the table and all protocol interaction.

func ListenUDP 

func ListenUDP(priv *ecdsa.PrivateKey, laddr string, natm nat.Interface, nodeDBPath string, netrestrict *netutil.Netlist) (*Network, error)

ListenUDP returns a new table that listens for UDP packets on laddr.

func (*Network) Close 

func (net *Network) Close()

Close terminates the network listener and flushes the node database.

func (*Network) Lookup 

func (net *Network) Lookup(targetID NodeID) []*Node

Lookup performs a network search for nodes close to the given target. It approaches the target by querying nodes that are closer to it on each iteration. The given target does not need to be an actual node identifier.

The local node may be included in the result.

func (*Network) ReadRandomNodes 

func (net *Network) ReadRandomNodes(buf []*Node) (n int)

ReadRandomNodes fills the given slice with random nodes from the table. It will not write the same node more than once. The nodes in the slice are copies and can be modified by the caller.

func (*Network) RegisterTopic 

func (net *Network) RegisterTopic(topic Topic, stop <-chan struct{})

func (*Network) Resolve 

func (net *Network) Resolve(targetID NodeID) *Node

Resolve searches for a specific node with the given ID. It returns nil if the node could not be found.

func (*Network) SearchTopic 

func (net *Network) SearchTopic(topic Topic, setPeriod <-chan time.Duration, found chan<- *Node, lookup chan<- bool)

func (*Network) Self 

func (net *Network) Self() *Node

Self returns the local node. The returned node should not be modified by the caller.

func (*Network) SetFallbackNodes 

func (net *Network) SetFallbackNodes(nodes []*Node) error

SetFallbackNodes sets the initial points of contact. These nodes are used to connect to the network if the table is empty and there are no known nodes in the database.

type Node 

type Node struct {
	IP       types.IP `msg:",extension"` // len 4 for IPv4 or 16 for IPv6
	UDP, TCP uint16   // port numbers
	ID       NodeID   `msg:",extension"` // the node's public key
	// contains filtered or unexported fields
}

Node represents a host on the network. The public fields of Node may not be modified.

func MustParseNode 

func MustParseNode(rawurl string) *Node

MustParseNode parses a node URL. It panics if the URL is not valid.

func NewNode 

func NewNode(id NodeID, ip net.IP, udpPort, tcpPort uint16) *Node

NewNode creates a new node. It is mostly meant to be used for testing purposes.

Example 
id := MustHexID("1dd9d65c4552b5eb43d5ad55a2ee3f56c6cbc1c64a5c8d659f51fcd51bace24351232b8d7821617d2b29b54b81cdefb9b3e9c37d7fd5f63270bcc9e1a6f6a439")

// Complete nodes contain UDP and TCP endpoints:
n1 := NewNode(id, net.ParseIP("2001:db8:3c4d:15::abcd:ef12"), 52150, 30303)
fmt.Println("n1:", n1)
fmt.Println("n1.Incomplete() ->", n1.Incomplete())

// An incomplete node can be created by passing zero values
// for all parameters except id.
n2 := NewNode(id, nil, 0, 0)
fmt.Println("n2:", n2)
fmt.Println("n2.Incomplete() ->", n2.Incomplete())

Output:

n1: bnode://1dd9d65c4552b5eb43d5ad55a2ee3f56c6cbc1c64a5c8d659f51fcd51bace24351232b8d7821617d2b29b54b81cdefb9b3e9c37d7fd5f63270bcc9e1a6f6a439@[2001:db8:3c4d:15::abcd:ef12]:30303?discport=52150
n1.Incomplete() -> false
n2: bnode://1dd9d65c4552b5eb43d5ad55a2ee3f56c6cbc1c64a5c8d659f51fcd51bace24351232b8d7821617d2b29b54b81cdefb9b3e9c37d7fd5f63270bcc9e1a6f6a439
n2.Incomplete() -> true

func ParseNode 

func ParseNode(rawurl string) (*Node, error)

ParseNode parses a node designator.

There are two basic forms of node designators

  • incomplete nodes, which only have the public key (node ID)
  • complete nodes, which contain the public key and IP/Port information

For incomplete nodes, the designator must look like one of these 

bnode://<hex node id>
<hex node id>

For complete nodes, the node ID is encoded in the username portion of the URL, separated from the host by an @ sign. The hostname can only be given as an IP address, DNS domain names are not allowed. The port in the host name section is the TCP listening port. If the TCP and UDP (discovery) ports differ, the UDP port is specified as query parameter "discport".

In the following example, the node URL describes a node with IP address 10.3.58.6, TCP listening port 30303 and UDP discovery port 30301. 

bnode://<hex node id>@10.3.58.6:30303?discport=30301

func (*Node) DecodeMsg 

func (z *Node) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*Node) EncodeMsg 

func (z *Node) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Node) Incomplete 

func (n *Node) Incomplete() bool

Incomplete returns true for nodes with no IP address.

func (*Node) MarshalMsg 

func (z *Node) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Node) MarshalText 

func (n *Node) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Node) Msgsize 

func (z *Node) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Node) String 

func (n *Node) String() string

The string representation of a Node is a URL. Please see ParseNode for a description of the format.

func (*Node) UnmarshalMsg 

func (z *Node) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (*Node) UnmarshalText 

func (n *Node) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type NodeID 

type NodeID [NodeIDBytes]byte

NodeID is a unique identifier for each node. The node identifier is a marshaled elliptic curve public key.

func HexID 

func HexID(in string) (NodeID, error)

HexID converts a hex string to a NodeID. The string may be prefixed with 0x.

func MustHexID 

func MustHexID(in string) NodeID

MustHexID converts a hex string to a NodeID. It panics if the string is not a valid NodeID.

func PubkeyID 

func PubkeyID(pub *ecdsa.PublicKey) NodeID

PubkeyID returns a marshaled representation of the given public key.

func (NodeID) Bytes 

func (n NodeID) Bytes() []byte

Bytes returns a byte slice representation of the NodeID

func (*NodeID) DecodeMsg 

func (z *NodeID) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*NodeID) EncodeMsg 

func (z *NodeID) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*NodeID) ExtensionType 

func (*NodeID) ExtensionType() int8

Here, we'll pick an arbitrary number between 0 and 127 that isn't already in use

func (NodeID) GoString 

func (n NodeID) GoString() string

The Go syntax representation of a NodeID is a call to HexID.

func (*NodeID) Len 

func (*NodeID) Len() int

We'll always use 32 bytes to encode the data

func (*NodeID) MarshalBinaryTo 

func (nid *NodeID) MarshalBinaryTo(b []byte) error

MarshalBinaryTo simply copies the value of the bytes into 'b'

func (*NodeID) MarshalMsg 

func (z *NodeID) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*NodeID) Msgsize 

func (z *NodeID) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (NodeID) Pubkey 

func (id NodeID) Pubkey() (*ecdsa.PublicKey, error)

Pubkey returns the public key represented by the node ID. It returns an error if the ID is not a point on the curve.

func (NodeID) String 

func (n NodeID) String() string

NodeID prints as a long hexadecimal number.

func (NodeID) TerminalString 

func (n NodeID) TerminalString() string

TerminalString returns a shortened hex string for terminal logging.

func (*NodeID) UnmarshalBinary 

func (nid *NodeID) UnmarshalBinary(b []byte) error

UnmarshalBinary copies the value of 'b' into the Hash object. (We might want to add a sanity check here later that len(b) <= HashLength.)

func (*NodeID) UnmarshalMsg 

func (z *NodeID) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type Ping 

type Ping struct {
	Version    uint
	From, To   RpcEndpoint
	Expiration uint64

	// v5
	Topics []Topic

	// Ignore additional fields (for forward compatibility).
	Rest []byte `msg:"-"`
}

RPC request structures

func (*Ping) DecodeMsg 

func (z *Ping) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*Ping) EncodeMsg 

func (z *Ping) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Ping) MarshalMsg 

func (z *Ping) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Ping) Msgsize 

func (z *Ping) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Ping) UnmarshalMsg 

func (z *Ping) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type Pong 

type Pong struct {
	// This field should mirror the UDP envelope address
	// of the Ping packet, which provides a way to discover the
	// the external address (after NAT).
	To RpcEndpoint

	ReplyTok   []byte // This contains the hash of the Ping packet.
	Expiration uint64 // Absolute timestamp at which the packet becomes invalid.

	// v5
	TopicHash    types.Hash `msg:",extension"`
	TicketSerial uint32
	WaitPeriods  []uint32

	// Ignore additional fields (for forward compatibility).
	Rest []byte `msg:"-"`
}

pong is the reply to Ping.

func (*Pong) DecodeMsg 

func (z *Pong) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*Pong) EncodeMsg 

func (z *Pong) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Pong) MarshalMsg 

func (z *Pong) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Pong) Msgsize 

func (z *Pong) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Pong) UnmarshalMsg 

func (z *Pong) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type RpcEndpoint 

type RpcEndpoint struct {
	IP  types.IP `msg:",extension"` // len 4 for IPv4 or 16 for IPv6
	UDP uint16   // for discovery protocol
	TCP uint16   // for Msgpx protocol
}

RPC request structures

func (*RpcEndpoint) DecodeMsg 

func (z *RpcEndpoint) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*RpcEndpoint) EncodeMsg 

func (z *RpcEndpoint) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*RpcEndpoint) MarshalMsg 

func (z *RpcEndpoint) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*RpcEndpoint) Msgsize 

func (z *RpcEndpoint) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*RpcEndpoint) UnmarshalMsg 

func (z *RpcEndpoint) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type RpcNode 

type RpcNode struct {
	IP  types.IP `msg:",extension"` // len 4 for IPv4 or 16 for IPv6
	UDP uint16   // for discovery protocol
	TCP uint16   // for Msgpx protocol
	ID  NodeID
}

RPC request structures

func (*RpcNode) DecodeMsg 

func (z *RpcNode) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*RpcNode) EncodeMsg 

func (z *RpcNode) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*RpcNode) MarshalMsg 

func (z *RpcNode) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*RpcNode) Msgsize 

func (z *RpcNode) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*RpcNode) UnmarshalMsg 

func (z *RpcNode) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type Table 

type Table struct {
	// contains filtered or unexported fields
}

type Topic 

type Topic string

func (*Topic) DecodeMsg 

func (z *Topic) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (Topic) EncodeMsg 

func (z Topic) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (Topic) MarshalMsg 

func (z Topic) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (Topic) Msgsize 

func (z Topic) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Topic) UnmarshalMsg 

func (z *Topic) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type TopicNodes 

type TopicNodes struct {
	Echo  types.Hash `msg:",extension"`
	Nodes []RpcNode
}

reply to TopicQuery

func (*TopicNodes) DecodeMsg 

func (z *TopicNodes) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*TopicNodes) EncodeMsg 

func (z *TopicNodes) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*TopicNodes) MarshalMsg 

func (z *TopicNodes) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*TopicNodes) Msgsize 

func (z *TopicNodes) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*TopicNodes) UnmarshalMsg 

func (z *TopicNodes) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type TopicQuery 

type TopicQuery struct {
	Topic      Topic
	Expiration uint64
}

RPC request structures

func (*TopicQuery) DecodeMsg 

func (z *TopicQuery) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*TopicQuery) EncodeMsg 

func (z *TopicQuery) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*TopicQuery) MarshalMsg 

func (z *TopicQuery) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*TopicQuery) Msgsize 

func (z *TopicQuery) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*TopicQuery) UnmarshalMsg 

func (z *TopicQuery) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type TopicRegister 

type TopicRegister struct {
	Topics []Topic
	Idx    uint
	Pong   []byte
}

RPC request structures

func (*TopicRegister) DecodeMsg 

func (z *TopicRegister) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*TopicRegister) EncodeMsg 

func (z *TopicRegister) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*TopicRegister) MarshalMsg 

func (z *TopicRegister) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*TopicRegister) Msgsize 

func (z *TopicRegister) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*TopicRegister) UnmarshalMsg 

func (z *TopicRegister) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.