Documentation
¶
Index ¶
- Constants
- func IsAuthenticationError(err error) bool
- func ParseRegistryURL(registryURL string) (registryBase, repoName, tag string, err error)
- func ResolveCompatibleTag(artifactBuilder Artifact, urlPrefix string, tags []string) (tag string, version *semver.Version, ok bool, err error)
- func ValidateCliVersion(cliVersion, constraint string) error
- type Artifact
- type ArtifactBuilder
- func (a *ArtifactBuilder) Bundle() error
- func (a *ArtifactBuilder) ExtractModulePath(registry, repository, tag, modulePath string) (string, error)
- func (a *ArtifactBuilder) GetCacheDir(registry, repository, tag string) (string, error)
- func (a *ArtifactBuilder) GetCliVersionConstraint(ociRef string) (string, error)
- func (a *ArtifactBuilder) ListTags(ociRef string) ([]string, error)
- func (a *ArtifactBuilder) ParseOCIRef(ociRef string) (registry, repository, tag string, err error)
- func (a *ArtifactBuilder) Pull(ociRefs []string) (map[string]string, error)
- func (a *ArtifactBuilder) Push(registryBase string, repoName string, tag string) error
- func (a *ArtifactBuilder) VerifyCliVersionCompatibility(ociRef string) error
- func (a *ArtifactBuilder) Write(outputPath string, tag string) (string, error)
- type ArtifactManifest
- type ArtifactSource
- type ArtifactTransport
- type ArtifactType
- type BlueprintMetadata
- type BlueprintMetadataInput
- type BuilderInfo
- type FileInfo
- type GitProvenance
- type ManifestEntry
- type MockArtifact
- func (m *MockArtifact) Bundle() error
- func (m *MockArtifact) ExtractModulePath(registry, repository, tag, modulePath string) (string, error)
- func (m *MockArtifact) GetCacheDir(registry, repository, tag string) (string, error)
- func (m *MockArtifact) GetCliVersionConstraint(ociRef string) (string, error)
- func (m *MockArtifact) ListTags(ociRef string) ([]string, error)
- func (m *MockArtifact) ParseOCIRef(ociRef string) (registry, repository, tag string, err error)
- func (m *MockArtifact) Pull(ociRefs []string) (map[string]string, error)
- func (m *MockArtifact) Push(registryBase string, repoName string, tag string) error
- func (m *MockArtifact) VerifyCliVersionCompatibility(ociRef string) error
- func (m *MockArtifact) Write(outputPath string, tag string) (string, error)
- type OCIArtifactInfo
- type PathProcessor
- type Provenance
- type Shims
- type TarReader
- type TarWriter
Constants ¶
const CliVersionAnnotationKey = "windsorcli.dev/cli-version"
CliVersionAnnotationKey mirrors BlueprintMetadataInput.CliVersion into the OCI manifest, so GetCliVersionConstraint can check it without a full Pull.
const ManifestFileName = "artifact-manifest.yaml"
ManifestFileName is the canonical filename for the manifest inside a blueprint OCI bundle and at the blueprint source root.
const ManifestVersion = "v1alpha1"
ManifestVersion is the current schema version for ArtifactManifest documents.
Variables ¶
This section is empty.
Functions ¶
func IsAuthenticationError ¶
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 ¶
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 ¶
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 ¶
BuilderInfo contains information about who/what built the artifact
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
type OCIArtifactInfo ¶
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