runtime

type BuildEvent struct {
	Kind    BuildEventKind
	Message string
	LayerID string
	Digest  string
}

type BuildEventKind string

type BuildSpec struct {
	ContextPath string
	Dockerfile  string
	Tag         string
	Args        map[string]string
	Target      string
	CacheFrom   []string
	NoCache     bool
	Platform    string
}

type BuilderUnavailableError struct {
	// Hint is a backend-specific message telling the user how to
	// remediate (e.g. "run `container builder start`").
	Hint string
	Err  error
}

type Capabilities struct {
	// Healthchecks: backend honors HEALTHCHECK directives on
	// RunSpec/BuildSpec, and InspectContainer surfaces
	// State.Health.Status. Required for compose's
	// depends_on.<svc>.condition: service_healthy gating.
	//
	// Apple 0.12.x: false (apple/container #1502).
	Healthchecks bool

	// ExitCodes: InspectContainer returns the container's exit code
	// after Stop (ContainerDetails.ExitCode is meaningful for
	// state=exited). Required for compose's depends_on condition:
	// service_completed_successfully.
	//
	// Apple 0.12.x: false (apple/container #1501).
	ExitCodes bool

	// NamespaceSharing: backend supports network_mode / pid / ipc
	// set to service:<other> (Linux namespace sharing within one
	// kernel).
	//
	// Apple: architectural false — one VM per container means
	// separate kernels; namespace sharing is not implementable.
	NamespaceSharing bool

	// RestartPolicies: backend enforces compose's `restart:` field
	// via RunSpec or backend-equivalent. When false, the
	// orchestrator emits a single WarnRestartPolicyIgnoredOnBackend
	// event per Plan rather than refusing the project.
	//
	// Apple 0.12.x: false (apple/container #286).
	RestartPolicies bool

	// SharedVolumes: a single named volume can be concurrently
	// mounted into 2+ running containers. Apple's
	// ext4-on-disk-image volumes refuse multi-attach with
	// VZErrorDomain Code=2; Plan.Validate refuses such projects on
	// backends where this is false.
	//
	// Apple 0.12.x: false (apple/container #889).
	SharedVolumes bool

	// ServiceNameDNS: containers on the project network can resolve
	// peers by service name out of the box (compose's default
	// behavior). When false, the orchestrator falls back to a
	// post-start /etc/hosts patch driven by InspectContainer +
	// ExecContainer to seed the service→IP map.
	//
	// Apple 0.12.x: false (probe 3; apple/container #856 / 856
	// resolution upstream is open). The hosts-patch workaround
	// covers depends_on-declared edges; intra-level peers without a
	// depends_on edge race and may miss the patch on first DNS
	// lookup — documented limitation on this backend.
	ServiceNameDNS bool
}

type ComposeDownSpec struct {
	Files       []string
	ProjectName string
	WorkingDir  string

	// RemoveImages, when true, passes --rmi local (removes images
	// the project built locally; spares pulled images).
	RemoveImages bool

	// RemoveVolumes, when true, passes --volumes (removes named
	// volumes declared by the project plus anonymous volumes).
	RemoveVolumes bool
}

type ComposeFailedError struct {
	Args     []string
	ExitCode int
	Stderr   string
}

type ComposePsSpec struct {
	Files       []string
	ProjectName string
	WorkingDir  string
}

type ComposeRuntime interface {
	// ComposeUp brings the project up in the background (-d).
	// Compose decides what to (re)build via its own logic; we feed it
	// override files that pin the primary service's image to a tag we
	// already built, so it does not rebuild that one.
	ComposeUp(ctx context.Context, spec ComposeUpSpec, events chan<- BuildEvent) error

	// ComposeDown stops and (optionally) removes the project's
	// containers, networks, and volumes.
	ComposeDown(ctx context.Context, spec ComposeDownSpec) error

	// ComposeContainerID returns the container id for a service in a
	// running project. Used by Engine.Up to pick out the primary
	// service's container after `compose up -d` settles. Returns
	// empty string if the service isn't running.
	ComposeContainerID(ctx context.Context, spec ComposePsSpec, service string) (string, error)
}

type ComposeUnavailableError struct {
	Err error
}

