core

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package core provides shared types and the registry system.

Index

Constants

This section is empty.

Variables

View Source 
var (
	DefaultClient  = client.DefaultClient
	NewClient      = client.NewClient
	WithTimeout    = client.WithTimeout
	WithMaxRetries = client.WithMaxRetries
	BuildURLs      = client.BuildURLs
)

Function aliases for backward compatibility.

View Source 
var ErrNotFound = client.ErrNotFound

ErrNotFound is returned when a package or version is not found.

Functions 

func AppendFundingLink(links []string, link string) []string

AppendFundingLink appends link to links after trimming whitespace, skipping empty values and links already present.

func BulkFetchLatestVersions 

func BulkFetchLatestVersions(ctx context.Context, purls []string, client *Client) map[string]*Version

BulkFetchLatestVersions fetches the latest version for multiple PURLs in parallel using the shared latest-release policy.

func BulkFetchLatestVersionsWithConcurrency 

func BulkFetchLatestVersionsWithConcurrency(ctx context.Context, purls []string, client *Client, concurrency int) map[string]*Version

BulkFetchLatestVersionsWithConcurrency fetches latest versions using the shared policy and a custom concurrency limit.

func BulkFetchPackages 

func BulkFetchPackages(ctx context.Context, purls []string, client *Client) map[string]*Package

BulkFetchPackages fetches package metadata for multiple PURLs in parallel. Individual fetch errors are silently ignored - those PURLs are omitted from results. Returns a map of PURL to Package.

func BulkFetchPackagesWithConcurrency 

func BulkFetchPackagesWithConcurrency(ctx context.Context, purls []string, client *Client, concurrency int) map[string]*Package

BulkFetchPackagesWithConcurrency fetches packages with a custom concurrency limit.

func BulkFetchVersions 

func BulkFetchVersions(ctx context.Context, purls []string, client *Client) map[string]*Version

BulkFetchVersions fetches version metadata for multiple versioned PURLs in parallel. PURLs without versions are silently skipped. Individual fetch errors are silently ignored - those PURLs are omitted from results. Returns a map of PURL to Version.

func BulkFetchVersionsWithConcurrency 

func BulkFetchVersionsWithConcurrency(ctx context.Context, purls []string, client *Client, concurrency int) map[string]*Version

BulkFetchVersionsWithConcurrency fetches versions with a custom concurrency limit.

func DefaultURL 

func DefaultURL(ecosystem string) string

DefaultURL returns the default registry URL for an ecosystem.

func ExtractLicense 

func ExtractLicense(v interface{}) string

ExtractLicense extracts a license string from various API response formats and normalizes it via SPDX. Handles:

  • Plain string: "MIT"
  • Map with type key: {"type": "MIT", "url": "..."}
  • Array of strings or maps: ["MIT", "Apache-2.0"]

func ExtractLicenseFromClassifiers 

func ExtractLicenseFromClassifiers(classifiers []string) string

ExtractLicenseFromClassifiers extracts a license from Python classifiers. Looks for "License :: OSI Approved :: MIT License" style classifiers.

func ExtractLicenseRaw 

func ExtractLicenseRaw(v interface{}) string

ExtractLicenseRaw extracts a license without SPDX normalization.

func ExtractRepoURL 

func ExtractRepoURL(v interface{}) string

ExtractRepoURL extracts a repository URL from various API response formats. Handles:

  • Plain string: "https://github.com/user/repo"
  • Map with url/git/http key: {"url": "...", "type": "git"}
  • Array of strings or maps: tries first valid entry

func ExtractRepoURLWithFallback 

func ExtractRepoURLWithFallback(values ...interface{}) string

ExtractRepoURLWithFallback tries multiple values and returns the first valid repo URL.

func FundingLinksFromLabels added in v0.11.0 

func FundingLinksFromLabels(links map[string]string) []string

FundingLinksFromLabels returns the URLs in links whose labels name a funding page. The result is sorted and deduplicated so output is stable across map iteration order. It returns nil when no labels match.

func IsFundingLabel added in v0.11.0 

func IsFundingLabel(label string) bool

IsFundingLabel reports whether a link label from registry metadata names a funding page, such as PyPI project_urls or Hex package links.

func NormalizeLicense 

func NormalizeLicense(license string) string

NormalizeLicense normalizes a license string via SPDX.

func ParallelMap 

func ParallelMap[K comparable, V any](
	ctx context.Context,
	inputs []K,
	concurrency int,
	fn func(ctx context.Context, input K) (*V, error),
) map[K]*V

ParallelMap executes fn for each input in parallel with bounded concurrency. Results are collected into a map keyed by the input. If fn returns an error or nil result, that input is omitted from the results.

func Register 

func Register(ecosystem string, defaultURL string, factory Factory)

Register adds a registry factory to the global registry. ecosystem is the PURL type (e.g., "cargo", "npm", "gem", "pypi", "golang"). defaultURL is the default registry URL for the ecosystem.

func SupportedEcosystems 

func SupportedEcosystems() []string

SupportedEcosystems returns all registered ecosystem types.

Types

type Artifact 

type Artifact struct {
	URL       string
	Filename  string
	Integrity string
	Size      int64 // Zero when the registry does not publish a size.
	MediaType string
	Metadata  map[string]any
}

Artifact describes one file published for a package version.

type BaseURLs 

type BaseURLs = client.BaseURLs

Type aliases for backward compatibility with ecosystem implementations.

type Client 

type Client = client.Client

Type aliases for backward compatibility with ecosystem implementations.

type Dependency 

type Dependency struct {
	Name         string
	Requirements string
	Scope        Scope
	Optional     bool
}

Dependency represents a package dependency.

func FetchDependenciesFromPURL 

