forwarding

package
v0.12.0-beta7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2021 License: MIT Imports: 24 Imported by: 1

Documentation

Overview

Package forwarding provides infrastructure for forwarding sessions.

Index

Constants

This section is empty.

Variables

View Source 
var (
	SocketOverwriteMode_name = map[int32]string{
		0: "SocketOverwriteModeDefault",
		1: "SocketOverwriteModeLeave",
		2: "SocketOverwriteModeOverwrite",
	}
	SocketOverwriteMode_value = map[string]int32{
		"SocketOverwriteModeDefault":   0,
		"SocketOverwriteModeLeave":     1,
		"SocketOverwriteModeOverwrite": 2,
	}
)

Enum value maps for SocketOverwriteMode.

View Source 
var (
	Status_name = map[int32]string{
		0: "Disconnected",
		1: "ConnectingSource",
		2: "ConnectingDestination",
		3: "ForwardingConnections",
	}
	Status_value = map[string]int32{
		"Disconnected":          0,
		"ConnectingSource":      1,
		"ConnectingDestination": 2,
		"ForwardingConnections": 3,
	}
)

Enum value maps for Status.

View Source 
var (
	Version_name = map[int32]string{
		0: "Invalid",
		1: "Version1",
	}
	Version_value = map[string]int32{
		"Invalid":  0,
		"Version1": 1,
	}
)

Enum value maps for Version.

View Source 
var File_forwarding_configuration_proto protoreflect.FileDescriptor
View Source 
var File_forwarding_session_proto protoreflect.FileDescriptor
View Source 
var File_forwarding_socket_overwrite_mode_proto protoreflect.FileDescriptor
View Source 
var File_forwarding_state_proto protoreflect.FileDescriptor
View Source 
var File_forwarding_version_proto protoreflect.FileDescriptor
View Source 
var ProtocolHandlers = map[urlpkg.Protocol]ProtocolHandler{}

ProtocolHandlers is a map of registered protocol handlers. It should only be modified during init() operations.

Functions

func ForwardAndClose added in v0.10.2 

func ForwardAndClose(ctx context.Context, first, second net.Conn)

ForwardAndClose performs bidirectional forwarding between the specified connections. It waits for both directions to see EOF, for one direction to see an error, or for context cancellation. Once one of these events occurs, the connections are closed (terminating forwarding) and the function returns. Both connections must implement CloseWriter or this function will panic.

Types

type Configuration 

type Configuration struct {

	// SocketOverwriteMode specifies whether or not existing Unix domain sockets
	// should be overwritten when creating new listener sockets.
	SocketOverwriteMode SocketOverwriteMode `` /* 129-byte string literal not displayed */
	// SocketOwner specifies the owner identifier to use for Unix domain
	// listener sockets.
	SocketOwner string `protobuf:"bytes,42,opt,name=socketOwner,proto3" json:"socketOwner,omitempty"`
	// SocketGroup specifies the group identifier to use for Unix domain
	// listener sockets.
	SocketGroup string `protobuf:"bytes,43,opt,name=socketGroup,proto3" json:"socketGroup,omitempty"`
	// SocketPermissionMode specifies the permission mode to use for Unix domain
	// listener sockets.
	SocketPermissionMode uint32 `protobuf:"varint,44,opt,name=socketPermissionMode,proto3" json:"socketPermissionMode,omitempty"`
	// contains filtered or unexported fields
}

Configuration encodes session configuration parameters. It is used for create commands to specify configuration options, for loading global configuration options, and for storing a merged configuration inside sessions. It should be considered immutable.

func MergeConfigurations 

func MergeConfigurations(lower, higher *Configuration) *Configuration

MergeConfigurations merges two configurations of differing priorities. Both configurations must be non-nil.

func (*Configuration) Descriptor deprecated 

func (*Configuration) Descriptor() ([]byte, []int)

Deprecated: Use Configuration.ProtoReflect.Descriptor instead.

func (*Configuration) EnsureValid 

func (c *Configuration) EnsureValid(endpointSpecific bool) error

EnsureValid ensures that Configuration's invariants are respected. The validation of the configuration depends on whether or not it is endpoint-specific.

func (*Configuration) Equal added in v0.12.0 

func (c *Configuration) Equal(other *Configuration) bool

Equal returns whether or not the configuration is equivalent to another. The result of this method is only valid if both configurations are valid.

func (*Configuration) GetSocketGroup 

func (x *Configuration) GetSocketGroup() string

func (*Configuration) GetSocketOverwriteMode 

func (x *Configuration) GetSocketOverwriteMode() SocketOverwriteMode

