build

package
v0.0.0-...-54ed9d2 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package build provides the build orchestration service for Helix Cluster OS.

Package build provides the build orchestration service for Helix Cluster OS.

Package build provides the build orchestration service for Helix Cluster OS.

Package build provides the build orchestration service for Helix Cluster OS.

Package build provides the build orchestration service for Helix Cluster OS.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ArtifactStore 

type ArtifactStore interface {
	Put(digest string, data []byte) error
}

ArtifactStore is the minimal sink ExecBuilder needs to persist a real produced artifact. pkg/build/cache.Cache satisfies it.

type BuildFilters 

type BuildFilters struct {
	State   State
	RepoURL string
}

BuildFilters defines filtering criteria for listing builds.

type BuildSpec 

type BuildSpec struct {
	ID             string
	RepoURL        string
	Ref            string
	DockerfilePath string
	BuildArgs      map[string]string
	Platforms      []build.Platform
}

BuildSpec defines the parameters for submitting a new build job.

type ExecArtifact 

type ExecArtifact struct {
	Digest   string // sha256 hex of the produced artifact bytes
	Size     int    // byte length of the produced artifact
	ExitCode int    // real process exit code
	ImageTag string // content-addressed tag derived from the digest
}

ExecArtifact records the real result of an exec build for a job.

type ExecBuilder 

type ExecBuilder struct {
	// Shell is the shell binary used to interpret Command. Defaults to "sh".
	Shell string

	// Command is the shell command line executed for every job. It is run as
	// `Shell -c Command` inside the per-job workdir. If empty, the builder uses
	// the job's DockerfilePath only as a label and fails the job, since there is
	// nothing real to execute — it never fabricates a success.
	Command string

	// OutputName is the basename of the artifact file the command is expected to
	// write inside the workdir. Its absolute path is exported as HELIX_OUTPUT.
	// Defaults to "artifact.out".
	OutputName string

	// ArtifactStore, if set, receives the produced artifact bytes keyed by their
	// content digest, enabling end-to-end retrieval of the REAL output. It mirrors
	// the pkg/build/cache.Cache.Put signature without importing it here.
	ArtifactStore ArtifactStore

	// BaseDir, if set, is the parent directory under which per-job temp workdirs
	// are created. Defaults to the OS temp dir.
	BaseDir string
	// contains filtered or unexported fields
}

ExecBuilder is a REAL, NON-SIMULATED build implementation. It satisfies the pkgbuild.Builder seam (see pkg/build.NewServiceWithBuilder) and runs an actual local build command via os/exec in a per-job temporary working directory.

What it really does (honestly):

  • Creates a fresh per-job temp workdir on the local filesystem.
  • Executes the configured command line through "sh -c" inside that workdir, with build context exported via environment variables (HELIX_BUILD_ID, HELIX_REF, HELIX_REPO_URL, HELIX_WORKDIR, HELIX_OUTPUT, plus every entry of Job.BuildArgs).
  • Streams the command's REAL stdout and stderr, line by line, into the job logs as they are produced.
  • Captures the command's REAL process exit code.
  • On a zero exit code, reads the REAL artifact file the command was asked to produce (HELIX_OUTPUT), computes its sha256 digest, and derives the image tag from that digest. The artifact bytes and digest reflect actual command output, not a fabricated constant.

What it is NOT (honest seam boundary, PCS-6 / CLAUDE-1): ExecBuilder is NOT a container image builder. It does not invoke podman/docker/buildkit, does not produce OCI layers, and does not push to a registry. It runs ordinary local shell commands. The "image tag" it emits is a content-addressed reference to the locally produced artifact file, suitable for a registry/cache that stores such artifacts — it is real with respect to the command's output, but it is a local-exec artifact, not a pulled-and-pushed container image. Because the result is derived from a real process, Simulated() returns false.

func (*ExecBuilder) ArtifactFor 

func (b *ExecBuilder) ArtifactFor(jobID string) (ExecArtifact, bool)

ArtifactFor returns the last recorded artifact for a job, if any.

func (*ExecBuilder) Build 

func (b *ExecBuilder) Build(ctx context.Context, j *pkgbuild.Job)

Build implements pkgbuild.Builder by executing a real local command. It MUST drive the job to a terminal state before returning.

func (*ExecBuilder) Simulated 

func (b *ExecBuilder) Simulated() bool

Simulated reports that this builder is NOT a simulation. It runs real processes and derives output from their real results.

