build

type Attestations struct {
	// SBOM is the bare SPDX or CycloneDX document, empty when none was produced.
	SBOM []byte
	// Provenance is the SLSA provenance predicate, empty when none was produced.
	Provenance []byte
	// Incomplete is true when scanning the image stream failed part way, so a
	// missing SBOM or provenance may be a read error rather than "none produced".
	Incomplete bool
	// ScanError says why the stream scan stopped, empty when it finished.
	ScanError string
}

type Builder interface {
	Build(ctx context.Context, req Request, progress func(ProgressEvent)) (*Result, error)
	BuildRailpack(ctx context.Context, req RailpackRequest, progress func(ProgressEvent)) (*Result, error)
}

type CacheConfig struct {
	// Dir enables BuildKit's "local" cache backend: a directory on this
	// process's own disk. Only ever useful to the one build node that
	// owns that disk, which is exactly Phase 1's scoped-down cache
	// (client.go's WithCacheDir).
	Dir string

	// RegistryRef enables BuildKit's "registry" cache backend: an image
	// reference (e.g. "registry.example.com/levelrail/build-cache:app")
	// that cache blobs are pushed to and pulled from using the same
	// registry credentials Docker itself already has configured. This
	// is the actual "remote cache... shared across dedicated build
	// nodes" the build design calls for: any build
	// node with network access to the registry gets the same cache,
	// unlike Dir.
	RegistryRef string

	// RegistryInsecure allows the registry backend to talk plain HTTP
	// or accept a self-signed certificate, matching BuildKit's own
	// "insecure" cache attribute. Only meaningful when RegistryRef is
	// set; ignored otherwise.
	RegistryInsecure bool

	// S3 enables BuildKit's s3 cache backend for one build.
	S3 *S3Cache
}

type CgroupProvisioner interface {
	Provision(id string, memoryMB, cpuMillis int) (parent string, cleanup func(), err error)
}

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

type Clock interface {
	Now() time.Time
	After(d time.Duration) <-chan time.Time
}

type DetectRequest struct {
	// RepoURL is the git remote to shallow-clone. Required, and must pass
	// ValidatePublicRepoURL.
	RepoURL string
	// Ref is the branch to check out. Empty means the remote's default
	// branch (HEAD).
	Ref string
}

type DetectResult struct {
	// Provider is Railpack's own raw provider id (e.g. "node", "golang"),
	// empty if Railpack detected nothing buildable at all.
	Provider string
	// FrameworkName is FrameworkLabel(Provider)'s human-readable name,
	// empty if Provider is empty or not in supportedRailpackProviders:
	// either way, the caller's own contract is "fall back to manual build
	// type selection" for an empty FrameworkName, not an error.
	FrameworkName string
	// Port is the detected container port the app listens on, or 0 if
	// detection failed or no port flag was found. For Node, parsed from
	// scripts.start (or preview/serve); for Dockerfile, from EXPOSE.
	Port int
	// PortSource describes where Port came from (e.g. "from scripts.start
	// --port 4173"), empty if Port is 0.
	PortSource string
	// FrameworkID is the matched internal/frameworks preset id, empty when
	// no preset matched.
	FrameworkID string
}

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

type ImageSizer func(ctx context.Context, tag string) int64

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

type LimiterOption func(*Limiter)

type Limits struct {
	MaxConcurrent int
	Timeout       time.Duration
	MemoryMB      int
	CPUMillis     int
}

type LimitsSource func(ctx context.Context, app string) Limits

type MemGuard struct {
	Percent         int
	ReserveMB       int
	NodeHeapPercent int
}

type NetworkFacts struct {
	Mode       NetworkMode
	Enforced   bool
	Summary    string
	NotProven  string
	DocsAnchor string
}

type NetworkMode string

type NodeBuilder interface {
	BuildOnNode(ctx context.Context, nodeID string, req RemoteRequest, image io.Writer, progress func(ProgressEvent)) (*Result, error)
}

