artifact

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2026 License: MPL-2.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source
const CliVersionAnnotationKey = "windsorcli.dev/cli-version"

CliVersionAnnotationKey mirrors BlueprintMetadataInput.CliVersion into the OCI manifest, so GetCliVersionConstraint can check it without a full Pull.

View Source
const ManifestFileName = "artifact-manifest.yaml"

ManifestFileName is the canonical filename for the manifest inside a blueprint OCI bundle and at the blueprint source root.

View Source
const ManifestVersion = "v1alpha1"

ManifestVersion is the current schema version for ArtifactManifest documents.

Variables

This section is empty.

Functions

func IsAuthenticationError

func IsAuthenticationError(err error) bool

IsAuthenticationError reports whether err originates from a registry authentication or authorization failure, detected via the *transport.Error type from go-containerregistry (HTTP 401/403 or UNAUTHORIZED/DENIED diagnostic codes). Walks the wrap chain via errors.As, so wrapping with fmt.Errorf("...: %w", err) is transparent. Used by the push command to decide whether to hint the user to run `docker login`.

func ParseRegistryURL

func ParseRegistryURL(registryURL string) (registryBase, repoName, tag string, err error)

ParseRegistryURL parses a registry URL string into its components. It handles formats like "registry.com/repo:tag", "registry.com/repo", or "oci://registry.com/repo:tag". Returns registryBase, repoName, tag, and an error if parsing fails.

func ResolveCompatibleTag added in v0.9.0

func ResolveCompatibleTag(artifactBuilder Artifact, urlPrefix string, tags []string) (tag string, version *semver.Version, ok bool, err error)

ResolveCompatibleTag walks tags newest-first (stable semver only) and returns the highest one this CLI is compatible with. Checks the cheap manifest annotation first; falls back to VerifyCliVersionCompatibility (a real pull) when the annotation is absent, since older tags predate that annotation and can't be assumed compatible. A manifest-fetch error skips that candidate instead of aborting the walk; it's only returned if no candidate ends up qualifying.

func ValidateCliVersion

func ValidateCliVersion(cliVersion, constraint string) error

ValidateCliVersion validates that the provided CLI version satisfies the cliVersion constraint specified in the template metadata. If constraint is empty, validation is skipped. If cliVersion is empty, validation is skipped (caller cannot determine version). If the CLI version is "dev" or "main" or "latest", validation is skipped as these are development builds. A pre-release CLI version (e.g. "0.9.0-rc.1") is checked against its release version (Masterminds/semver excludes pre-releases from a range unless the constraint itself declares one, which would otherwise fail every release-candidate build against an ordinary ">=" constraint). Returns an error if the constraint is specified and the version does not satisfy it.

Types

type Artifact

type Artifact interface {
	Bundle() error
	Write(outputPath string, tag string) (string, error)
	Push(registryBase string, repoName string, tag string) error
	Pull(ociRefs []string) (map[string]string, error)
	ExtractModulePath(registry, repository, tag, modulePath string) (string, error)
	ParseOCIRef(ociRef string) (registry, repository, tag string, err error)
	GetCacheDir(registry, repository, tag string) (string, error)
	ListTags(ociRef string) ([]string, error)
	GetCliVersionConstraint(ociRef string) (string, error)
	VerifyCliVersionCompatibility(ociRef string) error
}

Artifact defines the interface for artifact creation operations

type ArtifactBuilder

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

ArtifactBuilder implements the Artifact interface

func NewArtifactBuilder

func NewArtifactBuilder(rt *runtime.Runtime) *ArtifactBuilder

NewArtifactBuilder creates a new ArtifactBuilder instance with the provided shell dependency. If overrides are provided, any non-nil component in the override ArtifactBuilder will be used instead of creating a default. The shell is used for retrieving git provenance and builder information during metadata generation.

func (*ArtifactBuilder) Bundle

func (a *ArtifactBuilder) Bundle() error

Bundle traverses the project directories and collects all relevant files to be included in the artifact. It applies configurable path-based processors that determine how files from each directory (such as "_template", "kustomize", or "terraform") are incorporated into the artifact. The method supports extensibility by allowing custom handling of different directory structures and types, and skips files in the "terraform" directory based on predefined logic.