type Job 

type Job struct {
	ID             string
	RepoURL        string
	Ref            string
	DockerfilePath string
	BuildArgs      map[string]string
	State          State
	ImageTag       string
	CreatedAt      time.Time
	StartedAt      *time.Time
	CompletedAt    *time.Time
	Logs           []string
	// contains filtered or unexported fields
}

Job represents a single build request managed by the orchestrator.

func (*Job) AppendLog 

func (j *Job) AppendLog(line string)

AppendLog adds a log line thread-safely.

func (*Job) GetLogs 

func (j *Job) GetLogs() []string

GetLogs returns a copy of log lines thread-safely.

func (*Job) IsTerminal 

func (j *Job) IsTerminal() bool

IsTerminal returns true if the build has reached a terminal state.

func (*Job) TransitionTo 

func (j *Job) TransitionTo(newState State) error

TransitionTo updates the job state with validation.

type Orchestrator 

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

Orchestrator manages build jobs, their lifecycle, artifacts, and cache.

func NewOrchestrator 

func NewOrchestrator(workers int, c cache.Cache) *Orchestrator

NewOrchestrator creates a build orchestrator with the given worker pool size and cache, backed by the REAL podman executor (production default).

func NewOrchestratorWithBuilder 

func NewOrchestratorWithBuilder(workers int, c cache.Cache, builder OrchestratorBuilder) *Orchestrator

NewOrchestratorWithBuilder creates a build orchestrator with an injectable OrchestratorBuilder, enabling unit tests to supply a fake runner. Passing nil for builder defaults to the real podman executor.

func (*Orchestrator) Cache 

func (o *Orchestrator) Cache() cache.Cache

Cache returns the underlying cache instance.

func (*Orchestrator) CancelBuild 

func (o *Orchestrator) CancelBuild(ctx context.Context, buildID string) error

CancelBuild attempts to cancel a queued or running build.

func (*Orchestrator) GetArtifactDigest 

func (o *Orchestrator) GetArtifactDigest(buildID string) (string, bool)

GetArtifactDigest returns the artifact digest for a build, if any.

func (*Orchestrator) GetBuildStatus 

func (o *Orchestrator) GetBuildStatus(ctx context.Context, buildID string) (*Job, error)

GetBuildStatus retrieves the current status of a build by ID.

func (*Orchestrator) ListBuilds 

func (o *Orchestrator) ListBuilds(ctx context.Context, filters BuildFilters) []*Job

ListBuilds returns all builds matching the provided filters.

func (*Orchestrator) PurgeTerminal 

func (o *Orchestrator) PurgeTerminal(before time.Time) int

PurgeTerminal removes terminal jobs (succeeded/failed/cancelled) that completed at or before the given cutoff, returning the number reaped. It exists to bound orchestrator memory: without reaping, the jobs map grows without limit for the process lifetime. Non-terminal jobs and jobs with no CompletedAt are retained.

func (*Orchestrator) RegisterArtifact 

func (o *Orchestrator) RegisterArtifact(buildID, digest string)

RegisterArtifact associates a build with a cached artifact digest.

func (*Orchestrator) Start 

func (o *Orchestrator) Start(ctx context.Context)

Start begins the internal worker pool that processes queued jobs.

func (*Orchestrator) Stop 

func (o *Orchestrator) Stop()

Stop gracefully shuts down the orchestrator and waits for workers to finish.

func (*Orchestrator) SubmitBuild 

func (o *Orchestrator) SubmitBuild(ctx context.Context, spec BuildSpec) (*Job, error)

SubmitBuild enqueues a new build job from a spec.

type OrchestratorBuilder 

type OrchestratorBuilder interface {
	Execute(ctx context.Context, j *Job)
}

OrchestratorBuilder is the interface through which the Orchestrator delegates actual build execution. It mirrors pkg/build.Builder but operates on the internal *Job type so the Orchestrator's state machine remains the authority over state transitions.

Contract: Execute MUST drive the job to a terminal state (StateSucceeded / StateFailed / StateCancelled) before returning, and on success MUST set j.ImageTag to a tag that refers to a real image that was built.

func NewPodmanOrchestratorBuilder 

func NewPodmanOrchestratorBuilder(runner OrchestratorCommandRunner) OrchestratorBuilder

NewPodmanOrchestratorBuilder creates a podmanOrchestratorBuilder backed by the given runner. Pass nil to use the production os/exec runner.

func NewSimulatedBuilder 

func NewSimulatedBuilder() OrchestratorBuilder

NewSimulatedBuilder returns a NON-PRODUCTION OrchestratorBuilder that drives jobs to a terminal state deterministically (no real build). Inject it via NewOrchestratorWithBuilder for orchestration/plumbing tests that must not depend on a real podman daemon. Do NOT use in production.

type OrchestratorCommandRunner 

type OrchestratorCommandRunner interface {
	// Run executes the named command with the given arguments.
	// It returns combined stdout, stderr bytes and any error.
	Run(ctx context.Context, name string, args ...string) (stdout, stderr []byte, err error)
}

OrchestratorCommandRunner is the injectable seam for running external commands inside the Orchestrator's build executor. Unit tests inject a fakeOrchestratorRunner; production code uses realOrchestratorRunner which shells out via os/exec.

type Server 

type Server struct {
	helixv1.UnimplementedBuildServiceServer
	// contains filtered or unexported fields
}

Server implements the helix.v1.BuildService gRPC interface.

func NewServer 

func NewServer(orch *Orchestrator, pool *WorkerPool) *Server

NewServer creates a gRPC build service backed by an orchestrator and worker pool.

func (*Server) CancelBuild 

func (s *Server) CancelBuild(ctx context.Context, req *helixv1.CancelBuildRequest) (*helixv1.CancelBuildResponse, error)

CancelBuild handles build cancellation requests.

func (*Server) GetBuildStatus 

func (s *Server) GetBuildStatus(ctx context.Context, req *helixv1.GetBuildStatusRequest) (*helixv1.BuildStatus, error)

GetBuildStatus returns the current status of a build.

func (*Server) Register 

func (s *Server) Register(registrar grpc.ServiceRegistrar)

Register registers the server with a gRPC registrar.

func (*Server) StreamBuildLogs 

func (s *Server) StreamBuildLogs(req *helixv1.StreamBuildLogsRequest, stream helixv1.BuildService_StreamBuildLogsServer) error

StreamBuildLogs streams build log lines to the client.

func (*Server) SubmitBuild 

func (s *Server) SubmitBuild(ctx context.Context, req *helixv1.SubmitBuildRequest) (*helixv1.SubmitBuildResponse, error)

SubmitBuild handles build submission requests.

type State 

type State string

State represents the lifecycle of a build job. 

const (
	StateQueued    State = "queued"
	StateRunning   State = "running"
	StateSucceeded State = "succeeded"
	StateFailed    State = "failed"
	StateCancelled State = "cancelled"
)

type Worker 

type Worker struct {
	ID       string
	Address  string
	Capacity int // max concurrent builds
	Load     int // current active builds
	Healthy  bool
	LastSeen time.Time
	Labels   map[string]string
	// contains filtered or unexported fields
}

Worker represents a build worker node in the cluster.

type WorkerPool 

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

WorkerPool manages registration, allocation, and release of build workers.

func NewWorkerPool 

func NewWorkerPool() *WorkerPool

NewWorkerPool creates an empty worker pool.

func (*WorkerPool) AllocateWorker 

func (p *WorkerPool) AllocateWorker(ctx context.Context) (*Worker, error)

AllocateWorker selects and reserves an available worker for a build. It prefers the worker with the most remaining capacity.

func (*WorkerPool) GetWorker 

func (p *WorkerPool) GetWorker(workerID string) (*Worker, bool)

GetWorker returns a worker by ID.

func (*WorkerPool) ListWorkers 

func (p *WorkerPool) ListWorkers() []*Worker

ListWorkers returns all registered workers.

func (*WorkerPool) RegisterWorker 

func (p *WorkerPool) RegisterWorker(ctx context.Context, w *Worker) error

RegisterWorker adds or updates a worker in the pool.

func (*WorkerPool) ReleaseWorker 

func (p *WorkerPool) ReleaseWorker(workerID string) error

ReleaseWorker decrements the load of a worker by ID.

func (*WorkerPool) RemoveWorker 

func (p *WorkerPool) RemoveWorker(workerID string)

RemoveWorker removes a worker from the pool.

func (*WorkerPool) TotalCapacity 

func (p *WorkerPool) TotalCapacity() int

TotalCapacity returns the sum of all worker capacities.

func (*WorkerPool) TotalLoad 

func (p *WorkerPool) TotalLoad() int

TotalLoad returns the sum of all current worker loads.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.