build

type AuthMethod string

type BaseImage struct {
	// Format is the layout of a cached listing (baseCacheFormat).
	Format int `json:"format"`
	// Digest is the digest of the platform image, sha256:<hex>.
	Digest string `json:"digest"`
	// Python is PYTHON_VERSION of the image config, X.Y.Z; empty when the
	// config sets none, which no Dexaflow runtime base does.
	Python string `json:"python"`
	// Glibc is the version of the libc6 package dpkg installed, X.Y; empty
	// when the image records none (a musl or distroless image).
	Glibc string `json:"glibc"`
	// SitePackages reports that the image has the site-packages directory
	// of Python, usr/local/lib/pythonX.Y/site-packages.
	SitePackages bool `json:"site_packages"`
	// Dists are the distributions installed in that site-packages, as
	// name==version with the name normalized, sorted.
	Dists []string `json:"dists"`
	// PipConfig names what in the image tells pip where or what to install,
	// sorted: PIP_* (and XDG_CONFIG_*) variables of the config, and pip
	// configuration files (/etc/pip.conf, ...). The daemon's pip honors
	// them; the dependency layer cannot, so it declines such a base.
	PipConfig []string `json:"pip_config"`
}

type Builder interface {
	// Path is the resolution step this builder implements.
	Path() Path
	// Describe names the builder for the command output.
	Describe() string
	// Build produces the image described by req.
	Build(ctx context.Context, req Request) (Result, error)
}

type CloudBuild struct {
	// Project is the Google Cloud project the build runs in.
	Project string
	// Region is the Cloud Build region; gcloud's builds/region, else global,
	// when empty.
	Region string
	// WorkerPool is a private pool, projects/<p>/locations/<r>/workerPools/<n>;
	// the default pool when empty.
	WorkerPool string
	// ServiceAccount is the service account the build runs as,
	// projects/<p>/serviceAccounts/<email>; Cloud Build's default when empty.
	ServiceAccount string
	// Tool is the gcloud executable, "gcloud" from PATH when empty.
	Tool string
	// Registry reads the pushed digest; the registry client when nil.
	Registry Resolver
	// Poll is how often a build whose log cannot be streamed is described
	// until it ends, and the first wait before a failed describe is tried
	// again; cloudBuildPoll when zero.
	Poll time.Duration
	// MaxContext is the largest compressed build context uploaded, in
	// bytes; defaultMaxContext (2 GiB) when zero.
	MaxContext int64
}

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

type CloudKeychain interface {
	// Owns reports whether a cloud owns the registry host, so that its
	// session is the place to read a credential for it.
	Owns(host string) bool
	// Credential returns the credential the cloud session holds for the
	// registry host, an empty Credential when no cloud owns host, or an
	// error saying why the session gave none.
	Credential(ctx context.Context, host string) (Credential, error)
}

type CloudRegistry struct {
	// Provider is ProviderGoogle, ProviderAWS or ProviderAzure.
	Provider string
	// Host is the registry host, as `docker login` takes it.
	Host string
	// Region is the AWS region of an ECR host.
	Region string
	// Name is the registry name of an ACR host.
	Name string
}

type CodeLayer struct {
	// Split names the dependency image and its Dockerfile.
	Split Split
	// Deps is the dependency image found in the registry, or nil when it is
	// built first.
	Deps *Pinned
	// Daemon builds the dependency image when Deps is nil and neither the
	// wheels nor Remote do.
	Daemon LocalDaemon
	// Remote builds the dependency image in the daemon's place when it is
	// set (path 4): when the wheels do not apply, or fail.
	Remote Remote
	// Registry reads digests and pushes the image.
	Registry codeRegistry
}

type CommandRunner func(ctx context.Context, argv []string) ([]byte, error)

type Credential struct {
	// Username and Password are what the registry is sent.
	Username, Password string
	// Source names where the credential came from, for the command output,
	// such as "the gcloud session".
	Source string
}

