routing

Documentation

Overview

Package routing provides interfaces for peer routing and content routing in libp2p.

Index

• Variables
• func GetPublicKey(r ValueStore, ctx context.Context, p peer.ID) (ci.PubKey, error)
• func KeyForPublicKey(id peer.ID) string
• func PublishQueryEvent(ctx context.Context, ev *QueryEvent)
• func RegisterForQueryEvents(ctx context.Context) (context.Context, <-chan *QueryEvent)
• func SubscribesToQueryEvents(ctx context.Context) bool
• type ContentRouting
• type Option
• type Options
  • func (opts *Options) Apply(options ...Option) error
  • func (opts *Options) ToOption() Option
• type PeerRouting
• type PubKeyFetcher
• type QueryEvent
  • func (qe *QueryEvent) MarshalJSON() ([]byte, error)
  • func (qe *QueryEvent) UnmarshalJSON(b []byte) error
• type QueryEventType
• type Routing
• type ValueStore

Variables

var ErrNotFound = errors.New("routing: not found")

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

var ErrNotSupported = errors.New("routing: operation or key not supported")

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

var QueryEventBufferSize = 16

Number of events to buffer.

Functions

func GetPublicKey

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

func KeyForPublicKey(id peer.ID) string

KeyForPublicKey returns the key used to retrieve public keys from a value store.

func PublishQueryEvent

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

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

func SubscribesToQueryEvents(ctx context.Context) bool

SubscribesToQueryEvents returns true if the context subscribes to query events. If this function returns falls, calling `PublishQueryEvent` on the context will be a no-op.

Types

type ContentRouting

type ContentRouting interface {
	// 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.
	Provide(context.Context, cid.Cid, bool) error

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

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.

type Option

type Option func(opts *Options) error

Option is a single routing option.

var Expired Option = func(opts *Options) error {
	opts.Expired = true
	return nil
}

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

var Offline Option = func(opts *Options) error {
	opts.Offline = true
	return nil
}

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

type Options

type Options struct {
	// Allow expired values.
	Expired bool
	Offline bool
	// Other (ValueStore implementation specific) options.
	Other map[interface{}]interface{}
}

Options is a set of routing options

func (*Options) Apply

func (opts *Options) Apply(options ...Option) error

Apply applies the given options to this Options

func (*Options) ToOption

func (opts *Options) ToOption() Option

ToOption converts this Options to a single Option.

type PeerRouting

type PeerRouting interface {
	// FindPeer searches for a peer with given ID, returns a peer.AddrInfo
	// with relevant addresses.
	FindPeer(context.Context, peer.ID) (peer.AddrInfo, error)
}

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.

type PubKeyFetcher

type PubKeyFetcher interface {
	// GetPublicKey returns the public key for the given peer.
	GetPublicKey(context.Context, peer.ID) (ci.PubKey, error)
}

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.

type QueryEvent

type QueryEvent struct {
	ID        peer.ID
	Type      QueryEventType
	Responses []*peer.AddrInfo
	Extra     string
}

QueryEvent is emitted for every notable event that happens during a DHT query.

func (*QueryEvent) MarshalJSON

func (qe *QueryEvent) MarshalJSON() ([]byte, error)

func (*QueryEvent) UnmarshalJSON

func (qe *QueryEvent) UnmarshalJSON(b []byte) error

type QueryEventType

type QueryEventType int

QueryEventType indicates the query event's type.

const (
	// Sending a query to a peer.
	SendingQuery QueryEventType = iota
	// Got a response from a peer.
	PeerResponse
	// Found a "closest" peer (not currently used).
	FinalPeer
	// Got an error when querying.
	QueryError
	// Found a provider.
	Provider
	// Found a value.
	Value
	// Adding a peer to the query.
	AddingPeer
	// Dialing a peer.
	DialingPeer
)

type Routing

type Routing interface {
	ContentRouting
	PeerRouting
	ValueStore

	// Bootstrap allows callers to hint to the routing system to get into a
	// Boostrapped state and remain there. It is not a synchronous call.
	Bootstrap(context.Context) error
}

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.

type ValueStore

type ValueStore interface {

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

	// GetValue searches for the value corresponding to given Key.
	GetValue(context.Context, string, ...Option) ([]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
	SearchValue(context.Context, string, ...Option) (<-chan []byte, error)
}

ValueStore is a basic Put/Get interface.