func (*Configuration) GetSocketOwner 

func (x *Configuration) GetSocketOwner() string

func (*Configuration) GetSocketPermissionMode 

func (x *Configuration) GetSocketPermissionMode() uint32

func (*Configuration) ProtoMessage 

func (*Configuration) ProtoMessage()

func (*Configuration) ProtoReflect added in v0.12.0 

func (x *Configuration) ProtoReflect() protoreflect.Message

func (*Configuration) Reset 

func (x *Configuration) Reset()

func (*Configuration) String 

func (x *Configuration) String() string

type Endpoint 

type Endpoint interface {
	// TransportErrors returns a channel that will be populated if an error
	// occurs on the underlying transport. This is necessary for forwarding
	// endpoints because (unlike synchronization endpoints) there's no
	// simultaneous polling of both endpoints that will detect connection
	// failure. By monitoring for transport errors separately, the forwarding
	// loop can be cancelled immediately (instead of waiting for a dial
	// operation to fail once the next connection is accepted). The endpoint
	// should make no assumptions about whether this method will be called or
	// whether the resulting channel will be read from. Callers should make no
	// assumptions about whether or not the resulting channel will be populated.
	// The returned channel may be nil if transport errors are not possible for
	// the endpoint (e.g. with local endpoints).
	TransportErrors() <-chan error

	// Open should open a network connection for the endpoint. For listener
	// (source) endpoints, this function should block until an incoming
	// connection arrives. For dialer (destination) endpoints, this function
	// should dial the underlying target.
	Open() (net.Conn, error)

	// Shutdown shuts down the endpoint. This function must unblock any pending
	// Open call.
	Shutdown() error
}

Endpoint is a generic network connectivity interface that can represent both listening or dialing. None of its methods should be considered safe for concurrent invocation except Shutdown.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager provides forwarding session management facilities. Its methods are safe for concurrent usage, so it can be easily exported via an RPC interface.

func NewManager 

func NewManager(logger *logging.Logger) (*Manager, error)

NewManager creates a new Manager instance.

func (*Manager) Create 

func (m *Manager) Create(
	ctx context.Context,
	source, destination *url.URL,
	configuration, configurationSource, configurationDestination *Configuration,
	name string,
	labels map[string]string,
	paused bool,
	prompter string,
) (string, error)

Create tells the manager to create a new session.

func (*Manager) List 

func (m *Manager) List(_ context.Context, selection *selection.Selection, previousStateIndex uint64) (uint64, []*State, error)

List requests a state snapshot for the specified sessions.

func (*Manager) Pause 

func (m *Manager) Pause(ctx context.Context, selection *selection.Selection, prompter string) error

Pause tells the manager to pause sessions matching the given specifications.

func (*Manager) Resume 

func (m *Manager) Resume(ctx context.Context, selection *selection.Selection, prompter string) error

Resume tells the manager to resume sessions matching the given specifications.

func (*Manager) Shutdown 

func (m *Manager) Shutdown()

Shutdown tells the manager to gracefully halt sessions.

func (*Manager) Terminate 

func (m *Manager) Terminate(ctx context.Context, selection *selection.Selection, prompter string) error

Terminate tells the manager to terminate sessions matching the given specifications.

type ProtocolHandler 

type ProtocolHandler interface {
	// Connect connects to an endpoint using the connection parameters in the
	// provided URL and the specified prompter (if any). It then initializes the
	// endpoint using the specified parameters.
	Connect(
		ctx context.Context,
		logger *logging.Logger,
		url *urlpkg.URL,
		prompter string,
		session string,
		version Version,
		configuration *Configuration,
		source bool,
	) (Endpoint, error)
}

ProtocolHandler defines the interface that protocol handlers must support in order to connect to endpoints.

type Session 

