workspace

package
v1.4.0-beta.3 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	DefaultDockerCommand   = "docker"
	ContainerStatusRunning = "running"
)
View Source 
const ProjectLabel = "devsy.sh/project"

Variables

View Source 
var ErrNoWorkspaceFound = errors.New("no workspace found")
View Source 
var ErrWorkspaceNotFound = errors.New("workspace not found")

ErrWorkspaceNotFound is returned by Get when the requested workspace is not present in the local store or any configured provider. Callers should use errors.Is to detect it; the wrapping message includes the args for context. See pkg/exitcode.WorkspaceNotFound for the corresponding process exit code.

Functions

func AddProvider 

func AddProvider(
	ctx context.Context,
	devsyConfig *config.Config,
	providerName, providerSourceRaw string,
) (*provider.ProviderConfig, error)

func AddProviderRaw 

func AddProviderRaw(ctx context.Context, p ProviderParams) (*provider.ProviderConfig, error)

func BuildExecEnv added in v1.3.1 

func BuildExecEnv(
	result *devcconfig.Result,
	cliEnv []string,
	probedEnv map[string]string,
) map[string]string

BuildExecEnv merges probed env, result remote env, and caller-supplied env slices.

func CheckAllProviderVersions added in v1.3.1 

func CheckAllProviderVersions(
	devsyConfig *config.Config,
) (map[string]provider.ProviderVersionCheckResult, error)

CheckAllProviderVersions queries the latest version for every installed provider whose source supports version listing. Per-provider errors are recorded in the result map, not returned as a fatal error. Bypasses the cache so callers always see the freshest data.

func CheckProviderUpdate 

func CheckProviderUpdate(
	ctx context.Context,
	devsyConfig *config.Config,
	proInstance *provider2.ProInstance,
) error

CheckProviderUpdate currently only ensures the local provider is in sync with the remote for Devsy Pro instances. Potentially auto-upgrade other providers in the future.

func Delete 

func Delete(ctx context.Context, opts DeleteOptions) (string, error)

Delete deletes a workspace, handling imported workspaces, single-machine cleanup, and force-deletion of broken workspaces. When the workspace is running it is stopped first so callers see a predictable running -> stopped -> deleted lifecycle, and any detached browser tunnel helper is reaped so its host ports do not outlive the workspace.

func Exists 

func Exists(
	ctx context.Context,
	devsyConfig *config.Config,
	args []string,
	workspaceID string,
	owner platform.OwnerFilter,
) string

Exists checks if the given workspace already exists.

func FindProviderProInstance 

func FindProviderProInstance(
	proInstances []*provider2.ProInstance,
	providerName string,
) (*provider2.ProInstance, bool)

func Get 

func Get(ctx context.Context, opts GetOptions) (client.BaseWorkspaceClient, error)

Get tries to retrieve an already existing workspace.

func GetMachine 

func GetMachine(
	devsyConfig *config.Config,
	args []string,
) (client.MachineClient, error)

GetMachine creates a machine client.

func GetProInstance 

func GetProInstance(
	devsyConfig *config.Config,
	providerName string,
) *provider2.ProInstance

GetProInstance returns the ProInstance associated with the given provider name, or nil if not found.

func List 

func List(
	ctx context.Context,
	devsyConfig *config.Config,
	skipPro bool,
	owner platform.OwnerFilter,
) ([]*providerpkg.Workspace, error)

func ListLocalWorkspaces 

func ListLocalWorkspaces(
	contextName string,
	skipPro bool,
) ([]*providerpkg.Workspace, error)

func ListMachines 

func ListMachines(devsyConfig *config.Config) ([]*providerpkg.Machine, error)

ListMachines returns all machines configured in the given Devsy context.

func ListProInstances 

func ListProInstances(
	devsyConfig *config.Config,
) ([]*provider2.ProInstance, error)

func ListProviderVersions added in v1.3.1 

func ListProviderVersions(
	devsyConfig *config.Config,
	providerName string,
	opts provider.ListVersionsOptions,
) ([]provider.ProviderVersion, error)

ListProviderVersions returns available versions for the named provider, newest first. Returns provider.ErrVersionListUnsupported when the source type can't be enumerated.

func LoadAllProviders 

func LoadAllProviders(
	devsyConfig *config.Config,
) (map[string]*ProviderWithOptions, error)

func LoadExecResult added in v1.3.1 

func LoadExecResult(
	workspaceConfig *provider2.Workspace,
	containerDetails *devcconfig.ContainerDetails,
) *devcconfig.Result

func MachineExists 

