package routing

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

Dependency Relation
	imports 7 packages, and imported by one package

Involved Source Files

	    options.go
	    query.go
	    query_serde.go
	  d routing.go
		Package routing provides interfaces for peer routing and content routing in libp2p.
Package-Level Type Names (total 11)

	/* sort by: alphabet | popularity */
	 type ContentDiscovery (interface)
		ContentDiscovery is able to retrieve providers for a given CID using
		the Routing system.

		Methods (only one)
			( ContentDiscovery) FindProvidersAsync(context.Context, cid.Cid, int) <-chan peer.AddrInfo
				Search for peers who are able to provide a given key
				
				When count is 0, this method will return an unbounded number of
				results.

		Implemented By (at least 2)
			 ContentRouting (interface)
			 Routing (interface)

	 type ContentProviding (interface)
		ContentProviding is able to announce where to find content on the Routing
		system.

		Methods (only one)
			( ContentProviding) Provide(context.Context, cid.Cid, bool) error
				Provide adds the given cid to the content routing system. If 'true' is
				passed, it also announces it, otherwise it is just kept in the local
				accounting of which objects are being provided.

		Implemented By (at least 2)
			 ContentRouting (interface)
			 Routing (interface)

	 type ContentRouting (interface)
		ContentRouting is a value provider layer of indirection. It is used to find
		information about who has what content.
		
		Content is identified by CID (content identifier), which encodes a hash
		of the identified content in a future-proof manner.

		Methods (total 2)
			( ContentRouting) FindProvidersAsync(context.Context, cid.Cid, int) <-chan peer.AddrInfo
				Search for peers who are able to provide a given key
				
				When count is 0, this method will return an unbounded number of
				results.

			( ContentRouting) Provide(context.Context, cid.Cid, bool) error
				Provide adds the given cid to the content routing system. If 'true' is
				passed, it also announces it, otherwise it is just kept in the local
				accounting of which objects are being provided.

		Implemented By (at least one exported)
			 Routing (interface)
		Implements (at least 2)
			 ContentRouting : ContentDiscovery
			 ContentRouting : ContentProviding

	 type Option (func)
		Option is a single routing option.

		As Outputs Of (at least one exported)
			func (*Options).ToOption() Option
		As Inputs Of (at least 7)
			func (*Options).Apply(options ...Option) error
			func Routing.GetValue(context.Context, string, ...Option) ([]byte, error)
			func Routing.PutValue(context.Context, string, []byte, ...Option) error
			func Routing.SearchValue(context.Context, string, ...Option) (<-chan []byte, error)
			func ValueStore.GetValue(context.Context, string, ...Option) ([]byte, error)
			func ValueStore.PutValue(context.Context, string, []byte, ...Option) error
			func ValueStore.SearchValue(context.Context, string, ...Option) (<-chan []byte, error)
		As Types Of (total 2)
			  var Expired
			  var Offline

	 type Options (struct)
		Options is a set of routing options

		Fields (total 3)
			Expired bool
				Allow expired values.

			Offline bool
			Other map[interface{}]interface{}
				Other (ValueStore implementation specific) options.

		Methods (total 2)
			(*Options) Apply(options ...Option) error
				Apply applies the given options to this Options

			(*Options) ToOption() Option
				ToOption converts this Options to a single Option.


	 type PeerRouting (interface)
		PeerRouting is a way to find address information about certain peers.
		This can be implemented by a simple lookup table, a tracking server,
		or even a DHT.

		Methods (only one)
			( PeerRouting) FindPeer(context.Context, peer.ID) (peer.AddrInfo, error)
				FindPeer searches for a peer with given ID, returns a peer.AddrInfo
				with relevant addresses.

		Implemented By (at least 2)
			 Routing (interface)
			 github.com/libp2p/go-libp2p/p2p/host/routed.Routing (interface)
		Implements (at least one exported)
			 PeerRouting : github.com/libp2p/go-libp2p/p2p/host/routed.Routing

	 type PubKeyFetcher (interface)
		PubKeyFetcher is an interfaces that should be implemented by value stores
		that can optimize retrieval of public keys.
		
		TODO(steb): Consider removing, see https://github.com/libp2p/go-libp2p-routing/issues/22.

		Methods (only one)
			( PubKeyFetcher) GetPublicKey(context.Context, peer.ID) (ci.PubKey, error)
				GetPublicKey returns the public key for the given peer.


	 type QueryEvent (struct)
		QueryEvent is emitted for every notable event that happens during a DHT query.

		Fields (total 4)
			Extra string
			ID peer.ID
			Responses []*peer.AddrInfo
			Type QueryEventType
		Methods (total 2)
			(*QueryEvent) MarshalJSON() ([]byte, error)
			(*QueryEvent) UnmarshalJSON(b []byte) error
		Implements (at least 4)
			*QueryEvent : github.com/goccy/go-json.Marshaler
			*QueryEvent : github.com/goccy/go-json.Unmarshaler
			*QueryEvent : encoding/json.Marshaler
			*QueryEvent : encoding/json.Unmarshaler
		As Outputs Of (at least one exported)
			func RegisterForQueryEvents(ctx context.Context) (context.Context, <-chan *QueryEvent)
		As Inputs Of (at least one exported)
			func PublishQueryEvent(ctx context.Context, ev *QueryEvent)

	 type QueryEventType int (basic type)
		QueryEventType indicates the query event's type.

		As Types Of (total 8)
			const AddingPeer
			const DialingPeer
			const FinalPeer
			const PeerResponse
			const Provider
			const QueryError
			const SendingQuery
			const Value

	 type Routing (interface)
		Routing is the combination of different routing types supported by libp2p.
		It can be satisfied by a single item (such as a DHT) or multiple different
		pieces that are more optimized to each task.

		Methods (total 7)
			( Routing) Bootstrap(context.Context) error
				Bootstrap allows callers to hint to the routing system to get into a
				Bootstrapped state and remain there. It is not a synchronous call.

			( Routing) FindPeer(context.Context, peer.ID) (peer.AddrInfo, error)
				FindPeer searches for a peer with given ID, returns a peer.AddrInfo
				with relevant addresses.

			( Routing) FindProvidersAsync(context.Context, cid.Cid, int) <-chan peer.AddrInfo
				Search for peers who are able to provide a given key
				
				When count is 0, this method will return an unbounded number of
				results.

			( Routing) GetValue(context.Context, string, ...Option) ([]byte, error)
				GetValue searches for the value corresponding to given Key.

			( Routing) Provide(context.Context, cid.Cid, bool) error
				Provide adds the given cid to the content routing system. If 'true' is
				passed, it also announces it, otherwise it is just kept in the local
				accounting of which objects are being provided.

			( Routing) PutValue(context.Context, string, []byte, ...Option) error
				PutValue adds value corresponding to given Key.

			( Routing) SearchValue(context.Context, string, ...Option) (<-chan []byte, error)
				SearchValue searches for better and better values from this value
				store corresponding to the given Key. By default, implementations must
				stop the search after a good value is found. A 'good' value is a value
				that would be returned from GetValue.
				
				Useful when you want a result *now* but still want to hear about
				better/newer results.
				
				Implementations of this methods won't return ErrNotFound. When a value
				couldn't be found, the channel will get closed without passing any results

		Implements (at least 6)
			 Routing : ContentDiscovery
			 Routing : ContentProviding
			 Routing : ContentRouting
			 Routing : PeerRouting
			 Routing : ValueStore
			 Routing : github.com/libp2p/go-libp2p/p2p/host/routed.Routing

	 type ValueStore (interface)
		ValueStore is a basic Put/Get interface.

		Methods (total 3)
			( ValueStore) GetValue(context.Context, string, ...Option) ([]byte, error)
				GetValue searches for the value corresponding to given Key.

			( ValueStore) PutValue(context.Context, string, []byte, ...Option) error
				PutValue adds value corresponding to given Key.

			( ValueStore) SearchValue(context.Context, string, ...Option) (<-chan []byte, error)
				SearchValue searches for better and better values from this value
				store corresponding to the given Key. By default, implementations must
				stop the search after a good value is found. A 'good' value is a value
				that would be returned from GetValue.
				
				Useful when you want a result *now* but still want to hear about
				better/newer results.
				
				Implementations of this methods won't return ErrNotFound. When a value
				couldn't be found, the channel will get closed without passing any results

		Implemented By (at least one exported)
			 Routing (interface)
		As Inputs Of (at least one exported)
			func GetPublicKey(r ValueStore, ctx context.Context, p peer.ID) (ci.PubKey, error)


Package-Level Functions (total 5)

	 func GetPublicKey(r ValueStore, ctx context.Context, p peer.ID) (ci.PubKey, error)
		GetPublicKey retrieves the public key associated with the given peer ID from
		the value store.
		
		If the ValueStore is also a PubKeyFetcher, this method will call GetPublicKey
		(which may be better optimized) instead of GetValue.

	 func KeyForPublicKey(id peer.ID) string
		KeyForPublicKey returns the key used to retrieve public keys
		from a value store.

	 func PublishQueryEvent(ctx context.Context, ev *QueryEvent)
		PublishQueryEvent publishes a query event to the query event channel
		associated with the given context, if any.

	 func RegisterForQueryEvents(ctx context.Context) (context.Context, <-chan *QueryEvent)
		RegisterForQueryEvents registers a query event channel with the given
		context. The returned context can be passed to DHT queries to receive query
		events on the returned channels.
		
		The passed context MUST be canceled when the caller is no longer interested
		in query events.

	 func SubscribesToQueryEvents(ctx context.Context) bool
		SubscribesToQueryEvents returns true if the context subscribes to query
		events. If this function returns false, calling `PublishQueryEvent` on the
		context will be a no-op.


Package-Level Variables (total 5)

	  var ErrNotFound error
		ErrNotFound is returned when the router fails to find the requested record.

	  var ErrNotSupported error
		ErrNotSupported is returned when the router doesn't support the given record
		type/operation.

	  var Expired Option
		Expired is an option that tells the routing system to return expired records
		when no newer records are known.

	  var Offline Option
		Offline is an option that tells the routing system to operate offline (i.e., rely on cached/local data only).

	  var QueryEventBufferSize int
		Number of events to buffer.


Package-Level Constants (total 8)

	const AddingPeer QueryEventType = 6
		Adding a peer to the query.

	const DialingPeer QueryEventType = 7
		Dialing a peer.

	const FinalPeer QueryEventType = 2
		Found a "closest" peer (not currently used).

	const PeerResponse QueryEventType = 1
		Got a response from a peer.

	const Provider QueryEventType = 4
		Found a provider.

	const QueryError QueryEventType = 3
		Got an error when querying.

	const SendingQuery QueryEventType = 0
		Sending a query to a peer.

	const Value QueryEventType = 5
		Found a value.

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.