link

Documentation

Index

• Variables
• func WithMountedStreamContext(ctx context.Context, msc MountedStreamContext) context.Context
• type EstablishLinkWithPeer
  • func NewEstablishLinkWithPeer(srcPeer, destPeer peer.ID) EstablishLinkWithPeer
• type EstablishLinkWithPeerValue
• type HandleMountedStream
  • func NewHandleMountedStream(protocolID protocol.ID, localPeerID, remotePeerID peer.ID) HandleMountedStream
• type HandleMountedStreamValue
• type Link
  • func EstablishLinkWithPeerEx(ctx context.Context, b bus.Bus, localPeerID, remotePeerID peer.ID, ...) (Link, func(), error)
• type MountedStream
  • func OpenStreamViaLinkEx(ctx context.Context, b bus.Bus, remotePeerID peer.ID, protocolID protocol.ID, ...) (MountedStream, error)
  • func OpenStreamWithPeerEx(ctx context.Context, b bus.Bus, protocolID protocol.ID, ...) (MountedStream, func(), error)
• type MountedStreamContext
  • func GetMountedStreamContext(ctx context.Context) MountedStreamContext
  • func MustGetMountedStreamContext(ctx context.Context) (MountedStreamContext, error)
• type MountedStreamHandler
• type OpenStreamViaLink
  • func NewOpenStreamViaLink(linkUUID uint64, protocolID protocol.ID, openOpts stream.OpenOpts, ...) OpenStreamViaLink
• type OpenStreamViaLinkValue
• type OpenStreamWithPeer
  • func NewOpenStreamWithPeer(protocolID protocol.ID, sourcePeerID, targetPeerID peer.ID, ...) OpenStreamWithPeer

Variables

var ErrNoMountedStreamContext = errors.New("no mounted stream context")

ErrNoMountedStreamContext is returned if there was no MountedStreamContext.

Functions

func WithMountedStreamContext

func WithMountedStreamContext(ctx context.Context, msc MountedStreamContext) context.Context

WithMountedStreamContext attaches a MountedStreamContext to a Context.

Types

type EstablishLinkWithPeer

type EstablishLinkWithPeer interface {
	// Directive indicates EstablishLinkWithPeer is a directive.
	directive.Directive

	// EstablishLinkSourcePeerId returns the source peer ID.
	// Can be empty to allow any.
	EstablishLinkSourcePeerId() peer.ID
	// EstablishLinkTargetPeerId returns the target peer ID.
	// Cannot be empty.
	EstablishLinkTargetPeerId() peer.ID
}

EstablishLinkWithPeer is a directive to establish a link with a peer.

Value: Link

func NewEstablishLinkWithPeer

func NewEstablishLinkWithPeer(srcPeer, destPeer peer.ID) EstablishLinkWithPeer

NewEstablishLinkWithPeer constructs a new EstablishLinkWithPeer directive.

type EstablishLinkWithPeerValue

type EstablishLinkWithPeerValue = Link

EstablishLinkWithPeerValue is the type emitted when resolving EstablishLinkWithPeer.

type HandleMountedStream

type HandleMountedStream interface {
	// Directive indicates HandleMountedStream is a directive.
	directive.Directive

	// HandleMountedStreamProtocolID returns the protocol ID we are requesting a
	// handler for. Cannot be empty.
	HandleMountedStreamProtocolID() protocol.ID
	// HandleMountedStreamLocalPeerID returns the local peer ID we are
	// requesting a handler for. Cannot be empty.
	HandleMountedStreamLocalPeerID() peer.ID
	// HandleMountedStreamRemotePeerID returns the remote peer ID we are
	// requesting a handler for. Cannot be empty.
	HandleMountedStreamRemotePeerID() peer.ID
}

HandleMountedStream is a directive to return a mounted stream handler for a protocol ID. Value is of type link.MountedStreamHandler.

func NewHandleMountedStream

func NewHandleMountedStream(
	protocolID protocol.ID,
	localPeerID, remotePeerID peer.ID,
) HandleMountedStream

NewHandleMountedStream constructs a new HandleMountedStream directive.

type HandleMountedStreamValue

type HandleMountedStreamValue = MountedStreamHandler

HandleMountedStreamValue is the value type for HandleMountedStream.

type Link

type Link interface {
	// GetUUID returns the host-unique ID.
	// This should be repeatable between re-constructions of the same link.
	GetUUID() uint64
	// GetTransportUUID returns the unique ID of the transport.
	GetTransportUUID() uint64
	// OpenStream opens a stream on the link, with the given parameters.
	OpenStream(opts stream.OpenOpts) (stream.Stream, error)
	// AcceptStream accepts a stream from the link.
	// Terminates when the link closes.
	AcceptStream() (stream.Stream, stream.OpenOpts, error)
	// GetRemotePeer returns the identity of the remote peer.
	GetRemotePeer() peer.ID
	// GetLocalPeer returns the identity of the local peer.
	GetLocalPeer() peer.ID
	// GetRemoteTransportUUID returns the reported remote transport UUID.
	// This should be negotiated in the handshake.
	GetRemoteTransportUUID() uint64
	// Close closes the link.
	// Any blocked ReadFrom or WriteTo operations will be unblocked and return errors.
	// The link should call the HandleLinkLost callback exactly once.
	// Close may be called many times.
	Close() error
}

Link represents a one-hop connection between two peers.

func EstablishLinkWithPeerEx

func EstablishLinkWithPeerEx(
	ctx context.Context,
	b bus.Bus,
	localPeerID, remotePeerID peer.ID,
	returnIfIdle bool,
) (Link, func(), error)

