step

package
v0.1.18-rc11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 35 Imported by: 0

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:

  1. Default gates catalog (gates/gates.yaml) - lowest precedence
  2. 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

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

func WithExecutionLogWriter(ctx context.Context, w io.Writer) context.Context

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

func WithGateContainerLabels(ctx context.Context, labels map[string]string) context.Context

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

type ContainerMount struct {
	Source   string
	Target   string
	ReadOnly bool
}

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

type DiffGenerator interface {
	Generate(ctx context.Context, workspace string) ([]byte, error)
}

DiffGenerator generates diffs between states.

func NewFilesystemDiffGenerator

func NewFilesystemDiffGenerator() DiffGenerator

NewFilesystemDiffGenerator creates a DiffGenerator backed by a temporary git index snapshot.

type DockerJobOwner

type DockerJobOwner struct {
	RunID       types.RunID
	JobID       types.JobID
	ResumeCount int
}

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 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

type GateRuntimeImageObserver func(ctx context.Context, image string)

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
	Share        string
	RuntimeShare string
	NodeCache    string
	CommonConfig string
	JobConfig    string
	JobType      types.JobType
}

JobMounts is the workflow boundary for job, run, and node host storage.

type PatchStats

type PatchStats struct {
	FilesChanged int
	LinesAdded   int
	LinesRemoved int
}

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.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context, req Request) (Result, error)

Run executes a step and returns the result.

type StageTiming

type StageTiming struct {
	HydrationDuration types.Duration
	ExecutionDuration types.Duration
	TotalDuration     types.Duration
}

StageTiming captures duration of each execution stage.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL