Documentation
¶
Overview ¶
build_gate_image_resolver.go implements the Build Gate image catalog resolver.
The resolver selects runtime images for Build Gate containers when Stack Gate is enabled. It loads rules from multiple sources with precedence ordering:
- Default gates catalog (gates/gates.yaml) - lowest precedence
- Mig-level image overrides - highest precedence
Resolution uses "most specific match wins" semantics:
- Tool-specific rules (specificity 3) beat tool-agnostic rules (specificity 2)
- Same-specificity ties with different images are configuration errors
gate_docker.go implements the Docker-based GateExecutor.
This executor is the canonical source of gate validation results: it runs a language-specific image with the workspace mounted at /workspace, captures logs and resource usage, and returns BuildGateStageMetadata. Concerns are split across sibling files: mounts (gate_docker_mounts.go), log streaming (container_log_streamer.go), env-driven resource limits (gate_docker_env.go), and result normalization (gate_docker_metadata.go). Stack detection + image resolution live in gate_plan_resolver.go.
Index ¶
- func NormalizeContainerResourceUsage(usage *contracts.BuildGateResourceUsage) *types.RunStatsJobResources
- func RemoveDockerJobResources(ctx context.Context, docker DockerJobResourceClient, owner DockerJobOwner) error
- func WithExecutionLogWriter(ctx context.Context, w io.Writer) context.Context
- func WithGateContainerLabels(ctx context.Context, labels map[string]string) context.Context
- func WithGateRuntimeImageObserver(ctx context.Context, obs GateRuntimeImageObserver) context.Context
- type ContainerHandle
- type ContainerMount
- type ContainerResult
- type ContainerRuntime
- type ContainerRuntimeOptions
- type ContainerSpec
- type DiffGenerator
- type DockerJobOwner
- type DockerJobResourceClient
- type GateExecutor
- type GateRuntimeImageObserver
- type JobMounts
- type PatchStats
- type Request
- type Result
- type Runner
- type StageTiming
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NormalizeContainerResourceUsage ¶
func NormalizeContainerResourceUsage(usage *contracts.BuildGateResourceUsage) *types.RunStatsJobResources
NormalizeContainerResourceUsage converts Docker counters to persisted job metrics.
func RemoveDockerJobResources ¶
func RemoveDockerJobResources(ctx context.Context, docker DockerJobResourceClient, owner DockerJobOwner) error
RemoveDockerJobResources requires the owner to have stopped creating resources. It never adopts external resources or force-removes volumes used elsewhere.
func WithExecutionLogWriter ¶
WithExecutionLogWriter stores an optional live log sink in context so lower-level executors (for example gate runtime) can stream container output through the standard node log uploader path.
func WithGateContainerLabels ¶
WithGateContainerLabels attaches container labels to gate execution context. Labels are copied and merged with existing gate labels in the context.
func WithGateRuntimeImageObserver ¶
func WithGateRuntimeImageObserver(ctx context.Context, obs GateRuntimeImageObserver) context.Context
WithGateRuntimeImageObserver attaches an observer to the context used for gate execution. The observer is called with the resolved runtime image before container execution starts.
Types ¶
type ContainerHandle ¶
type ContainerHandle string
ContainerHandle identifies a prepared container by its ID.
type ContainerMount ¶
ContainerMount describes a host path mount.
type ContainerResult ¶
type ContainerResult struct {
ExitCode int
StartedAt time.Time
CompletedAt time.Time
ContainerID string
InspectJSON []byte
}
ContainerResult captures container exit metadata.
type ContainerRuntime ¶
type ContainerRuntime interface {
Create(ctx context.Context, spec ContainerSpec) (ContainerHandle, error)
Start(ctx context.Context, handle ContainerHandle) error
Wait(ctx context.Context, handle ContainerHandle) (ContainerResult, error)
Logs(ctx context.Context, handle ContainerHandle) ([]byte, error)
Remove(ctx context.Context, handle ContainerHandle) error
}
ContainerRuntime executes containers. Docker-socket specs require job-owned /tmp storage. Their socket proxy uses the spec's mount projection and lasts for one Create/Start/Wait execution.
func NewContainerRuntime ¶
func NewContainerRuntime(opts ContainerRuntimeOptions) (ContainerRuntime, error)
NewContainerRuntime constructs a Docker-backed container runtime. It uses client.FromEnv to read DOCKER_HOST and related environment variables, and WithAPIVersionNegotiation to auto-negotiate API version with the daemon.
type ContainerRuntimeOptions ¶
type ContainerRuntimeOptions struct {
// PullImage controls whether the runtime refreshes the image before container
// creation.
PullImage bool
// Network is optional Docker network name (empty => default bridge).
Network string
// RegistryAuthConfigFile is a Docker auth config JSON file path
// (DOCKER_AUTH_CONFIG format). When set, each image pull reads current
// credentials from this file.
RegistryAuthConfigFile string
// RegistryAuthRefreshSocket is an optional Unix socket owned by the host.
// When set, an auth failure on image pull asks the host to refresh registry
// auth before retrying the same pull once.
RegistryAuthRefreshSocket string
// RegistryAuthConfigJSON is a Docker auth config JSON payload (DOCKER_AUTH_CONFIG
// format). When set, image pulls use matching registry credentials.
RegistryAuthConfigJSON string
}
ContainerRuntimeOptions holds configuration for Docker runtime.
type ContainerSpec ¶
type ContainerSpec struct {
Image string
Command []string
WorkingDir string
Env map[string]string
Mounts []ContainerMount
Labels map[string]string
// Optional resource limits (0 => unlimited)
LimitNanoCPUs int64
LimitMemoryBytes int64
// Optional disk limit for writable layer (bytes; 0 => unlimited).
// When set, Docker runtime may pass a storage option (driver dependent).
LimitDiskBytes int64
// Optional raw storage size option string passed to Docker (e.g., "10G").
// Set only when the operator provided PLOY_BUILDGATE_LIMIT_DISK_SPACE.
StorageSizeOpt string
}
ContainerSpec describes a container execution request.
type DiffGenerator ¶
DiffGenerator generates diffs between states.
func NewFilesystemDiffGenerator ¶
func NewFilesystemDiffGenerator() DiffGenerator
NewFilesystemDiffGenerator creates a DiffGenerator backed by a temporary git index snapshot.
type DockerJobOwner ¶
DockerJobOwner fences cleanup to one execution, including retries of a job.
func DockerJobOwnerFromLabels ¶
func DockerJobOwnerFromLabels(labels map[string]string) (DockerJobOwner, error)
func ListDockerJobOwners ¶
func ListDockerJobOwners(ctx context.Context, docker DockerJobResourceClient) ([]DockerJobOwner, error)
type DockerJobResourceClient ¶
type DockerJobResourceClient interface {
ContainerList(context.Context, client.ContainerListOptions) (client.ContainerListResult, error)
ContainerRemove(context.Context, string, client.ContainerRemoveOptions) (client.ContainerRemoveResult, error)
NetworkList(context.Context, client.NetworkListOptions) (client.NetworkListResult, error)
NetworkRemove(context.Context, string, client.NetworkRemoveOptions) (client.NetworkRemoveResult, error)
VolumeList(context.Context, client.VolumeListOptions) (client.VolumeListResult, error)
VolumeInspect(context.Context, string, client.VolumeInspectOptions) (client.VolumeInspectResult, error)
VolumeRemove(context.Context, string, client.VolumeRemoveOptions) (client.VolumeRemoveResult, error)
}
type GateExecutor ¶
type GateExecutor interface {
Execute(ctx context.Context, spec *contracts.StepGateSpec, workspace string, mounts JobMounts) (*contracts.BuildGateStageMetadata, error)
}
GateExecutor validates build artifacts. The primary implementation is gateExecutor (gate_docker.go) which runs validation containers locally via the container runtime.
func NewGateExecutor ¶
func NewGateExecutor(rt ContainerRuntime) GateExecutor
NewGateExecutor constructs a GateExecutor that uses the provided ContainerRuntime to run build commands.
type GateRuntimeImageObserver ¶
GateRuntimeImageObserver is a hook that is called once the gate runtime image is resolved (after stack detection / stack gate checks), and before the gate container is started.
type JobMounts ¶
type JobMounts struct {
Cache string
Home string
In string
Out string
Staging string
Tmp string
NodeCache string
CommonConfig string
JobConfig string
JobType types.JobType
}
JobMounts is the workflow boundary for job, run, and node host storage.
type PatchStats ¶
PatchStats holds line-level statistics derived from a unified diff.
func CountPatchStats ¶
func CountPatchStats(patchBytes []byte) PatchStats
CountPatchStats parses a unified diff and returns file and line delta counts. It counts `+` lines (excluding `+++ ` file headers) as additions and `-` lines (excluding `--- ` file headers) as removals. Each `diff --*` header marks one changed file.
type Request ¶
type Request struct {
ResumeCount int
// RunID threads the workflow run identifier for correlation/labels.
// Container labels and telemetry use this value via LabelRunID.
RunID types.RunID
// JobID threads the workflow job identifier for correlation/labels.
// Container labels and telemetry use this value via LabelJobID.
JobID types.JobID
Manifest contracts.StepManifest
Workspace string
JobMounts JobMounts
}
Request describes a step execution request.
type Result ¶
type Result struct {
ExitCode int
// Docker container identity and inspect output when a container was run.
ContainerID string
ContainerInspectJSON []byte
// Per-stage timings captured during execution.
Timings StageTiming
ContainerResources *types.RunStatsJobResources
}
Result contains the outcome of a step execution.
type Runner ¶
type Runner struct {
Containers ContainerRuntime
LogWriter io.Writer // Optional: streams logs to server as gzipped chunks.
}
Runner executes one workflow container. Nodeagent owns workspace preparation, gate orchestration, and whole-job timing around this execution boundary.
Source Files
¶
- build_gate_image_resolver.go
- container_docker.go
- container_docker_auth.go
- container_docker_auth_refresh.go
- container_docker_bind_mounts.go
- container_docker_proxy.go
- container_docker_stats.go
- container_log_streamer.go
- container_spec.go
- diff.go
- docker_job_resources.go
- gate_docker.go
- gate_docker_env.go
- gate_docker_metadata.go
- gate_docker_mounts.go
- gate_plan_resolver.go
- gate_plan_stack_context.go
- gate_runtime_image_observer.go
- interfaces.go
- job_mounts.go
- log_writer_context.go
- runner.go
- stack_match.go