registry

package
v1.220.0 Latest Latest
Warning

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

Go to latest
Published: May 28, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const BuiltinAtmosRegistryPriority = 100

BuiltinAtmosRegistryPriority is the priority assigned to the curated Atmos registry in the composite. Above Aqua's default 10 so overrides win, low enough that users can still override even the built-ins with a higher-priority registry in atmos.yaml.

Variables

View Source
var (
	// ErrToolNotFound indicates a tool was not found in the registry.
	ErrToolNotFound = errors.New("tool not found")

	// ErrNoVersionsFound indicates no versions are available for a tool.
	ErrNoVersionsFound = errors.New("no versions found")

	// ErrInvalidToolSpec indicates the tool specification format is invalid.
	ErrInvalidToolSpec = errors.New("invalid tool specification")

	// ErrHTTPRequest indicates an HTTP request failed.
	ErrHTTPRequest = errors.New("HTTP request failed")

	// ErrHTTP404 indicates an HTTP 404 Not Found response.
	ErrHTTP404 = errors.New("HTTP 404 Not Found")

	// ErrRegistryParse indicates the registry file could not be parsed.
	ErrRegistryParse = errors.New("registry parse error")

	// ErrNoPackagesInRegistry indicates the registry contains no packages.
	ErrNoPackagesInRegistry = errors.New("no packages found in registry")

	// ErrNoAssetTemplate indicates no asset template is defined for the tool.
	ErrNoAssetTemplate = errors.New("no asset template defined")

	// ErrFileOperation indicates a file operation failed.
	ErrFileOperation = errors.New("file operation failed")

	// ErrUnknownRegistry indicates the registry name is not recognized.
	ErrUnknownRegistry = errors.New("unknown registry")

	// ErrRegistryNotRegistered indicates a registry factory has not been registered.
	ErrRegistryNotRegistered = errors.New("registry not registered")

	// ErrRegistryConfiguration indicates the registry configuration is invalid.
	ErrRegistryConfiguration = errors.New("invalid registry configuration")

	// ErrToolAlreadyExists indicates the tool version already exists in .tool-versions.
	ErrToolAlreadyExists = errors.New("tool already exists")

	// ErrNoValidTools indicates no valid tools were provided for installation.
	ErrNoValidTools = errors.New("no valid tools to install")
)

Error definitions for the registry package.

Functions

func HasChecksumConfig added in v1.220.0

func HasChecksumConfig(c *ChecksumConfig) bool

HasChecksumConfig reports whether any meaningful field is set on a checksum configuration.

func HasCosignConfig added in v1.220.0

func HasCosignConfig(c *CosignConfig) bool

HasCosignConfig reports whether any meaningful field is set on a cosign verification configuration.

func HasDownloadedFile added in v1.220.0

func HasDownloadedFile(f *DownloadedFile) bool

HasDownloadedFile reports whether any meaningful field is set on a sidecar file descriptor. Used to decide whether an override should be applied.

func HasGitHubArtifactAttestations added in v1.220.0

func HasGitHubArtifactAttestations(g *GitHubArtifactAttestations) bool

HasGitHubArtifactAttestations reports whether any meaningful field is set on a GitHub artifact attestation configuration.

func HasMinisignConfig added in v1.220.0

func HasMinisignConfig(m *MinisignConfig) bool

HasMinisignConfig reports whether any meaningful field is set on a minisign verification configuration.

func HasSLSAProvenance added in v1.220.0

func HasSLSAProvenance(s *SLSAProvenance) bool

HasSLSAProvenance reports whether any meaningful field is set on a SLSA provenance configuration.

func RegisterAtmosRegistry

func RegisterAtmosRegistry(factory atmosRegistryFactory)

RegisterAtmosRegistry allows the atmos package to register its constructor. This is called by atmos package during initialization.

func RegisterBuiltinAtmosRegistry added in v1.220.0

func RegisterBuiltinAtmosRegistry(factory builtinAtmosRegistryFactory)

RegisterBuiltinAtmosRegistry allows the atmos package to register a factory that returns the curated registry baked into the binary. Called by atmos package init().

func RegisterDefaultRegistry

func RegisterDefaultRegistry(factory registryFactory)