type ComposeUpSpec struct {
	// Files lists compose files in declaration order — user files
	// first, then our generated overrides (build, run). Each becomes
	// a `-f <path>` flag.
	Files []string

	// ProjectName is passed via -p / --project-name. Engine derives
	// it from the workspace id (`dc-<devcontainerId>` per PRD §12.5).
	ProjectName string

	// Services optionally restricts which services to start. Empty =
	// all services in the project (compose default).
	Services []string

	// WorkingDir is the directory `docker compose` runs in. Used as
	// the base for compose's relative-path resolution. Engine sets
	// this to the workspace folder.
	WorkingDir string

	// NoRecreate, when true, appends `--no-recreate` to the compose
	// invocation. Tells compose to keep an existing container even if
	// it thinks the config drifted — used on the resume path so we
	// don't destroy the container's writable layer (and anything in
	// $HOME inside it) on a spurious drift detection. Matches the
	// upstream devcontainers/cli gate (`container || expectExistingContainer`).
	NoRecreate bool
}

type Container struct {
	ID    string
	Name  string
	Image string
	State State

	// Labels are populated by ListContainers and FindContainerByLabel
	// when the backend can surface them cheaply. RunContainer may
	// leave this nil; callers that need labels after a fresh create
	// should InspectContainer. The compose orchestrator reads this
	// to identify the service name during reverse-topo teardown.
	Labels map[string]string
}

type ContainerDetails struct {
	Container
	Created   time.Time
	StartedAt time.Time
	User      string
	Env       []string // KEY=VALUE pairs from the running container
	Mounts    []MountInspect
	Labels    map[string]string

	// ExitCode is the container's last exit code. Zero is ambiguous:
	// either "process is still running" or "process exited cleanly".
	// Use State to disambiguate (running vs exited).
	ExitCode int

	// FinishedAt is when the container's main process last exited. Zero
	// for never-exited containers.
	FinishedAt time.Time

	// Health reports the most recent HEALTHCHECK result.
	// HealthNone means the image declared no healthcheck (i.e. the
	// daemon never produced one); the compose orchestrator's
	// service_healthy gate treats this as "satisfied" so projects
	// without healthchecks still come up.
	Health HealthStatus
}

type ContainerNotFoundError struct {
	ID  string
	Err error
}

type DaemonUnavailableError struct {
	Err error
}

type ExecFailedError struct {
	ExitCode int
	Stderr   string
}

type ExecOptions struct {
	Cmd        []string
	Env        map[string]string
	User       string
	WorkingDir string
	Tty        bool
	Stdin      io.Reader
	Stdout     io.Writer
	Stderr     io.Writer
}

type ExecResult struct {
	ExitCode int
	Stdout   string // only populated if ExecOptions.Stdout was nil
	Stderr   string // only populated if ExecOptions.Stderr was nil
}

type HealthCheckSpec struct {
	Test          []string
	Interval      time.Duration
	Timeout       time.Duration
	Retries       int
	StartPeriod   time.Duration
	StartInterval time.Duration
	Disable       bool
}

type HealthStatus string

type ImageDetails struct {
	ID     string
	Tags   []string
	Labels map[string]string
	Env    []string

	// User is the image's default USER directive (Config.User), or "" if
	// unset. Used to determine the effective container user for UID
	// reconciliation when devcontainer.json's remoteUser/containerUser
	// are also empty.
	User string
}

type ImageNotFoundError struct {
	Ref string
	Err error
}

type ImageRef struct {
	ID   string // sha256:... digest
	Tags []string
}

type LabelFilter struct {
	// Match is the AND set: every key must be present on the
	// resource AND its value must equal the requested value.
	// Implementations that lack server-side filtering (apple, per
	// design probe R1b) translate this client-side after enumeration.
	Match map[string]string
}

type MountInspect struct {
	Type     string
	Source   string
	Target   string
	ReadOnly bool
}

type MountSpec struct {
	Type        MountType
	Source      string
	Target      string
	ReadOnly    bool
	Propagation string // host bind consistency: "consistent" | "cached" | "delegated" | "" (Linux default)
}

type MountType string

