Thanks to visit codestin.com
Credit goes to pkg.go.dev

agentcontainers

package
v2.24.0 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2025 License: AGPL-3.0 Imports: 41 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DevcontainerLocalFolderLabel is the label that contains the path to
	// the local workspace folder for a devcontainer.
	DevcontainerLocalFolderLabel = "devcontainer.local_folder"
	// DevcontainerConfigFileLabel is the label that contains the path to
	// the devcontainer.json configuration file.
	DevcontainerConfigFileLabel = "devcontainer.config_file"
	// DevcontainerIsTestRunLabel is set if the devcontainer is part of a test
	// and should be excluded.
	DevcontainerIsTestRunLabel = "devcontainer.is_test_run"
	// The default workspace folder inside the devcontainer.
	DevcontainerDefaultContainerWorkspaceFolder = "/workspaces"
)

Variables

This section is empty.

Functions

func ExpandAllDevcontainerPaths added in v2.23.0 

func ExpandAllDevcontainerPaths(logger slog.Logger, expandPath func(string) (string, error), devcontainers []codersdk.WorkspaceAgentDevcontainer) []codersdk.WorkspaceAgentDevcontainer

ExpandAllDevcontainerPaths expands all devcontainer paths in the given devcontainers. This is required by the devcontainer CLI, which requires absolute paths for the workspace folder and config path.

func ExtractDevcontainerScripts added in v2.24.0 

func ExtractDevcontainerScripts(
	devcontainers []codersdk.WorkspaceAgentDevcontainer,
	scripts []codersdk.WorkspaceAgentScript,
) (filteredScripts []codersdk.WorkspaceAgentScript, devcontainerScripts map[uuid.UUID]codersdk.WorkspaceAgentScript)

Types

type API added in v2.22.0 

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

API is responsible for container-related operations in the agent. It provides methods to list and manage containers.

func NewAPI added in v2.22.0 

func NewAPI(logger slog.Logger, options ...Option) *API

NewAPI returns a new API with the given options applied.

func (*API) Close added in v2.22.0 

func (api *API) Close() error

func (*API) CreateDevcontainer added in v2.24.0 

func (api *API) CreateDevcontainer(workspaceFolder, configPath string, opts ...DevcontainerCLIUpOptions) error

createDevcontainer should run in its own goroutine and is responsible for recreating a devcontainer based on the provided devcontainer configuration. It updates the devcontainer status and logs the process. The configPath is passed as a parameter for the odd chance that the container being recreated has a different config file than the one stored in the devcontainer state. The devcontainer state must be set to starting and the asyncWg must be incremented before calling this function.

func (*API) Init added in v2.24.0 

func (api *API) Init(opts ...Option)

Init applies a final set of options to the API and then closes initDone. This method can only be called once.

func (*API) RefreshContainers added in v2.24.0 

func (api *API) RefreshContainers(ctx context.Context) (err error)

RefreshContainers triggers an immediate update of the container list and waits for it to complete.

func (*API) Routes added in v2.22.0 

func (api *API) Routes() http.Handler

Routes returns the HTTP handler for container-related routes.

func (*API) Start added in v2.24.0 

func (api *API) Start()

Start starts the API by initializing the watcher and updater loops. This method calls Init, if it is desired to apply options after the API has been created, it should be done by calling Init before Start. This method must only be called once.

func (*API) UpdateSubAgentClient added in v2.24.0 

func (api *API) UpdateSubAgentClient(client SubAgentClient)

UpdateSubAgentClient updates the `SubAgentClient` for the API.

type CoderCustomization added in v2.24.0 

type CoderCustomization struct {
	DisplayApps map[codersdk.DisplayApp]bool `json:"displayApps,omitempty"`
	Apps        []SubAgentApp                `json:"apps,omitempty"`
	Name        string                       `json:"name,omitempty"`
	Ignore      bool                         `json:"ignore,omitempty"`
}

type CommandEnv added in v2.24.0 

type CommandEnv func(ei usershell.EnvInfoer, addEnv []string) (shell, dir string, env []string, err error)

CommandEnv is a function that returns the shell, working directory, and environment variables to use when executing a command. It takes an EnvInfoer and a pre-existing environment slice as arguments. This signature matches agentssh.Server.CommandEnv.

