dockercompose

type BuildPrimaryInputs struct {
	// SkipDefaultLoad leaves BuilderOptions.Load unchanged instead of enabling
	// local loading by default. Push and filesystem exports retain their meaning.
	SkipDefaultLoad bool

	// Spec is the parsed devcontainer.json (compose mode).
	Spec *spec.DevContainer
	// Workspace is the host workspace path; used as the build context.
	Workspace string
	// LocalEnv is forwarded to compose interpolation.
	LocalEnv map[string]string
	// Tag is the image tag to assign. When empty, a timestamped tag
	// under "devcontainer-builder/compose-primary" is generated.
	Tag string
	// BuilderOptions tunes the underlying builder. Spec, SpecPath and Workspace
	// are derived from the primary service. Tag overrides the first image name;
	// additional Tags are retained. Load defaults on unless pushing or exporting.
	BuilderOptions builder.Options
}

type BuildPrimaryResult struct {
	// Image is the image reference compose should use for the primary
	// service. Equal to the primary service's compose `image:` when
	// no feature, server, or export customization requires a derived image.
	Image string
	// Built is true when a Compose service or derived image was built.
	Built bool
	// BuildResult is non-nil only for a derived build. Its image label owns
	// the full current config/features; pass ImageBuilt: BuildResult != nil
	// to Up. A Compose service build alone does not have that provenance.
	BuildResult *builder.Result
}

type BuildServiceImagesInputs struct {
	OmitSyntaxDirective bool
	// Project is the loaded compose project. Required.
	Project *types.Project
	// Services restricts the build to the named services. When empty,
	// every service in the project that has a `build:` block is built.
	// Names that don't exist in the project are an error.
	Services []string
	// Skip lists service names to leave alone even if they have a
	// `build:` block. Useful when an embedder is baking a particular
	// service through a different path (e.g. BuildPrimaryImage for the
	// devcontainer primary).
	Skip []string
	// BuildKitAddress selects a separate BuildKit. Empty falls back to
	// BUILDKIT_HOST, then to the Docker daemon's built-in BuildKit.
	BuildKitAddress string
	// Docker is the Engine API client the built images are loaded
	// through. When nil, one is created from the DOCKER_* environment.
	Docker *dockerclient.Client
	// Platforms are the target platforms. Empty means the daemon's
	// default. Per-service compose `build.platforms` takes precedence
	// over this when set.
	Platforms []string
	// NoCache disables the build cache.
	NoCache bool
	// Pull always re-pulls referenced images.
	Pull bool
	// RegistryAuth supplies the registry credentials of every service
	// build. When nil, BuildKit reads the docker CLI's configuration
	// (registryauth.FromEnvironment).
	RegistryAuth buildkit.RegistryAuth
	// Progress one of "auto" | "plain" | "tty" | "rawjson".
	Progress string
	// Stdout / Stderr receive build output. nil means os.Stdout /
	// os.Stderr; pass io.Discard to silence.
	Stdout io.Writer
	Stderr io.Writer
	// Logger receives informational messages.
	Logger func(format string, args ...any)
}

type BuildServiceImagesResult struct {
	// Images maps service name → built image reference. Only contains
	// services whose `build:` was honored.
	Images map[string]string
	// Built lists service names actually built (vs skipped because
	// they had no `build:`).
	Built []string
}

type ContainerInfo struct {
	ID        string
	Service   string
	Image     string
	Running   bool
	StartedAt string
	CreatedAt string
	Primary   bool
	Labels    map[string]string
}

type ExecRequest struct {
	// TerminalSize sets the initial PTY size [rows, columns] when TTY is true.
	TerminalSize *[2]uint
	ContainerID  string
	Cmd          []string
	User         string
	WorkDir      string
	Env          map[string]string
	TTY          bool
	Stdin        io.Reader
	Stdout       io.Writer
	Stderr       io.Writer
}

