package peerstore

Import Path
	github.com/libp2p/go-libp2p/core/peerstore (on go.dev)

Dependency Relation
	imports 10 packages, and imported by 16 packages

Involved Source Files

	    helpers.go
	  d peerstore.go
		Package peerstore provides types and interfaces for local storage of address information,
		metadata, and public key material about libp2p peers.
Package-Level Type Names (total 7)

	/* sort by: alphabet | popularity */
	 type AddrBook (interface)
		AddrBook holds the multiaddrs of peers.

		Methods (total 9)
			( AddrBook) AddAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)
				AddAddr calls AddAddrs(p, []ma.Multiaddr{addr}, ttl)

			( AddrBook) AddAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)
				AddAddrs gives this AddrBook addresses to use, with a given ttl
				(time-to-live), after which the address is no longer valid.
				If the manager has a longer TTL, the operation is a no-op for that address

			( AddrBook) AddrStream(context.Context, peer.ID) <-chan ma.Multiaddr
				AddrStream returns a channel that gets all addresses for a given
				peer sent on it. If new addresses are added after the call is made
				they will be sent along through the channel as well.

			( AddrBook) Addrs(p peer.ID) []ma.Multiaddr
				Addrs returns all known (and valid) addresses for a given peer.

			( AddrBook) ClearAddrs(p peer.ID)
				ClearAddresses removes all previously stored addresses.

			( AddrBook) PeersWithAddrs() peer.IDSlice
				PeersWithAddrs returns all the peer IDs stored in the AddrBook.

			( AddrBook) SetAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)
				SetAddr calls mgr.SetAddrs(p, addr, ttl)

			( AddrBook) SetAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)
				SetAddrs sets the ttl on addresses. This clears any TTL there previously.
				This is used when we receive the best estimate of the validity of an address.

			( AddrBook) UpdateAddrs(p peer.ID, oldTTL time.Duration, newTTL time.Duration)
				UpdateAddrs updates the addresses associated with the given peer that have
				the given oldTTL to have the given newTTL.

		Implemented By (at least one exported)
			 Peerstore (interface)
		As Inputs Of (at least one exported)
			func GetCertifiedAddrBook(ab AddrBook) (cab CertifiedAddrBook, ok bool)

	 type CertifiedAddrBook (interface)
		CertifiedAddrBook manages signed peer records and "self-certified" addresses
		contained within them.
		Use this interface with an `AddrBook`.
		
		To test whether a given AddrBook / Peerstore implementation supports
		certified addresses, callers should use the GetCertifiedAddrBook helper or
		type-assert on the CertifiedAddrBook interface:
		
			if cab, ok := aPeerstore.(CertifiedAddrBook); ok {
			    cab.ConsumePeerRecord(signedPeerRecord, aTTL)
			}

		Methods (total 2)
			( CertifiedAddrBook) ConsumePeerRecord(s *record.Envelope, ttl time.Duration) (accepted bool, err error)
				ConsumePeerRecord stores a signed peer record and the contained addresses for
				ttl duration.
				The addresses contained in the signed peer record will expire after ttl. If any
				address is already present in the peer store, it'll expire at max of existing ttl and
				provided ttl.
				The signed peer record itself will be expired when all the addresses associated with the peer,
				self-certified or not, are removed from the AddrBook.
				
				To delete the signed peer record, use `AddrBook.UpdateAddrs`,`AddrBook.SetAddrs`, or
				`AddrBook.ClearAddrs` with ttl 0.
				Note: Future calls to ConsumePeerRecord will not expire self-certified addresses from the
				previous calls.
				
				The `accepted` return value indicates that the record was successfully processed. If
				`accepted` is false but no error is returned, it means that the record was ignored, most
				likely because a newer record exists for the same peer with a greater seq value.
				
				The Envelopes containing the signed peer records can be retrieved by calling
				GetPeerRecord(peerID).

			( CertifiedAddrBook) GetPeerRecord(p peer.ID) *record.Envelope
				GetPeerRecord returns an Envelope containing a peer record for the
				peer, or nil if no record exists.

		As Outputs Of (at least one exported)
			func GetCertifiedAddrBook(ab AddrBook) (cab CertifiedAddrBook, ok bool)

	 type KeyBook (interface)
		KeyBook tracks the keys of Peers.

		Methods (total 6)
			( KeyBook) AddPrivKey(peer.ID, ic.PrivKey) error
				AddPrivKey stores the private key of a peer.

			( KeyBook) AddPubKey(peer.ID, ic.PubKey) error
				AddPubKey stores the public key of a peer.

			( KeyBook) PeersWithKeys() peer.IDSlice
				PeersWithKeys returns all the peer IDs stored in the KeyBook.

			( KeyBook) PrivKey(peer.ID) ic.PrivKey
				PrivKey returns the private key of a peer, if known. Generally this might only be our own
				private key, see
				https://discuss.libp2p.io/t/what-is-the-purpose-of-having-map-peer-id-privatekey-in-peerstore/74.

			( KeyBook) PubKey(peer.ID) ic.PubKey
				PubKey returns the public key of a peer.

			( KeyBook) RemovePeer(peer.ID)
				RemovePeer removes all keys associated with a peer.

		Implemented By (at least one exported)
			 Peerstore (interface)

	 type Metrics (interface)
		Metrics tracks metrics across a set of peers.

		Methods (total 3)
			( Metrics) LatencyEWMA(peer.ID) time.Duration
				LatencyEWMA returns an exponentially-weighted moving avg.
				of all measurements of a peer's latency.

			( Metrics) RecordLatency(peer.ID, time.Duration)
				RecordLatency records a new latency measurement

			( Metrics) RemovePeer(peer.ID)
				RemovePeer removes all metrics stored for a peer.

		Implemented By (at least one exported)
			 Peerstore (interface)

	 type PeerMetadata (interface)
		PeerMetadata can handle values of any type. Serializing values is
		up to the implementation. Dynamic type introspection may not be
		supported, in which case explicitly enlisting types in the
		serializer may be required.
		
		Refer to the docs of the underlying implementation for more
		information.

		Methods (total 3)
			( PeerMetadata) Get(p peer.ID, key string) (interface{}, error)
				Get / Put is a simple registry for other peer-related key/value pairs.
				If we find something we use often, it should become its own set of
				methods. This is a last resort.

			( PeerMetadata) Put(p peer.ID, key string, val interface{}) error
			( PeerMetadata) RemovePeer(peer.ID)
				RemovePeer removes all values stored for a peer.

		Implemented By (at least one exported)
			 Peerstore (interface)

	 type Peerstore (interface)
		Peerstore provides a thread-safe store of Peer related
		information.

		Methods (total 28)
			( Peerstore) AddAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)
				AddAddr calls AddAddrs(p, []ma.Multiaddr{addr}, ttl)

			( Peerstore) AddAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)
				AddAddrs gives this AddrBook addresses to use, with a given ttl
				(time-to-live), after which the address is no longer valid.
				If the manager has a longer TTL, the operation is a no-op for that address

			( Peerstore) AddPrivKey(peer.ID, ic.PrivKey) error
				AddPrivKey stores the private key of a peer.

			( Peerstore) AddProtocols(peer.ID, ...protocol.ID) error
			( Peerstore) AddPubKey(peer.ID, ic.PubKey) error
				AddPubKey stores the public key of a peer.

			( Peerstore) AddrStream(context.Context, peer.ID) <-chan ma.Multiaddr
				AddrStream returns a channel that gets all addresses for a given
				peer sent on it. If new addresses are added after the call is made
				they will be sent along through the channel as well.

			( Peerstore) Addrs(p peer.ID) []ma.Multiaddr
				Addrs returns all known (and valid) addresses for a given peer.

			( Peerstore) ClearAddrs(p peer.ID)
				ClearAddresses removes all previously stored addresses.

			( Peerstore) Close() error
			( Peerstore) FirstSupportedProtocol(peer.ID, ...protocol.ID) (protocol.ID, error)
				FirstSupportedProtocol returns the first protocol that the peer supports among the given protocols.
				If the peer does not support any of the given protocols, this function will return an empty protocol.ID and a nil error.
				If the returned error is not nil, the result is indeterminate.

			( Peerstore) Get(p peer.ID, key string) (interface{}, error)
				Get / Put is a simple registry for other peer-related key/value pairs.
				If we find something we use often, it should become its own set of
				methods. This is a last resort.

			( Peerstore) GetProtocols(peer.ID) ([]protocol.ID, error)
			( Peerstore) LatencyEWMA(peer.ID) time.Duration
				LatencyEWMA returns an exponentially-weighted moving avg.
				of all measurements of a peer's latency.

			( Peerstore) PeerInfo(peer.ID) peer.AddrInfo
				PeerInfo returns a peer.PeerInfo struct for given peer.ID.
				This is a small slice of the information Peerstore has on
				that peer, useful to other services.

			( Peerstore) Peers() peer.IDSlice
				Peers returns all the peer IDs stored across all inner stores.

			( Peerstore) PeersWithAddrs() peer.IDSlice
				PeersWithAddrs returns all the peer IDs stored in the AddrBook.

			( Peerstore) PeersWithKeys() peer.IDSlice
				PeersWithKeys returns all the peer IDs stored in the KeyBook.

			( Peerstore) PrivKey(peer.ID) ic.PrivKey
				PrivKey returns the private key of a peer, if known. Generally this might only be our own
				private key, see
				https://discuss.libp2p.io/t/what-is-the-purpose-of-having-map-peer-id-privatekey-in-peerstore/74.

			( Peerstore) PubKey(peer.ID) ic.PubKey
				PubKey returns the public key of a peer.

			( Peerstore) Put(p peer.ID, key string, val interface{}) error
			( Peerstore) RecordLatency(peer.ID, time.Duration)
				RecordLatency records a new latency measurement

			( Peerstore) RemovePeer(peer.ID)
				RemovePeer removes all keys associated with a peer.

			( Peerstore) RemoveProtocols(peer.ID, ...protocol.ID) error
			( Peerstore) SetAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)
				SetAddr calls mgr.SetAddrs(p, addr, ttl)

			( Peerstore) SetAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)
				SetAddrs sets the ttl on addresses. This clears any TTL there previously.
				This is used when we receive the best estimate of the validity of an address.

			( Peerstore) SetProtocols(peer.ID, ...protocol.ID) error
			( Peerstore) SupportsProtocols(peer.ID, ...protocol.ID) ([]protocol.ID, error)
				SupportsProtocols returns the set of protocols the peer supports from among the given protocols.
				If the returned error is not nil, the result is indeterminate.

			( Peerstore) UpdateAddrs(p peer.ID, oldTTL time.Duration, newTTL time.Duration)
				UpdateAddrs updates the addresses associated with the given peer that have
				the given oldTTL to have the given newTTL.

		Implements (at least 7)
			 Peerstore : AddrBook
			 Peerstore : KeyBook
			 Peerstore : Metrics
			 Peerstore : PeerMetadata
			 Peerstore : ProtoBook
			 Peerstore : github.com/prometheus/common/expfmt.Closer
			 Peerstore : io.Closer
		As Outputs Of (at least 8)
			func github.com/libp2p/go-libp2p/core/host.Host.Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/core/network.Dialer.Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/core/network.Network.Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/p2p/host/basic.(*BasicHost).Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/p2p/host/blank.(*BlankHost).Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/p2p/host/routed.(*RoutedHost).Peerstore() Peerstore
			func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).Peerstore() Peerstore
		As Inputs Of (at least 5)
			func AddrInfos(ps Peerstore, peers []peer.ID) []peer.AddrInfo
			func github.com/libp2p/go-libp2p.Peerstore(ps Peerstore) libp2p.Option
			func github.com/libp2p/go-libp2p/p2p/host/peerstore.PeerInfos(ps Peerstore, peers peer.IDSlice) []peer.AddrInfo
			func github.com/libp2p/go-libp2p/p2p/host/pstoremanager.NewPeerstoreManager(pstore Peerstore, eventBus event.Bus, network network.Network, opts ...pstoremanager.Option) (*pstoremanager.PeerstoreManager, error)
			func github.com/libp2p/go-libp2p/p2p/net/swarm.NewSwarm(local peer.ID, peers Peerstore, eventBus event.Bus, opts ...swarm.Option) (*swarm.Swarm, error)

	 type ProtoBook (interface)
		ProtoBook tracks the protocols supported by peers.

		Methods (total 7)
			( ProtoBook) AddProtocols(peer.ID, ...protocol.ID) error
			( ProtoBook) FirstSupportedProtocol(peer.ID, ...protocol.ID) (protocol.ID, error)
				FirstSupportedProtocol returns the first protocol that the peer supports among the given protocols.
				If the peer does not support any of the given protocols, this function will return an empty protocol.ID and a nil error.
				If the returned error is not nil, the result is indeterminate.

			( ProtoBook) GetProtocols(peer.ID) ([]protocol.ID, error)
			( ProtoBook) RemovePeer(peer.ID)
				RemovePeer removes all protocols associated with a peer.

			( ProtoBook) RemoveProtocols(peer.ID, ...protocol.ID) error
			( ProtoBook) SetProtocols(peer.ID, ...protocol.ID) error
			( ProtoBook) SupportsProtocols(peer.ID, ...protocol.ID) ([]protocol.ID, error)
				SupportsProtocols returns the set of protocols the peer supports from among the given protocols.
				If the returned error is not nil, the result is indeterminate.

		Implemented By (at least one exported)
			 Peerstore (interface)


