modules

package
v0.30.18 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrProbeNoLowerBound = errors.New("constraint has no parseable lower-bound version literal — probing requires an explicit starting point")

ErrProbeNoLowerBound is returned when a constraint without a parseable lower bound is handed to ProbeAvailableVersions. Callers should surface this to the user as "your constraint needs an explicit version anchor (e.g. ^1.65.0, ~1.65.0, or >=1.65.0)" rather than silently scanning from v0.0.0.

Functions

func ProbeAvailableVersions added in v0.30.11 

func ProbeAvailableVersions(
	ctx context.Context,
	constraint *SemanticVersionConstraint,
	check ProbeChecker,
) ([]*semver.Version, error)

ProbeAvailableVersions enumerates registry tags by walking semver versions starting from the constraint's lower bound. It exists for proxy/caching registries that do NOT expose the registry catalog API but DO serve manifests for tags they cache.

Walk rules (intentionally identical to the user-facing description):

  1. From the lower-bound (M, m, p), increment patch one step at a time. Each step is tested with `check` and (when present and matching the constraint) appended to the result. The patch series ends as soon as a step does not exist OR does not satisfy the constraint.
  2. When the patch series ends, advance one step to (M, m+1, 0) and retry. If that exists, resume rule 1 from there; if not, fall through to rule 3.
  3. When the new-minor step also fails, advance to (M+1, 0, 0). If that exists, resume rule 1 from there; if not, terminate the probe.

The probe never invents a tag — every appended version was confirmed by the registry. It also never widens past the constraint: a version that the constraint does not accept is treated the same as a missing tag for rule-1 purposes, and the rule-2 / rule-3 jump points are also constraint-gated so the probe can terminate cleanly inside a bounded range like ">=1.64 <=1.68".

Context cancellation is honoured between every probe step so a proxy registry that hangs on a single HEAD request does not block shutdown indefinitely.

Types

type ExactTagConstraint added in v0.29.0 

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

func NewExactTagConstraint added in v0.29.0 

func NewExactTagConstraint(tag string) *ExactTagConstraint

func NewExactTagConstraintWithChannel added in v0.29.0 

func NewExactTagConstraintWithChannel(tag string, channel string) *ExactTagConstraint

func (*ExactTagConstraint) Channel added in v0.29.0 

func (e *ExactTagConstraint) Channel() string

func (*ExactTagConstraint) HasChannelAlias added in v0.29.0 

func (e *ExactTagConstraint) HasChannelAlias() bool

func (*ExactTagConstraint) IsExact added in v0.29.0 

func (e *ExactTagConstraint) IsExact() bool

func (*ExactTagConstraint) Match added in v0.29.0 

func (e *ExactTagConstraint) Match(version interface{}) bool

func (*ExactTagConstraint) Tag added in v0.29.0 

func (e *ExactTagConstraint) Tag() string

type Filter added in v0.3.0 

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

Filter for modules by black and whitelists. Maps module names to minimal versions of these modules to be pulled. By default, this is a whitelist filter, but that can be changed via SetType.

func NewFilter added in v0.3.0 

func NewFilter(filterExpressions []string, filterType FilterType) (*Filter, error)

func (*Filter) GetConstraint added in v0.29.0 

func (f *Filter) GetConstraint(moduleName string) (VersionConstraint, bool)

func (*Filter) IsWhitelist added in v0.30.11 

func (f *Filter) IsWhitelist() bool

IsWhitelist reports whether the filter is operating in whitelist mode. It exists so the modules service can take alternate code paths that only make sense when a finite, user-supplied module list is available (e.g. proxy-registry probing, which has no module catalog to enumerate).

func (*Filter) Len added in v0.29.0 

func (f *Filter) Len() int

func (*Filter) Match added in v0.29.0 

func (f *Filter) Match(mod *Module) bool

func (*Filter) ModuleNames added in v0.30.11 

func (f *Filter) ModuleNames() []string

ModuleNames returns the names registered with the filter in deterministic insertion-agnostic order (sorted). For a whitelist filter this is exactly the set of modules the user named with --include-module; for a blacklist filter it is the set the user asked to exclude.

The slice is freshly allocated so callers may mutate it freely.

func (*Filter) ShouldMirrorReleaseChannels added in v0.29.0 

func (f *Filter) ShouldMirrorReleaseChannels(moduleName string) bool

func (*Filter) UseLogger added in v0.29.0 

func (f *Filter) UseLogger(logger params.Logger) *Filter

func (*Filter) VersionsToMirror added in v0.29.0 

func (f *Filter) VersionsToMirror(mod *Module) []string

VersionsToMirror resolves module constraints from --include-module into concrete tags to pull. Returns nil when no explicit version tags should be added for this module.