func (*ArtifactBuilder) ExtractModulePath added in v0.9.0

func (a *ArtifactBuilder) ExtractModulePath(registry, repository, tag, modulePath string) (string, error)

ExtractModulePath extracts a specific module path from a cached OCI artifact. It checks if the module path already exists in the cache directory, and if not, extracts it from the cached artifact.tar file. Returns the full path to the extracted module or an error if extraction fails.

func (*ArtifactBuilder) GetCacheDir added in v0.9.0

func (a *ArtifactBuilder) GetCacheDir(registry, repository, tag string) (string, error)

GetCacheDir returns the cache directory path for an OCI artifact identified by registry, repository, and tag. The cache directory is located at <projectRoot>/.windsor/cache/oci/<extractionKey> where extractionKey is the cacheKey with / and : replaced with _ for filesystem safety. Returns an error if project root is empty.

func (*ArtifactBuilder) GetCliVersionConstraint added in v0.9.0

func (a *ArtifactBuilder) GetCliVersionConstraint(ociRef string) (string, error)

GetCliVersionConstraint returns ociRef's declared cliVersion constraint, via a manifest-only fetch (no layer pull). Empty string, not an error, means no constraint declared.

func (*ArtifactBuilder) ListTags added in v0.9.0

func (a *ArtifactBuilder) ListTags(ociRef string) ([]string, error)

ListTags returns the tags published for the repository of an OCI reference (the tag in ociRef is ignored). It is used to resolve the latest available version when upgrading a source. Returns an error if the reference is malformed or the registry cannot be reached.

func (*ArtifactBuilder) ParseOCIRef added in v0.9.0

func (a *ArtifactBuilder) ParseOCIRef(ociRef string) (registry, repository, tag string, err error)

ParseOCIRef parses an OCI reference into registry, repository, and tag components. Requires the format "oci://registry/repository:tag". The registry may itself contain a colon (an explicit port, e.g. "localhost:5000/repo:tag"), so registry/repository are split on the first "/" before the tag is found at the last ":" — a repository containing a colon (e.g. "repo:tag:extra") is rejected rather than silently misparsed.

func (*ArtifactBuilder) Pull

func (a *ArtifactBuilder) Pull(ociRefs []string) (map[string]string, error)

Pull downloads and extracts OCI artifacts to disk cache for use by other components. It takes a slice of OCI references and downloads unique artifacts, returning a map of cache directory paths keyed by their registry/repository:tag identifier. The method provides efficient caching to avoid duplicate downloads of the same artifact. It checks disk cache first, then downloads if needed, and extracts artifacts to disk cache. Returns cache directory paths instead of binary data.

func (*ArtifactBuilder) Push

func (a *ArtifactBuilder) Push(registryBase string, repoName string, tag string) error

Push uploads the artifact to an OCI registry with explicit blob handling to prevent MANIFEST_BLOB_UNKNOWN errors. Implements robust blob upload strategy recommended by Red Hat for resolving registry upload issues. Bundles files from the project, creates tarball in memory, constructs OCI image, uploads blobs explicitly, then uploads manifest. Uses authenticated keychain for registry access and retry backoff for resilience. Registry base should be the base URL (e.g., "ghcr.io/namespace"), repoName the repository name, tag the version.

func (*ArtifactBuilder) VerifyCliVersionCompatibility added in v0.9.0

func (a *ArtifactBuilder) VerifyCliVersionCompatibility(ociRef string) error

VerifyCliVersionCompatibility pulls ociRef and validates its metadata.yaml cliVersion constraint against the running CLI. Used as ResolveCompatibleTag's fallback when a candidate's manifest annotation is absent. Returns nil if compatible or undeclared; any other error means "don't trust this candidate."

func (*ArtifactBuilder) Write

func (a *ArtifactBuilder) Write(outputPath string, tag string) (string, error)

Write bundles all files and creates a compressed tar.gz artifact file with optional tag override. Accepts optional tag in "name:version" format to override metadata.yaml values. Tag takes precedence over existing metadata. If no metadata.yaml exists, tag is required. OutputPath can be file or directory - generates filename from metadata if directory. Creates compressed tar.gz with all files including enriched metadata.yaml. Returns the final output path of the created artifact file.

type ArtifactManifest added in v0.9.0