type ExecResult struct {
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

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

type LoadInputs struct {
	// Spec is the parsed devcontainer.json. Must be in compose mode.
	Spec *spec.DevContainer
	// Workspace is the host workspace path; used for the default project name
	// and the upstream CLI working directory for the .env name lookup.
	Workspace string
	// LocalEnv is the host environment forwarded to compose's
	// `${VAR}` interpolation. Pass an empty map (not nil) for none.
	LocalEnv map[string]string
	// Override is an additional YAML layer appended to the merge chain.
	// Optional: callers that don't need overrides can leave it nil.
	// When the package builds an internal override (derived image,
	// runtime labels, etc.) it appends it here.
	Override []byte
}

type Options struct {
	// RegistryAuth supplies the same native pull credentials as the Docker
	// host, and the credentials of Up's service builds. A value that also
	// implements buildkit.RegistryAuth (such as a *registryauth.Store or a
	// registryauth.Static) answers the builds directly; any other value
	// answers them through its EngineAuth values. When nil, pulls are
	// anonymous and service builds read the docker CLI's configuration.
	RegistryAuth interface{ EngineAuth(string) (string, error) }
	// UserDataFolder selects the parent for private materialized configs/secrets.
	UserDataFolder string
	// TerminalSize is the optional lifecycle PTY size [rows, columns].
	TerminalSize *[2]uint
	// Logger receives informational messages. nil discards.
	Logger func(format string, args ...any)
	// Stdout / Stderr default to nil. Lifecycle command output goes
	// here unless the per-call request supplies its own writers.
	Stdout io.Writer
	Stderr io.Writer
	// StopTimeout bounds graceful shutdown. Defaults to 10s.
	StopTimeout time.Duration
	// DependencyTimeout bounds how long Up will wait for any single
	// `depends_on` entry to reach its declared condition
	// (service_healthy / service_completed_successfully). Defaults to
	// 5 minutes; the condition is rechecked every 500ms.
	DependencyTimeout time.Duration
	// SkipServiceBuild disables the auto-build pass that walks the
	// project for non-primary services with a `build:` block and
	// builds them with BuildKit before bring-up. Embedders that
	// pre-build their own images can set this to skip it.
	SkipServiceBuild bool
	// NoRecreate, when true, preserves an existing container even if
	// its config-hash label disagrees with the current spec. Default
	// behavior (false) mirrors `docker compose up`: a config-hash
	// mismatch (or missing label) triggers a stop+remove+create cycle
	// so the container picks up the new spec.
	NoRecreate bool
}

type OverrideInputs struct {
	// Spec is the parsed devcontainer.json (must be compose mode).
	Spec *spec.DevContainer
	// PrimaryImage, when non-empty, replaces the primary service's
	// `image:` (used after a derived feature build).
	PrimaryImage string
	// RemoteEnv is layered onto the primary service's environment.
	// Values flow from devcontainer.json's `remoteEnv`.
	RemoteEnv map[string]string
	// OverrideCommand: when true (matching the spec's default in compose
	// mode), the primary service's command is replaced by a long-running
	// keepalive so lifecycle commands and exec attach have a live
	// container regardless of the image's ENTRYPOINT/CMD. When false,
	// the original entrypoint/command are preserved.
	OverrideCommand bool
	// Entrypoints are the features' entrypoint contributions, run by the
	// keepalive command when OverrideCommand is true.
	Entrypoints []string
	// Labels merged onto the primary service.
	Labels map[string]string
}

type ProjectConflict struct {
	Name        string `json:"name"`
	ID          string `json:"id"`
	LocalFolder string `json:"localFolder"`
}

type ProjectConflictError struct {
	Project   string
	Workspace string
	Conflicts []ProjectConflict
}

type ProjectInfo struct {
	Name       string
	Workspace  string
	Containers []ContainerInfo
}

type UpRequest struct {
	// ContainerDataFolder selects lifecycle and dotfiles marker storage.
	ContainerDataFolder string
	// ContainerSystemDataFolder selects the upstream system patch marker folder.
	ContainerSystemDataFolder string
	// GPUAvailability controls implicit hostRequirements.gpu reservations. Empty means detect.
	GPUAvailability string
	// OmitConfigRemoteEnvFromMetadata omits the current config remoteEnv from new labels.
	OmitConfigRemoteEnvFromMetadata bool
	// Spec is the parsed devcontainer.json (must be in compose mode).
	Spec *spec.DevContainer
	// SpecPath is the host-side path the spec was loaded from. Used
	// for the devcontainer.config_file label on every container.
	SpecPath string
	// LocalWorkspace is the host workspace path; absolute. Used for
	// project identity and local workspace substitution.
	LocalWorkspace string
	// ContainerWorkspace is the in-container workspace folder. When
	// empty, falls back to spec.WorkspaceFolder, then "/" like upstream.
	// Used for lifecycle commands and substitution; Compose owns the mounts.
	ContainerWorkspace string
	// PrimaryImage, when set, overrides the primary service's image
	// in the override layer. Used to point compose at a feature-built
	// derived image.
	PrimaryImage string
	// ImageBuilt means PrimaryImage contains the complete current config and
	// feature metadata produced by BuildPrimaryImage.BuildResult, not only a
	// Compose service build. Such contributions must not be collected twice.
	ImageBuilt bool
	// SkipLifecycle suppresses all lifecycle commands for this invocation.
	SkipLifecycle bool
	// SkipPostAttach suppresses postAttachCommand for this invocation.
	SkipPostAttach bool
	// Dotfiles installs the user's dotfiles after postCreateCommand unless
	// SkipLifecycle is set.
	Dotfiles runner.Dotfiles
	// Lifecycle selects lifecycle stop points and prebuild behavior.
	Lifecycle runner.LifecycleControls
	// RemoteEnv is the caller's remote environment for lifecycle commands
	// and the dotfiles install (upstream --remote-env). The configuration's
	// remoteEnv wins for the same name, as upstream. It is not stored.
	RemoteEnv map[string]string
	// DefaultUserEnvProbe selects the shell probe when userEnvProbe is not configured.
	DefaultUserEnvProbe string
	// Secrets are secret environment variables for lifecycle commands and
	// the dotfiles install (upstream --secrets-file). They win over every
	// other layer and are never stored in container configuration, labels
	// or files.
	Secrets map[string]string
	// Features as resolved by pkg/features. Their containerEnv and
	// lifecycle commands are merged into the primary service.
	Features []features.Resolved
	// LocalEnv is forwarded to compose's `${VAR}` interpolation and
	// to ${localEnv:VAR} substitution in the spec. It's also the
	// lookup table for `environment:` source secrets/configs.
	LocalEnv map[string]string
	// Profiles activates compose service profiles. Services whose
	// `profiles:` are set to a non-empty list are excluded unless one
	// matches an entry here (or "*" is supplied). The primary service
	// (spec.Service) is always kept; its declared profiles are folded
	// into the active set so its own dependencies-by-profile come up.
	Profiles []string
	// Mounts are added to the primary service after the metadata mounts, in
	// devcontainer mount syntax (a CLI --mount). A named volume is a project
	// volume unless marked external=true. Up adds no host path that is not in
	// the configuration or here.
	Mounts []string
	// IDLabels, when non-empty, are set on the primary container and seed
	// ${devcontainerId} in place of the workspace labels, as upstream
	// --id-label does. The workspace labels stay on the primary so project
	// ownership checks and workspace-scoped Stop/Remove still apply.
	IDLabels map[string]string
	// AllowProjectConflict permits Up to reuse/recreate a project containing
	// another workspace's containers, matching upstream. The default refuses.
	AllowProjectConflict bool
}

type UpResult struct {
	// ProjectName is the resolved compose project name.
	ProjectName string
	// PrimaryContainerID is the ID of the container the spec's
	// `service` runs in.
	PrimaryContainerID string
	// ContainerIDs maps service name → container ID for every service
	// that was started this call (or reused).
	ContainerIDs map[string]string
	// CreatedThisCall enumerates services whose container was created
	// this call (vs reused).
	CreatedThisCall []string
	// StartedThisCall enumerates services whose container had to be
	// started this call (vs already running).
	StartedThisCall []string
	// RecreatedThisCall enumerates services whose container was
	// destroyed and recreated this call because its config-hash label
	// disagreed with the current spec.
	RecreatedThisCall []string
	// PhasesRun lists lifecycle phases that actually ran on the
	// primary (markers may have skipped some).
	PhasesRun []lifecycle.Hook
}

type WatchRequest struct {
	// Spec is the parsed devcontainer.json (must be in compose mode).
	Spec *spec.DevContainer
	// SpecPath is the host path the spec was loaded from. Used only
	// for diagnostics.
	SpecPath string
	// LocalWorkspace is the absolute host workspace path. Used as
	// the project name source so the active project lookup matches
	// what Up brought up.
	LocalWorkspace string
	// LocalEnv is forwarded to compose's `${VAR}` interpolation.
	LocalEnv map[string]string
	// PollInterval governs the host-side mtime sweep cadence.
	// Defaults to 1 second; smaller values are CPU-hungry on deep
	// trees.
	PollInterval time.Duration
	// OnEvent receives one callback per fired trigger. Optional;
	// useful for progress UIs and tests. The slice of changed
	// relative paths is supplied for `sync` and `sync+*` actions;
	// `restart` and `rebuild` pass nil.
	OnEvent func(service string, action types.WatchAction, changed []string)
}