docker

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

type ClientError struct {
	// Op is the operation that failed: "create", "start", "wait", "pull".
	Op string

	// Image is the image reference.
	Image string

	// ContainerID is the container ID if available.
	ContainerID string

	// Err is the underlying error.
	Err error
}

type Config struct {
	// ImageName is the Docker image to use for execution.
	// Default: toolruntime-sandbox:latest
	ImageName string

	// SeccompPath is the path to a custom seccomp profile for hardened mode.
	SeccompPath string

	// Client is the container runner implementation.
	// If nil, Execute() returns ErrClientNotConfigured.
	Client ContainerRunner

	// ImageResolver optionally resolves/pulls images before execution.
	// If nil, images are assumed to exist locally.
	ImageResolver ImageResolver

	// HealthChecker optionally verifies daemon health before execution.
	// If nil, health checks are skipped.
	HealthChecker HealthChecker

	// Logger is an optional logger for backend events.
	Logger Logger
}

type ContainerOptions struct {
	// NetworkDisabled disables network access.
	NetworkDisabled bool

	// ReadOnlyRootfs makes the root filesystem read-only.
	ReadOnlyRootfs bool

	// MemoryLimit is the memory limit in bytes.
	MemoryLimit int64

	// CPUQuota is the CPU quota in microseconds.
	CPUQuota int64

	// PidsLimit is the maximum number of processes.
	PidsLimit int64

	// SeccompProfile is the path to a seccomp profile.
	SeccompProfile string

	// User is the user to run as (non-root).
	User string
}

type ContainerResult struct {
	// ExitCode is the container's exit code.
	ExitCode int

	// Stdout contains the container's stdout output.
	Stdout string

	// Stderr contains the container's stderr output.
	Stderr string

	// Duration is the execution time.
	Duration time.Duration
}

type ContainerRunner interface {
	// Run executes code in a container and returns the result.
	// The container lifecycle (create, start, wait, remove) is atomic.
	//
	// The implementation must:
	//   - Validate the spec before execution
	//   - Respect ctx cancellation
	//   - Respect spec.Timeout if set
	//   - Capture stdout and stderr
	//   - Return the exit code
	//   - Clean up the container on completion or error
	Run(ctx context.Context, spec ContainerSpec) (ContainerResult, error)
}

type ContainerSpec struct {
	// Image is the Docker image reference (required).
	Image string

	// Command is the command to execute.
	Command []string

	// WorkingDir is the working directory inside the container.
	WorkingDir string

	// Env contains environment variables in KEY=value format.
	Env []string

	// Mounts defines volume mounts for the container.
	Mounts []Mount

	// Resources defines resource limits.
	Resources ResourceSpec

	// Security defines security settings.
	Security SecuritySpec

	// Timeout is the maximum execution duration.
	Timeout time.Duration

	// Labels are container labels for tracking.
	Labels map[string]string
}

type DaemonInfo struct {
	// Version is the daemon version.
	Version string

	// APIVersion is the API version.
	APIVersion string

	// OS is the daemon operating system.
	OS string

	// Architecture is the daemon CPU architecture.
	Architecture string

	// RootDir is the daemon's root directory.
	RootDir string
}

type HealthChecker interface {
	// Ping checks if the Docker daemon is responsive.
	Ping(ctx context.Context) error

	// Info returns daemon information (version, OS, etc.).
	Info(ctx context.Context) (DaemonInfo, error)
}

type ImageResolver interface {
	// Resolve ensures the image is available locally.
	// Returns the resolved image reference (may include digest).
	// If the image doesn't exist locally, it will be pulled.
	Resolve(ctx context.Context, image string) (string, error)
}

type Logger interface {
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

type Mount struct {
	// Type specifies the mount type: "bind", "volume", or "tmpfs".
	Type MountType

	// Source is the host path (bind) or volume name (volume).
	// Ignored for tmpfs mounts.
	Source string

	// Target is the path inside the container.
	Target string

	// ReadOnly mounts the volume as read-only.
	ReadOnly bool

	// Consistency is the mount consistency mode: "consistent", "cached", "delegated".
	// Only relevant for bind mounts on macOS.
	Consistency string
}

type MountType string

type ResourceSpec struct {
	// MemoryBytes is the memory limit in bytes.
	// Zero means unlimited.
	MemoryBytes int64

	// CPUQuota is the CPU quota in microseconds per 100ms period.
	// Zero means unlimited.
	CPUQuota int64

	// PidsLimit is the maximum number of processes.
	// Zero means unlimited.
	PidsLimit int64

	// DiskBytes is the disk limit in bytes.
	// Zero means unlimited. Not all runtimes support this.
	DiskBytes int64
}

type SecuritySpec struct {
	// User is the user to run as (e.g., "nobody:nogroup").
	User string

	// ReadOnlyRootfs mounts the root filesystem as read-only.
	ReadOnlyRootfs bool

	// NetworkMode is the network mode: "none", "bridge", "host".
	// "host" is not allowed in sandbox contexts.
	NetworkMode string

	// SeccompProfile is the path to a seccomp profile.
	// Empty uses the runtime's default profile.
	SeccompProfile string

	// Privileged grants extended privileges to the container.
	// Must always be false in sandbox contexts.
	Privileged bool
}

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

type StreamEvent struct {
	// Type identifies the event type.
	Type StreamEventType

	// Data contains the event payload (stdout/stderr bytes).
	Data []byte

	// ExitCode is set when Type is StreamEventExit.
	ExitCode int

	// Error is set when Type is StreamEventError.
	Error error
}

type StreamEventType string

type StreamRunner interface {
	ContainerRunner

	// RunStream executes and streams stdout/stderr as events.
	// The returned channel is closed when execution completes.
	// Callers should drain the channel to receive the exit event.
	RunStream(ctx context.Context, spec ContainerSpec) (<-chan StreamEvent, error)
}