workspacesdk

package
v2.21.3 Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2025 License: AGPL-3.0 Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AgentSSHPort             = tailnet.WorkspaceAgentSSHPort
	AgentStandardSSHPort     = tailnet.WorkspaceAgentStandardSSHPort
	AgentReconnectingPTYPort = tailnet.WorkspaceAgentReconnectingPTYPort
	AgentSpeedtestPort       = tailnet.WorkspaceAgentSpeedtestPort
	// AgentHTTPAPIServerPort serves a HTTP server with endpoints for e.g.
	// gathering agent statistics.
	AgentHTTPAPIServerPort = 4

	// AgentMinimumListeningPort is the minimum port that the listening-ports
	// endpoint will return to the client, and the minimum port that is accepted
	// by the proxy applications endpoint. Coder consumes ports 1-4 at the
	// moment, and we reserve some extra ports for future use. Port 9 and up are
	// available for the user.
	//
	// This is not enforced in the CLI intentionally as we don't really care
	// *that* much. The user could bypass this in the CLI by using SSH instead
	// anyways.
	AgentMinimumListeningPort = 9
)
View Source 
const (
	AgentAPIMismatchMessage = "Unknown or unsupported API version"

	CoordinateAPIInvalidResumeToken = "Invalid resume token"
)

Variables

View Source 
var AgentIgnoredListeningPorts = map[uint16]struct{}{
	0: {},

	1: {},
	2: {},
	3: {},
	4: {},
	5: {},
	6: {},
	7: {},
	8: {},

	20: {},
	21: {},

	22: {},

	23: {},

	25: {},

	53: {},

	110: {},

	143: {},

	179: {},

	389: {},
	636: {},

	465: {},

	587: {},

	989: {},
	990: {},

	993: {},

	995: {},

	3306: {},

	3389: {},

	5432: {},

	27017: {},
	27018: {},
	27019: {},
	28017: {},
}

AgentIgnoredListeningPorts contains a list of ports to ignore when looking for running applications inside a workspace. We want to ignore non-HTTP servers, so we pre-populate this list with common ports that are not HTTP servers.

This is implemented as a map for fast lookup.

View Source 
var ErrSkipClose = xerrors.New("skip tailnet close")

Functions

This section is empty.

Types

type AgentConn 

type AgentConn struct {
	*tailnet.Conn
	// contains filtered or unexported fields
}

AgentConn represents a connection to a workspace agent. @typescript-ignore AgentConn

func NewAgentConn 

func NewAgentConn(conn *tailnet.Conn, opts AgentConnOptions) *AgentConn

NewAgentConn creates a new WorkspaceAgentConn. `conn` may be unique to the WorkspaceAgentConn, or it may be shared in the case of coderd. If the conn is shared and closing it is undesirable, you may return ErrNoClose from opts.CloseFunc. This will ensure the underlying conn is not closed.

func (*AgentConn) AwaitReachable 

func (c *AgentConn) AwaitReachable(ctx context.Context) bool

AwaitReachable waits for the agent to be reachable.

func (*AgentConn) Close 

func (c *AgentConn) Close() error

Close ends the connection to the workspace agent.

func (*AgentConn) DebugLogs 

func (c *AgentConn) DebugLogs(ctx context.Context) ([]byte, error)

DebugLogs returns up to the last 10MB of `/tmp/coder-agent.log`

func (*AgentConn) DebugMagicsock 

func (c *AgentConn) DebugMagicsock(ctx context.Context) ([]byte, error)

DebugMagicsock makes a request to the workspace agent's magicsock debug endpoint.

func (*AgentConn) DebugManifest 

func (c *AgentConn) DebugManifest(ctx context.Context) ([]byte, error)

DebugManifest returns the agent's in-memory manifest. Unfortunately this must be returns as a []byte to avoid an import cycle.

func (*AgentConn) DialContext 

func (c *AgentConn) DialContext(ctx context.Context, network string, addr string) (net.Conn, error)

DialContext dials the address provided in the workspace agent. The network must be "tcp" or "udp".

func (*AgentConn) GetPeerDiagnostics 

func (c *AgentConn) GetPeerDiagnostics() tailnet.PeerDiagnostics

func (*AgentConn) ListContainers added in v2.20.0 