type NetworkSpec struct {
	// Name is the user-facing network name (e.g. dc-<id>_default).
	// Backends namespace internally if their model requires it; the
	// returned ID is what callers store for later RemoveNetwork.
	Name string

	// Labels are stamped on the network for identification at
	// teardown. The orchestrator uses com.docker.compose.project +
	// dev.containers.engine labels exclusively; backends pass them
	// through verbatim.
	Labels map[string]string

	// Driver selects the backend's network driver. Empty string means
	// "backend default" (bridge on docker; vmnet-based default on
	// apple). Non-default drivers are out of scope for v1.
	Driver string

	// Options is the driver-options string map (compose's
	// driver_opts:). Pass-through; backends may reject unknown keys
	// with a typed error.
	Options map[string]string
}

type PortBinding struct {
	// HostIP optionally restricts the bind to a specific host
	// address. Empty = all interfaces (docker's 0.0.0.0 default).
	HostIP string

	// HostPort is the host-side port. Empty = let the daemon pick
	// (docker assigns from the ephemeral range).
	HostPort string

	// ContainerPort is the in-container port that's being
	// published. Required.
	ContainerPort int

	// Protocol is "tcp" or "udp". Empty defaults to "tcp".
	Protocol string
}

type RemoveOptions struct {
	Force         bool
	RemoveVolumes bool
}

type RestartPolicy string

type RunSpec struct {
	Image      string
	Name       string
	Cmd        []string
	Entrypoint []string

	User       string
	WorkingDir string
	Env        map[string]string
	Labels     map[string]string

	Mounts []MountSpec

	// RunArgs is a list of additional Docker CLI-style flags (e.g.
	// "--add-host=host:ip"). Implementations parse and apply where
	// supported; unsupported flags become warnings, not errors.
	RunArgs []string

	Init        bool
	Privileged  bool
	CapAdd      []string
	SecurityOpt []string

	// HealthCheck declares the HEALTHCHECK directive at create time.
	// Nil means inherit from the image (i.e. no override). Used by
	// the compose orchestrator to translate `healthcheck:` directives.
	HealthCheck *HealthCheckSpec

	// Networks lists project networks the container joins. Empty
	// means "backend default" — docker assigns the default bridge;
	// apple assigns the built-in vmnet network. Used by the compose
	// orchestrator to attach services to the project network it
	// just created via CreateNetwork.
	Networks []string

	// Ports lists the ports this container publishes to the host.
	// Empty means no publishing (the container's ports are reachable
	// inside the project network but not from the host). Used by
	// the compose orchestrator to translate `ports:` directives.
	Ports []PortBinding

	// RestartPolicy controls whether the runtime restarts the
	// container on exit. Zero-value (RestartNo) matches docker's
	// `no` default. Used by the compose orchestrator to translate
	// `restart:` directives.
	RestartPolicy RestartPolicy

	// OverrideCommand, when true, forces Cmd to be ["/bin/sh","-c","while sleep 1000; do :; done"]
	// so the container stays alive for exec-based interaction. Spec default true.
	OverrideCommand bool

	// MemoryBytes is the hard memory limit for the container, in bytes.
	// Zero means "unset": the backend's own default applies — for docker
	// that's no cgroup limit; for apple it's the apiserver's per-VM
	// default (1 GiB on 0.12.x). Negative values are rejected by the
	// backend.
	//
	// On apple, this sizes the per-container VM at boot; the guest
	// kernel sees exactly this much memory and the value cannot be
	// resized without container recreation. On docker, this maps to
	// HostConfig.Memory and is enforced by cgroups.
	MemoryBytes int64

	// NanoCPUs is the CPU limit expressed in nano-units: 1_000_000_000
	// = one full CPU, 2_500_000_000 = 2.5 CPUs. Matches docker's
	// HostConfig.NanoCPUs convention so a single field works across
	// backends. Zero means "unset". Apple's apiserver takes an integer
	// CPU count, so the value is rounded up to the next whole CPU at
	// the bridge boundary (e.g. 1_500_000_000 → 2 cpus).
	NanoCPUs int64
}

