provider

package
v0.1.4 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package provider defines the Provider interface, the compiled-in registry (init self-registration), and optional capabilities (Anchorer, Digester, Linker, Committer, BranchChecker, Authenticator).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Deep 

func Deep(ctx context.Context) bool

Deep reports whether a deep lookup was requested for this run. The default is shallow (first page only), which suffices for recency-ordered sources and keeps a run fast and within rate limits.

func DiscoverOCITags added in v0.1.0 

func DiscoverOCITags(
	ctx context.Context,
	client *oci.Client,
	repo oci.Repo,
	describe, url string,
) ([]model.Candidate, error)

DiscoverOCITags lists an OCI repository's tags as candidates via the shared registry client, honoring a deep lookup and noting truncation when a shallow lookup left a further page unread so the edge can suggest --deep. Registry tag lists carry no timestamps, so cooldown does not apply to these candidates.

func KeyNames added in v0.1.0 

func KeyNames(p Provider) []string

KeyNames returns the names of the directive keys a provider accepts, in its canonical order.

func Names 

func Names() []string

Names returns the registered provider names, sorted for stable output.

func NoteTruncated 

func NoteTruncated(ctx context.Context, resource, url string)

NoteTruncated reports that resource's shallow lookup was incomplete, invoking the sink set by WithTruncationSink if any with the resource's label and its upstream web page. It is a no-op otherwise, so a provider can call it unconditionally.

func Qualifier added in v0.1.1 

func Qualifier(ctx context.Context) string

Qualifier returns the qualifier hint for this lookup, "" when selection is not pinned to one and discovery must stay unfiltered.

func Register 

func Register(p Provider)

Register adds p under its name. A duplicate name overwrites, which only happens if two providers claim the same name.

func RegisterAll 

func RegisterAll(providers ...Provider)

RegisterAll adds each provider under its name. The composition root calls it once at startup with the built-in providers, so registration is explicit rather than hidden in package init functions.

func StatusError added in v0.1.0 

func StatusError(action string, resp *http.Response) error

StatusError formats a failed HTTP response as "<action>: <body> (<status>)", reading the body for the upstream's own message.

func TagPrefix added in v0.1.1 

func TagPrefix(ctx context.Context) string

TagPrefix returns the tag-prefix hint for this lookup, "" when the marker has none and discovery must stay unfiltered.

func VersionFloor added in v0.1.1 

func VersionFloor(ctx context.Context) string

VersionFloor returns the version floor for this lookup, "" when selection may reach below the current version and pagination must run to exhaustion.

func WithDeep 

func WithDeep(ctx context.Context, deep bool) context.Context

WithDeep returns a context that asks providers to perform a deep lookup - following pagination to exhaustion rather than reading only the first page. It is a run-scoped flag the CLI sets from --deep and providers read in Discover, so the lookup depth need not widen the Provider interface.

func WithQualifier added in v0.1.1 

func WithQualifier(ctx context.Context, qualifier string) context.Context

WithQualifier returns a context carrying the located tag's qualifier (e.g. "alpine3.22" for a line on 1.27-alpine3.22). The pipeline sets it only when selection is pinned to that exact qualifier, so a provider may narrow discovery to tags containing it - a strict superset of what selection can accept - and skip pages that could never be selected.

func WithTagPrefix added in v0.1.1 

func WithTagPrefix(ctx context.Context, prefix string) context.Context

WithTagPrefix returns a context carrying the marker's tag-prefix (e.g. "api/" for a monorepo component). Selection cannot accept a tag without the prefix, so a provider may narrow discovery to tags containing it - a strict superset of what selection can accept - and skip tags that could never be selected.

func WithTruncationSink 

func WithTruncationSink(ctx context.Context, sink func(Truncation)) context.Context

