tunnel

package
v1.4.2-beta.1 Latest Latest
Warning

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

Go to latest
Published: Jul 7, 2026 License: MPL-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package tunnel provides the functions used by the CLI to tunnel into a container using either a tunneled connection from the workspace client (using a machine provider) or a direct SSH connection from the proxy client (Ssh, k8s or docker provider)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClassifyTunnelErrors added in v1.1.0

func ClassifyTunnelErrors(tunnelErr, handlerErr error) error

func CreateSSHCommand

func CreateSSHCommand(
	ctx context.Context,
	client client2.BaseWorkspaceClient,
	extraArgs []string,
) (*exec.Cmd, error)

CreateSSHCommand builds an exec.Cmd that runs `devsy ssh` with the given arguments.

func IsEOF added in v1.1.0

func IsEOF(err error) bool

func NewTunnel

func NewTunnel(ctx context.Context, tunnel Tunnel, handler Handler) error

NewTunnel creates a tunnel to the devcontainer using generic functions to establish the "outer" and "inner" tunnel, used by proxy clients. The tunnel will be an SSH connection with its STDIO as arguments and the handler will be the function to execute the command using the connected SSH client.

func RunServices

func RunServices(ctx context.Context, opts RunServicesOptions) error

RunServices forwards the ports for a given workspace and uses its SSH client to run the credentials server remotely and the services server locally to communicate with the container.

func SetupBackhaul

func SetupBackhaul(
	ctx context.Context,
	client client2.BaseWorkspaceClient,
	authSockID string,
) error

SetupBackhaul sets up a long-running SSH connection for backhaul.

func StartBrowserTunnel

func StartBrowserTunnel(ctx context.Context, p BrowserTunnelParams) error

StartBrowserTunnel sets up a browser tunnel for IDE access, either via daemon or SSH.

Types

type BrowserTunnelParams

type BrowserTunnelParams struct {
	DevsyConfig      *config.Config
	Client           client2.BaseWorkspaceClient
	User             string
	TargetURL        string
	ForwardPorts     bool
	ExtraPorts       []string
	AuthSockID       string
	GitSSHSigningKey string

	// ExtraListeners holds pre-bound listeners for ExtraPorts entries,
	// keyed by host addr (e.g. "localhost:10800"). Set by the parent so the
	// helper can skip net.Listen and avoid a probe-to-listen TOCTOU race.
	ExtraListeners map[string]net.Listener

	// DaemonStartFunc is called when the client is a DaemonClient.
	// If nil, the SSH tunnel path is always used.
	DaemonStartFunc func(ctx context.Context) error

	// DisableIdleTimeout opts forwarded ports out of the
	// EXIT_AFTER_TIMEOUT idle shutdown. Set by callers whose lifecycle
	// is managed out-of-band (e.g. the detached browser-tunnel helper,
	// reaped by KillBrowserTunnel and devsy stop/delete).
	DisableIdleTimeout bool
}

BrowserTunnelParams bundles the arguments for browser-based IDE tunnels.

type ContainerTunnel

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

ContainerTunnel manages the state of the tunnel to the container.

func NewContainerTunnel

func NewContainerTunnel(client client.WorkspaceClient) *ContainerTunnel

NewContainerTunnel constructs a ContainerTunnel using the workspace client, if proxy is True then the workspace's agent config is not periodically updated.

func (*ContainerTunnel) Run

func (c *ContainerTunnel) Run(
	ctx context.Context,
	handler Handler,
	cfg *config.Config,
	envVars map[string]string,
) error

Run creates an "outer" tunnel to the host to start the SSH server so that the "inner" tunnel can connect to the container over SSH.

type DialFunc added in v1.3.1

type DialFunc func(ctx context.Context) (io.ReadWriteCloser, error)

DialFunc establishes a connection to the remote SSH server. Each call returns a new bidirectional stream to the container SSH port.

type ErrorKind added in v1.1.0

type ErrorKind int
const (
	ErrorTransient ErrorKind = iota
	ErrorPermanent
	ErrorShutdown
)

func ClassifyError added in v1.1.0

func ClassifyError(err error) ErrorKind

type Handler

type Handler func(ctx context.Context, containerClient *ssh.Client) error

Handler defines what to do once the tunnel has a client established.

type HandlerFunc added in v1.1.0

type HandlerFunc func(ctx context.Context, stdout *os.File, stdin *os.File) error