func (c *AgentConn) ListContainers(ctx context.Context) (codersdk.WorkspaceAgentListContainersResponse, error)

ListContainers returns a response from the agent's containers endpoint

func (*AgentConn) ListeningPorts 

func (c *AgentConn) ListeningPorts(ctx context.Context) (codersdk.WorkspaceAgentListeningPortsResponse, error)

ListeningPorts lists the ports that are currently in use by the workspace.

func (*AgentConn) Netcheck added in v2.15.0 

func (c *AgentConn) Netcheck(ctx context.Context) (healthsdk.AgentNetcheckReport, error)

Netcheck returns a network check report from the workspace agent.

func (*AgentConn) Ping 

func (c *AgentConn) Ping(ctx context.Context) (time.Duration, bool, *ipnstate.PingResult, error)

Ping pings the agent and returns the round-trip time. The bool returns true if the ping was made P2P.

func (*AgentConn) PrometheusMetrics 

func (c *AgentConn) PrometheusMetrics(ctx context.Context) ([]byte, error)

PrometheusMetrics returns a response from the agent's prometheus metrics endpoint

func (*AgentConn) ReconnectingPTY 

func (c *AgentConn) ReconnectingPTY(ctx context.Context, id uuid.UUID, height, width uint16, command string, initOpts ...AgentReconnectingPTYInitOption) (net.Conn, error)

ReconnectingPTY spawns a new reconnecting terminal session. `ReconnectingPTYRequest` should be JSON marshaled and written to the returned net.Conn. Raw terminal output will be read from the returned net.Conn.

func (*AgentConn) SSH 

func (c *AgentConn) SSH(ctx context.Context) (*gonet.TCPConn, error)

SSH pipes the SSH protocol over the returned net.Conn. This connects to the built-in SSH server in the workspace agent.

func (*AgentConn) SSHClient 

func (c *AgentConn) SSHClient(ctx context.Context) (*ssh.Client, error)

SSHClient calls SSH to create a client that uses a weak cipher to improve throughput.

func (*AgentConn) SSHClientOnPort added in v2.20.0 

func (c *AgentConn) SSHClientOnPort(ctx context.Context, port uint16) (*ssh.Client, error)

SSHClientOnPort calls SSH to create a client on a specific port that uses a weak cipher to improve throughput.

func (*AgentConn) SSHOnPort added in v2.20.0 

func (c *AgentConn) SSHOnPort(ctx context.Context, port uint16) (*gonet.TCPConn, error)

SSHOnPort pipes the SSH protocol over the returned net.Conn. This connects to the built-in SSH server in the workspace agent on the specified port.

func (*AgentConn) Speedtest 

func (c *AgentConn) Speedtest(ctx context.Context, direction speedtest.Direction, duration time.Duration) ([]speedtest.Result, error)

Speedtest runs a speedtest against the workspace agent.

type AgentConnOptions 

type AgentConnOptions struct {
	AgentID   uuid.UUID
	CloseFunc func() error
}

@typescript-ignore AgentConnOptions

type AgentConnectionInfo 

type AgentConnectionInfo struct {
	DERPMap                  *tailcfg.DERPMap `json:"derp_map"`
	DERPForceWebSockets      bool             `json:"derp_force_websockets"`
	DisableDirectConnections bool             `json:"disable_direct_connections"`
}

AgentConnectionInfo returns required information for establishing a connection with a workspace. @typescript-ignore AgentConnectionInfo

type AgentReconnectingPTYInit 

type AgentReconnectingPTYInit struct {
	ID      uuid.UUID
	Height  uint16
	Width   uint16
	Command string
	// Container, if set, will attempt to exec into a running container visible to the agent.
	// This should be a unique container ID (implementation-dependent).
	Container string
	// ContainerUser, if set, will set the target user when execing into a container.
	// This can be a username or UID, depending on the underlying implementation.
	// This is ignored if Container is not set.
	ContainerUser string

	BackendType string
}

AgentReconnectingPTYInit initializes a new reconnecting PTY session. @typescript-ignore AgentReconnectingPTYInit

type AgentReconnectingPTYInitOption added in v2.21.0 

type AgentReconnectingPTYInitOption func(*AgentReconnectingPTYInit)

AgentReconnectingPTYInitOption is a functional option for AgentReconnectingPTYInit.