For semver constraints (caret, tilde, ranges) only the highest patch in each (major, minor) bucket that satisfies the constraint is returned. This mirrors the platform-level discovery rule (filterOnlyLatestPatches in internal/mirror/platform/platform.go) and avoids pulling N redundant patches per minor when the user wires a single module pin like `module@v1.6.0`.

Anchor exception: versions named with an inclusive boundary operator (`>=` or `<=`) are always restored to the result if they exist in the registry. `>=1.40.0` literally encodes "v1.40.0 OR newer" — the user named v1.40.0 by hand and we MUST honour that even when a newer patch (v1.40.1) exists in the same minor. Caret (`^`) and tilde (`~`) are syntactic shorthand for a range; their lower bounds are NOT anchors.

Exact-tag constraints (`module@=vX.Y.Z`) bypass this filter — when the user asks for a specific tag they get exactly that tag.

Channel snapshot versions (alpha/beta/early-access/stable/rock-solid) are merged into the pull list outside this method, so an older patch that a channel still points at remains reachable through the channel snapshot even when filterOnlyLatestPatches drops it from the constraint set.

type FilterType added in v0.29.0 

type FilterType int
const (
	FilterTypeWhitelist FilterType = iota
	FilterTypeBlacklist
)

type ImageDownloadList added in v0.22.9 

type ImageDownloadList struct {
	Module                map[string]*puller.ImageMeta
	ModuleReleaseChannels map[string]*puller.ImageMeta
	ModuleExtra           map[string]*puller.ImageMeta
	// contains filtered or unexported fields
}

func NewImageDownloadList added in v0.22.9 

func NewImageDownloadList(rootURL string) *ImageDownloadList

func (*ImageDownloadList) FillForTag added in v0.22.9 

func (l *ImageDownloadList) FillForTag(tag string)

type ImageLayouts added in v0.22.9 

type ImageLayouts struct {

	// Modules is the main module image layout (modules/<name>/)
	Modules *regimage.ImageLayout
	// ModulesReleaseChannels is the release channel layout (modules/<name>/release/)
	ModulesReleaseChannels *regimage.ImageLayout
	// ExtraImages holds layouts for each extra image (modules/<name>/extra/<extra-name>/)
	// Key is the extra image name (e.g., "scanner", "enforcer")
	ExtraImages map[string]*regimage.ImageLayout
	// contains filtered or unexported fields
}

func NewImageLayouts added in v0.22.9 

func NewImageLayouts(rootFolder string) *ImageLayouts

func (*ImageLayouts) AsList added in v0.22.9 

func (l *ImageLayouts) AsList() []layout.Path

AsList returns a list of layout.Path's in it. Undefined path's are not included in the list.

func (*ImageLayouts) GetOrCreateExtraLayout added in v0.26.4 

func (l *ImageLayouts) GetOrCreateExtraLayout(extraName string) (*regimage.ImageLayout, error)

GetOrCreateExtraLayout returns or creates a layout for a specific extra image. Extra images are stored under: modules/<name>/extra/<extra-name>/

func (*ImageLayouts) HasImages added in v0.30.4 

func (l *ImageLayouts) HasImages() bool

HasImages reports whether any sub-layout of this module contains at least one image manifest. Returns false when all layouts are empty (i.e. the module was discovered but no images were pulled into it).

type Module 

type Module struct {
	Name         string
	RegistryPath string
	Releases     []string
}

func (*Module) Versions added in v0.29.0 

func (m *Module) Versions() []*semver.Version

type ModulesDownloadList added in v0.24.3 

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

func NewModulesDownloadList added in v0.24.3 

func NewModulesDownloadList(rootURL string) *ModulesDownloadList

func (*ModulesDownloadList) FillModulesImages added in v0.24.3 

func (l *ModulesDownloadList) FillModulesImages(modules []string)

func (*ModulesDownloadList) Module added in v0.24.3 

func (l *ModulesDownloadList) Module(moduleName string) *ImageDownloadList

type ModulesImageLayouts added in v0.24.3 

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

func NewModulesImageLayouts added in v0.24.3 

func NewModulesImageLayouts(rootFolder string) *ModulesImageLayouts

func (*ModulesImageLayouts) AsList added in v0.24.3 

func (l *ModulesImageLayouts) AsList() []layout.Path

AsList returns a list of layout.Path's from all modules. Undefined path's are not included in the list.

func (*ModulesImageLayouts) Module added in v0.24.3 

func (l *ModulesImageLayouts) Module(moduleName string) *ImageLayouts

type Options added in v0.24.3 