type ContainerCLI added in v2.24.0 

type ContainerCLI interface {
	// List returns a list of containers visible to the workspace agent.
	// This should include running and stopped containers.
	List(ctx context.Context) (codersdk.WorkspaceAgentListContainersResponse, error)
	// DetectArchitecture detects the architecture of a container.
	DetectArchitecture(ctx context.Context, containerName string) (string, error)
	// Copy copies a file from the host to a container.
	Copy(ctx context.Context, containerName, src, dst string) error
	// ExecAs executes a command in a container as a specific user.
	ExecAs(ctx context.Context, containerName, user string, args ...string) ([]byte, error)
}

ContainerCLI is an interface for interacting with containers in a workspace.

func NewDockerCLI added in v2.24.0 

func NewDockerCLI(execer agentexec.Execer) ContainerCLI

type DevcontainerCLI added in v2.22.0 

type DevcontainerCLI interface {
	Up(ctx context.Context, workspaceFolder, configPath string, opts ...DevcontainerCLIUpOptions) (id string, err error)
	Exec(ctx context.Context, workspaceFolder, configPath string, cmd string, cmdArgs []string, opts ...DevcontainerCLIExecOptions) error
	ReadConfig(ctx context.Context, workspaceFolder, configPath string, env []string, opts ...DevcontainerCLIReadConfigOptions) (DevcontainerConfig, error)
}

DevcontainerCLI is an interface for the devcontainer CLI.

func NewDevcontainerCLI added in v2.22.0 

func NewDevcontainerCLI(logger slog.Logger, execer agentexec.Execer) DevcontainerCLI

type DevcontainerCLIExecOptions added in v2.24.0 

type DevcontainerCLIExecOptions func(*devcontainerCLIExecConfig)

DevcontainerCLIExecOptions are options for the devcontainer CLI Exec command.

func WithExecContainerID added in v2.24.0 

func WithExecContainerID(id string) DevcontainerCLIExecOptions

WithExecContainerID sets the container ID to target a specific container.

func WithExecOutput added in v2.24.0 

func WithExecOutput(stdout, stderr io.Writer) DevcontainerCLIExecOptions

WithExecOutput sets additional stdout and stderr writers for logs during Exec operations.

func WithRemoteEnv added in v2.24.0 

func WithRemoteEnv(env ...string) DevcontainerCLIExecOptions

WithRemoteEnv sets environment variables for the Exec command.

type DevcontainerCLIReadConfigOptions added in v2.24.0 

type DevcontainerCLIReadConfigOptions func(*devcontainerCLIReadConfigConfig)

DevcontainerCLIExecOptions are options for the devcontainer CLI ReadConfig command.

func WithReadConfigOutput added in v2.24.0 

func WithReadConfigOutput(stdout, stderr io.Writer) DevcontainerCLIReadConfigOptions

WithReadConfigOutput sets additional stdout and stderr writers for logs during ReadConfig operations.

type DevcontainerCLIUpOptions added in v2.22.0 

type DevcontainerCLIUpOptions func(*devcontainerCLIUpConfig)

DevcontainerCLIUpOptions are options for the devcontainer CLI Up command.

func WithRemoveExistingContainer added in v2.22.0 

func WithRemoveExistingContainer() DevcontainerCLIUpOptions

WithRemoveExistingContainer is an option to remove the existing container.

func WithUpOutput added in v2.24.0 

func WithUpOutput(stdout, stderr io.Writer) DevcontainerCLIUpOptions

WithUpOutput sets additional stdout and stderr writers for logs during Up operations.

type DevcontainerConfig added in v2.24.0 

type DevcontainerConfig struct {
	MergedConfiguration DevcontainerMergedConfiguration `json:"mergedConfiguration"`
	Configuration       DevcontainerConfiguration       `json:"configuration"`
	Workspace           DevcontainerWorkspace           `json:"workspace"`
}

DevcontainerConfig is a wrapper around the output from `read-configuration`. Unfortunately we cannot make use of `dcspec` as the output doesn't appear to match.

type DevcontainerConfiguration added in v2.24.0 

type DevcontainerConfiguration struct {
	Customizations DevcontainerCustomizations `json:"customizations,omitempty"`
}

type DevcontainerCustomizations added in v2.24.0 