func AgentReconnectingPTYInitWithContainer added in v2.21.0 

func AgentReconnectingPTYInitWithContainer(container, containerUser string) AgentReconnectingPTYInitOption

AgentReconnectingPTYInitWithContainer sets the container and container user for the reconnecting PTY session.

type Client 

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

func New 

func New(c *codersdk.Client) *Client

func (*Client) AgentConnectionInfo 

func (c *Client) AgentConnectionInfo(ctx context.Context, agentID uuid.UUID) (AgentConnectionInfo, error)

func (*Client) AgentConnectionInfoGeneric 

func (c *Client) AgentConnectionInfoGeneric(ctx context.Context) (AgentConnectionInfo, error)

func (*Client) AgentReconnectingPTY 

func (c *Client) AgentReconnectingPTY(ctx context.Context, opts WorkspaceAgentReconnectingPTYOpts) (net.Conn, error)

AgentReconnectingPTY spawns a PTY that reconnects using the token provided. It communicates using `agent.ReconnectingPTYRequest` marshaled as JSON. Responses are PTY output that can be rendered.

func (*Client) DialAgent 

func (c *Client) DialAgent(dialCtx context.Context, agentID uuid.UUID, options *DialAgentOptions) (agentConn *AgentConn, err error)

type DialAgentOptions 

type DialAgentOptions struct {
	Logger slog.Logger
	// BlockEndpoints forced a direct connection through DERP. The Client may
	// have DisableDirect set which will override this value.
	BlockEndpoints bool
	// CaptureHook is a callback that captures Disco packets and packets sent
	// into the tailnet tunnel.
	CaptureHook capture.Callback
	// Whether the client will send network telemetry events.
	// Enable instead of Disable so it's initialized to false (in tests).
	EnableTelemetry bool
}

@typescript-ignore DialAgentOptions

type ReconnectingPTYRequest 

type ReconnectingPTYRequest struct {
	Data   string `json:"data,omitempty"`
	Height uint16 `json:"height,omitempty"`
	Width  uint16 `json:"width,omitempty"`
}

ReconnectingPTYRequest is sent from the client to the server to pipe data to a PTY. @typescript-ignore ReconnectingPTYRequest

type WebsocketDialer added in v2.18.0 

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

func NewWebsocketDialer added in v2.18.0 

func NewWebsocketDialer(
	logger slog.Logger, u *url.URL, websocketOptions *websocket.DialOptions,
	dialerOptions ...WebsocketDialerOption,
) *WebsocketDialer

func (*WebsocketDialer) Connected added in v2.18.0 

func (w *WebsocketDialer) Connected() <-chan error

func (*WebsocketDialer) Dial added in v2.18.0 

func (w *WebsocketDialer) Dial(ctx context.Context, r tailnet.ResumeTokenController,
) (
	tailnet.ControlProtocolClients, error,
)

type WebsocketDialerOption added in v2.18.0 

type WebsocketDialerOption func(*WebsocketDialer)

func WithWorkspaceUpdates added in v2.18.0 

func WithWorkspaceUpdates(req *proto.WorkspaceUpdatesRequest) WebsocketDialerOption

type WorkspaceAgentReconnectingPTYOpts 

type WorkspaceAgentReconnectingPTYOpts struct {
	AgentID   uuid.UUID
	Reconnect uuid.UUID
	Width     uint16
	Height    uint16
	Command   string

	// SignedToken is an optional signed token from the
	// issue-reconnecting-pty-signed-token endpoint. If set, the session token
	// on the client will not be sent.
	SignedToken string

	// Experimental: Container, if set, will attempt to exec into a running container
	// visible to the agent. This should be a unique container ID
	// (implementation-dependent).
	// ContainerUser is the user as which to exec into the container.
	// NOTE: This feature is currently experimental and is currently "opt-in".
	// In order to use this feature, the agent must have the environment variable
	// CODER_AGENT_DEVCONTAINERS_ENABLE set to "true".
	Container     string
	ContainerUser string

	// BackendType is the type of backend to use for the PTY. If not set, the
	// workspace agent will attempt to determine the preferred backend type.
	// Supported values are "screen" and "buffered".
	BackendType string
}

@typescript-ignore:WorkspaceAgentReconnectingPTYOpts

Source Files

View all Source files

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.