driver

Documentation

Index

• Constants
• func AutoStartDisabledByEnv() bool
• func DriverPreflight(ctx context.Context, d Driver, opts PreflightOptions) error
• func DriverProvisioningPreflight(ctx context.Context, d Driver) error
• func DriverRequiresMountStreaming(d Driver) bool
• func DriverRequiresRecreate(d Driver, details *config.ContainerDetails, remoteUser string) (bool, string)
• func DriverRequiresWorkspaceChown(d Driver) bool
• func DriverSupportsMountType(d Driver, mountType string) bool
• type ArgvExecDriver
• type BuildRequest
• type CommandParams
• type ComposeDriver
• type ContainerUserUpdater
• type DockerHelperProvider
• type Driver
• type ImageBackend
• type ImageBuilder
• type ImageDriver
• type ImageInspector
• type ImagePublisher
• type ImageRunValidator
• type ImageRunner
• type MountCapableDriver
• type MountDeliveryDriver
• type PreflightError
  • func (e *PreflightError) Error() string
  • func (e *PreflightError) Unwrap() error
• type PreflightOptions
• type Preflighter
• type ProvisioningPreflighter
• type RecreateMode
  • func DriverRecreateMode(d Driver) RecreateMode
• type RecreatePolicyDriver
• type RecreateRequiredDriver
• type ReprovisioningDriver
• type ReusePreflightDriver
• type RunImageDevContainerParams
• type RunOptions
• type RunOptionsDriver
• type SnapshotCapableDriver
• type Streams
• type WorkspaceChowner

Constants

const (
	MountTypeBind   = "bind"
	MountTypeVolume = "volume"
	MountTypeTmpfs  = "tmpfs"
)

const NoAutoStartEnv = "DEVSY_NO_AUTOSTART"

NoAutoStartEnv disables preflight auto-starting a stopped backend.

Functions

func AutoStartDisabledByEnv

func AutoStartDisabledByEnv() bool

AutoStartDisabledByEnv reports whether NoAutoStartEnv opts out of auto-start.

func DriverPreflight

func DriverPreflight(ctx context.Context, d Driver, opts PreflightOptions) error

DriverPreflight runs the driver's preflight check, or nothing if it has none.

func DriverProvisioningPreflight

func DriverProvisioningPreflight(ctx context.Context, d Driver) error

DriverProvisioningPreflight runs a driver's provisioning check when supported.

func DriverRequiresMountStreaming

func DriverRequiresMountStreaming(d Driver) bool

Drivers without an explicit mount policy retain streamed delivery.

func DriverRequiresRecreate

func DriverRequiresRecreate(
	d Driver,
	details *config.ContainerDetails,
	remoteUser string,
) (bool, string)

func DriverRequiresWorkspaceChown

func DriverRequiresWorkspaceChown(d Driver) bool

Drivers without an explicit ownership policy retain workspace chown.

func DriverSupportsMountType

func DriverSupportsMountType(d Driver, mountType string) bool

DriverSupportsMountType reports whether the driver can honor mountType, defaulting to true for drivers that do not advertise the capability.

Types

type ArgvExecDriver

type ArgvExecDriver interface {
	Driver
	CommandContainerArgv(
		ctx context.Context,
		workspaceID string,
		argv []string,
		streams Streams,
	) error
}

type BuildRequest

type BuildRequest struct {
	PrebuildHash         string
	ParsedConfig         *config.SubstitutedConfig
	ExtendedBuildInfo    *feature.ExtendedBuildInfo
	DockerfilePath       string
	DockerfileContent    string
	LocalWorkspaceFolder string
	Options              provider.BuildOptions
}

type CommandParams

type CommandParams struct {
	WorkspaceID string
	User        string
	Command     string
	Stdin       io.Reader
	Stdout      io.Writer
	Stderr      io.Writer
	// RawStdout preserves protocol bytes; text commands keep stdout redacted.
	// Protocol consumers must not log the unredacted stream.
	RawStdout bool
}

CommandParams holds the parameters for running a command inside a devcontainer.

type ComposeDriver

type ComposeDriver interface {
	Driver

	// ComposeHelper returns the compose helper
	ComposeHelper() (*compose.ComposeHelper, error)
}

