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

func RegisterForQueryEvents

func RegisterForQueryEvents(ctx context.Context) (context.Context, <-chan *QueryEvent)

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
	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 {
	// Find specific Peer
	// 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
}

func (*QueryEvent) MarshalJSON

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

func (*QueryEvent) UnmarshalJSON

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

type QueryEventType

type QueryEventType int

const (
	SendingQuery QueryEventType = iota
	PeerResponse
	FinalPeer
	QueryError
	Provider
	Value
	AddingPeer
	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.