Documentation
¶
Overview ¶
Package imageref renders machine-readable and human-friendly references for image-type component builds.
All builds for image components (Docker builds, external images) populate a common set of source-identity fields on the build record:
- SourceImage — repo only, e.g. "nginx"
- SourceRef — what the user wrote, e.g. "nginx:1.25.3"
- ResolvedTag — the tag the runner actually pulled, e.g. "1.25.5"
- SourceDigest — manifest list digest, e.g. "sha256:abc..."
This package converts those fields into the canonical forms used across the platform:
- ImageRef for pod specs, Helm values, and rendered K8s manifests (always digest-only — `repo@sha256:...`)
- DisplayRef for Nuon plan output, dashboard, CLI, and audit logs (human-friendly — `repo:tag (sha256:short)`)
The package takes a primitive Source struct so that both ctl-api (which uses internal app models) and the CLI (which uses generated SDK models) can call it without importing each other.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DisplayRef ¶
DisplayRef returns a human-friendly reference for plan output, the dashboard, the CLI, and audit logs. The form is:
repo:tag (sha256:abcdef0)
Tag preference is ResolvedTag → tag parsed from SourceRef → none. When no tag is available the result falls back to a digest-only display:
repo@sha256:abcdef0
When both digest and tag are unavailable, falls back to whichever of SourceRef or SourceImage is set (keeps the function safe to call on legacy builds without surfacing an empty string).
func ImageRef ¶
ImageRef returns the canonical machine-readable reference for use in Kubernetes pod specs, Helm values, and rendered manifests. The reference is always digest-only:
nginx@sha256:abc...
Returns "" when the build has no SourceDigest. Callers should fall back to legacy behavior when the result is empty.
Types ¶
type Source ¶
type Source struct {
// SourceImage is the bare repository portion of the user's spec,
// e.g. "nginx" or "ghcr.io/nuonco/foo". Always set for image builds.
SourceImage string
// SourceRef is the original reference the user wrote, e.g.
// "nginx:1.25.3" or "nginx@sha256:abc...". Always set for image builds.
SourceRef string
// ResolvedTag is the tag the runner actually pulled, when known.
// Empty for digest-pinned references (where the user wrote
// "repo@sha256:...").
ResolvedTag string
// SourceDigest is the manifest list digest of the resolved image.
// Empty for legacy builds without recorded source identity.
SourceDigest string
}
Source captures the image-source identity fields needed to render references for an image-type component build. ctl-api and the CLI populate this struct from their own ComponentBuild model types.
type Spec ¶ added in v0.19.1012
type Spec struct {
// Image is the image_url. It may carry a "@sha256:..." digest when the
// user pinned by digest in the image field rather than the tag.
Image string
// Tag is the literal tag. It may be a plain tag ("1.25.3"), a bare
// digest ("sha256:..."), or a full "repo@sha256:..." reference.
Tag string
// UpdatePolicy is the semver constraint. When set it takes precedence:
// the runner selects a concrete tag at build time and passes it back as
// selectedTag.
UpdatePolicy string
}
Spec is the raw image source a build planner hands the runner: the image_url, the literal tag (which may itself be a bare "sha256:..." digest or a full "repo@sha256:..." reference), and an optional update_policy semver constraint. The same `@sha256:` shapes are parsed once here so the pull reference and the recorded Source identity never disagree.
func (Spec) Identity ¶ added in v0.19.1012
Identity returns the source-identity fields to record on the ComponentBuild row. SourceDigest is left empty: the caller fills it in after resolving the manifest. selectedTag is the update_policy-selected tag (ignored when no policy is set).
- SourceRef is what the user asked for: "repo:tag" for tag-based refs, "repo@sha256:..." for digest-pinned refs, or "repo:<update_policy>" when a semver constraint is set (the constraint, not the tag we happened to select on this build).
- SourceImage is the bare repository.
- ResolvedTag is the tag the runner pulled: the selected tag for update_policy, the literal tag for tag-based refs, empty for digest pins.
func (Spec) PullRef ¶ added in v0.19.1012
PullRef returns the repo-relative reference to hand the OCI resolver and copier: the update_policy-selected tag when a policy is set, otherwise a plain tag or a bare "sha256:..." digest. The source repository config is already scoped to the repository, so any "repo@" prefix is stripped to the bare digest. Returns "" only when the spec carries no tag and no digest, in which case the resolver surfaces a clear error.
Source Files