type Options struct {
	// Filter is the module filter (whitelist/blacklist)
	Filter *Filter
	// OnlyExtraImages pulls only extra images without main module images
	OnlyExtraImages bool
	// SkipVexImages allows skipping VEX images
	SkipVexImages bool
	// BundleDir is the directory to store the bundle
	BundleDir string
	// BundleChunkSize is the max size of bundle chunks in bytes (0 = no chunking)
	BundleChunkSize int64
	// Timeout is the timeout for the modules access check
	Timeout time.Duration
	// DryRun prints the pull plan without downloading any image blobs
	DryRun bool
	// ProxyRegistry replaces catalog-based discovery (ListTags of the
	// modules root and per-module tag listings) with a sequential probe
	// of individual version tags derived from the user's --include-module
	// version constraint. It exists for proxy/caching registries that do
	// not implement the registry catalog API but DO serve manifests for
	// tags they cache.
	//
	// The CLI requires --include-module with explicit version anchors
	// when ProxyRegistry is set so the probe has both a module name list
	// and a per-module lower bound to start incrementing from.
	ProxyRegistry bool
}

Options contains configuration options for the modules service

type ProbeChecker added in v0.30.11 

type ProbeChecker func(ctx context.Context, version *semver.Version) (bool, error)

ProbeChecker reports whether a specific semver tag is served by the registry. The boolean MUST be false (with a nil error) when the tag is definitively absent — this is the signal the probe uses to decide that a patch series has ended. A non-nil error indicates a real failure (network, auth, ...) and aborts the probe.

Callers integrating with a registry client typically translate the client's "image not found" sentinel to (false, nil) and propagate all other errors.

type SemanticVersionConstraint added in v0.29.0 

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

func NewSemanticVersionConstraint added in v0.29.0 

func NewSemanticVersionConstraint(c string) (*SemanticVersionConstraint, error)

func (*SemanticVersionConstraint) Anchors added in v0.30.10 

func (s *SemanticVersionConstraint) Anchors() []*semver.Version

Anchors returns the versions explicitly named with an inclusive boundary operator (>=, <=). Callers must re-check membership against the constraint itself (Match) before consuming an anchor: an anchor that fails Match means the user wrote a contradictory constraint (e.g. `>=2.0.0 <1.0.0`) and we will not silently widen the range.

func (*SemanticVersionConstraint) HasChannelAlias added in v0.29.0 

func (s *SemanticVersionConstraint) HasChannelAlias() bool

func (*SemanticVersionConstraint) IsExact added in v0.29.0 

func (s *SemanticVersionConstraint) IsExact() bool

func (*SemanticVersionConstraint) LowerBound added in v0.30.11 

func (s *SemanticVersionConstraint) LowerBound() *semver.Version

LowerBound returns the smallest version literal found in the constraint string. This is the natural starting point for callers that enumerate (major, minor, patch) by probing the registry one tag at a time (proxy registry mode) — incrementing forward from a version the user has explicitly named avoids scanning from v0.0.0.

Returns nil only when the constraint string contained no recognisable version literal. NewSemanticVersionConstraint refuses such constraints so consumers can treat a nil result as a programming error.

func (*SemanticVersionConstraint) Match added in v0.29.0 

func (s *SemanticVersionConstraint) Match(version interface{}) bool

type Service added in v0.22.9 

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

func NewService added in v0.22.9 

func NewService(
	registryService *registryservice.Service,
	workingDir string,
	options *Options,
	logger *dkplog.Logger,
	userLogger *log.SLogger,
) *Service

func (*Service) PullModules added in v0.22.9 

func (svc *Service) PullModules(ctx context.Context) error

PullModules pulls the Deckhouse modules It validates access to the registry and pulls the module images

type VersionConstraint added in v0.29.0 

type VersionConstraint interface {
	Match(version interface{}) bool
	IsExact() bool
	HasChannelAlias() bool
}

func ParseVersionConstraint added in v0.30.11 

func ParseVersionConstraint(v string) (VersionConstraint, error)

ParseVersionConstraint turns a user-supplied constraint string into a VersionConstraint. The syntax mirrors the `module-name@<constraint>` body accepted by --include-module so any consumer (modules filter, platform --include-platform, future call sites) speaks the same dialect:

  • "=v1.2.3" → exact tag (no channel propagation)
  • "=v1.2.3+stable" → exact tag pinned to the named release channel
  • ">=1.2.0 <=1.3.0" → semver range with inclusive anchors
  • "^1.2.0", "~1.2.0" → semver shorthand
  • "1.2.0" → implicit caret (^1.2.0), kept for backward compat

An empty or whitespace-only input is rejected so callers see a clear error instead of silently producing a no-op constraint.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.