peer

Documentation

Overview

Package peer implements an object used to represent peers in the libp2p network.

This file contains Protobuf and JSON serialization/deserialization methods for peer IDs.

Index

• Variables
• func AddrInfoToP2pAddrs(pi *AddrInfo) ([]ma.Multiaddr, error)
• func Encode(id ID) string
• func IDB58Encode(id ID) string
• func IDHexEncode(id ID) string
• func ToCid(id ID) cid.Cid
• type AddrInfo
  • func AddrInfoFromP2pAddr(m ma.Multiaddr) (*AddrInfo, error)
  • func AddrInfosFromP2pAddrs(maddrs ...ma.Multiaddr) ([]AddrInfo, error)
  • func (pi *AddrInfo) Loggable() map[string]interface{}
  • func (pi AddrInfo) MarshalJSON() ([]byte, error)
  • func (pi AddrInfo) String() string
  • func (pi *AddrInfo) UnmarshalJSON(b []byte) error
• type ID
  • func Decode(s string) (ID, error)
  • func FromCid(c cid.Cid) (ID, error)
  • func IDB58Decode(s string) (ID, error)
  • func IDFromBytes(b []byte) (ID, error)
  • func IDFromPrivateKey(sk ic.PrivKey) (ID, error)
  • func IDFromPublicKey(pk ic.PubKey) (ID, error)
  • func IDFromString(s string) (ID, error)
  • func IDHexDecode(s string) (ID, error)
  • func SplitAddr(m ma.Multiaddr) (transport ma.Multiaddr, id ID)
  • func (id ID) ExtractPublicKey() (ic.PubKey, error)
  • func (id ID) Loggable() map[string]interface{}
  • func (id ID) Marshal() ([]byte, error)
  • func (id ID) MarshalBinary() ([]byte, error)
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id ID) MarshalText() ([]byte, error)
  • func (id ID) MarshalTo(data []byte) (n int, err error)
  • func (id ID) MatchesPrivateKey(sk ic.PrivKey) bool
  • func (id ID) MatchesPublicKey(pk ic.PubKey) bool
  • func (id ID) Pretty() string
  • func (id ID) ShortString() string
  • func (id ID) Size() int
  • func (id ID) String() string
  • func (id *ID) Unmarshal(data []byte) (err error)
  • func (id *ID) UnmarshalBinary(data []byte) error
  • func (id *ID) UnmarshalJSON(data []byte) (err error)
  • func (id *ID) UnmarshalText(data []byte) error
  • func (id ID) Validate() error
• type IDSlice
  • func (es IDSlice) Len() int
  • func (es IDSlice) Less(i, j int) bool
  • func (es IDSlice) Swap(i, j int)
• type Set
  • func NewLimitedSet(size int) *Set
  • func NewSet() *Set
  • func (ps *Set) Add(p ID)
  • func (ps *Set) Contains(p ID) bool
  • func (ps *Set) Peers() []ID
  • func (ps *Set) Size() int
  • func (ps *Set) TryAdd(p ID) bool

Variables

var (
	// ErrEmptyPeerID is an error for empty peer ID.
	ErrEmptyPeerID = errors.New("empty peer ID")
	// ErrNoPublicKey is an error for peer IDs that don't embed public keys
	ErrNoPublicKey = errors.New("public key is not embedded in peer ID")
)

var AdvancedEnableInlining = true

AdvancedEnableInlining enables automatically inlining keys shorter than 42 bytes into the peer ID (using the "identity" multihash function).

WARNING: This flag will likely be set to false in the future and eventually be removed in favor of using a hash function specified by the key itself. See: https://github.com/libp2p/specs/issues/138

DO NOT change this flag unless you know what you're doing.

This currently defaults to true for backwards compatibility but will likely be set to false by default when an upgrade path is determined.

var ErrInvalidAddr = fmt.Errorf("invalid p2p multiaddr")

Functions

func AddrInfoToP2pAddrs

func AddrInfoToP2pAddrs(pi *AddrInfo) ([]ma.Multiaddr, error)

AddrInfoToP2pAddr converts an AddrInfo to a list of Multiaddrs.

func Encode

func Encode(id ID) string

Encode encodes a peer ID as a string.

At the moment, it base58 encodes the peer ID but, in the future, it will switch to encoding it as a CID by default.

func IDB58Encode

func IDB58Encode(id ID) string

IDB58Encode returns the base58-encoded multihash representation of the ID.

Deprecated: Use Encode.

func IDHexEncode

func IDHexEncode(id ID) string

IDHexEncode returns the hex-encoded multihash representation of the ID.

Deprecated: Don't raw-hex encode peer IDs, use base16 CIDs.

func ToCid

func ToCid(id ID) cid.Cid

ToCid encodes a peer ID as a CID of the public key.

If the peer ID is invalid (e.g., empty), this will return the empty CID.

Types

type AddrInfo

type AddrInfo struct {
	ID    ID
	Addrs []ma.Multiaddr
}

AddrInfo is a small struct used to pass around a peer with a set of addresses (and later, keys?).

func AddrInfoFromP2pAddr

func AddrInfoFromP2pAddr(m ma.Multiaddr) (*AddrInfo, error)

AddrInfoFromP2pAddr converts a Multiaddr to an AddrInfo.

func AddrInfosFromP2pAddrs

func AddrInfosFromP2pAddrs(maddrs ...ma.Multiaddr) ([]AddrInfo, error)

AddrInfosFromP2pAddrs converts a set of Multiaddrs to a set of AddrInfos.

func (*AddrInfo) Loggable