RegisterDefaultRegistry allows a registry implementation to register itself as the default. This is called by aqua package during initialization.

Types

type AquaOverride

type AquaOverride struct {
	GOOS                       string                     `yaml:"goos"`
	GOARCH                     string                     `yaml:"goarch"`
	Envs                       []string                   `yaml:"envs"` // Supported environments for this override.
	Type                       string                     `yaml:"type"`
	URL                        string                     `yaml:"url"`
	Asset                      string                     `yaml:"asset"`
	Format                     string                     `yaml:"format"`
	Files                      []File                     `yaml:"files"`
	Replacements               map[string]string          `yaml:"replacements"`
	Checksum                   ChecksumConfig             `yaml:"checksum"`
	Cosign                     CosignConfig               `yaml:"cosign"`
	SLSAProvenance             SLSAProvenance             `yaml:"slsa_provenance"`
	Minisign                   MinisignConfig             `yaml:"minisign"`
	GitHubArtifactAttestations GitHubArtifactAttestations `yaml:"github_artifact_attestations"`
}

AquaOverride represents platform-specific overrides in Aqua format. Aqua uses 'goos' and 'goarch' (lowercase) as field names.

type AquaPackage

type AquaPackage struct {
	Type       string `yaml:"type"`
	RepoOwner  string `yaml:"repo_owner"`
	RepoName   string `yaml:"repo_name"`
	Name       string `yaml:"name"`  // Used by http and some go_install types.
	Path       string `yaml:"path"`  // Used by go_install types (Go module path).
	Asset      string `yaml:"asset"` // Used by github_release types.
	URL        string `yaml:"url"`   // Used by http types (complete URL).
	Format     string `yaml:"format"`
	BinaryName string `yaml:"binary_name"`
	// FormatOverrides provides per-OS format overrides (e.g., zip on Windows).
	FormatOverrides []FormatOverride `yaml:"format_overrides"`
	// Files specifies which files to extract from archive with their destination names.
	Files []File `yaml:"files"`
	// Overrides provides platform-specific (goos/goarch) configuration overrides.
	Overrides []AquaOverride `yaml:"overrides"`
	// Replacements provides OS/Arch string mappings (e.g., amd64 -> x86_64).
	Replacements map[string]string `yaml:"replacements"`
	// Additional Aqua fields.
	Description                string                     `yaml:"description"`
	SupportedEnvs              []string                   `yaml:"supported_envs"`
	Rosetta2                   bool                       `yaml:"rosetta2"`
	WindowsArmEmulation        bool                       `yaml:"windows_arm_emulation"`
	Checksum                   ChecksumConfig             `yaml:"checksum"`
	VersionConstraint          string                     `yaml:"version_constraint"`
	VersionOverrides           []VersionOverride          `yaml:"version_overrides"`
	VersionPrefix              string                     `yaml:"version_prefix"` // GitHub tag prefix (e.g., "v", "kustomize/").
	ErrorMessage               string                     `yaml:"error_message"`
	VersionSource              string                     `yaml:"version_source"` // Version source: "github_release" (default) or "github_tag".
	NoAsset                    bool                       `yaml:"no_asset"`
	Cosign                     CosignConfig               `yaml:"cosign"`
	SLSAProvenance             SLSAProvenance             `yaml:"slsa_provenance"`
	Minisign                   MinisignConfig             `yaml:"minisign"`
	GitHubArtifactAttestations GitHubArtifactAttestations `yaml:"github_artifact_attestations"`
}

AquaPackage represents a single package in the Aqua registry format. This struct matches the Aqua registry YAML fields exactly and is used only for parsing Aqua registry files.

type AquaRegistryFile

type AquaRegistryFile struct {
	Packages []AquaPackage `yaml:"packages"`
}

AquaRegistryFile represents the structure of an Aqua registry YAML file (uses 'packages' key).

type ChecksumConfig