type Session struct {

	// Identifier is the (unique) session identifier. It is static. It cannot be
	// empty.
	Identifier string `protobuf:"bytes,1,opt,name=identifier,proto3" json:"identifier,omitempty"`
	// Version is the session version. It is static.
	Version Version `protobuf:"varint,2,opt,name=version,proto3,enum=forwarding.Version" json:"version,omitempty"`
	// CreationTime is the creation time of the session. It is static. It cannot
	// be nil.
	CreationTime *timestamppb.Timestamp `protobuf:"bytes,3,opt,name=creationTime,proto3" json:"creationTime,omitempty"`
	// CreatingVersionMajor is the major version component of the version of
	// Mutagen which created the session. It is static.
	CreatingVersionMajor uint32 `protobuf:"varint,4,opt,name=creatingVersionMajor,proto3" json:"creatingVersionMajor,omitempty"`
	// CreatingVersionMinor is the minor version component of the version of
	// Mutagen which created the session. It is static.
	CreatingVersionMinor uint32 `protobuf:"varint,5,opt,name=creatingVersionMinor,proto3" json:"creatingVersionMinor,omitempty"`
	// CreatingVersionPatch is the patch version component of the version of
	// Mutagen which created the session. It is static.
	CreatingVersionPatch uint32 `protobuf:"varint,6,opt,name=creatingVersionPatch,proto3" json:"creatingVersionPatch,omitempty"`
	// Source is the source endpoint URL. It is static. It cannot be nil.
	Source *url.URL `protobuf:"bytes,7,opt,name=source,proto3" json:"source,omitempty"`
	// Destination is the destination endpoint URL. It is static. It cannot be
	// nil.
	Destination *url.URL `protobuf:"bytes,8,opt,name=destination,proto3" json:"destination,omitempty"`
	// Configuration is the flattened session configuration. It is static. It
	// cannot be nil.
	Configuration *Configuration `protobuf:"bytes,9,opt,name=configuration,proto3" json:"configuration,omitempty"`
	// ConfigurationSource are the source-specific session configuration
	// overrides. It is static.
	ConfigurationSource *Configuration `protobuf:"bytes,10,opt,name=configurationSource,proto3" json:"configurationSource,omitempty"`
	// ConfigurationDestination are the destination-specific session
	// configuration overrides. It is static.
	ConfigurationDestination *Configuration `protobuf:"bytes,11,opt,name=configurationDestination,proto3" json:"configurationDestination,omitempty"`
	// Name is a user-friendly name for the session. It may be empty and is not
	// guaranteed to be unique across all sessions. It is only used as a simpler
	// handle for specifying sessions. It is static.
	Name string `protobuf:"bytes,12,opt,name=name,proto3" json:"name,omitempty"`
	// Labels are the session labels. They are static.
	Labels map[string]string `` /* 154-byte string literal not displayed */
	// Paused indicates whether or not the session is marked as paused.
	Paused bool `protobuf:"varint,14,opt,name=paused,proto3" json:"paused,omitempty"`
	// contains filtered or unexported fields
}

Session represents a forwarding session configuration and persistent state. It is mutable within the context of the daemon, so it should be accessed and modified in a synchronized fashion. Outside of the daemon (e.g. when returned via the API), it should be considered immutable.

func (*Session) Descriptor deprecated 

func (*Session) Descriptor() ([]byte, []int)

Deprecated: Use Session.ProtoReflect.Descriptor instead.

func (*Session) EnsureValid 

func (s *Session) EnsureValid() error

EnsureValid ensures that Session's invariants are respected.

func (*Session) GetConfiguration 

func (x *Session) GetConfiguration() *Configuration

func (*Session) GetConfigurationDestination 

func (x *Session) GetConfigurationDestination() *Configuration

func (*Session) GetConfigurationSource 

func (x *Session) GetConfigurationSource() *Configuration

func (*Session) GetCreatingVersionMajor 

func (x *Session) GetCreatingVersionMajor() uint32

func (*Session) GetCreatingVersionMinor 

func (x *Session) GetCreatingVersionMinor() uint32

func (*Session) GetCreatingVersionPatch 

func (x *Session) GetCreatingVersionPatch() uint32

func (*Session) GetCreationTime 

func (x *Session) GetCreationTime() *timestamppb.Timestamp

func (*Session) GetDestination 

func (x *Session) GetDestination() *url.URL

func (*Session) GetIdentifier 

func (x *Session) GetIdentifier() string

func (*Session) GetLabels 

func (x *Session) GetLabels() map[string]string

func (*Session) GetName 

func (x *Session) GetName() string

func (*Session) GetPaused 

func (x *Session) GetPaused() bool

func (*Session) GetSource 

func (x *Session) GetSource() *url.URL

func (*Session) GetVersion 

func (x *Session) GetVersion() Version

func (*Session) ProtoMessage 

func (*Session) ProtoMessage()

func (*Session) ProtoReflect added in v0.12.0 

func (x *Session) ProtoReflect() protoreflect.Message

func (*Session) Reset 

func (x *Session) Reset()

func (*Session) String 

func (x *Session) String() string

type SocketOverwriteMode 

type SocketOverwriteMode int32

SocketOverwriteMode specifies the behavior for overwriting (removing) existing Unix domain sockets. 