type DependencyLayer struct {
	// Base is the runtime base, pinned by digest: an index or one image.
	Base Pinned
	// Python is the X.Y of the base's Python.
	Python string
	// Env are the KEY=VALUE variables the image sets on top of the base's.
	Env []string
	// User is the user the image runs as; empty keeps the base's.
	User string
	// Installer installs the dependencies of each platform.
	Installer Installer
	// Registry is the registry client that reads the base and pushes the
	// image, with its credentials (registry.auth_method).
	Registry Registry
}

type Existing struct {
	// Pinned is what the registry holds under the image tag.
	Pinned Pinned
}

type InCluster struct {
	// Namespace is the namespace of the builder.
	Namespace string
	// PodSelector is the label selector of the builder pod; the chart's
	// (domain.DefaultBuildKitPodSelector) when empty.
	PodSelector string
	// Context is the kubeconfig context; kubectl's current one when empty.
	Context string
	// Registry reads the pushed digest when BuildKit reports none; the
	// registry client when nil.
	Registry Resolver
}

type Installer interface {
	// Describe names the installer and its version, "uv 0.11.32".
	Describe() string
	// Install installs the dependencies of platform into dir.
	Install(ctx context.Context, platform, dir string) error
}

type LayerFile struct {
	// Path is the slash-separated path under the root of the layer: Workdir
	// for the code layer.
	Path string
	// Source is the file on disk whose bytes the entry carries; empty for a
	// directory or a symlink.
	Source string
	// Dir marks a directory entry.
	Dir bool
	// Link is the target of a symlink entry, kept as written.
	Link string
	// Exec marks a regular file with an execute bit, which keeps it
	// executable in the image.
	Exec bool
}

type LocalDaemon struct {
	// Tool is the executable to run, "docker" when empty.
	Tool string
	// Registry reads the pushed digest; the registry client when nil.
	Registry Resolver
}

type Options struct {
	// Tool is the local container tool for the fallback path (--builder).
	Tool string
	// Reuse allows the skip path: the image tag names the build's content
	// (the default version label with tag_strategy version), so an image the
	// registry already holds under it was built from the same inputs. The
	// caller leaves it off for any other tag and for --rebuild.
	Reuse bool
	// Split is how this build divides into a dependency image and a code
	// layer (ADR 0077), or nil when it cannot: then NoSplit says why.
	Split *Split
	// NoSplit says why the build is not split, for the builder line; empty
	// when there is nothing to say (a build that is not pushed).
	NoSplit string
	// Rebuild builds the dependency image again even when the registry holds
	// one for its key (--rebuild).
	Rebuild bool
	// Registry reads what the registry holds; the registry client when nil.
	// A split build also needs it to push (codeRegistry).
	Registry Resolver
	// Remote is the remote builder the project or its target configured
	// (path 4), or nil when none is.
	Remote Remote
	// RemoteSource names where Remote was configured, for the builder line,
	// such as the project's dexaflow.yaml.
	RemoteSource string
	// Push says the build is pushed. The remote builder pushes what it
	// builds, so it applies only to a pushed build.
	Push bool
	// LocalOnly says why the build must run on this machine (its build
	// secrets or package index come from this machine's environment), or ""
	// when the remote builder may take it.
	LocalOnly string
}

type Path string

type Pinned struct {
	// Ref is the image as written with its tag replaced by the digest,
	// <repo>@sha256:<hex>.
	Ref string
	// Manifest is the raw manifest or index the digest names.
	Manifest []byte
	// Platform is os/arch[/variant] from the config of a single image, filled
	// by the skip path only (Registry.Platform); empty for an index.
	Platform string
}

type PushAccess struct {
	// Registry is the registry host, as a `docker login` takes it.
	Registry string
	// Repository is the repository a push goes to, <registry>/<path>.
	Repository string
	// Anonymous is true when no credential was found for the registry, in
	// the docker config, its credential helpers or the cloud session, as
	// the auth method reads them.
	Anonymous bool
	// Source names where the credential came from (SourceDockerConfig, or
	// the cloud CLI's session); empty when Anonymous.
	Source string
	// CloudError says why the cloud session gave no credential, when it was
	// asked and could not (the CLI is not installed or not signed in). It
	// carries the command and the last line of its stderr, capped; the token
	// is on stdout and never in it.
	CloudError error
}

