link

Documentation

Index

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

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.

Used in several places to pass stream info via Context, for example: - stream/srpc/server: attach stream info to RPC context - stream/drpc/server: attach stream info to RPC context

func GetMountedStreamContext

func GetMountedStreamContext(ctx context.Context) MountedStreamContext

GetMountedStreamContext returns the MountedStreamContext from the Context or nil 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.