type NodeInfo struct {
	// ID is the node's identifier, matching store.Node.ID.
	ID string
	// AcceptsBuildWorkloads mirrors store.Node.AcceptsBuildWorkloads
	// (migrations/0010_node_workloads.sql): whether this node has opted
	// in to running build work at all.
	AcceptsBuildWorkloads bool
	// Online reports whether this node is currently reachable through
	// the agent transport, i.e. whether
	// agent.Registry.Get for this node's ID currently succeeds. A
	// build-capable node the control plane cannot currently reach is
	// not a usable candidate, the same reasoning resolveNodeTransport
	// (cmd/levelrail/main.go) already applies to service/database
	// placement.
	Online bool
}

type NodeLoad struct {
	Node    string
	Running int
	Waiting int
	Limit   int
}

type NodeResolver func(ctx context.Context) string

type NodeSource func(ctx context.Context) ([]NodeInfo, error)

type Option func(*Client)

type ProgressEvent struct {
	// Step is the build step's name, e.g. "[2/4] RUN go build".
	Step string
	// Cached is true when this step was skipped because BuildKit's cache
	// (see WithCacheDir) already had the result.
	Cached bool
	// Completed is true once Step finished, successfully or not.
	Completed bool
	// Error is non-empty when Step failed.
	Error string
	// Log is a raw output line from the step (stdout/stderr from the
	// build), empty for step-lifecycle events.
	Log string
	// Stream is "stdout" or "stderr" when Log is non-empty, and empty
	// for a step-lifecycle event (Log == ""), since those never came
	// from either stream. Added for internal/deploylog.Recorder, so a
	// persisted/live-streamed build log line can carry the same
	// stdout/stderr distinction web/src/hooks/useDeployLogStream.ts's
	// contract already expects (its own doc comment: "distinguishing
	// stdout/stderr is useful for highlighting failed build steps").
	// Populated from BuildKit's own VertexLog.Stream (see
	// relayProgress), 1/2 being BuildKit's stdout/stderr convention; the
	// docker-image-load phase (loadImage) has no equivalent stream
	// signal from the Engine API, so it always reports "stdout".
	Stream string
	// CacheWarning is set when the remote build cache was skipped or failed and
	// the build carried on without it. Log carries the same text.
	CacheWarning string
}

type RailpackRequest struct {
	// SourceDir is the app's source root Railpack inspects to detect its
	// provider and generate a build plan, and the build context BuildKit
	// reads from. Required.
	SourceDir string

	// Tag is the image reference given to the built image, e.g.
	// "levelrail/thesvg:abc1234". Required.
	Tag string

	// CgroupParent places every build step in a pre-sized cgroup. Set by the Limiter; local builds only.
	CgroupParent string
	// NodeHeapMB, when positive, sets NODE_OPTIONS=--max-old-space-size for Node builds that did not set NODE_OPTIONS.
	NodeHeapMB int
	// Network is the RUN step policy; the Client fills it from APP_BUILD_NETWORK.
	Network NetworkMode
	// Env is build-time env, as Railpack's own --env does. Callers pass only
	// public-prefix literals; it reaches every build step as an env var.
	Env map[string]string
}

type RemoteKind string

type RemoteRequest struct {
	Kind RemoteKind

	// ContextDir is the build context root on whichever side currently
	// holds it: the control plane's checkout when dispatching, the build
	// node's unpacked copy when running.
	ContextDir string

	// DockerfilePath is relative to ContextDir, since the control plane's
	// own absolute paths mean nothing on the build node. Empty means the
	// context root's own Dockerfile. Ignored for RemoteKindRailpack.
	DockerfilePath string

	Tag       string
	Target    string
	BuildArgs map[string]string
	NoCache   bool

	// Cache is the registry cache backend the build node should import
	// from and export to. CacheConfig.Dir is never carried here: it names
	// a directory on the dispatching side's own disk.
	Cache CacheConfig

	// Network is the control plane's resolved build network mode. The node
	// runs the stricter of it and its own setting, never a looser one.
	Network NetworkMode
}

