Documentation

Overview

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

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

    Index

    Constants

    View Source
    const PeerRecordEnvelopeDomain = "libp2p-peer-record"

      PeerRecordEnvelopeDomain is the domain string used for peer records contained in a Envelope.

      Variables

      View Source
      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")
      )
      View Source
      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.

        View Source
        var ErrInvalidAddr = fmt.Errorf("invalid p2p multiaddr")
        View Source
        var PeerRecordEnvelopePayloadType = []byte{0x03, 0x01}

          PeerRecordEnvelopePayloadType is the type hint used to identify peer records in a Envelope. Defined in https://github.com/multiformats/multicodec/blob/master/table.csv with name "libp2p-peer-record".

          Functions

          func AddrInfoToP2pAddrs

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

            AddrInfoToP2pAddrs 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 TimestampSeq

                  func TimestampSeq() uint64

                    TimestampSeq is a helper to generate a timestamp-based sequence number for a PeerRecord.

                    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)

                                                      MarshalBinary 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)

                                                        MarshalText 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

                                                                ShortString 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

                                                                  Size 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

                                                                    UnmarshalBinary 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

                                                                      UnmarshalText 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 PeerRecord

                                                                          type PeerRecord struct {
                                                                          	// PeerID is the ID of the peer this record pertains to.
                                                                          	PeerID ID
                                                                          
                                                                          	// Addrs contains the public addresses of the peer this record pertains to.
                                                                          	Addrs []ma.Multiaddr
                                                                          
                                                                          	// Seq is a monotonically-increasing sequence counter that's used to order
                                                                          	// PeerRecords in time. The interval between Seq values is unspecified,
                                                                          	// but newer PeerRecords MUST have a greater Seq value than older records
                                                                          	// for the same peer.
                                                                          	Seq uint64
                                                                          }

                                                                            PeerRecord contains information that is broadly useful to share with other peers, either through a direct exchange (as in the libp2p identify protocol), or through a Peer Routing provider, such as a DHT.

                                                                            Currently, a PeerRecord contains the public listen addresses for a peer, but this is expected to expand to include other information in the future.

                                                                            PeerRecords are ordered in time by their Seq field. Newer PeerRecords must have greater Seq values than older records. The NewPeerRecord function will create a PeerRecord with a timestamp-based Seq value. The other PeerRecord fields should be set by the caller:

                                                                            rec := peer.NewPeerRecord()
                                                                            rec.PeerID = aPeerID
                                                                            rec.Addrs = someAddrs
                                                                            

                                                                            Alternatively, you can construct a PeerRecord struct directly and use the TimestampSeq helper to set the Seq field:

                                                                            rec := peer.PeerRecord{PeerID: aPeerID, Addrs: someAddrs, Seq: peer.TimestampSeq()}
                                                                            

                                                                            Failing to set the Seq field will not result in an error, however, a PeerRecord with a Seq value of zero may be ignored or rejected by other peers.

                                                                            PeerRecords are intended to be shared with other peers inside a signed routing.Envelope, and PeerRecord implements the routing.Record interface to facilitate this.

                                                                            To share a PeerRecord, first call Sign to wrap the record in a Envelope and sign it with the local peer's private key:

                                                                            rec := &PeerRecord{PeerID: myPeerId, Addrs: myAddrs}
                                                                            envelope, err := rec.Sign(myPrivateKey)
                                                                            

                                                                            The resulting record.Envelope can be marshalled to a []byte and shared publicly. As a convenience, the MarshalSigned method will produce the Envelope and marshal it to a []byte in one go:

                                                                            rec := &PeerRecord{PeerID: myPeerId, Addrs: myAddrs}
                                                                            recordBytes, err := rec.MarshalSigned(myPrivateKey)
                                                                            

                                                                            To validate and unmarshal a signed PeerRecord from a remote peer, "consume" the containing envelope, which will return both the routing.Envelope and the inner Record. The Record must be cast to a PeerRecord pointer before use:

                                                                            envelope, untypedRecord, err := ConsumeEnvelope(envelopeBytes, PeerRecordEnvelopeDomain)
                                                                            if err != nil {
                                                                              handleError(err)
                                                                              return
                                                                            }
                                                                            peerRec := untypedRecord.(*PeerRecord)
                                                                            

                                                                            func NewPeerRecord

                                                                            func NewPeerRecord() *PeerRecord

                                                                              NewPeerRecord returns a PeerRecord with a timestamp-based sequence number. The returned record is otherwise empty and should be populated by the caller.

                                                                              func PeerRecordFromAddrInfo

                                                                              func PeerRecordFromAddrInfo(info AddrInfo) *PeerRecord

                                                                                PeerRecordFromAddrInfo creates a PeerRecord from an AddrInfo struct. The returned record will have a timestamp-based sequence number.

                                                                                func PeerRecordFromProtobuf

                                                                                func PeerRecordFromProtobuf(msg *pb.PeerRecord) (*PeerRecord, error)

                                                                                  PeerRecordFromProtobuf creates a PeerRecord from a protobuf PeerRecord struct.

                                                                                  func (*PeerRecord) Codec

                                                                                  func (r *PeerRecord) Codec() []byte

                                                                                    Codec is a binary identifier for the PeerRecord type. It is constant for all PeerRecord instances.

                                                                                    func (*PeerRecord) Domain

                                                                                    func (r *PeerRecord) Domain() string

                                                                                      Domain is used when signing and validating PeerRecords contained in Envelopes. It is constant for all PeerRecord instances.

                                                                                      func (*PeerRecord) Equal

                                                                                      func (r *PeerRecord) Equal(other *PeerRecord) bool

                                                                                        Equal returns true if the other PeerRecord is identical to this one.

                                                                                        func (*PeerRecord) MarshalRecord

                                                                                        func (r *PeerRecord) MarshalRecord() ([]byte, error)

                                                                                          MarshalRecord serializes a PeerRecord to a byte slice. This method is called automatically when constructing a routing.Envelope using Seal or PeerRecord.Sign.

                                                                                          func (*PeerRecord) ToProtobuf

                                                                                          func (r *PeerRecord) ToProtobuf() (*pb.PeerRecord, error)

                                                                                            ToProtobuf returns the equivalent Protocol Buffer struct object of a PeerRecord.

                                                                                            func (*PeerRecord) UnmarshalRecord

                                                                                            func (r *PeerRecord) UnmarshalRecord(bytes []byte) error

                                                                                              UnmarshalRecord parses a PeerRecord from a byte slice. This method is called automatically when consuming a record.Envelope whose PayloadType indicates that it contains a PeerRecord. It is generally not necessary or recommended to call this method directly.

                                                                                              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

                                                                                                  Directories

                                                                                                  Path Synopsis