type Registry struct {
	// Auth is registry.auth_method; empty is AuthAuto.
	Auth AuthMethod
	// Cloud reads the cloud session; the cloud CLIs on PATH when nil.
	Cloud CloudKeychain
}

type Remote interface {
	Builder
	// Ready says why the builder cannot run on this machine (its CLI is not
	// on PATH, or the person deploying may not use it), or nil when it can.
	Ready(ctx context.Context) error
	// Decline says why the builder does not build for platforms, or "" when
	// it does.
	Decline(platforms []string) string
}

type Request struct {
	// Image is the tag reference to build, <registry>/<name>:<tag>.
	Image string
	// Dockerfile is the path of the Dockerfile the build reads.
	Dockerfile string
	// ContextDir is the build context, the DAG project directory.
	ContextDir string
	// Platforms are the os/arch targets; empty means the builder's default.
	Platforms []string
	// Push pushes the image to its registry after the build.
	Push bool
	// Pin asks for the digest of the pushed image in Result.Ref. It needs
	// Push: an image that is not pushed has no registry digest.
	Pin bool
	// Code is the DAG project files of the code layer, for a split build
	// (Split); other builders read ContextDir.
	Code []LayerFile
	// ContextFiles is the build context as the build would read it, the
	// files of ContextDir that the .dockerignore keeps, for a builder that
	// sends the context to another machine (the remote path). nil means not
	// listed: such a builder refuses to run rather than send the whole
	// directory; an empty list is an empty context.
	ContextFiles []LayerFile
	// BuildArgs are the build arguments a Dockerfile build passes with
	// --build-arg, in name order. Plain values, never secrets.
	BuildArgs map[string]string
	// Secrets are the build secrets a Dockerfile build passes with
	// --secret id=<ID>,env=<Env>; the tool reads each value from its own
	// environment, so none reaches its argv.
	Secrets []Secret
	// Env are KEY=VALUE variables added to the environment of the tool, for
	// a secret whose value the caller composed (the package index URL).
	Env []string
	// Stdout and Stderr receive the builder's own output.
	Stdout io.Writer
	Stderr io.Writer
}

type Resolver interface {
	// Resolve returns what image (a tag reference) names in its registry.
	Resolve(ctx context.Context, image string) (Pinned, error)
}

type Result struct {
	// Path is the resolution step that produced the image.
	Path Path
	// Image is the tag reference that was built.
	Image string
	// Platforms are the platforms the image was built for.
	Platforms []string
	// Pushed reports that the image is in its registry.
	Pushed bool
	// Ref is the digest-pinned reference, <repo>@sha256:<hex>, when the
	// request asked for a pin; empty otherwise.
	Ref string
}

type Secret struct {
	// ID is the id of --mount=type=secret,id=<ID>.
	ID string
	// Env is the environment variable holding the value.
	Env string
}

type Split struct {
	// DepsImage is the dependency image, <repo>:deps-<key> in the DAG's own
	// repository.
	DepsImage string
	// Dockerfile is the content of the dependency image's Dockerfile. It
	// copies nothing, so it builds from an empty context.
	Dockerfile string
	// Wheels builds the dependency image without a daemon (ADR 0078), or is
	// nil when the daemon builds it from Dockerfile; then NoWheels says why.
	Wheels *DependencyLayer
	// DaemonDepsImage is the dependency image the daemon builds, under the
	// key of its own builds (ADR 0077), when Wheels fails before anything is
	// pushed; empty when the daemon's key cannot cover the dependencies
	// (they are not pinned), and then the failure stands.
	DaemonDepsImage string
	// NoWheels says why the dependency layer does not apply, for the
	// builder line; empty when Wheels is set.
	NoWheels string
	// Note is said on the builder line after the reason, such as how long
	// the resolution of the dependencies took; empty when there is nothing
	// to say.
	Note string
}