type ChecksumConfig struct {
	Type                       string                     `yaml:"type"`
	Asset                      string                     `yaml:"asset"` // Checksum asset filename (e.g., "sha256sum.txt").
	URL                        string                     `yaml:"url"`
	Algorithm                  string                     `yaml:"algorithm"`
	Enabled                    *bool                      `yaml:"enabled"`
	FileFormat                 string                     `yaml:"file_format"`
	Pattern                    ChecksumPattern            `yaml:"pattern"`
	Replacements               map[string]string          `yaml:"replacements"`
	Cosign                     CosignConfig               `yaml:"cosign"`
	Minisign                   MinisignConfig             `yaml:"minisign"`
	GitHubArtifactAttestations GitHubArtifactAttestations `yaml:"github_artifact_attestations"`
}

ChecksumConfig represents checksum configuration for Aqua packages.

type ChecksumPattern added in v1.220.0

type ChecksumPattern struct {
	Checksum string `yaml:"checksum"`
	File     string `yaml:"file"`
}

ChecksumPattern describes Aqua regexp checksum-file extraction.

type CompositeRegistry

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

CompositeRegistry coordinates multiple registry sources with priority-based precedence. Higher priority registries are checked first, with fallback to lower priority registries.

func NewCompositeRegistry

func NewCompositeRegistry(registries []PrioritizedRegistry) *CompositeRegistry

NewCompositeRegistry creates a new composite registry from multiple registry sources.

func (*CompositeRegistry) GetLatestVersion

func (cr *CompositeRegistry) GetLatestVersion(owner, repo string) (string, error)

GetLatestVersion tries to get the latest version from registries in priority order.

func (*CompositeRegistry) GetMetadata

func (cr *CompositeRegistry) GetMetadata(ctx context.Context) (*RegistryMetadata, error)

GetMetadata returns aggregated metadata from all registries.

func (*CompositeRegistry) GetTool

func (cr *CompositeRegistry) GetTool(owner, repo string) (*Tool, error)

GetTool tries to get tool metadata from registries in priority order.

func (*CompositeRegistry) GetToolWithVersion

func (cr *CompositeRegistry) GetToolWithVersion(owner, repo, version string) (*Tool, error)

GetToolWithVersion tries to get versioned tool metadata from registries in priority order.

func (*CompositeRegistry) ListAll

func (cr *CompositeRegistry) ListAll(ctx context.Context, opts ...ListOption) ([]*Tool, error)

ListAll lists tools from all registries, deduplicated.

func (*CompositeRegistry) LoadLocalConfig

func (cr *CompositeRegistry) LoadLocalConfig(configPath string) error

LoadLocalConfig is deprecated and no-op for compatibility.

func (*CompositeRegistry) Search

func (cr *CompositeRegistry) Search(ctx context.Context, query string, opts ...SearchOption) ([]*Tool, error)

Search searches across all registries and combines results. Results are deduplicated (highest priority registry wins) and sorted by relevance.

type CosignConfig added in v1.220.0

type CosignConfig struct {
	Enabled     *bool          `yaml:"enabled"`
	Opts        []string       `yaml:"opts"`
	Signature   DownloadedFile `yaml:"signature"`
	Certificate DownloadedFile `yaml:"certificate"`
	Key         DownloadedFile `yaml:"key"`
	Bundle      DownloadedFile `yaml:"bundle"`
}

CosignConfig represents Aqua cosign verification configuration.

type DownloadedFile added in v1.220.0

type DownloadedFile struct {
	Type      string `yaml:"type"`
	RepoOwner string `yaml:"repo_owner"`
	RepoName  string `yaml:"repo_name"`
	Asset     string `yaml:"asset"`
	URL       string `yaml:"url"`
}

DownloadedFile describes a verification sidecar file.

type File

type File struct {
	Name string `yaml:"name"`
	Src  string `yaml:"src"`
}

File represents a file to be extracted from the archive.

type FormatOverride added in v1.208.0

type FormatOverride struct {
	GOOS   string `yaml:"goos"`
	Format string `yaml:"format"`
}

FormatOverride represents a per-OS format override (e.g., zip on Windows, tar.gz on Linux).

type GitHubArtifactAttestations added in v1.220.0

type GitHubArtifactAttestations struct {
	Enabled        *bool  `yaml:"enabled"`
	PredicateType  string `yaml:"predicate_type"`
	SignerWorkflow string `yaml:"signer_workflow"`
}

GitHubArtifactAttestations represents Aqua GitHub artifact attestation configuration.

type ListConfig

type ListConfig struct {
	Limit  int
	Offset int
	Sort   string // "name", "date", "popularity"
}