WithTruncationSink returns a context carrying a callback a provider invokes (via NoteTruncated) when a shallow lookup stopped with more results still available - so the edge can suggest --deep without the provider depending on a logger. The sink may be called from multiple goroutines, so it must be safe for concurrent use. A nil sink disables the notification.

func WithVersionFloor added in v0.1.1 

func WithVersionFloor(ctx context.Context, floor string) context.Context

WithVersionFloor returns a context carrying the marker's current version. The pipeline sets it only when selection cannot pick anything below that version (downgrades off), so a provider whose listing is version-ordered may stop paging once it passes the floor - every later page holds only versions that could never be selected.

Types

type Anchorer 

type Anchorer interface {
	// Anchor marks the provider as line-anchored; the method body is empty, its
	// presence is the signal.
	Anchor()
}

Anchorer is an optional capability for a provider whose resolved value is the value already on the target line, not one discovered upstream. clover skips discovery and selection for an anchored provider, publishing the located value under the marker's id so followers and side values stay in step, and leaves the line itself untouched. The manual provider uses it to declare a human-owned root.

type Authenticator 

type Authenticator interface {
	// Authenticate loads and verifies credentials, without blocking on a prompt.
	Authenticate(ctx context.Context) error
	// AuthHint returns an actionable message describing how to authenticate when
	// Authenticate fails.
	AuthHint() string
}

Authenticator is an optional capability for providers that need credentials. clover type-asserts for it during the authenticate phase; a provider without it is treated as needing no authentication.

type Branch 

type Branch struct {
	Name string
	Tip  string
}

Branch is a repository branch: its name and the commit at its tip.

type BranchChecker 

type BranchChecker interface {
	DefaultBranch(ctx context.Context, r Resource) (string, error)
	Branches(ctx context.Context, r Resource) ([]Branch, error)
	Reachable(ctx context.Context, r Resource, branch, commit string) (bool, error)
}

BranchChecker is an optional capability for verifying a commit's branch provenance under --verify: resolving the default branch, listing branches to match an allowed-branch pattern, and testing whether a commit is reachable from a branch. It guards against a tag that points at an off-trunk commit.

type Committer 

type Committer interface {
	Commit(ctx context.Context, r Resource, tag string) (string, error)
}

Committer is an optional capability for providers that can resolve a specific tag's commit SHA - the peeled commit for an annotated tag. clover uses it under --verify to deep-check an action pin against the tag it claims, including tags off the discovered page or about to be bumped.

type Digester 

type Digester interface {
	Digest(ctx context.Context, r Resource, tag string) (string, error)
}

Digester is an optional capability for providers that can resolve a version's content digest (e.g. an OCI image's manifest digest), for secure-pin rewriting. clover resolves it only for the chosen candidate of a digest-pinned marker.

type Key 

type Key struct {
	Name     string
	Required bool
}

Key is one directive key a provider accepts. Keys are returned in the provider's canonical order and drive both validation (required keys) and the middle zone of the directive's canonical key ordering in format mode.

type Linker 

type Linker interface {
	URL(r Resource, c model.Candidate) string
}

Linker is an optional capability for providers that can build a web URL for a resolved candidate (e.g. a GitHub release/tag page). clover hyperlinks the reported version when the provider implements it; absent, the value logs as plain text. An empty return means no meaningful URL, so the value is not linked.

type Provider 

type Provider interface {
	// Name is the provider's identifier, as written in a directive's provider=.
	Name() string
	// Keys reports the directive keys the provider accepts, in canonical order.
	Keys() []Key
	// Resource builds and validates the provider's descriptor from a directive,
	// erroring on missing required keys.
	Resource(d directive.Directive) (Resource, error)
	// Describe returns a human-readable label for a resource.
	Describe(r Resource) string
	// Discover lists the candidate versions for a resource.
	Discover(ctx context.Context, r Resource) ([]model.Candidate, error)
}

Provider adapts one upstream source of versions. Resource validates a directive into a descriptor once; Discover is the single network method, returning rich candidates with whatever metadata the API gave for free.