type DevcontainerCustomizations struct {
	Coder CoderCustomization `json:"coder,omitempty"`
}

type DevcontainerFeatures added in v2.24.0 

type DevcontainerFeatures map[string]any

func (DevcontainerFeatures) OptionsAsEnvs added in v2.24.0 

func (f DevcontainerFeatures) OptionsAsEnvs() []string

OptionsAsEnvs converts the DevcontainerFeatures into a list of environment variables that can be used to set feature options. The format is FEATURE_<FEATURE_NAME>_OPTION_<OPTION_NAME>=<value>. For example, if the feature is: 

	"ghcr.io/coder/devcontainer-features/code-server:1": {
   "port": 9090,
 }

It will produce: 

FEATURE_CODE_SERVER_OPTION_PORT=9090

Note that the feature name is derived from the last part of the key, so "ghcr.io/coder/devcontainer-features/code-server:1" becomes "CODE_SERVER". The version part (e.g. ":1") is removed, and dashes in the feature and option names are replaced with underscores.

type DevcontainerMergedConfiguration added in v2.24.0 

type DevcontainerMergedConfiguration struct {
	Customizations DevcontainerMergedCustomizations `json:"customizations,omitempty"`
	Features       DevcontainerFeatures             `json:"features,omitempty"`
}

type DevcontainerMergedCustomizations added in v2.24.0 

type DevcontainerMergedCustomizations struct {
	Coder []CoderCustomization `json:"coder,omitempty"`
}

type DevcontainerWorkspace added in v2.24.0 

type DevcontainerWorkspace struct {
	WorkspaceFolder string `json:"workspaceFolder"`
}

type DockerEnvInfoer 

type DockerEnvInfoer struct {
	usershell.SystemEnvInfo
	// contains filtered or unexported fields
}

DockerEnvInfoer is an implementation of agentssh.EnvInfoer that returns information about a container.

func EnvInfo 

func EnvInfo(ctx context.Context, execer agentexec.Execer, container, containerUser string) (*DockerEnvInfoer, error)

EnvInfo returns information about the environment of a container.

func (*DockerEnvInfoer) ModifyCommand 

func (dei *DockerEnvInfoer) ModifyCommand(cmd string, args ...string) (string, []string)

func (*DockerEnvInfoer) Shell added in v2.21.0 

func (dei *DockerEnvInfoer) Shell(string) (string, error)

func (*DockerEnvInfoer) User added in v2.21.0 

func (dei *DockerEnvInfoer) User() (*user.User, error)

type Option 

type Option func(*API)

Option is a functional option for API.

func WithClock added in v2.22.0 

func WithClock(clock quartz.Clock) Option

WithClock sets the quartz.Clock implementation to use. This is primarily used for testing to control time.

func WithCommandEnv added in v2.24.0 

func WithCommandEnv(ce CommandEnv) Option

WithCommandEnv sets the CommandEnv implementation to use.

func WithContainerCLI added in v2.24.0 

func WithContainerCLI(ccli ContainerCLI) Option

WithContainerCLI sets the agentcontainers.ContainerCLI implementation to use. The default implementation uses the Docker CLI.

func WithContainerLabelIncludeFilter added in v2.24.0 

func WithContainerLabelIncludeFilter(label, value string) Option

WithContainerLabelIncludeFilter sets a label filter for containers. This option can be given multiple times to filter by multiple labels. The behavior is such that only containers matching one or more of the provided labels will be included.

func WithDevcontainerCLI added in v2.22.0 

func WithDevcontainerCLI(dccli DevcontainerCLI) Option

WithDevcontainerCLI sets the DevcontainerCLI implementation to use. This can be used in tests to modify @devcontainer/cli behavior.

func WithDevcontainers added in v2.22.0 

func WithDevcontainers(devcontainers []codersdk.WorkspaceAgentDevcontainer, scripts []codersdk.WorkspaceAgentScript) Option

WithDevcontainers sets the known devcontainers for the API. This allows the API to be aware of devcontainers defined in the workspace agent manifest.

func WithExecer added in v2.22.0 

func WithExecer(execer agentexec.Execer) Option

WithExecer sets the agentexec.Execer implementation to use.

func WithManifestInfo added in v2.24.0 

func WithManifestInfo(owner, workspace, parentAgent string) Option