ListConfig contains list configuration.

type ListOption

type ListOption func(*ListConfig)

ListOption configures list behavior.

func WithListLimit

func WithListLimit(limit int) ListOption

WithListLimit sets the maximum number of results for list operations.

func WithListOffset

func WithListOffset(offset int) ListOption

WithListOffset sets the starting offset for list operations.

func WithSort

func WithSort(sort string) ListOption

WithSort sets the sort order for list operations.

type MinisignConfig added in v1.220.0

type MinisignConfig struct {
	Enabled   *bool  `yaml:"enabled"`
	Type      string `yaml:"type"`
	RepoOwner string `yaml:"repo_owner"`
	RepoName  string `yaml:"repo_name"`
	Asset     string `yaml:"asset"`
	URL       string `yaml:"url"`
	PublicKey string `yaml:"public_key"`
}

MinisignConfig represents Aqua minisign verification configuration.

type Override

type Override struct {
	GOOS                       string                     `yaml:"goos"`
	GOARCH                     string                     `yaml:"goarch"`
	Envs                       []string                   `yaml:"envs,omitempty"` // Supported environments for this override (e.g., "darwin/arm64").
	Type                       string                     `yaml:"type,omitempty"`
	Asset                      string                     `yaml:"asset"`
	URL                        string                     `yaml:"url,omitempty"`
	Format                     string                     `yaml:"format"`
	Files                      []File                     `yaml:"files"`
	Replacements               map[string]string          `yaml:"replacements"`
	Checksum                   ChecksumConfig             `yaml:"checksum,omitempty"`
	Cosign                     CosignConfig               `yaml:"cosign,omitempty"`
	SLSAProvenance             SLSAProvenance             `yaml:"slsa_provenance,omitempty"`
	Minisign                   MinisignConfig             `yaml:"minisign,omitempty"`
	GitHubArtifactAttestations GitHubArtifactAttestations `yaml:"github_artifact_attestations,omitempty"`
}

Override represents platform-specific overrides.

type PrioritizedRegistry

type PrioritizedRegistry struct {
	Name     string
	Registry ToolRegistry
	Priority int
}

PrioritizedRegistry wraps a registry with priority and name metadata.

type RegistryMetadata

type RegistryMetadata struct {
	Name        string
	Type        string // "aqua", "atmos"
	Source      string // URL
	Priority    int
	ToolCount   int
	LastUpdated time.Time
}

RegistryMetadata contains registry-level information.

type SLSAProvenance added in v1.220.0

type SLSAProvenance struct {
	Enabled   *bool  `yaml:"enabled"`
	Type      string `yaml:"type"`
	RepoOwner string `yaml:"repo_owner"`
	RepoName  string `yaml:"repo_name"`
	Asset     string `yaml:"asset"`
	URL       string `yaml:"url"`
	SourceURI string `yaml:"source_uri"`
	SourceTag string `yaml:"source_tag"`
}

SLSAProvenance represents Aqua slsa_provenance configuration.

type SearchConfig

type SearchConfig struct {
	Limit         int
	Offset        int
	InstalledOnly bool
	AvailableOnly bool
}

SearchConfig contains search configuration.

type SearchOption

type SearchOption func(*SearchConfig)

SearchOption configures search behavior.

func WithAvailableOnly

func WithAvailableOnly(availableOnly bool) SearchOption

WithAvailableOnly filters to only show non-installed tools.

func WithInstalledOnly

func WithInstalledOnly(installedOnly bool) SearchOption

WithInstalledOnly filters to only show installed tools.

func WithLimit

func WithLimit(limit int) SearchOption

WithLimit sets the maximum number of results.

func WithOffset

func WithOffset(offset int) SearchOption

WithOffset sets the starting offset for results.

type SearchTotalProvider

type SearchTotalProvider interface {
	GetLastSearchTotal() int
}

SearchTotalProvider is an optional interface that registries can implement to provide the total count of search results (for pagination UI).

type SupportedIf

type SupportedIf struct {
	GOOS   string `yaml:"goos"`
	GOARCH string `yaml:"goarch"`
}

SupportedIf represents conditions for when a tool is supported.

type Tool

