Documentation
¶
Overview ¶
Package discover implements the Node Discovery Protocol.
The Node 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 ¶
- Constants
- type Findnode
- type Neighbors
- type Node
- func (z *Node) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *Node) EncodeMsg(en *msgp.Writer) (err error)
- func (n *Node) Incomplete() bool
- func (z *Node) MarshalMsg(b []byte) (o []byte, err error)
- func (n *Node) MarshalText() ([]byte, error)
- func (z *Node) Msgsize() (s int)
- func (n *Node) String() string
- func (z *Node) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (n *Node) UnmarshalText(text []byte) error
- type NodeID
- func (n NodeID) Bytes() []byte
- func (z *NodeID) DecodeMsg(dc *msgp.Reader) (err error)
- func (z *NodeID) EncodeMsg(en *msgp.Writer) (err error)
- func (*NodeID) ExtensionType() int8
- func (n NodeID) GoString() string
- func (*NodeID) Len() int
- func (nid *NodeID) MarshalBinaryTo(b []byte) error
- func (z *NodeID) MarshalMsg(b []byte) (o []byte, err error)
- func (n NodeID) MarshalText() ([]byte, error)
- func (z *NodeID) Msgsize() (s int)
- func (id NodeID) Pubkey() (*ecdsa.PublicKey, error)
- func (n NodeID) String() string
- func (n NodeID) TerminalString() string
- func (nid *NodeID) UnmarshalBinary(b []byte) error
- func (z *NodeID) UnmarshalMsg(bts []byte) (o []byte, err error)
- func (n *NodeID) UnmarshalText(text []byte) error
- type Ping
- type Pong
- type RpcEndpoint
- type RpcNode
- type Table
Examples ¶
Constants ¶
const NodeIDBits = 512
const NodeIDBytes = NodeIDBits / 8
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) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Neighbors ¶
type Neighbors struct {
Nodes []RpcNode
Expiration uint64
// Ignore additional fields (for forward compatibility).
Rest []byte `msg:"-"`
}
reply to Findnode
func (*Neighbors) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
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
// This is a cached copy of sha3(ID) which is used for node
// distance calculations. This is part of Node in order to make it
// possible to write tests that need a node at a certain distance.
// In those tests, the content of sha will not actually correspond
// with ID.
Sha types.Hash `msg:",extension"`
// whether this node is currently being pinged in order to replace
// it in a bucket
Contested bool
}
Node represents a host on the network. The fields of Node may not be modified.
func MustParseNode ¶
MustParseNode parses a node URL. It panics if the URL is not valid.
func NewNode ¶
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 (*Node) Incomplete ¶
Incomplete returns true for nodes with no IP address.
func (*Node) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (*Node) MarshalText ¶
MarshalText implements encoding.TextMarshaler.
func (*Node) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (*Node) String ¶
The string representation of a Node is a URL. Please see ParseNode for a description of the format.
func (*Node) UnmarshalMsg ¶
UnmarshalMsg implements msgp.Unmarshaler
func (*Node) UnmarshalText ¶
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 MustBytesID ¶
MustBytesID converts a byte slice to a NodeID. It panics if the byte slice is not a valid NodeID.
func MustHexID ¶
MustHexID converts a hex string to a NodeID. It panics if the string is not a valid NodeID.
func (*NodeID) ExtensionType ¶
Here, we'll pick an arbitrary number between 0 and 127 that isn't already in use
func (*NodeID) MarshalBinaryTo ¶
MarshalBinaryTo simply copies the value of the bytes into 'b'
func (*NodeID) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
func (NodeID) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (*NodeID) Msgsize ¶
Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message
func (NodeID) Pubkey ¶
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) TerminalString ¶
TerminalString returns a shortened hex string for terminal logging.
func (*NodeID) UnmarshalBinary ¶
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 ¶
UnmarshalMsg implements msgp.Unmarshaler
func (*NodeID) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
type Ping ¶
type Ping struct {
Version uint
From RpcEndpoint
To RpcEndpoint
Expiration uint64
// Ignore additional fields (for forward compatibility).
Rest []byte `msg:"-"`
}
RPC request structures
func (*Ping) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
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.
// Ignore additional fields (for forward compatibility).
Rest []byte `msg:"-"`
}
Pong is the reply to Ping.
func (*Pong) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
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 `msg:",extension"`
}
RPC request structures
func (*RpcNode) MarshalMsg ¶
MarshalMsg implements msgp.Marshaler
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
func ListenUDP ¶
func ListenUDP(priv *ecdsa.PrivateKey, laddr string, natm nat.Interface, nodeDBPath string, netrestrict *netutil.Netlist) (*Table, error)
ListenUDP returns a new table that listens for UDP packets on laddr.
func (*Table) Close ¶
func (tab *Table) Close()
Close terminates the network listener and flushes the node database.
func (*Table) Lookup ¶
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.
func (*Table) ReadRandomNodes ¶
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 (*Table) Resolve ¶
Resolve searches for a specific node with the given ID. It returns nil if the node could not be found.
func (*Table) Self ¶
Self returns the local node. The returned node should not be modified by the caller.
func (*Table) SetFallbackNodes ¶
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.
Source Files