local

Documentation

Overview

Package local provides a local forwarding endpoint implementation.

Index

• Variables
• func NewDialerEndpoint(version forwarding.Version, configuration *forwarding.Configuration, ...) (forwarding.Endpoint, error)
• func NewListenerEndpoint(version forwarding.Version, configuration *forwarding.Configuration, ...) (forwarding.Endpoint, error)

Variables

var DisableLazyListenerInitialization bool

DisableLazyListenerInitialization indicates that lazy listener initialization should be disabled for all endpoints in the current process. It must be set during an init function and must not be changed later. This should only be used for integration tests, where lazy listener initialization needs to be disabled for proper coordination.

Functions

func NewDialerEndpoint

func NewDialerEndpoint(
	version forwarding.Version,
	configuration *forwarding.Configuration,
	protocol string,
	address string,
) (forwarding.Endpoint, error)

NewDialerEndpoint creates a new forwarding.Endpoint that acts as a dialer.

func NewListenerEndpoint

func NewListenerEndpoint(
	version forwarding.Version,
	configuration *forwarding.Configuration,
	protocol string,
	address string,
	lazy bool,
) (forwarding.Endpoint, error)

NewListenerEndpoint creates a new forwarding.Endpoint that behaves as a listener. If lazy is true, then the underlying listener won't be initialized until the first call to Open. This is recommended for local endpoints since their primary use case is forwarding to remote endpoints whose connections may take longer to establish, thus leaving a window open where the accept backlog for the listener makes it appear that there's an active listener even though the forwarding loop isn't yet accepting connections. It is not recommended for remote endpoints because there's no good mechanism to report lazy initialization errors. Fortunately, for remote listeners, the most common use case is remote-to-local forwarding, meaning that there won't be much delay between the time the listener is established and the time that it starts accepting connections.

TODO: We might want to create a better post-initialization error reporting mechanism for remote endpoints so that they can switch to using lazy initialization. This is pretty complicated since yamux owns the wire at that point and doesn't provide a mechanism for performing that error transmission. In any event, this would require a breaking change to the Mutagen forwarding protocol, and the benefit would be for a fairly niche scenario of a fairly niche use case (i.e. remote-to-remote forwarding where only the source endpoint connects and there is some application behaving badly while blocked on that listener's backlog). I think we should wait until there's some demand for that, but certainly consider proactively addressing it if we decide to refactor the forwarding protocol. In any case, this TODO belongs to the remote endpoint package rather than the local one.