const (
	// SocketOverwriteMode_SocketOverwriteModeDefault represents an unspecified
	// socket overwrite mode. It should be converted to one of the following
	// values based on the desired default behavior.
	SocketOverwriteMode_SocketOverwriteModeDefault SocketOverwriteMode = 0
	// SocketOverwriteMode_SocketOverwriteModeLeave specifies that existing
	// sockets should not be overwritten when creating a Unix domain socket
	// listener.
	SocketOverwriteMode_SocketOverwriteModeLeave SocketOverwriteMode = 1
	// SocketOverwriteMode_SocketOverwriteModeOverwrite specifies that existing
	// sockets should be overwritten when creating a Unix domain socket
	// listener.
	SocketOverwriteMode_SocketOverwriteModeOverwrite SocketOverwriteMode = 2
)

func (SocketOverwriteMode) AttemptOverwrite added in v0.11.2 

func (m SocketOverwriteMode) AttemptOverwrite() bool

AttemptOverwrite indicates whether or not the socket overwrite mode is SocketOverwriteMode_SocketOverwriteModeOverwrite.

func (SocketOverwriteMode) Description 

func (m SocketOverwriteMode) Description() string

Description returns a human-readable description of a socket overwrite mode.

func (SocketOverwriteMode) Descriptor added in v0.12.0 

func (SocketOverwriteMode) Descriptor() protoreflect.EnumDescriptor

func (SocketOverwriteMode) Enum added in v0.12.0 

func (x SocketOverwriteMode) Enum() *SocketOverwriteMode

func (SocketOverwriteMode) EnumDescriptor deprecated 

func (SocketOverwriteMode) EnumDescriptor() ([]byte, []int)

Deprecated: Use SocketOverwriteMode.Descriptor instead.

func (SocketOverwriteMode) IsDefault 

func (m SocketOverwriteMode) IsDefault() bool

IsDefault indicates whether or not the socket overwrite mode is SocketOverwriteMode_SocketOverwriteModeDefault.

func (SocketOverwriteMode) Number added in v0.12.0 

func (x SocketOverwriteMode) Number() protoreflect.EnumNumber

func (SocketOverwriteMode) String 

func (x SocketOverwriteMode) String() string

func (SocketOverwriteMode) Supported 

func (m SocketOverwriteMode) Supported() bool

Supported indicates whether or not a particular socket overwrite mode is a valid, non-default value.

func (SocketOverwriteMode) Type added in v0.12.0 

func (SocketOverwriteMode) Type() protoreflect.EnumType

func (*SocketOverwriteMode) UnmarshalText 

func (m *SocketOverwriteMode) UnmarshalText(textBytes []byte) error

UnmarshalText implements the text unmarshalling interface used when loading from TOML files.

type State 

type State struct {

	// Session is the session specification.
	Session *Session `protobuf:"bytes,1,opt,name=session,proto3" json:"session,omitempty"`
	// Status is the status of the session.
	Status Status `protobuf:"varint,2,opt,name=status,proto3,enum=forwarding.Status" json:"status,omitempty"`
	// SourceConnected indicates whether or not the source endpoint is
	// connected.
	SourceConnected bool `protobuf:"varint,3,opt,name=sourceConnected,proto3" json:"sourceConnected,omitempty"`
	// DestinationConnected indicates whether or not the destination endpoint is
	// connected.
	DestinationConnected bool `protobuf:"varint,4,opt,name=destinationConnected,proto3" json:"destinationConnected,omitempty"`
	// LastError indicates the last error that occurred during forwarding.
	LastError string `protobuf:"bytes,5,opt,name=lastError,proto3" json:"lastError,omitempty"`
	// OpenConnections is the number of connections currently open and being
	// forwarded.
	OpenConnections uint64 `protobuf:"varint,6,opt,name=openConnections,proto3" json:"openConnections,omitempty"`
	// TotalConnections is the number of total connections that have been opened
	// and forwarded (including those that are currently open).
	TotalConnections uint64 `protobuf:"varint,7,opt,name=totalConnections,proto3" json:"totalConnections,omitempty"`
	// contains filtered or unexported fields
}

State encodes the current state of a forwarding session. It is mutable within the context of the daemon, so it should be accessed and modified in a synchronized fashion. Outside of the daemon (e.g. when returned via the API), it should be considered immutable.

func (*State) Descriptor deprecated 

func (*State) Descriptor() ([]byte, []int)

Deprecated: Use State.ProtoReflect.Descriptor instead.

func (*State) EnsureValid 

func (s *State) EnsureValid() error

EnsureValid ensures that State's invariants are respected.

func (*State) GetDestinationConnected 

func (x *State) GetDestinationConnected() bool

func (*State) GetLastError 

func (x *State) GetLastError() string

func (*State) GetOpenConnections 