func Get 

func Get(name string) (Provider, bool)

Get returns the registered provider with the given name.

type RecencyOrderer 

type RecencyOrderer interface {
	// RecencyOrdered marks the provider's listing as newest-first; the method body
	// is empty, its presence is the signal.
	RecencyOrdered()
}

RecencyOrderer is an optional capability marking a provider whose Discover lists candidates newest-first, so a shallow lookup always holds the latest version. clover then suppresses the blanket truncation hint - the newest is never missed - and instead suggests --deep only when a constrained marker resolves to no candidate while more pages remained. A lexically ordered source (an OCI tags list) does not implement it, keeping the blanket hint that a newer version may sit on an unread page.

type Resource 

type Resource any

Resource is a provider-specific, validated descriptor built from a directive. Each provider creates and consumes its own concrete type; to the rest of clover it is opaque, so a single registry can hold heterogeneous providers.

type Truncation 

type Truncation struct {
	Resource string // short label shown in the hint
	URL      string // upstream web page the label links to
}

Truncation identifies a resource whose shallow lookup was incomplete, paired with the upstream web page a --deep hint can link to.

Source Files

View all Source files

Directories

Path Synopsis
Package all is the composition helper that constructs every built-in provider.
 Package all is the composition helper that constructs every built-in provider.
Package docker resolves container image versions from a registry's tags, using Docker Hub's API for hub.docker.com and the OCI registry v2 bearer-token challenge elsewhere, piggybacking on the user's existing docker login for credentials.
 Package docker resolves container image versions from a registry's tags, using Docker Hub's API for hub.docker.com and the OCI registry v2 bearer-token challenge elsewhere, piggybacking on the user's existing docker login for credentials.
Package follow implements the follow provider: reuses another marker's resolved Candidate (via from=) from the registry and renders a value (version/commit/sha256).
 Package follow implements the follow provider: reuses another marker's resolved Candidate (via from=) from the registry and renders a value (version/commit/sha256).
Package gitea resolves versions from a Gitea or Forgejo forge's tags and releases.
 Package gitea resolves versions from a Gitea or Forgejo forge's tags and releases.
Package github resolves versions from GitHub releases/tags, enriches candidates with commit SHAs, and sources checksums via an ordered chain.
 Package github resolves versions from GitHub releases/tags, enriches candidates with commit SHAs, and sources checksums via an ordered chain.
Package gitlab resolves versions from a GitLab project's tags or releases, enriching candidates with the commit SHA the REST API returns for free.
 Package gitlab resolves versions from a GitLab project's tags or releases, enriching candidates with the commit SHA the REST API returns for free.
Package hashicorp resolves HashiCorp tool versions (Terraform, Vault, Consul, Nomad, Packer, Boundary, Sentinel, ...) from HashiCorp's public, unauthenticated releases API.
 Package hashicorp resolves HashiCorp tool versions (Terraform, Vault, Consul, Nomad, Packer, Boundary, Sentinel, ...) from HashiCorp's public, unauthenticated releases API.
Package helm resolves Helm chart versions from both classic HTTP chart repositories (an index.yaml served under the repo URL) and OCI registries (oci://, where a chart's versions are the repository's tags).
 Package helm resolves Helm chart versions from both classic HTTP chart repositories (an index.yaml served under the repo URL) and OCI registries (oci://, where a chart's versions are the repository's tags).
Package http resolves versions from an arbitrary HTTP endpoint, the escape hatch for any source clover has no bespoke provider for.
 Package http resolves versions from an arbitrary HTTP endpoint, the escape hatch for any source clover has no bespoke provider for.
Package manual implements a human-owned root provider.
 Package manual implements a human-owned root provider.
Package node resolves Node.js runtime versions from nodejs.org's public, unauthenticated release index.
 Package node resolves Node.js runtime versions from nodejs.org's public, unauthenticated release index.

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.