type Runtime interface {
	// BuildImage builds an image from a build spec and returns its
	// reference. Build progress is streamed on events (best-effort; events
	// may be dropped if the channel is full).
	BuildImage(ctx context.Context, spec BuildSpec, events chan<- BuildEvent) (ImageRef, error)

	// PullImage fetches an image from a registry, returning its reference.
	// Pull progress is streamed on events.
	PullImage(ctx context.Context, ref string, events chan<- BuildEvent) (ImageRef, error)

	// RunContainer creates a container from a run spec. The container is
	// not started — call StartContainer when ready. Splitting create from
	// start lets callers attach hooks (e.g. mark files) between phases.
	RunContainer(ctx context.Context, spec RunSpec) (*Container, error)

	// StartContainer starts a previously created container.
	StartContainer(ctx context.Context, id string) error

	// StopContainer stops a running container, waiting up to opts.Timeout
	// for graceful shutdown before SIGKILL.
	StopContainer(ctx context.Context, id string, opts StopOptions) error

	// RemoveContainer removes a container. The container must be stopped
	// unless opts.Force is set.
	RemoveContainer(ctx context.Context, id string, opts RemoveOptions) error

	// ExecContainer runs a command inside a running container. If
	// opts.Stdout / Stderr are nil, output is captured into ExecResult.
	ExecContainer(ctx context.Context, id string, opts ExecOptions) (ExecResult, error)

	// InspectContainer returns full details for a container, including
	// the live env (used for ${containerEnv:*} substitution).
	InspectContainer(ctx context.Context, id string) (*ContainerDetails, error)

	// InspectImage returns the image's labels, env, and other config.
	// Used by the engine to read the devcontainer.metadata label off
	// pre-baked images and skip already-installed features.
	InspectImage(ctx context.Context, ref string) (*ImageDetails, error)

	// ContainerLogs streams the container's stdout+stderr to w. If follow
	// is true, the call blocks until ctx is cancelled or the container exits.
	ContainerLogs(ctx context.Context, id string, w io.Writer, follow bool) error

	// FindContainerByLabel returns the most recently created container
	// matching the given label. Returns nil, nil if no match.
	FindContainerByLabel(ctx context.Context, key, value string) (*Container, error)

	// CreateNetwork creates a network with the given name and
	// labels. Returns the backend's network ID for later
	// RemoveNetwork. Idempotent on (name, labels) match: if a
	// network with the same name and matching label set already
	// exists, return its ID without error (same shape as compose's
	// own up behavior).
	CreateNetwork(ctx context.Context, spec NetworkSpec) (string, error)

	// RemoveNetwork removes a network by its backend ID. No-op if
	// the network is already gone.
	RemoveNetwork(ctx context.Context, id string) error

	// CreateVolume creates a named volume. Idempotent on (name,
	// labels). Returns the backend's volume identifier — usually
	// the name itself, but backends may translate.
	CreateVolume(ctx context.Context, spec VolumeSpec) (string, error)

	// RemoveVolume removes a named volume. No-op if missing.
	RemoveVolume(ctx context.Context, name string) error

	// ListContainers returns containers matching every label in the
	// filter. Empty filter is rejected — we never want to enumerate
	// all containers. Implementations without server-side filtering
	// (e.g. applecontainer per design probe R1b) filter client-side
	// after a full enumeration.
	ListContainers(ctx context.Context, filter LabelFilter) ([]Container, error)

	// ListImages returns local images matching the filter. Used by
	// Down --rmi local: built images are stamped with project labels
	// so teardown can prune by label. Same empty-filter rule as
	// ListContainers.
	ListImages(ctx context.Context, filter LabelFilter) ([]ImageRef, error)

	// RemoveImage removes a local image by ID or reference. No-op
	// if missing.
	RemoveImage(ctx context.Context, ref string) error

	// Capabilities advertises optional features this backend
	// supports. compose.Plan.Validate keys feature gates off this
	// struct so per-backend conditionals stay out of the validator.
	// The returned value should be a constant for the lifetime of
	// the Runtime; callers may cache it.
	Capabilities() Capabilities
}

type State string

type StopOptions struct {
	Timeout time.Duration // grace period before SIGKILL; 0 = engine default
}

type UnsupportedOptionError struct {
	Backend string
	Option  string
}

type VolumeSpec struct {
	// Name is the user-facing volume name (e.g. dc-<id>_<volname>).
	// Backends translate to whatever their native naming requires.
	Name string

	// Labels for teardown lookup. Same convention as NetworkSpec.
	Labels map[string]string

	// Driver selects the backend's volume driver. Empty = backend
	// default (local on docker; the file-backed driver on apple).
	Driver string

	// Options is the driver-options string map. Pass-through.
	Options map[string]string
}