func MachineExists(devsyConfig *config.Config, args []string) string

MachineExists checks if the given workspace already exists.

func ProviderFromHost 

func ProviderFromHost(
	ctx context.Context,
	devsyConfig *config.Config,
	proHost string,
) (*provider.ProviderConfig, error)

func Rename added in v1.3.0 

func Rename(ctx context.Context, opts RenameOptions) error

Rename auto-stops the workspace, deletes the stale container, moves its directory, and clears the old SSH entry. The container is rebuilt on the next `up`. Container removal happens before the disk move so a failure aborts cleanly with the workspace still intact under its old name.

func Resolve 

func Resolve(
	ctx context.Context,
	devsyConfig *config.Config,
	params ResolveParams,
) (client.BaseWorkspaceClient, error)

func ResolveDockerCommand added in v1.3.1 

func ResolveDockerCommand(
	workspace *provider2.Workspace,
	override string,
) string

ResolveDockerCommand returns the docker binary to invoke. Precedence: override → provider config (agent.docker.path) → default. The override is honored even when workspace is nil.

func ResolveExecWorkdir added in v1.3.1 

func ResolveExecWorkdir(result *devcconfig.Result, workspaceName string) string

func ResolveMachine 

func ResolveMachine(
	devsyConfig *config.Config,
	args []string,
	userOptions []string,
) (client.Client, error)

func ResolveProviderSource 

func ResolveProviderSource(
	devsyConfig *config.Config,
	providerName string,
) (string, error)

func SetProviderVersion added in v1.3.1 

func SetProviderVersion(
	ctx context.Context,
	devsyConfig *config.Config,
	providerName, tag string,
) error

SetProviderVersion switches the provider to the given tag.

func SingleMachineName 

func SingleMachineName(devsyConfig *config.Config, provider string) string

func SweepOrphanWorkspaceDirs added in v1.3.1 

func SweepOrphanWorkspaceDirs(contextName string)

func SwitchProvider 

func SwitchProvider(
	ctx context.Context,
	devsyConfig *config.Config,
	workspace *provider.Workspace,
	newProviderName string,
) error

SwitchProvider updates the provider name for the given workspace with client locking. It persists the new provider name before resolving the client so that FindProvider can locate the already-renamed provider directory.

func ToID 

func ToID(str string) string

func UpdateProvider 

func UpdateProvider(
	ctx context.Context,
	devsyConfig *config.Config,
	providerName, providerSourceRaw string,
) (*provider.ProviderConfig, error)

Types

type ContainerRuntime added in v1.3.1 

type ContainerRuntime interface {
	// FindRunning resolves a running container by workspace ID and/or labels.
	// A non-nil error includes the not-found and not-running cases.
	FindRunning(
		ctx context.Context,
		workspaceID string,
		idLabels []string,
	) (*devcconfig.ContainerDetails, error)

	// Exec runs req inside a container and returns the process exit code.
	// A non-nil error means the exec machinery itself failed (e.g. binary
	// missing), not a non-zero exit.
	Exec(ctx context.Context, req ExecRequest) (exitCode int, err error)

	// ProbeEnv reads the container's environment via shell. Returns an empty
	// map on any failure; probeMode comes from devcconfig.UserEnvProbe.
	ProbeEnv(ctx context.Context, target ContainerTarget, probeMode string) map[string]string
}

ContainerRuntime abstracts find/exec/probe over a container runtime so callers and tests don't depend on a particular CLI (docker, podman, ...).

type ContainerTarget added in v1.3.1 

type ContainerTarget struct {
	ContainerID string
	User        string
}

ContainerTarget identifies a container and the user to exec as.

type DeleteOptions 

type DeleteOptions struct {
	DevsyConfig    *config.Config
	Args           []string
	IgnoreNotFound bool
	Force          bool
	ClientDelete   client2.DeleteOptions
	Owner          platform.OwnerFilter
}

DeleteOptions holds the parameters for deleting a workspace.

type DockerRuntime added in v1.3.1 

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

DockerRuntime is the production ContainerRuntime, shelling out to a docker-compatible binary.

func NewDockerRuntime added in v1.3.1 

func NewDockerRuntime(workspace *provider2.Workspace, override string) *DockerRuntime

NewDockerRuntime builds a DockerRuntime using ResolveDockerCommand to pick the binary; override wins if set.

func (*DockerRuntime) DockerCommand added in v1.3.1 

func (r *DockerRuntime) DockerCommand() string

func (*DockerRuntime) Exec added in v1.3.1 

func (r *DockerRuntime) Exec(ctx context.Context, req ExecRequest) (int, error)