type ArtifactManifest struct {
	Version   string          `yaml:"version"`
	Blueprint Provenance      `yaml:"blueprint,omitempty"`
	Artifacts []ManifestEntry `yaml:"artifacts"`
}

ArtifactManifest is the top-level document written as artifact-manifest.yaml.

type ArtifactSource added in v0.9.0

type ArtifactSource struct {
	File       string `yaml:"file"`
	Line       int    `yaml:"line,omitempty"`
	Datasource string `yaml:"datasource"`
	DepName    string `yaml:"depName,omitempty"`
	Package    string `yaml:"package,omitempty"`
	HelmRepo   string `yaml:"helmRepo,omitempty"`
}

ArtifactSource records where in the blueprint tree an artifact was declared and which Renovate annotation surfaced it. File paths are blueprint-relative so manifests remain stable across checkout locations.

type ArtifactTransport added in v0.9.0

type ArtifactTransport string

ArtifactTransport classifies how a consumer must retrieve an artifact from its upstream source. Hydrate dispatches on this field to select the appropriate client (OCI registry, raw HTTP download, git mirror).

const (
	// ArtifactTransportOCI identifies artifacts fetched from — and published
	// to — an OCI registry. Applies to container images and all Helm charts
	// (Windsor always re-hosts Helm via OCI).
	ArtifactTransportOCI ArtifactTransport = "oci"

	// ArtifactTransportTarball identifies artifacts downloaded as raw HTTP
	// archives (GitHub release assets, chart tarballs when shipped verbatim).
	ArtifactTransportTarball ArtifactTransport = "tarball"

	// ArtifactTransportGit identifies artifacts retrieved by cloning a git
	// repository at a specific tag.
	ArtifactTransportGit ArtifactTransport = "git"
)

type ArtifactType added in v0.9.0

type ArtifactType string

ArtifactType classifies an artifact by the semantic role it plays in the blueprint. It is derived from the Renovate datasource that surfaced it and is independent of transport — a Helm chart is a Helm chart whether it ships over HTTP or OCI.

const (
	// ArtifactTypeDocker identifies a container image (Renovate datasource
	// "docker").
	ArtifactTypeDocker ArtifactType = "docker"

	// ArtifactTypeHelm identifies a Helm chart (Renovate datasource "helm"),
	// regardless of whether the upstream is a traditional HTTP repository or
	// an OCI registry. Hydrate consumers always publish these to OCI.
	ArtifactTypeHelm ArtifactType = "helm"

	// ArtifactTypeGitHubRelease identifies a release asset downloaded from a
	// GitHub release (Renovate datasource "github-releases").
	ArtifactTypeGitHubRelease ArtifactType = "github-release"

	// ArtifactTypeGitTag identifies a git tag reference (Renovate datasource
	// "git-tags"), typically used for CLI tool versions.
	ArtifactTypeGitTag ArtifactType = "git-tag"
)

type BlueprintMetadata

type BlueprintMetadata struct {
	Name        string        `json:"name"`
	Description string        `json:"description,omitempty"`
	Version     string        `json:"version,omitempty"`
	Author      string        `json:"author,omitempty"`
	Tags        []string      `json:"tags,omitempty"`
	Homepage    string        `json:"homepage,omitempty"`
	License     string        `json:"license,omitempty"`
	CliVersion  string        `json:"cliVersion,omitempty"`
	Timestamp   string        `json:"timestamp"`
	Git         GitProvenance `json:"git"`
	Builder     BuilderInfo   `json:"builder"`
}

BlueprintMetadata represents the complete metadata embedded in artifacts

type BlueprintMetadataInput

type BlueprintMetadataInput struct {
	Name        string   `yaml:"name"`
	Description string   `yaml:"description,omitempty"`
	Version     string   `yaml:"version,omitempty"`
	Author      string   `yaml:"author,omitempty"`
	Tags        []string `yaml:"tags,omitempty"`
	Homepage    string   `yaml:"homepage,omitempty"`
	License     string   `yaml:"license,omitempty"`
	CliVersion  string   `yaml:"cliVersion,omitempty"`
}

BlueprintMetadataInput represents the input metadata from contexts/_template/metadata.yaml

type BuilderInfo

