resolve

package
v1.3.1 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package resolve decides which package versions to install and whether a package's requirements and conflicts are satisfied.

It deliberately is not a general SAT solver. Requirements are mostly on capabilities, constraints are expected to be loose, and a distribution pins exact versions; a solver that finds clever combinations nobody tested would be a liability. The search below takes the highest acceptable version of each package, prefers providers that are already installed, and backtracks only within that order.

Index

Constants

View Source
const APIPrefix = "api:"

APIPrefix marks a capability that the API server can satisfy through discovery, e.g. "api:cert-manager.io/v1".

View Source
const Unversioned = "0.0.0-unversioned"

Unversioned is the version of a package that declares none.

Variables

View Source
var ErrConflictingRequirements = errors.New("packages that require it disagree")

ErrConflictingRequirements is returned when packages that require the same package ask for different variants of it or pass different values for the same key.

View Source
var ErrUnresolvable = errors.New("requests cannot be satisfied")

ErrUnresolvable is returned when no combination satisfies the requests. The wrapped message explains the closest attempt.

Functions

func CheckRequirement added in v1.3.0

func CheckRequirement(q v1.Requirement) error

CheckRequirement refuses what a requirement cannot carry: a variant or values without a package, or values that are not an object.

func Conflicts

func Conflicts(r Release, st State) []string

Conflicts returns the installed packages that conflict with r, in either direction: r declares a conflict with them, or they declare one with r. The package itself is ignored, so an upgrade does not conflict with its previous version.

func Satisfies

func Satisfies(version, constraint string) (bool, error)

Satisfies reports whether version meets constraint. An empty constraint accepts anything; the unversioned version satisfies only an empty one.

Types

type Action

type Action string

Action is what a plan does to one package.

const (
	ActionInstall   Action = "install"
	ActionUpgrade   Action = "upgrade"
	ActionDowngrade Action = "downgrade"
	ActionKeep      Action = "keep"
)

type Catalog

type Catalog map[string][]Release

Catalog holds every published release, by package name.

type Change

type Change struct {
	Name   string
	From   string
	To     string
	Action Action
	// Reason says why the package is in the plan: "requested" or the
	// requirement that pulled it in.
	Reason string
	// Variant is the variant the package is resolved in.
	Variant string
	// Passed is what the packages requiring this one pass to it.
	Passed Passed
}

Change is one line of a plan.

type Installed

type Installed struct {
	Release
	Ready bool
	// VariantSet is true when the Package names its variant, so the
	// variant is a choice the plan must not change.
	VariantSet bool
	// Leaving is true for a package being deleted: what it passes to the
	// packages it requires no longer counts.
	Leaving bool
}

Installed is a package present in the cluster.

type Pass added in v1.3.0

type Pass struct {
	From    string
	Variant string
	Values  map[string]map[string]any
	// Invalid says why the requirement's values cannot be read.
	Invalid string
}

Pass is what one package passes to a package it requires: a variant, values by component, or both.

func PassesTo added in v1.3.0

func PassesTo(name string, requirers []Release) []Pass

PassesTo collects what the given releases pass to the package name, ordered by the name of the release passing it.

type Passed added in v1.3.0

type Passed struct {
	// Variant is the variant they ask for; empty when none asks.
	Variant string
	// Values are the values for each component, merged.
	Values map[string]map[string]any
	// From names the packages that pass something, sorted.
	From []string
}

Passed is the merged outcome of what several packages pass to one.

func MergePasses added in v1.3.0

func MergePasses(name string, passes []Pass) (Passed, error)

MergePasses merges what several packages pass to the package name. Values merge key by key; two packages setting the same key to different values, or asking for different variants, is an error wrapping ErrConflictingRequirements that names them. Nothing is resolved silently, since either choice would break the other package.

type Plan

type Plan struct {
	Changes []Change
}

Plan is the outcome of resolving a set of requests.

func Resolve

func Resolve(cat Catalog, st State, reqs []Request) (Plan, error)

Resolve picks a release for every requested package and everything they require. Already installed versions are kept when they still satisfy the constraints, so asking for one package does not silently upgrade its dependencies; requested packages get the highest acceptable version.

type Release

type Release struct {
	Name      string
	Version   string
	Provides  []string
	Requires  []Requirement
	Conflicts []string
	// Variant is the variant Requires belongs to; empty means default.
	Variant string
	// Variants holds the requirements of every variant, so a package can
	// be resolved in a variant that a package requiring it asks for.
	Variants map[string][]Requirement
}

Release is one version of a package as published in a repository.

func ReleaseOf

func ReleaseOf(name string, spec *v1.PackageSourceSpec, variant string) Release

ReleaseOf describes one variant of a package version for resolving, with the requirements of its other variants for packages that require it in one of them. A missing variant leaves the release without requirements.

func (Release) VariantName added in v1.3.0

func (r Release) VariantName() string

VariantName is the variant a release is resolved in.

type Request

type Request struct {
	Name    string
	Version string
}

Request asks for a package, optionally constrained to a version range.

type Requirement

type Requirement struct {
	Package    string
	Capability string
	Version    string
	Optional   bool
	// Variant is the variant of the required package asked for.
	Variant string
	// Values are passed to the required package's components, by
	// component name.
	Values map[string]map[string]any
	// Invalid says why values given for the requirement cannot be read.
	Invalid string
}

Requirement is a dependency on a package or a capability.

func RequirementsOf

func RequirementsOf(v *v1.Variant, ignore []string) []Requirement

RequirementsOf turns a variant's dependsOn and requires into requirements, minus the packages and capabilities listed in ignore.

func (Requirement) String

func (r Requirement) String() string

type State

type State struct {
	Packages map[string]Installed
	// APIs holds served group versions, e.g. "cert-manager.io/v1".
	APIs map[string]bool
}

State is what the cluster has: installed packages and served APIs.

type Unmet

type Unmet struct {
	Requirement Requirement
	Reason      string
}

Unmet is a requirement that is not satisfied, with the reason.

func Check

func Check(reqs []Requirement, st State) ([]Unmet, error)

Check evaluates requirements against the cluster. A requirement is met only by a Ready package, because the operator uses this to gate installation: something that exists but is not working yet does not count. Optional requirements are reported only when present but not ready.

func (Unmet) String

func (u Unmet) String() string

Jump to

Keyboard shortcuts

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