WithManifestInfo sets the owner name, and workspace name for the sub-agent.

func WithScriptLogger added in v2.23.0 

func WithScriptLogger(scriptLogger func(logSourceID uuid.UUID) ScriptLogger) Option

WithScriptLogger sets the script logger provider for devcontainer operations.

func WithSubAgentClient added in v2.24.0 

func WithSubAgentClient(client SubAgentClient) Option

WithSubAgentClient sets the SubAgentClient implementation to use. This is used to list, create, and delete devcontainer agents.

func WithSubAgentEnv added in v2.24.0 

func WithSubAgentEnv(env ...string) Option

WithSubAgentEnv sets the environment variables for the sub-agent.

func WithSubAgentURL added in v2.24.0 

func WithSubAgentURL(url string) Option

WithSubAgentURL sets the agent URL for the sub-agent for communicating with the control plane.

func WithWatcher added in v2.22.0 

func WithWatcher(w watcher.Watcher) Option

WithWatcher sets the file watcher implementation to use. By default a noop watcher is used. This can be used in tests to modify the watcher behavior or to use an actual file watcher (e.g. fsnotify).

type ScriptLogger added in v2.23.0 

type ScriptLogger interface {
	Send(ctx context.Context, log ...agentsdk.Log) error
	Flush(ctx context.Context) error
}

ScriptLogger is an interface for sending devcontainer logs to the controlplane.

type SubAgent added in v2.24.0 

type SubAgent struct {
	ID              uuid.UUID
	Name            string
	AuthToken       uuid.UUID
	Directory       string
	Architecture    string
	OperatingSystem string
	Apps            []SubAgentApp
	DisplayApps     []codersdk.DisplayApp
}

SubAgent represents an agent running in a dev container.

func (SubAgent) CloneConfig added in v2.24.0 

func (s SubAgent) CloneConfig(dc codersdk.WorkspaceAgentDevcontainer) SubAgent

CloneConfig makes a copy of SubAgent without ID and AuthToken. The name is inherited from the devcontainer.

func (SubAgent) EqualConfig added in v2.24.0 

func (s SubAgent) EqualConfig(other SubAgent) bool

type SubAgentApp added in v2.24.0 

type SubAgentApp struct {
	Slug        string                            `json:"slug"`
	Command     string                            `json:"command"`
	DisplayName string                            `json:"displayName"`
	External    bool                              `json:"external"`
	Group       string                            `json:"group"`
	HealthCheck SubAgentHealthCheck               `json:"healthCheck"`
	Hidden      bool                              `json:"hidden"`
	Icon        string                            `json:"icon"`
	OpenIn      codersdk.WorkspaceAppOpenIn       `json:"openIn"`
	Order       int32                             `json:"order"`
	Share       codersdk.WorkspaceAppSharingLevel `json:"share"`
	Subdomain   bool                              `json:"subdomain"`
	URL         string                            `json:"url"`
}

func (SubAgentApp) ToProtoApp added in v2.24.0 

func (app SubAgentApp) ToProtoApp() (*agentproto.CreateSubAgentRequest_App, error)

type SubAgentClient added in v2.24.0 

type SubAgentClient interface {
	// List returns a list of all agents.
	List(ctx context.Context) ([]SubAgent, error)
	// Create adds a new agent.
	Create(ctx context.Context, agent SubAgent) (SubAgent, error)
	// Delete removes an agent by its ID.
	Delete(ctx context.Context, id uuid.UUID) error
}

SubAgentClient is an interface for managing sub agents and allows changing the implementation without having to deal with the agentproto package directly.

func NewSubAgentClientFromAPI added in v2.24.0 

func NewSubAgentClientFromAPI(logger slog.Logger, agentAPI agentproto.DRPCAgentClient26) SubAgentClient

type SubAgentHealthCheck added in v2.24.0 

type SubAgentHealthCheck struct {
	Interval  int32  `json:"interval"`
	Threshold int32  `json:"threshold"`
	URL       string `json:"url"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package acmock is a generated GoMock package.
 Package acmock is a generated GoMock package.
Package dcspec contains an automatically generated Devcontainer specification.
 Package dcspec contains an automatically generated Devcontainer specification.
Package watcher provides file system watching capabilities for the agent.
 Package watcher provides file system watching capabilities for the agent.

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.