purlkit

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2026 License: Apache-2.0 Imports: 7 Imported by: 4

Documentation

Overview

Package purlkit is the single home for package-URL behavior in the Bomly SDK (ADR-0038 in bomly-cli's dev-docs/adr). It owns parsing, building, and canonicalizing PURLs — including qualifiers and subpath, which the legacy root helpers cannot represent — the one purl-type mapping table, and the per-ecosystem split of an ecosystem-native name back into org and name.

purlkit is a leaf package: it imports the packageurl library, the PEP 440 version library that owns PyPI's canonical version form, and the standard library only, never the root SDK package, so the root package can delegate to it without an import cycle. Its APIs are therefore string-typed; the typed wrappers live in the root package.

PURL strings are untrusted input (they arrive from lockfiles, SBOM documents, and registry APIs). Every entry point validates and returns errors or zero values; nothing here panics on malformed input.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidPURL = errors.New("invalid package URL")

ErrInvalidPURL reports a package URL that cannot be built or parsed. Every failure from Parse, Build, and their derivatives matches it with errors.Is, including failures surfaced by the underlying parser.

Functions

func Base

func Base(value string) string

Base strips version, qualifiers, and subpath, keeping the package identity (type, namespace, name). It works structurally on the parsed form — replacing the legacy string surgery that cut at the first '?' and the last '@', which mishandled subpath-carrying and version-less package URLs.

func Build

func Build(p PURL) (string, error)

Build normalizes the parts and renders the canonical string form. Type and name are required; qualifiers and subpath are preserved, which the legacy root builder cannot do. The output is a Parse fixed point.

func Canonical

func Canonical(existing string, p PURL) string

Canonical returns the canonical package URL for a package: the existing string wins when it canonicalizes, otherwise the parts are built — qualifier- and subpath-capable, closing the gap where the legacy fallback chain dropped both. This is the primitive the dependency-level identity rewrite (ADR-0036) wraps.

func CanonicalEcosystem

func CanonicalEcosystem(values ...string) (ecosystem string, ok bool)

CanonicalEcosystem folds the first recognizable value to its canonical Bomly ecosystem token, checking values in the order given (pass ecosystem, then package manager, then package type, so the most authoritative value wins). It returns ok=false when no value is recognized — including for "hex", whose refusal is deliberate.

func Canonicalize

func Canonicalize(value string) string

Canonicalize normalizes a package URL string, returning "" when the value does not parse. Signature-compatible with the root CanonicalizePackageURL.

func EcosystemForType

func EcosystemForType(purlType string) (ecosystem string, ok bool)

EcosystemForType returns the Bomly ecosystem token for a purl type whose spec name differs from the ecosystem token, and refuses ambiguous types. EcosystemForType("hex") returns ("", false) by decision, not omission — see the table comment. Callers that also accept identity mappings (purl types that are themselves Bomly ecosystem tokens, such as "npm") layer their own ecosystem parsing over this table; the kit stays string-typed and does not duplicate the ecosystem vocabulary.

func EvidenceQualifierKeys added in v0.6.0

func EvidenceQualifierKeys() []string

EvidenceQualifierKeys returns the specification's universal URL-valued evidence qualifier keys, sorted. The slice is a copy.

func IdentityForm added in v0.6.0

func IdentityForm(value string) string

IdentityForm renders the identity form of a package URL string: the canonical rendering with the universal evidence qualifiers removed and every other qualifier and the subpath preserved. It returns "" when the value does not parse.

func IsEvidenceQualifierKey added in v0.6.0

func IsEvidenceQualifierKey(key string) bool

IsEvidenceQualifierKey reports whether the key is one of the universal URL-valued evidence qualifier keys. Keys compare case-insensitively, as the specification lowercases qualifier keys.

func SplitEcosystemName

func SplitEcosystemName(ecosystem, ecosystemName string) (org, name string)

SplitEcosystemName splits an ecosystem-native package name back into its org and name halves — the inverse of the root Coordinates.EcosystemName join, under the same per-ecosystem rules (bomly-cli ADR-0021): joining is opt-in per ecosystem, so only ecosystems whose advisory databases key on the namespaced form split at all.

The ecosystem argument accepts canonical tokens and their aliases (it is resolved through CanonicalEcosystem). For every ecosystem outside the join list the whole input is the name and org is empty — for OS packages the org is a distro, not part of the package name, and splitting would corrupt identity. A name that does not carry the ecosystem's join shape (an npm name without a scope, a Maven name without a colon) is likewise returned whole: absence of a namespace is data, not an error.

func TypeForValues

func TypeForValues(values ...string) string

TypeForValues maps ecosystem / package-manager / package-type tokens to a package-url type. It is the one authority for this mapping (ADR-0038); the root PackageURLTypeForValues delegates here after converting its typed arguments to strings.

The explicit switch below is consulted for every value before the loose fallback runs, so the most specific mapping wins regardless of the order the caller passes ecosystem / package manager / package type in. The fallback then returns the first non-empty value verbatim, which is only correct where the Bomly identifier happens to be the purl type as well (npm, maven, apk, rpm, ...). Any ecosystem whose purl type differs from its Bomly name needs an explicit case here — without one we emit a type that is not in the purl spec, and consumers keyed on the type (OSV, SBOM ingest) silently fail to match. See bomly-cli issue #317.

Ecosystems that span more than one registry are the exception: erlang covers both Hex (rebar) and OTP (*.app), so it is mapped at the package-manager level only. A bare erlang value with no manager to disambiguate keeps the non-spec pkg:erlang rather than guessing a registry the package may not be published to.

func Validate added in v0.6.0

func Validate(p PURL) error

Validate reports whether the package URL satisfies its type's specification profile on top of the library's own syntactic and structural rules. The library remains the first gate — the parts must build and render canonically — and the profile table adds only the spec-stated requirements the library skips (a Maven group ID as the namespace, for example). A type with no profile and no library rule passes on syntax alone: custom purl types are first-class.

func ValidateString added in v0.6.0

func ValidateString(value string) error

ValidateString parses and profile-validates an untrusted package URL string in one step.

func WithoutVersion added in v0.6.0

func WithoutVersion(value string) string

WithoutVersion strips the version from a package URL, keeping qualifiers and subpath — the grouping key for version-change detection, where two architectures of one package must not read as a version pair. Returns "" when the value does not parse.

Types

type IdentitySplit added in v0.6.0

type IdentitySplit struct {
	// Identity is the canonical package URL with only identity qualifiers —
	// everything except the universal evidence keys.
	Identity PURL
	// Evidence holds the relocated URL-valued evidence qualifiers, in
	// canonical qualifier order. Consumers pass their values through the
	// origin constructors; the raw values never reach a published ID.
	Evidence []Qualifier
}

IdentitySplit partitions a package URL's qualifiers into the identity half and the evidence half.

func SplitIdentity added in v0.6.0

func SplitIdentity(p PURL) IdentitySplit

SplitIdentity partitions the qualifiers of a parsed package URL: the universal evidence keys move to Evidence, and everything else — spec-known and custom alike — stays on the identity, matching the specification's open qualifier vocabulary.

type PURL

type PURL struct {
	Type       string
	Namespace  string
	Name       string
	Version    string
	Qualifiers []Qualifier
	Subpath    string
}

PURL is the structured form of a package URL. Unlike the legacy root builder it carries qualifiers and subpath, so identities such as pkg:maven/g/a@1?type=jar and pkg:golang/m@v1#sub are representable.

func Parse

func Parse(value string) (PURL, error)

Parse parses and validates an untrusted package URL string. The returned value is canonical: qualifier keys are lowercased and sorted, type-specific case rules are applied, and rendering it with String and parsing it again yields the same value. Parse never panics.

func (PURL) String

func (p PURL) String() string

String renders the canonical string form, or "" when the value does not normalize. Use Build when the failure reason matters.

type Qualifier

type Qualifier struct {
	Key   string
	Value string
}

Qualifier is one key/value qualifier of a package URL. Keys are lowercase in canonical form; qualifier lists are sorted by key.

Jump to

Keyboard shortcuts

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