Package-Level Functions (total 2)

	 func AddrInfos(ps Peerstore, peers []peer.ID) []peer.AddrInfo
		AddrInfos returns an AddrInfo for each specified peer ID, in-order.

	 func GetCertifiedAddrBook(ab AddrBook) (cab CertifiedAddrBook, ok bool)
		GetCertifiedAddrBook is a helper to "upcast" an AddrBook to a
		CertifiedAddrBook by using type assertion. If the given AddrBook
		is also a CertifiedAddrBook, it will be returned, and the ok return
		value will be true. Returns (nil, false) if the AddrBook is not a
		CertifiedAddrBook.
		
		Note that since Peerstore embeds the AddrBook interface, you can also
		call GetCertifiedAddrBook(myPeerstore).


Package-Level Variables (total 5)

	  var AddressTTL time.Duration
		AddressTTL is the expiration time of addresses.

	  var ErrNotFound error
	  var OwnObservedAddrTTL time.Duration
		OwnObservedAddrTTL is used for our own external addresses observed by peers.
		
		Deprecated: observed addresses are maintained till we disconnect from the peer which provided it

	  var RecentlyConnectedAddrTTL time.Duration
		RecentlyConnectedAddrTTL is used when we recently connected to a peer.
		It means that we are reasonably certain of the peer's address.

	  var TempAddrTTL time.Duration
		TempAddrTTL is the ttl used for a short-lived address.


Package-Level Constants (total 2)

	const ConnectedAddrTTL = 9223372036854775806
		ConnectedAddrTTL is the ttl used for the addresses of a peer to whom
		we're connected directly. This is basically permanent, as we will
		clear them + re-add under a TempAddrTTL after disconnecting.

	const PermanentAddrTTL = 9223372036854775807
		PermanentAddrTTL is the ttl for a "permanent address" (e.g. bootstrap nodes).

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.