type BuilderInfo struct {
	User  string `json:"user"`
	Email string `json:"email"`
}

BuilderInfo contains information about who/what built the artifact

type FileInfo

type FileInfo struct {
	Content []byte
	Mode    os.FileMode
}

FileInfo holds file content and permission information

type GitProvenance

type GitProvenance struct {
	CommitSHA string `json:"commitSHA"`
	Tag       string `json:"tag,omitempty"`
	RemoteURL string `json:"remoteURL"`
}

GitProvenance contains git repository information for traceability

type ManifestEntry added in v0.9.0

type ManifestEntry struct {
	Type       ArtifactType      `yaml:"type"`
	Transport  ArtifactTransport `yaml:"transport"`
	Reference  string            `yaml:"reference"`
	Version    string            `yaml:"version,omitempty"`
	Digest     string            `yaml:"digest,omitempty"`
	Repository string            `yaml:"repository,omitempty"`
	Source     ArtifactSource    `yaml:"source"`
}

ManifestEntry describes a single external dependency. Reference is the canonical pull string a consumer would use against the upstream source; Digest, when present, pins the artifact to an immutable content hash; Transport tells the hydrate consumer which client is required to fetch it.

type MockArtifact

type MockArtifact struct {
	BundleFunc                        func() error
	WriteFunc                         func(outputPath string, tag string) (string, error)
	PushFunc                          func(registryBase string, repoName string, tag string) error
	PullFunc                          func(ociRefs []string) (map[string]string, error)
	ExtractModulePathFunc             func(registry, repository, tag, modulePath string) (string, error)
	ParseOCIRefFunc                   func(ociRef string) (registry, repository, tag string, err error)
	GetCacheDirFunc                   func(registry, repository, tag string) (string, error)
	ListTagsFunc                      func(ociRef string) ([]string, error)
	GetCliVersionConstraintFunc       func(ociRef string) (string, error)
	VerifyCliVersionCompatibilityFunc func(ociRef string) error
}

MockArtifact is a mock implementation of the Artifact interface

func NewMockArtifact

func NewMockArtifact() *MockArtifact

NewMockArtifact creates a new MockArtifact instance

func (*MockArtifact) Bundle

func (m *MockArtifact) Bundle() error

Bundle calls the mock BundleFunc if set, otherwise returns nil

func (*MockArtifact) ExtractModulePath added in v0.9.0

func (m *MockArtifact) ExtractModulePath(registry, repository, tag, modulePath string) (string, error)

ExtractModulePath calls the mock ExtractModulePathFunc if set, otherwise returns empty string and nil error

func (*MockArtifact) GetCacheDir added in v0.9.0

func (m *MockArtifact) GetCacheDir(registry, repository, tag string) (string, error)

GetCacheDir calls the mock GetCacheDirFunc if set, otherwise returns empty string and nil error

func (*MockArtifact) GetCliVersionConstraint added in v0.9.0

func (m *MockArtifact) GetCliVersionConstraint(ociRef string) (string, error)

GetCliVersionConstraint calls the mock GetCliVersionConstraintFunc if set, otherwise returns empty string and nil error

func (*MockArtifact) ListTags added in v0.9.0

func (m *MockArtifact) ListTags(ociRef string) ([]string, error)

ListTags calls the mock ListTagsFunc if set, otherwise returns an empty slice and nil error

func (*MockArtifact) ParseOCIRef added in v0.9.0

func (m *MockArtifact) ParseOCIRef(ociRef string) (registry, repository, tag string, err error)

ParseOCIRef calls the mock ParseOCIRefFunc if set, otherwise returns empty strings and nil error

func (*MockArtifact) Pull

func (m *MockArtifact) Pull(ociRefs []string) (map[string]string, error)

Pull calls the mock PullFunc if set, otherwise returns empty map and nil error

func (*MockArtifact) Push

func (m *MockArtifact) Push(registryBase string, repoName string, tag string) error

Push calls Bundle() first, then calls the mock PushFunc if set, otherwise returns nil

func (*MockArtifact) VerifyCliVersionCompatibility added in v0.9.0

func (m *MockArtifact) VerifyCliVersionCompatibility(ociRef string) error

VerifyCliVersionCompatibility calls the mock VerifyCliVersionCompatibilityFunc if set, otherwise returns nil