func (*DockerRuntime) FindRunning added in v1.3.1 

func (r *DockerRuntime) FindRunning(
	ctx context.Context,
	workspaceID string,
	idLabels []string,
) (*devcconfig.ContainerDetails, error)

func (*DockerRuntime) ProbeEnv added in v1.3.1 

func (r *DockerRuntime) ProbeEnv(
	ctx context.Context,
	target ContainerTarget,
	probe string,
) map[string]string

type ExecOneShotOptions added in v1.3.1 

type ExecOneShotOptions struct {
	WorkspaceName         string
	Command               []string
	Workdir               string
	Env                   map[string]string
	IDLabels              []string // additional id-labels for container lookup; nil uses defaults
	TimeoutSeconds        int
	TimeoutSecondsDefault int
	TimeoutSecondsMax     int
	Owner                 platform.OwnerFilter
	Context               string
	Provider              string
	Stdout                io.Writer
	Stderr                io.Writer
}

ExecOneShotOptions configures a single non-interactive exec inside a workspace's running container.

func (ExecOneShotOptions) ResolveTimeout added in v1.3.1 

func (o ExecOneShotOptions) ResolveTimeout(fallbackDefault int) (time.Duration, bool)

ResolveTimeout picks the first positive of TimeoutSeconds, TimeoutSecondsDefault, fallbackDefault, then clamps by TimeoutSecondsMax. The bool is true when clamping applied.

type ExecOneShotResult added in v1.3.1 

type ExecOneShotResult struct {
	ExitCode       int
	DurationMS     int64
	TimedOut       bool
	TimeoutSeconds int
	Clamped        bool
}

ExecOneShotResult is the outcome of an ExecOneShot call.

func ExecOneShot added in v1.3.1 

func ExecOneShot(ctx context.Context, opts ExecOneShotOptions) (*ExecOneShotResult, error)

ExecOneShot runs opts.Command in the workspace's container, capturing stdout/stderr via the provided writers. Never reads stdin, never allocates a TTY.

type ExecRequest added in v1.3.1 

type ExecRequest struct {
	Target  ContainerTarget
	Workdir string
	Env     map[string]string
	Argv    []string
	Stdout  io.Writer
	Stderr  io.Writer
}

ExecRequest is the per-call input to ContainerRuntime.Exec.

type GetOptions 

type GetOptions struct {
	DevsyConfig    *config.Config
	Args           []string
	ChangeLastUsed bool
	Owner          platform.OwnerFilter
	LocalOnly      bool
}

GetOptions holds the parameters for retrieving an existing workspace.

type ProviderParams 

type ProviderParams struct {
	DevsyConfig  *config.Config
	ProviderName string
	Raw          []byte
	Source       *provider.ProviderSource
}

type ProviderWithOptions 

type ProviderWithOptions struct {
	Config *provider.ProviderConfig `json:"config,omitempty"`
	State  *config.ProviderConfig   `json:"state,omitempty"`
}

func CloneProvider 

func CloneProvider(
	ctx context.Context,
	devsyConfig *config.Config,
	providerName, providerSourceRaw string,
) (*ProviderWithOptions, error)

func FindProvider 

func FindProvider(
	devsyConfig *config.Config,
	name string,
) (*ProviderWithOptions, error)

func LoadProviders 

func LoadProviders(
	devsyConfig *config.Config,
) (*ProviderWithOptions, map[string]*ProviderWithOptions, error)

LoadProviders loads all known providers for the given context.

type RemoteCreator 

type RemoteCreator interface {
	Create(ctx context.Context, stdin io.Reader, stdout, stderr io.Writer) error
}

RemoteCreator defines the interface for clients that support remote workspace creation. This interface is implemented by ProxyClient and DaemonClient to enable workspace creation on remote platforms.

type RenameOptions added in v1.3.0 

type RenameOptions struct {
	DevsyConfig *config.Config
	OldName     string
	NewName     string
}

RenameOptions holds parameters for renaming a workspace.

type ResolveParams 

type ResolveParams struct {
	IDE                  string
	IDEOptions           []string
	Args                 []string
	DesiredID            string
	DesiredMachine       string
	ProviderUserOptions  []string
	ReconfigureProvider  bool
	DevContainerImage    string
	DevContainerPath     string
	SSHConfigPath        string
	SSHConfigIncludePath string
	Source               *providerpkg.WorkspaceSource
	UID                  string
	ChangeLastUsed       bool
	Owner                platform.OwnerFilter
}

Resolve takes the `devsy up|build` CLI input and either finds an existing workspace or creates a new one.

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.