func (x *State) GetOpenConnections() uint64

func (*State) GetSession 

func (x *State) GetSession() *Session

func (*State) GetSourceConnected 

func (x *State) GetSourceConnected() bool

func (*State) GetStatus 

func (x *State) GetStatus() Status

func (*State) GetTotalConnections 

func (x *State) GetTotalConnections() uint64

func (*State) ProtoMessage 

func (*State) ProtoMessage()

func (*State) ProtoReflect added in v0.12.0 

func (x *State) ProtoReflect() protoreflect.Message

func (*State) Reset 

func (x *State) Reset()

func (*State) String 

func (x *State) String() string

type Status 

type Status int32

Status encodes the status of a forwarding session. 

const (
	// Status_Disconnected indicates that the session is disconnected.
	Status_Disconnected Status = 0
	// Status_ConnectingSource indicates that the session is in the process of
	// connecting to the source endpoint.
	Status_ConnectingSource Status = 1
	// Status_ConnectingDestination indicates that the session is in the process
	// of connecting to the destination endpoint.
	Status_ConnectingDestination Status = 2
	// Status_ForwardingConnections indicates that the session is connected and
	// currently forwarding connections.
	Status_ForwardingConnections Status = 3
)

func (Status) Description 

func (s Status) Description() string

Description returns a human-readable description of the session status.

func (Status) Descriptor added in v0.12.0 

func (Status) Descriptor() protoreflect.EnumDescriptor

func (Status) Enum added in v0.12.0 

func (x Status) Enum() *Status

func (Status) EnumDescriptor deprecated 

func (Status) EnumDescriptor() ([]byte, []int)

Deprecated: Use Status.Descriptor instead.

func (Status) Number added in v0.12.0 

func (x Status) Number() protoreflect.EnumNumber

func (Status) String 

func (x Status) String() string

func (Status) Type added in v0.12.0 

func (Status) Type() protoreflect.EnumType

type Version 

type Version int32

Version specifies a session version, providing default behavior that can vary without affecting existing sessions. 

const (
	// Invalid is the default session version and represents an unspecfied and
	// invalid version. It is used as a sanity check to ensure that version is
	// set for a session.
	Version_Invalid Version = 0
	// Version1 represents session version 1.
	Version_Version1 Version = 1
)

func (Version) DefaultSocketGroupSpecification 

func (v Version) DefaultSocketGroupSpecification() string

DefaultSocketGroupSpecification returns the default socket group specification for the session version.

func (Version) DefaultSocketOverwriteMode 

func (v Version) DefaultSocketOverwriteMode() SocketOverwriteMode

DefaultSocketOverwriteMode returns the default socket overwrite mode for the session version.

func (Version) DefaultSocketOwnerSpecification 

func (v Version) DefaultSocketOwnerSpecification() string

DefaultSocketOwnerSpecification returns the default socket owner specification for the session version.

func (Version) DefaultSocketPermissionMode 

func (v Version) DefaultSocketPermissionMode() filesystem.Mode

DefaultSocketPermissionMode returns the default socket permission mode for the session version.

func (Version) Descriptor added in v0.12.0 

func (Version) Descriptor() protoreflect.EnumDescriptor

func (Version) Enum added in v0.12.0 

func (x Version) Enum() *Version

func (Version) EnumDescriptor deprecated 

func (Version) EnumDescriptor() ([]byte, []int)

Deprecated: Use Version.Descriptor instead.

func (Version) Number added in v0.12.0 

func (x Version) Number() protoreflect.EnumNumber

func (Version) String 

func (x Version) String() string

func (Version) Supported 

func (v Version) Supported() bool

Supported indicates whether or not the session version is supported.

func (Version) Type added in v0.12.0 

func (Version) Type() protoreflect.EnumType

Source Files

View all Source files

Directories

Path Synopsis
Package endpoint provides forwarding endpoint implementations.
 Package endpoint provides forwarding endpoint implementations.
remote
Package remote provides a client/server architecture for connecting to and hosting a remote forwarding endpoint.
 Package remote provides a client/server architecture for connecting to and hosting a remote forwarding endpoint.
Package protocols provides forwarding session protocol handler implementations.
 Package protocols provides forwarding session protocol handler implementations.
docker
Package docker provides the Docker forwarding session protocol implementation.
 Package docker provides the Docker forwarding session protocol implementation.
local
Package local provides the local forwarding session protocol implementation.
 Package local provides the local forwarding session protocol implementation.
ssh
Package ssh provides the SSH forwarding session protocol implementation.
 Package ssh provides the SSH forwarding session protocol implementation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.