EstablishLinkWithPeerEx executes a EstablishLinkWithPeer directive. Returns a release function. if returnIfIdle: returns nil, nil, nil if not found (idle directive)

type MountedStream

type MountedStream interface {
	// GetStream returns the underlying stream object.
	GetStream() stream.Stream
	// GetProtocolID returns the protocol ID of the stream.
	GetProtocolID() protocol.ID
	// GetOpenOpts returns the options used to open the stream.
	GetOpenOpts() stream.OpenOpts
	// GetPeerID returns the peer ID for the other end of the stream.
	GetPeerID() peer.ID
	// GetLink returns the associated link carrying the stream.
	GetLink() Link
}

MountedStream is a stream attached to a Link. This is produced and managed by the link controller. A mounted stream is produced after the initial stream negotiation is completed.

func OpenStreamViaLinkEx

func OpenStreamViaLinkEx(
	ctx context.Context,
	b bus.Bus,
	remotePeerID peer.ID,
	protocolID protocol.ID,
	linkUUID uint64,
	transportID uint64,
	openOpts stream.OpenOpts,
) (MountedStream, error)

OpenStreamViaLinkEx executes a OpenStreamViaLink directive.

func OpenStreamWithPeerEx

func OpenStreamWithPeerEx(
	ctx context.Context,
	b bus.Bus,
	protocolID protocol.ID,
	localPeerID, remotePeerID peer.ID,
	transportID uint64,
	openOpts stream.OpenOpts,
) (MountedStream, func(), error)

OpenStreamWithPeerEx executes a OpenStreamWithPeer directive. Returns a release function for the links used for the stream.

type MountedStreamContext

type MountedStreamContext = MountedStream

MountedStreamContext is the value attached to a Context containing information about the current mounted stream.

func GetMountedStreamContext

func GetMountedStreamContext(ctx context.Context) MountedStreamContext

GetMountedStreamContext returns the MountedStreamContext from the Context or nil if unset.

func MustGetMountedStreamContext

func MustGetMountedStreamContext(ctx context.Context) (MountedStreamContext, error)

MustGetMountedStreamContext returns the MountedStreamContext from the Context or an error if unset.

type MountedStreamHandler

type MountedStreamHandler interface {
	// HandleMountedStream handles an incoming mounted stream.
	//
	// This function should return as soon as possible, and start
	// additional goroutines to manage the lifecycle of the stream.
	//
	// The context will be canceled when the Link closes.
	// The context will /not/ be canceled when ms closes.
	// Any returned error indicates the stream should be closed.
	HandleMountedStream(ctx context.Context, ms MountedStream) error
}

MountedStreamHandler handles an incoming mounted stream.

type OpenStreamViaLink

type OpenStreamViaLink interface {
	// Directive indicates OpenStreamViaLink is a directive.
	directive.Directive

	// OpenStreamViaLinkUUID returns the link UUID to select.
	// Cannot be empty.
	OpenStreamViaLinkUUID() uint64
	// OpenStreamViaLinkProtocolID returns the protocol ID to negotiate with the peer.
	// Cannot be empty.
	OpenStreamViaLinkProtocolID() protocol.ID
	// OpenStreamViaLinkOpenOpts returns the open stream options.
	// Cannot be empty.
	OpenStreamViaLinkOpenOpts() stream.OpenOpts
	// OpenStreamViaLinkTransportConstraint returns a specific transport ID we want.
	// Can be empty.
	// Used to guarantee the same link is selected.
	OpenStreamViaLinkTransportConstraint() uint64
}

OpenStreamViaLink is a directive to open a stream with a peer over an established link. Not de-duplicated, intended to be used with OneOff.

func NewOpenStreamViaLink

func NewOpenStreamViaLink(
	linkUUID uint64,
	protocolID protocol.ID,
	openOpts stream.OpenOpts,
	transportConstraint uint64,
) OpenStreamViaLink

NewOpenStreamViaLink constructs a new openStreamViaLink directive.

type OpenStreamViaLinkValue

type OpenStreamViaLinkValue = MountedStream

OpenStreamViaLinkValue is the value of OpenStreamViaLink.

type OpenStreamWithPeer

type OpenStreamWithPeer interface {
	// Directive indicates OpenStreamWithPeer is a directive.
	directive.Directive

	// OpenStreamWithPeerProtocolID returns the protocol ID to negotiate with the peer.
	// Cannot be empty.
	OpenStreamWPProtocolID() protocol.ID
	// OpenStreamWithPeerTargetPeerID returns the target peer ID.
	// Cannot be empty.
	OpenStreamWPTargetPeerID() peer.ID
	// OpenStreamWithPeerOpenOpts returns the open stream options.
	// Cannot be empty.
	OpenStreamWPOpenOpts() stream.OpenOpts

	// OpenStreamWithPeerSourcePeerID returns the source peer ID.
	// Can be empty.
	OpenStreamWPSourcePeerID() peer.ID
	// OpenStreamWithPeerTransportConstraint returns a specific transport ID we want.
	// Can be empty.
	OpenStreamWPTransportConstraint() uint64
}

OpenStreamWithPeer is a directive to open a stream with a peer. Not de-duplicated, intended to be used with OneOff.

func NewOpenStreamWithPeer

func NewOpenStreamWithPeer(
	protocolID protocol.ID,
	sourcePeerID, targetPeerID peer.ID,
	transportConstraint uint64,
	openOpts stream.OpenOpts,
) OpenStreamWithPeer

NewOpenStreamWithPeer constructs a new openStreamWithPeer directive.