type Tool struct {
	Name                       string                     `yaml:"name"`
	Registry                   string                     `yaml:"registry"`
	Version                    string                     `yaml:"version"`
	Type                       string                     `yaml:"type"`
	RepoOwner                  string                     `yaml:"repo_owner"`
	RepoName                   string                     `yaml:"repo_name"`
	Asset                      string                     `yaml:"asset"`
	URL                        string                     `yaml:"url"`
	Format                     string                     `yaml:"format"`
	FormatOverrides            []FormatOverride           `yaml:"format_overrides"`
	Files                      []File                     `yaml:"files"`
	Overrides                  []Override                 `yaml:"overrides"`
	VersionOverrides           []VersionOverride          `yaml:"version_overrides"`
	SupportedIf                *SupportedIf               `yaml:"supported_if"`
	Replacements               map[string]string          `yaml:"replacements"`
	BinaryName                 string                     `yaml:"binary_name"`
	VersionPrefix              string                     `yaml:"version_prefix"`        // GitHub tag prefix (e.g., "v", "jq-"). Empty means no prefix.
	SourceURL                  string                     `yaml:"-"`                     // URL where the registry file was found (not serialized).
	SupportedEnvs              []string                   `yaml:"supported_envs"`        // Supported platforms (e.g., "darwin", "linux", "windows", "darwin/amd64").
	Rosetta2                   bool                       `yaml:"rosetta2"`              // Allow arm64 to fall back to amd64 on macOS via Rosetta 2.
	WindowsArmEmulation        bool                       `yaml:"windows_arm_emulation"` // Allow arm64 to fall back to amd64 on Windows.
	ErrorMessage               string                     `yaml:"error_message"`         // Custom error message for unsupported versions.
	VersionSource              string                     `yaml:"version_source"`        // Version source: "github_release" (default) or "github_tag".
	NoAsset                    bool                       `yaml:"no_asset"`              // Tool has no downloadable asset (e.g., go_install only).
	Checksum                   ChecksumConfig             `yaml:"checksum"`              // Checksum verification configuration.
	Cosign                     CosignConfig               `yaml:"cosign"`
	SLSAProvenance             SLSAProvenance             `yaml:"slsa_provenance"`
	Minisign                   MinisignConfig             `yaml:"minisign"`
	GitHubArtifactAttestations GitHubArtifactAttestations `yaml:"github_artifact_attestations"`
}

Tool represents a single tool in the registry.

type ToolRegistry

type ToolRegistry interface {
	// GetTool fetches tool metadata from the registry.
	GetTool(owner, repo string) (*Tool, error)

	// GetToolWithVersion fetches tool metadata and resolves version-specific overrides.
	GetToolWithVersion(owner, repo, version string) (*Tool, error)

	// GetLatestVersion fetches the latest non-prerelease version for a tool.
	GetLatestVersion(owner, repo string) (string, error)

	// LoadLocalConfig is deprecated and will be removed. Returns nil for compatibility.
	LoadLocalConfig(configPath string) error

	// Search searches for tools matching the query string.
	// The query is matched against tool owner, repo, aliases, and description.
	// Results are sorted by relevance score.
	Search(ctx context.Context, query string, opts ...SearchOption) ([]*Tool, error)

	// ListAll returns all tools available in the registry.
	// Results can be paginated and sorted using options.
	ListAll(ctx context.Context, opts ...ListOption) ([]*Tool, error)

	// GetMetadata returns metadata about the registry itself.
	GetMetadata(ctx context.Context) (*RegistryMetadata, error)
}

ToolRegistry defines the interface for tool metadata registries. This abstraction allows multiple registry implementations (Aqua, custom URL-based, etc.) while keeping the toolchain package decoupled from specific registry formats.

func DefaultRegistry added in v1.219.0

func DefaultRegistry() ToolRegistry

DefaultRegistry returns a fresh instance of the registered default registry (Aqua), or nil if none has been registered. Use this to access registry capabilities (e.g., short-name resolution) from callers that don't have a full atmos configuration available.

func LoadFromConfig

func LoadFromConfig(atmosConfig *schema.AtmosConfiguration) (ToolRegistry, error)

LoadFromConfig creates a ToolRegistry from an Atmos configuration. Returns a CompositeRegistry that coordinates multiple registry sources.