func (*MockArtifact) Write

func (m *MockArtifact) Write(outputPath string, tag string) (string, error)

Write calls the mock WriteFunc if set, otherwise returns empty string and nil error

type OCIArtifactInfo

type OCIArtifactInfo struct {
	Name string
	URL  string
	Tag  string
}

OCIArtifactInfo contains information about the OCI artifact source for blueprint data

func ParseOCIReference

func ParseOCIReference(ociRef string) (*OCIArtifactInfo, error)

ParseOCIReference parses a blueprint reference string in OCI URL or org/repo:tag format and returns an OCIArtifactInfo struct. Accepts full OCI URLs (e.g., oci://ghcr.io/org/repo:v1.0.0) and org/repo:v1.0.0 formats only. Returns nil if the reference is empty, missing a version, or not in a supported format.

type PathProcessor

type PathProcessor struct {
	Pattern string
	Handler func(relPath string, data []byte, mode os.FileMode) error
}

PathProcessor defines a processor for files matching a specific path pattern

type Provenance added in v0.9.0

type Provenance struct {
	Name    string `yaml:"name,omitempty"`
	Version string `yaml:"version,omitempty"`
	Commit  string `yaml:"commit,omitempty"`
}

Provenance records which blueprint produced the manifest and at which revision. All fields are optional; absence indicates the manifest was generated outside a recognized blueprint build.

type Shims

type Shims struct {
	Stat              func(name string) (os.FileInfo, error)
	Create            func(name string) (io.WriteCloser, error)
	ReadFile          func(name string) ([]byte, error)
	Walk              func(root string, walkFn filepath.WalkFunc) error
	NewGzipWriter     func(w io.Writer) *gzip.Writer
	NewTarWriter      func(w io.Writer) TarWriter
	YamlUnmarshal     func(data []byte, v any) error
	FilepathRel       func(basepath, targpath string) (string, error)
	YamlMarshal       func(data any) ([]byte, error)
	ReadAll           func(reader io.Reader) ([]byte, error)
	ParseReference    func(ref string, opts ...name.Option) (name.Reference, error)
	RemoteImage       func(ref name.Reference, options ...remote.Option) (v1.Image, error)
	ImageLayers       func(img v1.Image) ([]v1.Layer, error)
	LayerUncompressed func(layer v1.Layer) (io.ReadCloser, error)
	AppendLayers      func(base v1.Image, layers ...v1.Layer) (v1.Image, error)
	ConfigFile        func(img v1.Image, cfg *v1.ConfigFile) (v1.Image, error)
	MediaType         func(img v1.Image, mt types.MediaType) v1.Image
	ConfigMediaType   func(img v1.Image, mt types.MediaType) v1.Image
	Annotations       func(img v1.Image, anns map[string]string) v1.Image
	EmptyImage        func() v1.Image
	RemoteGet         func(ref name.Reference, options ...remote.Option) (*remote.Descriptor, error)
	RemoteWriteLayer  func(repo name.Repository, layer v1.Layer, options ...remote.Option) error
	RemoteWrite       func(ref name.Reference, img v1.Image, options ...remote.Option) error
	RemoteList        func(repo name.Repository, options ...remote.Option) ([]string, error)
	NewRepository     func(repo string, opts ...name.Option) (name.Repository, error)
	MkdirAll          func(path string, perm os.FileMode) error
	NewBytesReader    func(b []byte) *bytes.Reader
	NewTarReader      func(r io.Reader) TarReader
	Copy              func(dst io.Writer, src io.Reader) (int64, error)
	Chmod             func(name string, mode os.FileMode) error
	Rename            func(oldpath, newpath string) error
	RemoveAll         func(path string) error
}

Shims provides mockable wrappers around system and file operations

func NewShims

func NewShims() *Shims

NewShims creates a new Shims instance with default implementations

type TarReader added in v0.9.0

type TarReader interface {
	Next() (*tar.Header, error)
	Read([]byte) (int, error)
}

TarReader provides an interface for tar archive reading operations

type TarWriter

type TarWriter interface {
	WriteHeader(hdr *tar.Header) error
	Write(b []byte) (int, error)
	Close() error
}

TarWriter provides an interface for tar writing operations

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL