build

Documentation

Overview

Package build provides build orchestration primitives for Helix Cluster OS.

Package build provides build orchestration primitives for Helix Cluster OS.

Index

• type Builder
  • func NewPodmanBuilder(runner CommandRunner) Builder
• type CommandRunner
• type Job
  • func (j *Job) AppendLog(line string)
  • func (j *Job) Done() <-chan struct{}
  • func (j *Job) GetLogs() []string
  • func (j *Job) IsTerminal() bool
  • func (j *Job) SetImageTag(tag string)
  • func (j *Job) TransitionTo(newState State) error
• type Manifest
  • func NewManifest() *Manifest
  • func (m *Manifest) Add(platform Platform, digest string) error
  • func (m *Manifest) Get(platform Platform) (string, bool)
  • func (m *Manifest) Platforms() []string
  • func (m *Manifest) Remove(platform Platform)
• type Platform
  • func ParsePlatform(s string) (Platform, error)
  • func (p Platform) String() string
• type Service
  • func NewService(workers int) *Service
  • func NewServiceWithBuilder(workers int, builder Builder) *Service
  • func (s *Service) Cancel(id string) error
  • func (s *Service) Get(id string) (*Job, error)
  • func (s *Service) List() []*Job
  • func (s *Service) Start(ctx context.Context)
  • func (s *Service) Stop()
  • func (s *Service) Submit(j *Job) error
  • func (s *Service) WaitDone(ctx context.Context, id string) (*Job, error)
• type State

Types

type Builder

type Builder interface {
	// Build runs the build for j. It must respect ctx cancellation and must
	// move j into a terminal state before returning.
	Build(ctx context.Context, j *Job)
}

Builder executes the actual build for a job and is the seam through which a REAL image builder (e.g. docker buildx / buildkit) is injected.

Contract: Build MUST drive the job to a terminal state via Job.TransitionTo (StateSucceeded / StateFailed / StateCancelled) and, on success of a REAL build, set Job.ImageTag to a tag that refers to an image that actually exists and is pullable. The default implementation (simulatedBuilder) does NOT satisfy that last guarantee — see its documentation.

func NewPodmanBuilder

func NewPodmanBuilder(runner CommandRunner) Builder

NewPodmanBuilder creates a podmanBuilder backed by the given runner. Pass nil to use the real os/exec runner (production use).

type CommandRunner

type CommandRunner 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)
}

CommandRunner is the injectable seam for running external commands. Unit tests inject a fakeRunner; production code uses execRunner.

type Job

type Job struct {
	ID             string            `json:"id"`
	RepoURL        string            `json:"repo_url"`
	Ref            string            `json:"ref"`
	DockerfilePath string            `json:"dockerfile_path"`
	BuildArgs      map[string]string `json:"build_args"`
	State          State             `json:"state"`
	ImageTag       string            `json:"image_tag"`
	CreatedAt      time.Time         `json:"created_at"`
	StartedAt      *time.Time        `json:"started_at,omitempty"`
	CompletedAt    *time.Time        `json:"completed_at,omitempty"`
	Logs           []string          `json:"logs"`
	// contains filtered or unexported fields
}

Job represents a single build request.

func (*Job) AppendLog

func (j *Job) AppendLog(line string)

AppendLog adds a log line thread-safely.

func (*Job) Done

func (j *Job) Done() <-chan struct{}

Done returns a channel that is closed when the job reaches a terminal state (StateSucceeded, StateFailed, or StateCancelled). It is safe to call Done from multiple goroutines. The channel is never nil once the job has been enqueued via Service.Submit.

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

func (j *Job) SetImageTag(tag string)

SetImageTag sets the resulting image tag thread-safely. Builders MUST use this (rather than assigning Job.ImageTag directly) so concurrent readers via Service.Get/clone observe the field under the same lock.

func (*Job) TransitionTo

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

TransitionTo updates the job state with validation.

type Manifest

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

Manifest maps platforms to content digests for multi-arch image manifests.

func NewManifest

func NewManifest() *Manifest

NewManifest creates an empty manifest.

func (*Manifest) Add

func (m *Manifest) Add(platform Platform, digest string) error

Add registers a platform→digest mapping.

func (*Manifest) Get

func (m *Manifest) Get(platform Platform) (string, bool)

Get looks up the digest for a given platform.

func (*Manifest) Platforms

func (m *Manifest) Platforms() []string

Platforms returns a sorted list of all supported platform strings.

func (*Manifest) Remove

func (m *Manifest) Remove(platform Platform)

Remove deletes a platform entry from the manifest.

type Platform

type Platform struct {
	OS      string
	Arch    string
	Variant string // optional, e.g. "v8" for arm64/v8
}

Platform represents an OS/Architecture/Variant target for multi-arch builds.

func ParsePlatform

func ParsePlatform(s string) (Platform, error)

ParsePlatform parses a platform string such as "linux/amd64" or "linux/arm64/v8".

func (Platform) String

func (p Platform) String() string

String returns the canonical platform string.

type Service

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

Service orchestrates build jobs.

func NewService

func NewService(workers int) *Service

NewService creates a build service with the given worker pool size.

WARNING: The returned Service uses simulatedBuilder, a NON-PRODUCTION simulation that produces NO real image. Use NewServiceWithBuilder with a real Builder for production. See simulatedBuilder docs.

func NewServiceWithBuilder

func NewServiceWithBuilder(workers int, builder Builder) *Service

NewServiceWithBuilder creates a build service backed by the given Builder. This is the injection seam for a real image builder.

func (*Service) Cancel

func (s *Service) Cancel(id string) error

Cancel attempts to cancel a queued or running job.

func (*Service) Get

func (s *Service) Get(id string) (*Job, error)

Get retrieves a deep copy of a job by ID.

func (*Service) List

func (s *Service) List() []*Job

List returns all jobs.

func (*Service) Start

func (s *Service) Start(ctx context.Context)

Start begins the worker pool.

func (*Service) Stop

func (s *Service) Stop()

Stop gracefully shuts down the service.

func (*Service) Submit

func (s *Service) Submit(j *Job) error

Submit enqueues a new build job.

func (*Service) WaitDone

func (s *Service) WaitDone(ctx context.Context, id string) (*Job, error)

WaitDone blocks until the job identified by id reaches a terminal state or the context is cancelled, then returns a snapshot via Get. It is the preferred alternative to polling in tests and production callers alike.

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