func FetchDependenciesFromPURL(ctx context.Context, purlStr string, client *Client) ([]Dependency, error)

FetchDependenciesFromPURL fetches dependencies for a specific version using a PURL. Returns an error if the PURL doesn't include a version.

type Factory 

type Factory func(baseURL string, client *Client) Registry

Factory creates a registry instance for a given base URL.

type HTTPError 

type HTTPError = client.HTTPError

Type aliases for backward compatibility.

type Maintainer 

type Maintainer struct {
	UUID  string
	Login string
	Name  string
	Email string
	URL   string
	Role  string
}

Maintainer represents a package maintainer.

func FetchMaintainersFromPURL 

func FetchMaintainersFromPURL(ctx context.Context, purlStr string, client *Client) ([]Maintainer, error)

FetchMaintainersFromPURL fetches maintainer information using a PURL.

type NotFoundError 

type NotFoundError = client.NotFoundError

Type aliases for backward compatibility.

type Option 

type Option = client.Option

Type aliases for backward compatibility with ecosystem implementations.

type Package 

type Package struct {
	Name          string
	Description   string
	Homepage      string
	Repository    string
	Licenses      string
	Keywords      []string
	Namespace     string         // @scope for npm, groupId for maven
	LatestVersion string         // latest version if returned by registry
	Metadata      map[string]any // registry-specific data

	// Maintainers is populated when the package endpoint already returns
	// maintainer data. It is nil otherwise; use FetchMaintainers instead.
	Maintainers []Maintainer

	// FundingLinks lists funding or sponsorship URLs declared for the
	// package. It is nil when the registry exposes none.
	FundingLinks []string
}

Package represents metadata about a package from a registry.

func FetchPackageFromPURL 

func FetchPackageFromPURL(ctx context.Context, purlStr string, client *Client) (*Package, error)

FetchPackageFromPURL fetches package metadata using a PURL.

type RateLimitError 

type RateLimitError = client.RateLimitError

Type aliases for backward compatibility.

type RateLimiter 

type RateLimiter = client.RateLimiter

Type aliases for backward compatibility with ecosystem implementations.

type Registry 

type Registry interface {
	// Ecosystem returns the PURL type for this registry (e.g., "cargo", "npm", "gem").
	Ecosystem() string

	// FetchPackage retrieves package metadata.
	FetchPackage(ctx context.Context, name string) (*Package, error)

	// FetchVersions retrieves all versions of a package.
	FetchVersions(ctx context.Context, name string) ([]Version, error)

	// FetchDependencies retrieves dependencies for a specific version.
	FetchDependencies(ctx context.Context, name, version string) ([]Dependency, error)

	// FetchMaintainers retrieves maintainer information.
	FetchMaintainers(ctx context.Context, name string) ([]Maintainer, error)

	// URLs returns the URL builder for this registry.
	URLs() URLBuilder
}

Registry is the interface implemented by all ecosystem registry clients.

func New 

func New(ecosystem string, baseURL string, client *Client) (Registry, error)

New creates a new registry for the given ecosystem. If baseURL is empty, the default registry URL is used.

func NewFromPURL 

func NewFromPURL(purlStr string, client *Client) (Registry, string, string, error)

NewFromPURL creates a registry client from a PURL and returns the parsed components. Returns the registry, full package name, and version (empty if not in PURL). If the PURL has a repository_url qualifier, it's used as the base URL for private registries.

type Scope 

type Scope string

Scope indicates when a dependency is required. Aligns with github.com/git-pkgs/manifests core.Scope. 

const (
	Runtime     Scope = "runtime"
	Development Scope = "development"
	Test        Scope = "test"
	Build       Scope = "build"
	Optional    Scope = "optional"
)

type URLBuilder 

type URLBuilder = client.URLBuilder

Type aliases for backward compatibility with ecosystem implementations.

type Version 

type Version struct {
	Number      string
	PublishedAt time.Time
	Licenses    string
	Integrity   string        // sha256-..., sha512-...
	Status      VersionStatus // "", "yanked", "deprecated", "retracted"
	Artifacts   []Artifact
	Metadata    map[string]any
}

Version represents a specific version of a package.

func FetchLatestVersion 

func FetchLatestVersion(ctx context.Context, reg Registry, name string) (*Version, error)

FetchLatestVersion returns the registry-advertised latest version when one is available. Otherwise it selects the latest active version by publication time, falling back to ecosystem version ordering when timestamps are absent. It returns nil when the registry reports no active versions. If fetching versions fails after an advertised version is found, it returns that version without metadata and suppresses the versions error.

func FetchLatestVersionFromPURL 

func FetchLatestVersionFromPURL(ctx context.Context, purl string, client *Client) (*Version, error)

FetchLatestVersionFromPURL returns the latest version for a PURL using the shared latest-release policy.

func FetchVersionFromPURL 

func FetchVersionFromPURL(ctx context.Context, purlStr string, client *Client) (*Version, error)

FetchVersionFromPURL fetches a specific version's metadata using a PURL. Returns an error if the PURL doesn't include a version.

func SelectLatestVersion 

func SelectLatestVersion(versions []Version, ecosystem, advertised string) *Version

SelectLatestVersion applies the shared latest-release policy to versions. An advertised version takes precedence, including when it is a prerelease or has a non-empty status. Without one, versions with a non-empty status are excluded and the newest publication time wins. Ecosystem version ordering breaks timestamp ties and is used when every active version lacks a timestamp. Prereleases remain eligible in that fallback. The input slice is not modified.

type VersionStatus 

type VersionStatus string

VersionStatus represents the status of a package version. 

const (
	StatusNone       VersionStatus = ""
	StatusYanked     VersionStatus = "yanked"
	StatusDeprecated VersionStatus = "deprecated"
	StatusRetracted  VersionStatus = "retracted"
)

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.