The composite ALWAYS includes the Atmos curated built-in registry (when registered by pkg/toolchain/registry/atmos) at high priority — that's where overrides for tools the upstream Aqua registry doesn't model well live (e.g., KICS). User-configured registries from atmos.yaml stack on top; users can override a built-in entry by configuring a registry with priority > BuiltinAtmosRegistryPriority.

If atmos.yaml has no `toolchain.registries` block, the result is the built-in registry composited with the default Aqua registry. This preserves the zero-config behavior while making the curated overrides available without YAML changes.

type ToolRegistryFile

type ToolRegistryFile struct {
	Tools []Tool `yaml:"tools"`
}

ToolRegistryFile represents the structure of a tool registry YAML file.

type URLRegistry

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

URLRegistry fetches tool metadata from a custom URL. Supports two modes: 1. Single index file (source ends with .yaml/.yml) - all packages in one file. 2. Directory structure (source ends with / or no extension) - per-tool registry files.

func NewURLRegistry

func NewURLRegistry(baseURL string, ref string) *URLRegistry

NewURLRegistry creates a new URL-based registry. If ref is provided and the URL is a GitHub raw content URL, the ref will be substituted into the URL path to fetch from that specific Git ref.

func (*URLRegistry) GetLatestVersion

func (ur *URLRegistry) GetLatestVersion(owner, repo string) (string, error)

GetLatestVersion is not implemented for URL registries. URL registries don't have version information; they only provide tool metadata.

func (*URLRegistry) GetMetadata

func (ur *URLRegistry) GetMetadata(ctx context.Context) (*RegistryMetadata, error)

GetMetadata returns metadata about the URL registry.

func (*URLRegistry) GetTool

func (ur *URLRegistry) GetTool(owner, repo string) (*Tool, error)

GetTool fetches tool metadata from the custom URL.

func (*URLRegistry) GetToolWithVersion

func (ur *URLRegistry) GetToolWithVersion(owner, repo, version string) (*Tool, error)

GetToolWithVersion fetches tool metadata and resolves version-specific overrides.

func (*URLRegistry) ListAll

func (ur *URLRegistry) ListAll(ctx context.Context, opts ...ListOption) ([]*Tool, error)

ListAll lists all tools in the URL registry. URL registries don't support listing, so this returns empty results.

func (*URLRegistry) LoadLocalConfig

func (ur *URLRegistry) LoadLocalConfig(configPath string) error

LoadLocalConfig is a no-op for URL registries.

func (*URLRegistry) Search

func (ur *URLRegistry) Search(ctx context.Context, query string, opts ...SearchOption) ([]*Tool, error)

Search searches tools in the URL registry. URL registries don't support full search, so this returns empty results.

type VersionOverride

type VersionOverride struct {
	VersionConstraint          string                     `yaml:"version_constraint"`
	Type                       string                     `yaml:"type"`
	RepoOwner                  string                     `yaml:"repo_owner"`
	RepoName                   string                     `yaml:"repo_name"`
	Asset                      string                     `yaml:"asset"`
	URL                        string                     `yaml:"url"`
	Format                     string                     `yaml:"format"`
	FormatOverrides            []FormatOverride           `yaml:"format_overrides"`
	Rosetta2                   bool                       `yaml:"rosetta2"`
	WindowsArmEmulation        bool                       `yaml:"windows_arm_emulation"`
	SupportedEnvs              []string                   `yaml:"supported_envs"`
	Checksum                   ChecksumConfig             `yaml:"checksum"`
	Files                      []File                     `yaml:"files"`
	Overrides                  []AquaOverride             `yaml:"overrides"`
	Replacements               map[string]string          `yaml:"replacements"`
	ErrorMessage               string                     `yaml:"error_message"`
	VersionPrefix              string                     `yaml:"version_prefix"`
	Cosign                     CosignConfig               `yaml:"cosign"`
	SLSAProvenance             SLSAProvenance             `yaml:"slsa_provenance"`
	Minisign                   MinisignConfig             `yaml:"minisign"`
	GitHubArtifactAttestations GitHubArtifactAttestations `yaml:"github_artifact_attestations"`
}

VersionOverride represents version-specific overrides for Aqua packages.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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