Documentation
¶
Overview ¶
Package container provides functions for managing Apple container operations
Index ¶
- Constants
- func DiagnoseNetworkHint(kind NetworkErrorKind, retriesExhausted bool) string
- func KernelsDir() string
- func SetKernelMock(empty bool, err error) func()
- func SetLookupPathMock(err error) func()
- type ContainerConfiguration
- type ContainerInfo
- type DefaultRunner
- func (r *DefaultRunner) CheckRunning(name string) bool
- func (r *DefaultRunner) CombinedOutput(args ...string) (string, error)
- func (r *DefaultRunner) ListImages() ([]string, error)
- func (r *DefaultRunner) Output(args ...string) (string, error)
- func (r *DefaultRunner) Run(args ...string) error
- func (r *DefaultRunner) RunInteractive(args ...string) error
- func (r *DefaultRunner) StreamCombinedOutput(w io.Writer, args ...string) (string, error)
- type DryRunRunner
- func (d *DryRunRunner) CheckRunning(name string) bool
- func (d *DryRunRunner) CombinedOutput(args ...string) (string, error)
- func (d *DryRunRunner) ListImages() ([]string, error)
- func (d *DryRunRunner) Output(args ...string) (string, error)
- func (d *DryRunRunner) Run(args ...string) error
- func (d *DryRunRunner) RunInteractive(args ...string) error
- type ImageBuilder
- type InitProcess
- type Manager
- func (m *Manager) BuildContainerArgs(workspace, worktrees string) ([]string, error)
- func (m *Manager) BuildImage(forceRebuild bool) error
- func (m *Manager) CheckDNSConfiguration(showPrompt bool)
- func (m *Manager) CheckRequirements() error
- func (m *Manager) Clean() error
- func (m *Manager) ImageExists() bool
- func (m *Manager) List() error
- func (m *Manager) ListContainers() []ContainerInfo
- func (m *Manager) PrepareContainer(workspace, worktrees string) error
- func (m *Manager) PrintStartupInfo(label, workspace, worktrees string)
- func (m *Manager) RunInteractive(workspace, worktrees string, useTmux bool, shellCmd string) error
- func (m *Manager) ScanCustomMounts(ctx context.Context) error
- func (m *Manager) ScanWorkspace(ctx context.Context, workspace string) error
- func (m *Manager) Stop(name string) error
- type MountInfo
- type NetworkChecker
- type NetworkErrorKind
- type NetworkInfo
- type Runner
- type StreamingRunner
- type SystemChecker
Constants ¶
const DefaultDNSDomain = "test"
DefaultDNSDomain is the DNS domain used for container hostname resolution
const StagedFilesContainerDir = "/tmp/bopca-staged-files"
StagedFilesContainerDir is the container path where the staged _files/ directory is mounted. The startup script copies files from here into $HOME.
Variables ¶
This section is empty.
Functions ¶
func DiagnoseNetworkHint ¶ added in v0.7.0
func DiagnoseNetworkHint(kind NetworkErrorKind, retriesExhausted bool) string
DiagnoseNetworkHint returns actionable hint text for the given network error kind. Suggestions escalate from simple checks to more disruptive steps. If retriesExhausted is true, the automatic service restart already failed and the hints include manual recovery and last-resort options.
func KernelsDir ¶ added in v0.6.0
func KernelsDir() string
KernelsDir returns the path to the container kernels directory. Returns empty string if home directory cannot be determined.
func SetKernelMock ¶ added in v0.6.0
SetKernelMock sets the kernel directory check function for testing from external packages. Returns a restore function that should be called to reset the original value.
func SetLookupPathMock ¶ added in v0.8.0
func SetLookupPathMock(err error) func()
SetLookupPathMock sets the lookupPath function for testing from external packages. Returns a restore function that should be called to reset the original value.
Types ¶
type ContainerConfiguration ¶ added in v0.7.0
type ContainerConfiguration struct {
ID string `json:"id"`
Mounts []MountInfo `json:"mounts"`
InitProcess InitProcess `json:"initProcess"`
}
ContainerConfiguration holds container configuration details
type ContainerInfo ¶ added in v0.7.0
type ContainerInfo struct {
Name string `json:"name"`
Configuration ContainerConfiguration `json:"configuration"`
Networks []NetworkInfo `json:"networks"`
Status string `json:"status"`
}
ContainerInfo represents a container from JSON output of `container ls --format json`
type DefaultRunner ¶
type DefaultRunner struct{}
DefaultRunner implements Runner using the actual container CLI
func (*DefaultRunner) CheckRunning ¶
func (r *DefaultRunner) CheckRunning(name string) bool
CheckRunning checks if a container with the given name is running
func (*DefaultRunner) CombinedOutput ¶ added in v0.6.0
func (r *DefaultRunner) CombinedOutput(args ...string) (string, error)
CombinedOutput executes a container command and returns combined stdout/stderr
func (*DefaultRunner) ListImages ¶
func (r *DefaultRunner) ListImages() ([]string, error)
ListImages returns a list of container images. Uses CombinedOutput to capture stderr so callers that treat failures as non-fatal don't leak raw error output to the terminal.
func (*DefaultRunner) Output ¶
func (r *DefaultRunner) Output(args ...string) (string, error)
Output executes a container command and returns its stdout. Stderr is captured and logged at debug level instead of leaking to the terminal.
func (*DefaultRunner) Run ¶
func (r *DefaultRunner) Run(args ...string) error
Run executes a container command, capturing stdout and stderr so they don't leak raw container-CLI output to the terminal in default mode.
func (*DefaultRunner) RunInteractive ¶
func (r *DefaultRunner) RunInteractive(args ...string) error
RunInteractive executes a container command with interactive I/O
func (*DefaultRunner) StreamCombinedOutput ¶ added in v0.6.0
StreamCombinedOutput executes a container command, streaming combined stdout/stderr line by line to w, and returns the full output.
type DryRunRunner ¶ added in v0.6.0
type DryRunRunner struct {
Wrapped Runner
// contains filtered or unexported fields
}
DryRunRunner wraps a Runner and prints commands instead of executing them
func NewDryRunRunner ¶ added in v0.6.0
func NewDryRunRunner(wrapped Runner, extraSensitiveEnvPrefixes ...string) *DryRunRunner
NewDryRunRunner creates a new DryRunRunner that wraps the given runner
func (*DryRunRunner) CheckRunning ¶ added in v0.6.0
func (d *DryRunRunner) CheckRunning(name string) bool
CheckRunning delegates to the wrapped runner (read-only operation)
func (*DryRunRunner) CombinedOutput ¶ added in v0.6.0
func (d *DryRunRunner) CombinedOutput(args ...string) (string, error)
CombinedOutput delegates to the wrapped runner (read-only operation)
func (*DryRunRunner) ListImages ¶ added in v0.6.0
func (d *DryRunRunner) ListImages() ([]string, error)
ListImages delegates to the wrapped runner (read-only operation)
func (*DryRunRunner) Output ¶ added in v0.6.0
func (d *DryRunRunner) Output(args ...string) (string, error)
Output delegates to the wrapped runner (read-only operation)
func (*DryRunRunner) Run ¶ added in v0.6.0
func (d *DryRunRunner) Run(args ...string) error
Run prints the command that would be executed instead of running it
func (*DryRunRunner) RunInteractive ¶ added in v0.6.0
func (d *DryRunRunner) RunInteractive(args ...string) error
RunInteractive prints the command that would be executed instead of running it
type ImageBuilder ¶ added in v0.6.0
type ImageBuilder struct {
Config *config.Config
Network *NetworkChecker
Runner Runner
Scanner scanner.Scanner
}
ImageBuilder handles container image creation and management
func NewImageBuilder ¶ added in v0.6.0
func NewImageBuilder(runner Runner, cfg *config.Config) *ImageBuilder
NewImageBuilder creates a new ImageBuilder with the given runner and config
func (*ImageBuilder) Build ¶ added in v0.6.0
func (b *ImageBuilder) Build(forceRebuild bool) error
Build builds the container image
func (*ImageBuilder) Exists ¶ added in v0.6.0
func (b *ImageBuilder) Exists() bool
Exists checks if the container image exists
func (*ImageBuilder) IsStale ¶ added in v0.8.0
func (b *ImageBuilder) IsStale() (bool, error)
IsStale checks whether the built image's recipe hash matches the current config. Returns true when the image should be rebuilt.
func (*ImageBuilder) Remove ¶ added in v0.6.0
func (b *ImageBuilder) Remove() error
Remove removes the container image
func (*ImageBuilder) ResolveImageName ¶ added in v0.8.0
func (b *ImageBuilder) ResolveImageName()
ResolveImageName resolves toolchains and sets Config.ImageName based on the content-derived name hash. Must be called before any image operations.
func (*ImageBuilder) ScanBuildInputs ¶ added in v0.6.0
func (b *ImageBuilder) ScanBuildInputs(ctx context.Context) error
ScanBuildInputs scans build configuration inputs for secrets
type InitProcess ¶ added in v0.8.0
type InitProcess struct {
Environment []string `json:"environment"`
WorkingDirectory string `json:"workingDirectory"`
}
InitProcess holds the init process configuration from container JSON output
type Manager ¶
type Manager struct {
Config *config.Config
Image *ImageBuilder
Network *NetworkChecker
Runner Runner
Scanner scanner.Scanner
System *SystemChecker
// contains filtered or unexported fields
}
Manager handles container operations by coordinating specialized components
func NewManager ¶
NewManager creates a new container manager with all components
func (*Manager) BuildContainerArgs ¶
BuildContainerArgs builds the arguments for running a container. When agentDef is nil, follows the shell path (no agent-specific mounts/env). Workspace and worktrees are mounted at their host paths. HOME is set to the host user's home directory.
func (*Manager) BuildImage ¶
BuildImage delegates to ImageBuilder after checking DNS
func (*Manager) CheckDNSConfiguration ¶
CheckDNSConfiguration delegates to SystemChecker
func (*Manager) CheckRequirements ¶
CheckRequirements delegates to SystemChecker
func (*Manager) Clean ¶
Clean stops all running bopca containers and removes all bopca-prefixed images. Note: Returns nil if nothing exists (idempotent operation).
func (*Manager) ImageExists ¶
ImageExists delegates to ImageBuilder
func (*Manager) List ¶
List shows image status and a table of running bopca-managed containers. Returns nil even if listing fails (graceful degradation).
func (*Manager) ListContainers ¶ added in v0.7.0
func (m *Manager) ListContainers() []ContainerInfo
ListContainers returns running bopca-managed containers (those with BOPCA_CONTAINER_NAME set). Returns nil on command or parse failure for graceful degradation.
func (*Manager) PrepareContainer ¶
PrepareContainer prepares for running a container
func (*Manager) PrintStartupInfo ¶
PrintStartupInfo prints information about the container being started. The label is displayed in the "Starting <label>..." message (e.g. "container" or an agent display name).
func (*Manager) RunInteractive ¶
RunInteractive starts an interactive container session
func (*Manager) ScanCustomMounts ¶ added in v0.6.0
ScanCustomMounts scans custom mounts for secrets before attaching them. Uses the same interactive/non-interactive flow as ScanWorkspace.
func (*Manager) ScanWorkspace ¶ added in v0.6.0
ScanWorkspace scans a workspace directory for secrets before mounting. In interactive (TTY) sessions, presents a multi-select form for review. In non-interactive sessions, blocks deterministically.
type NetworkChecker ¶ added in v0.7.0
type NetworkChecker struct {
Runner Runner
}
NetworkChecker provides network error classification and recovery for the container service. A single instance is shared across Manager components.
func NewNetworkChecker ¶ added in v0.7.0
func NewNetworkChecker(runner Runner) *NetworkChecker
NewNetworkChecker creates a NetworkChecker that uses the given runner for service restart commands.
func (*NetworkChecker) RestartContainerService ¶ added in v0.7.0
func (n *NetworkChecker) RestartContainerService() error
RestartContainerService stops then starts the container service. Each step has a 30-second timeout. Returns a wrapped error identifying which step failed.
type NetworkErrorKind ¶ added in v0.7.0
type NetworkErrorKind int
NetworkErrorKind classifies the type of network error detected.
const ( // NetworkErrorNone indicates no network error was detected. NetworkErrorNone NetworkErrorKind = iota // NetworkErrorDNS indicates a transient DNS resolution failure. NetworkErrorDNS // NetworkErrorTimeout indicates an I/O timeout. NetworkErrorTimeout // NetworkErrorXPC indicates an XPC connection error (service crash). NetworkErrorXPC // NetworkErrorBuiltinNetwork indicates the builtin network is not present. NetworkErrorBuiltinNetwork )
func (NetworkErrorKind) String ¶ added in v0.7.0
func (k NetworkErrorKind) String() string
String returns a human-readable label for the error kind.
type NetworkInfo ¶ added in v0.7.0
type NetworkInfo struct {
IPv4Address string `json:"ipv4Address"`
}
NetworkInfo represents a container network
type Runner ¶
type Runner interface {
CheckRunning(name string) bool
CombinedOutput(args ...string) (string, error)
ListImages() ([]string, error)
Output(args ...string) (string, error)
Run(args ...string) error
RunInteractive(args ...string) error
}
Runner provides an interface for executing container commands
type StreamingRunner ¶ added in v0.6.0
type StreamingRunner interface {
StreamCombinedOutput(w io.Writer, args ...string) (string, error)
}
StreamingRunner is optionally implemented by runners that support streaming combined output line by line.
type SystemChecker ¶ added in v0.6.0
type SystemChecker struct {
Network *NetworkChecker
Runner Runner
}
SystemChecker handles platform and service requirements verification
func NewSystemChecker ¶ added in v0.6.0
func NewSystemChecker(runner Runner) *SystemChecker
NewSystemChecker creates a new SystemChecker with the given runner
func (*SystemChecker) CheckDNSConfiguration ¶ added in v0.6.0
func (s *SystemChecker) CheckDNSConfiguration(showPrompt bool)
CheckDNSConfiguration checks and configures DNS if needed
func (*SystemChecker) CheckRequirements ¶ added in v0.6.0
func (s *SystemChecker) CheckRequirements() error
CheckRequirements verifies that the system meets requirements