func (pi *AddrInfo) Loggable() map[string]interface{}

func (AddrInfo) MarshalJSON

func (pi AddrInfo) MarshalJSON() ([]byte, error)

func (AddrInfo) String

func (pi AddrInfo) String() string

func (*AddrInfo) UnmarshalJSON

func (pi *AddrInfo) UnmarshalJSON(b []byte) error

type ID

type ID string

ID is a libp2p peer identity.

Peer IDs are derived by hashing a peer's public key and encoding the hash output as a multihash. See IDFromPublicKey for details.

func Decode

func Decode(s string) (ID, error)

Decode accepts an encoded peer ID and returns the decoded ID if the input is valid.

The encoded peer ID can either be a CID of a key or a raw multihash (identity or sha256-256).

func FromCid

func FromCid(c cid.Cid) (ID, error)

FromCid converts a CID to a peer ID, if possible.

func IDB58Decode

func IDB58Decode(s string) (ID, error)

IDB58Decode decodes a peer ID.

Deprecated: Use Decode.

func IDFromBytes

func IDFromBytes(b []byte) (ID, error)

IDFromBytes casts a byte slice to the ID type, and validates the value to make sure it is a multihash.

func IDFromPrivateKey

func IDFromPrivateKey(sk ic.PrivKey) (ID, error)

IDFromPrivateKey returns the Peer ID corresponding to the secret key sk.

func IDFromPublicKey

func IDFromPublicKey(pk ic.PubKey) (ID, error)

IDFromPublicKey returns the Peer ID corresponding to the public key pk.

func IDFromString

func IDFromString(s string) (ID, error)

IDFromString casts a string to the ID type, and validates the value to make sure it is a multihash.

func IDHexDecode

func IDHexDecode(s string) (ID, error)

IDHexDecode accepts a hex-encoded multihash representing a peer ID and returns the decoded ID if the input is valid.

Deprecated: Don't raw-hex encode peer IDs, use base16 CIDs.

func SplitAddr

func SplitAddr(m ma.Multiaddr) (transport ma.Multiaddr, id ID)

SplitAddr splits a p2p Multiaddr into a transport multiaddr and a peer ID.

* Returns a nil transport if the address only contains a /p2p part. * Returns a empty peer ID if the address doesn't contain a /p2p part.

func (ID) ExtractPublicKey

func (id ID) ExtractPublicKey() (ic.PubKey, error)

ExtractPublicKey attempts to extract the public key from an ID

This method returns ErrNoPublicKey if the peer ID looks valid but it can't extract the public key.

func (ID) Loggable

func (id ID) Loggable() map[string]interface{}

Loggable returns a pretty peer ID string in loggable JSON format.

func (ID) Marshal

func (id ID) Marshal() ([]byte, error)

func (ID) MarshalBinary

func (id ID) MarshalBinary() ([]byte, error)

BinaryMarshal returns the byte representation of the peer ID.

func (ID) MarshalJSON

func (id ID) MarshalJSON() ([]byte, error)

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, error)

TextMarshal returns the text encoding of the ID.

func (ID) MarshalTo

func (id ID) MarshalTo(data []byte) (n int, err error)

func (ID) MatchesPrivateKey

func (id ID) MatchesPrivateKey(sk ic.PrivKey) bool

MatchesPrivateKey tests whether this ID was derived from the secret key sk.

func (ID) MatchesPublicKey

func (id ID) MatchesPublicKey(pk ic.PubKey) bool

MatchesPublicKey tests whether this ID was derived from the public key pk.

func (ID) Pretty

func (id ID) Pretty() string

Pretty returns a base58-encoded string representation of the ID.

func (ID) ShortString

func (id ID) ShortString() string

String prints out the peer ID.

TODO(brian): ensure correctness at ID generation and enforce this by only exposing functions that generate IDs safely. Then any peer.ID type found in the codebase is known to be correct.

func (ID) Size

func (id ID) Size() int

Implements Gogo's proto.Sizer, but we omit the compile-time assertion to avoid introducing a hard dependency on gogo.

func (ID) String

func (id ID) String() string

func (*ID) Unmarshal

func (id *ID) Unmarshal(data []byte) (err error)

func (*ID) UnmarshalBinary

func (id *ID) UnmarshalBinary(data []byte) error

BinaryUnmarshal sets the ID from its binary representation.

func (*ID) UnmarshalJSON

func (id *ID) UnmarshalJSON(data []byte) (err error)

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(data []byte) error

TextUnmarshal restores the ID from its text encoding.

func (ID) Validate

func (id ID) Validate() error

Validate checks if ID is empty or not.

type IDSlice

type IDSlice []ID

IDSlice for sorting peers

func (IDSlice) Len

func (es IDSlice) Len() int

func (IDSlice) Less

func (es IDSlice) Less(i, j int) bool

func (IDSlice) Swap

func (es IDSlice) Swap(i, j int)

type Set

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

PeerSet is a threadsafe set of peers

func NewLimitedSet

func NewLimitedSet(size int) *Set

func NewSet

func NewSet() *Set

func (*Set) Add

func (ps *Set) Add(p ID)

func (*Set) Contains

func (ps *Set) Contains(p ID) bool

func (*Set) Peers

func (ps *Set) Peers() []ID

func (*Set) Size

func (ps *Set) Size() int

func (*Set) TryAdd

func (ps *Set) TryAdd(p ID) bool

TryAdd Attempts to add the given peer into the set. This operation can fail for one of two reasons: 1) The given peer is already in the set 2) The number of peers in the set is equal to size