type Request struct {
	// ContextDir is the build context root, matching `docker build <dir>`.
	// Required.
	ContextDir string

	// DockerfilePath is the path to the Dockerfile. It may live outside
	// ContextDir. Defaults to "<ContextDir>/Dockerfile" when empty.
	DockerfilePath string

	// RootDir, when set, is the checkout the build must stay inside:
	// ContextDir and the Dockerfile must resolve within it after symlinks.
	RootDir string

	// Tag is the image reference given to the built image, e.g.
	// "levelrail-spike:latest". Required.
	Tag string

	// Target is an optional multi-stage build target name.
	Target string

	// BuildArgs are passed through as build-time --build-arg equivalents.
	BuildArgs map[string]string

	// NoCache disables BuildKit's cache for this build.
	NoCache bool

	// Attest asks BuildKit for an SBOM and minimal provenance attestation.
	Attest bool

	// S3Cache adds BuildKit's s3 cache backend for this build. Nil means none.
	S3Cache *S3Cache

	// Secrets are BuildKit secret mounts by id, readable in a Dockerfile
	// with RUN --mount=type=secret,id=<id>. They never enter an image layer
	// or the build cache key. Local builds only: a remote build node does
	// not receive them.
	Secrets map[string][]byte

	// CgroupParent places the build's processes in a pre-sized cgroup so
	// CPU and memory limits hold. Set by the Limiter; local builds only.
	CgroupParent string

	// Network is the RUN step policy; the Client fills it from APP_BUILD_NETWORK.
	Network NetworkMode
}

type Result struct {
	Tag      string
	Duration time.Duration

	// ExporterResponse is BuildKit's raw exporter metadata (e.g. the
	// resulting image ID), passed through for callers that need it.
	ExporterResponse map[string]string

	// Attestations holds the SBOM and provenance of a build run with Request.Attest.
	Attestations Attestations
}

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

type RouterOption func(*Router)

type Run struct {
	App         string        `json:"app"`
	Tag         string        `json:"tag"`
	StartedAt   time.Time     `json:"started_at"`
	Duration    time.Duration `json:"-"`
	QueueWait   time.Duration `json:"-"`
	Status      RunStatus     `json:"status"`
	CachedSteps int           `json:"cached_steps"`
	TotalSteps  int           `json:"total_steps"`
	Error       string        `json:"error,omitempty"`
	Node        string        `json:"node,omitempty"`
	Platform    string        `json:"platform,omitempty"`
	ImageBytes  int64         `json:"image_bytes,omitempty"`
}

type RunRecorder interface {
	RecordBuildRun(ctx context.Context, r Run) error
}

type RunStatus string

type S3Cache struct {
	Region          string
	Bucket          string
	Prefix          string
	Endpoint        string
	PathStyle       bool
	AccessKeyID     string
	SecretAccessKey string
	Mode            string
}

type SpeedCacheState struct {
	Configured bool
	Enabled    bool
	TargetID   string
}

type SpeedFinding struct {
	Code     string `json:"code"`
	Severity string `json:"severity"`
	FixKind  string `json:"fix_kind"`
	TargetID string `json:"target_id,omitempty"`
}

type SpeedReport struct {
	Builds           int            `json:"builds"`
	WarmP50Seconds   float64        `json:"warm_p50_seconds"`
	ColdP50Seconds   float64        `json:"cold_p50_seconds"`
	WarmKnown        bool           `json:"warm_known"`
	TimeSavedSeconds float64        `json:"time_saved_seconds"`
	Findings         []SpeedFinding `json:"findings"`
}

type Trend struct {
	Builds     int     `json:"builds"`
	Succeeded  int     `json:"succeeded"`
	Failed     int     `json:"failed"`
	TimedOut   int     `json:"timed_out"`
	Canceled   int     `json:"canceled"`
	Skewed     int     `json:"skewed"`
	P50Seconds float64 `json:"p50_seconds"`
	P95Seconds float64 `json:"p95_seconds"`
	MinSeconds float64 `json:"min_seconds"`
	MaxSeconds float64 `json:"max_seconds"`
	// CacheHitRatio is cached steps over total steps across successful builds,
	// valid only when CacheKnown is true.
	CacheHitRatio float64 `json:"cache_hit_ratio"`
	CacheKnown    bool    `json:"cache_known"`
}

type UnsupportedProviderError struct {
	// Provider is the provider name Railpack detected, or "" if it
	// detected none at all.
	Provider string
}