ComposeDriver is a capability interface implemented by drivers that can run docker-compose based devcontainers. Not every container runtime has a compose engine (e.g. Apple's `container`), so callers detect support via a type assertion rather than forcing every driver to stub the method.

type ContainerUserUpdater

type ContainerUserUpdater interface {
	UpdateContainerUserUID(
		ctx context.Context,
		workspaceID string,
		parsedConfig *config.DevContainerConfig,
		writer io.Writer,
	) error
}

type DockerHelperProvider

type DockerHelperProvider interface {
	Driver

	// DockerHelper returns the docker helper
	DockerHelper() (*docker.DockerHelper, error)
}

DockerHelperProvider is a capability interface implemented by drivers backed by a Docker-compatible CLI that can expose the low-level *docker.DockerHelper. Runtimes without one (e.g. the Apple driver) simply do not implement it.

type Driver

type Driver interface {
	// FindDevContainer returns a running devcontainer details
	FindDevContainer(ctx context.Context, workspaceID string) (*config.ContainerDetails, error)

	// CommandDevContainer runs the given command inside the devcontainer
	CommandDevContainer(ctx context.Context, params *CommandParams) error

	// TargetArchitecture returns the architecture of the container runtime. e.g. amd64 or arm64
	TargetArchitecture(ctx context.Context, workspaceID string) (string, error)

	// DeleteDevContainer deletes the devcontainer
	DeleteDevContainer(ctx context.Context, workspaceID string) error

	// StartDevContainer starts the devcontainer
	StartDevContainer(ctx context.Context, workspaceID string) error

	// StopDevContainer stops the devcontainer
	StopDevContainer(ctx context.Context, workspaceID string) error

	// GetContainerLogs returns the logs of the devcontainer
	GetDevContainerLogs(
		ctx context.Context,
		workspaceID string,
		stdout io.Writer,
		stderr io.Writer,
	) error
}

Driver is the default interface for Devsy drivers.

type ImageBackend

type ImageBackend interface {
	ImageInspector
	ImageBuilder
	ImagePublisher
}

ImageBackend prepares and publishes images independently of runtime lifecycle.

type ImageBuilder

type ImageBuilder interface {
	BuildDevContainer(ctx context.Context, req BuildRequest) (*config.BuildInfo, error)
}

type ImageDriver

type ImageDriver interface {
	ImageRunner
	ImageBackend
	ContainerUserUpdater
}

ImageDriver is the legacy aggregate of runtime and image capabilities. New callers should use the individual capabilities or an ImageBackend.

type ImageInspector

type ImageInspector interface {
	InspectImage(ctx context.Context, imageName string) (*config.ImageDetails, error)
	GetImageTag(ctx context.Context, imageName string) (string, error)
}

type ImagePublisher

type ImagePublisher interface {
	PushDevContainer(ctx context.Context, image string) error
	TagDevContainer(ctx context.Context, image, tag string) error
}

type ImageRunValidator

type ImageRunValidator interface {
	ValidateRunImageDevContainer(params *RunImageDevContainerParams) error
}

ImageRunValidator checks resolved creation intent before an existing container is stopped or removed. Validation must not change runtime state.

type ImageRunner

type ImageRunner interface {
	Driver
	RunImageDevContainer(ctx context.Context, params *RunImageDevContainerParams) error
}

type MountCapableDriver

type MountCapableDriver interface {
	Driver

	SupportsMountType(mountType string) bool
}

MountCapableDriver is implemented by drivers that can report which mount types they support. Drivers that do not implement it are assumed to support the bind/volume/tmpfs types the docker driver has always handled.

type MountDeliveryDriver

type MountDeliveryDriver interface {
	Driver
	RequiresMountStreaming() bool
}

type PreflightError

type PreflightError struct {
	Provider string
	Err      error
}

PreflightError lets callers recognize a backend-readiness failure (errors.As) and surface the runtime's own message rather than wrapping it. Provider holds the runtime or driver identifier (e.g. "podman", "kubernetes") for grouping.

func (*PreflightError) Error

func (e *PreflightError) Error() string

func (*PreflightError) Unwrap

func (e *PreflightError) Unwrap() error

type PreflightOptions

type PreflightOptions struct {
	// DisableAutoStart reports whether a stopped backend should be left as-is
	// (reported) rather than started.
	DisableAutoStart bool
}

PreflightOptions carries per-invocation preflight settings, passed explicitly so behavior is not coupled to process-global state.

type Preflighter

type Preflighter interface {
	Driver

	Preflight(ctx context.Context, opts PreflightOptions) error
}

Preflighter is implemented by drivers that can validate their backend before use and optionally start it. Callers reach it via DriverPreflight.

type ProvisioningPreflighter

type ProvisioningPreflighter interface {
	Driver

	ProvisioningPreflight(ctx context.Context) error
}

ProvisioningPreflighter is implemented by drivers that need a compatibility check before Devsy creates or recreates a devcontainer. It is separate from Preflighter because ordinary preflight also runs for lifecycle operations.

type RecreateMode

type RecreateMode string

const (
	RecreateDelete RecreateMode = "delete"
	RecreateStop   RecreateMode = "stop"
	// RecreateOnRun lets the driver validate final run options before replacing the container.
	RecreateOnRun RecreateMode = "on-run"
)

func DriverRecreateMode

func DriverRecreateMode(d Driver) RecreateMode

type RecreatePolicyDriver

type RecreatePolicyDriver interface {
	Driver
	RecreateMode() RecreateMode
}

type RecreateRequiredDriver

type RecreateRequiredDriver interface {
	RequiresRecreate(details *config.ContainerDetails, remoteUser string) (bool, string)
}

RecreateRequiredDriver detects incompatible creation-time container contracts.

type ReprovisioningDriver

type ReprovisioningDriver interface {
	RunOptionsDriver

	// CanReprovision returns true if the driver can reprovision the devcontainer
	CanReprovision() bool
}

ReprovisioningDriver is a capability interface for drivers that can reprovision an existing devcontainer in place. Reprovisioning re-runs the container, so it embeds RunOptionsDriver.

type ReusePreflightDriver

type ReusePreflightDriver interface {
	SupportsReusePreflight() bool
	ReusePreflight(ctx context.Context, workspaceID, remoteUser string) error
}

ReusePreflightDriver validates an existing workspace against its resolved developer identity. It must not mutate the workspace. An error aborts reuse without scheduling recreation. Calls require SupportsReusePreflight to report true.

type RunImageDevContainerParams

type RunImageDevContainerParams struct {
	WorkspaceID          string
	Options              *RunOptions
	ParsedConfig         *config.DevContainerConfig
	IDE                  string
	IDEOptions           map[string]config2.OptionValue
	LocalWorkspaceFolder string
	GPUAvailability      string
}

type RunOptions

type RunOptions struct {
	// UID is a unique identifier for this workspace
	UID string `json:"uid,omitempty"`

	// Image is the image to run
	Image string `json:"image,omitempty"`

	// User is the user to run the container as
	User string `json:"user,omitempty"`

	// RemoteUser is the developer identity for remote tooling and workspace ownership.
	RemoteUser string `json:"remoteUser,omitempty"`

	// Dockerless builds the developer filesystem inside the runner after creation.
	Dockerless bool `json:"dockerless,omitempty"`

	// AllowRecreate authorizes replacing an existing VM and discarding its root disk.
	AllowRecreate bool `json:"allowRecreate,omitempty"`

	// Entrypoint is the entrypoint of the container
	Entrypoint string `json:"entrypoint,omitempty"`

	// Cmd are the cmd for the entrypoint
	Cmd []string `json:"cmd,omitempty"`

	// Env are additional environment variables to set
	Env map[string]string `json:"env,omitempty"`

	// CapAdd are additional capabilities for the container
	CapAdd []string `json:"capAdd,omitempty"`

	// SecurityOpt are additional security options
	SecurityOpt []string `json:"securityOpt,omitempty"`

	// Labels are labels to set on the container
	Labels []string `json:"labels,omitempty"`

	// Privileged indicates if the container should run with elevated permissions
	Privileged *bool `json:"privileged,omitempty"`

	// Init passes the --init flag when creating the container
	Init *bool `json:"init,omitempty"`

	// WorkspaceMount is the mount where the workspace should get mounted
	WorkspaceMount *config.Mount `json:"workspaceMount,omitempty"`

	// Mounts are additional mounts on the container. Supported are volume and bind mounts.
	// Bind mounts are expected to get copied from local to remote once. Volume mounts are expected
	// to be persisted for the lifetime of the container.
	Mounts []*config.Mount `json:"mounts,omitempty"`

	// Userns is the user namespace to use for the container
	Userns string `json:"userns,omitempty"`

	// UidMap are UID mappings for user namespace
	UidMap []string `json:"uidMap,omitempty"`

	// GidMap are GID mappings for user namespace
	GidMap []string `json:"gidMap,omitempty"`

	// Platform is the target platform (os/arch) to run the container under,
	// e.g. "linux/amd64". Empty means use the host's native platform.
	Platform string `json:"platform,omitempty"`

	// ImageBuilt is true if the image was built locally and is not expected to be
	// pullable from a registry. False for a devcontainer.json "image:" reference.
	ImageBuilt bool `json:"imageBuilt,omitempty"`
}

RunOptions are the options for running a container.

type RunOptionsDriver

type RunOptionsDriver interface {
	Driver

	// RunDevContainer runs a devcontainer
	RunDevContainer(ctx context.Context, workspaceID string, options *RunOptions) error
}

RunOptionsDriver is a capability interface for drivers that run a devcontainer directly from RunOptions. These drivers delegate container management to an external orchestrator (e.g. a Kubernetes pod or a custom command) rather than building and running a local OCI image; image runtimes use ImageRunner instead.

type SnapshotCapableDriver

type SnapshotCapableDriver interface {
	Driver

	// CommitContainer commits the running devcontainer's filesystem to a new
	// image, tagged as tag, to capture apt installs, global packages, and
	// other filesystem drift for workspace snapshots.
	CommitContainer(ctx context.Context, workspaceID, tag string) error
}

SnapshotCapableDriver is a capability interface implemented by drivers that can commit a running container's filesystem to a new image. Not every ImageDriver can do this (e.g. Apple's `container`), so callers detect support via a type assertion rather than forcing every ImageDriver to stub the method - the same pattern ComposeDriver and DockerHelperProvider already establish in this file.

type Streams

type Streams struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

Streams bundles the standard IO streams for an exec.

type WorkspaceChowner

type WorkspaceChowner interface {
	RequiresWorkspaceChown() bool
}

WorkspaceChowner is a capability interface for drivers whose workspace bind mount is root-owned in the guest, so the agent must chown it to the remote user during setup rather than relying on a UID remap.