type LocalTunnel added in v1.3.1

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

LocalTunnel manages a local TCP listener that forwards connections to a container SSH server through the Devsy tunnel infrastructure.

func NewLocalTunnel added in v1.3.1

func NewLocalTunnel(ctx context.Context, opts LocalTunnelOptions) (*LocalTunnel, error)

NewLocalTunnel creates and starts a local TCP listener that forwards connections to the container SSH server.

func (*LocalTunnel) Addr added in v1.3.1

func (t *LocalTunnel) Addr() string

Addr returns the full listener address (e.g., "127.0.0.1:10800").

func (*LocalTunnel) Close added in v1.3.1

func (t *LocalTunnel) Close() error

Close shuts down the tunnel listener and waits for active connections to finish.

func (*LocalTunnel) Port added in v1.3.1

func (t *LocalTunnel) Port() int

Port returns the local port the tunnel is listening on.

type LocalTunnelOptions added in v1.3.1

type LocalTunnelOptions struct {
	// BasePort is the starting port to search from (default: 10800)
	BasePort int
	// DialFunc creates a connection to the remote SSH endpoint
	DialFunc DialFunc
	// HealthCheckInterval overrides the default health check interval (for testing).
	// If zero, defaults to healthCheckInterval (30s).
	HealthCheckInterval time.Duration
}

LocalTunnelOptions configures a local TCP tunnel.

type PipeBridge added in v1.1.0

type PipeBridge struct {
	StdoutReader *os.File
	StdoutWriter *os.File
	StdinReader  *os.File
	StdinWriter  *os.File
}

func NewPipeBridge added in v1.1.0

func NewPipeBridge() (*PipeBridge, error)

func (*PipeBridge) Close added in v1.1.0

func (pb *PipeBridge) Close()

func (*PipeBridge) RunPair added in v1.1.0

func (pb *PipeBridge) RunPair(
	ctx context.Context,
	tunnelFn TunnelFunc,
	handlerFn HandlerFunc,
) error

type PortAttributeResolver added in v1.1.0

type PortAttributeResolver func(port string) config2.PortAttribute

PortAttributeResolver resolves port attributes for a given port string.

func NewPortAttributeResolver added in v1.1.0

func NewPortAttributeResolver(
	portsAttrs map[string]config2.PortAttribute,
	fallback *config2.PortAttribute,
) PortAttributeResolver

NewPortAttributeResolver builds a resolver from the devcontainer config.

type RunServicesOptions

type RunServicesOptions struct {
	DevsyConfig                    *config.Config
	ContainerClient                *ssh.Client
	User                           string
	ForwardPorts                   bool
	ExtraPorts                     []string
	PlatformOptions                *devsy.PlatformOptions
	Workspace                      *provider.Workspace
	ConfigureDockerCredentials     bool
	ConfigureGitCredentials        bool
	ConfigureGitSSHSignatureHelper bool
	GitSSHSigningKey               string
	// ExtraListeners holds pre-bound listeners keyed by "host:port" so the
	// helper can skip net.Listen and avoid a probe-to-listen TOCTOU race.
	ExtraListeners map[string]net.Listener
	// DisableIdleTimeout forces a zero idle-shutdown duration regardless of
	// the EXIT_AFTER_TIMEOUT context option. Used by callers reaped
	// out-of-band rather than by idle activity.
	DisableIdleTimeout bool
}

RunServicesOptions contains all options for running services.

type Tunnel

type Tunnel func(ctx context.Context, stdin io.Reader, stdout io.Writer) error

Tunnel defines the function to create an "outer" tunnel.

type TunnelFunc added in v1.1.0

type TunnelFunc func(ctx context.Context, stdin *os.File, stdout *os.File) error

type WorkspaceDialer added in v1.3.1

type WorkspaceDialer struct {
	// DevsyBinary is the path to the devsy binary. If empty, os.Executable() is used.
	DevsyBinary string
	// Context is the Devsy context name
	Context string
	// User is the workspace user
	User string
	// Workspace is the workspace name/ID
	Workspace string
	// Workdir is the optional working directory
	Workdir string
	// GPGAgent enables GPG agent forwarding
	GPGAgent bool
}

func (*WorkspaceDialer) Dial added in v1.3.1

Dial creates a new connection to the workspace by spawning devsy ssh --stdio. Each call creates an independent connection, allowing multiple simultaneous SSH sessions (e.g. VS Code opening several connections).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL