protocol

Documentation

Overview

Package protocol provides core interfaces for protocol routing and negotiation in libp2p.

Index

• func ConvertToStrings(ids []ID) (res []string)
• type HandlerFunc
• type ID
  • func ConvertFromStrings(ids []string) (res []ID)
• type Negotiator
• type Router
• type Switch

Functions

func ConvertToStrings

func ConvertToStrings(ids []ID) (res []string)

ConvertToStrings is a convenience function that takes a slice of protocol.ID and converts it to a slice of strings.

Types

type HandlerFunc

type HandlerFunc = func(protocol string, rwc io.ReadWriteCloser) error

HandlerFunc is a user-provided function used by the Router to handle a protocol/stream.

Will be invoked with the protocol ID string as the first argument, which may differ from the ID used for registration if the handler was registered using a match function.

type ID

type ID string

ID is an identifier used to write protocol headers in streams.

const (
	TestingID ID = "/p2p/_testing"
)

These are reserved protocol.IDs.

func ConvertFromStrings

func ConvertFromStrings(ids []string) (res []ID)

ConvertFromStrings is a convenience function that takes a slice of strings and converts it to a slice of protocol.ID.

type Negotiator

type Negotiator interface {
	// NegotiateLazy will return the registered protocol handler to use
	// for a given inbound stream, returning as soon as the protocol has been
	// determined. Returns an error if negotiation fails.
	//
	// NegotiateLazy may return before all protocol negotiation responses have been
	// written to the stream. This is in contrast to Negotiate, which will block until
	// the Negotiator is finished with the stream.
	//
	// Deprecated: use Negotiate instead.
	NegotiateLazy(rwc io.ReadWriteCloser) (io.ReadWriteCloser, string, HandlerFunc, error)

	// Negotiate will return the registered protocol handler to use for a given
	// inbound stream, returning after the protocol has been determined and the
	// Negotiator has finished using the stream for negotiation. Returns an
	// error if negotiation fails.
	Negotiate(rwc io.ReadWriteCloser) (string, HandlerFunc, error)

	// Handle calls Negotiate to determine which protocol handler to use for an
	// inbound stream, then invokes the protocol handler function, passing it
	// the protocol ID and the stream. Returns an error if negotiation fails.
	Handle(rwc io.ReadWriteCloser) error
}

Negotiator is a component capable of reaching agreement over what protocols to use for inbound streams of communication.

type Router

type Router interface {

	// AddHandler registers the given handler to be invoked for
	// an exact literal match of the given protocol ID string.
	AddHandler(protocol string, handler HandlerFunc)

	// AddHandlerWithFunc registers the given handler to be invoked
	// when the provided match function returns true.
	//
	// The match function will be invoked with an incoming protocol
	// ID string, and should return true if the handler supports
	// the protocol. Note that the protocol ID argument is not
	// used for matching; if you want to match the protocol ID
	// string exactly, you must check for it in your match function.
	AddHandlerWithFunc(protocol string, match func(string) bool, handler HandlerFunc)

	// RemoveHandler removes the registered handler (if any) for the
	// given protocol ID string.
	RemoveHandler(protocol string)

	// Protocols returns a list of all registered protocol ID strings.
	// Note that the Router may be able to handle protocol IDs not
	// included in this list if handlers were added with match functions
	// using AddHandlerWithFunc.
	Protocols() []string
}

Router is an interface that allows users to add and remove protocol handlers, which will be invoked when incoming stream requests for registered protocols are accepted.

Upon receiving an incoming stream request, the Router will check all registered protocol handlers to determine which (if any) is capable of handling the stream. The handlers are checked in order of registration; if multiple handlers are eligible, only the first to be registered will be invoked.

type Switch

type Switch interface {
	Router
	Negotiator
}

Switch is the component responsible for "dispatching" incoming stream requests to their corresponding stream handlers. It is both a Negotiator and a Router.