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 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 ¶
- Variables
- func Base(value string) string
- func Build(p PURL) (string, error)
- func Canonical(existing string, p PURL) string
- func CanonicalEcosystem(values ...string) (ecosystem string, ok bool)
- func Canonicalize(value string) string
- func EcosystemForType(purlType string) (ecosystem string, ok bool)
- func EvidenceQualifierKeys() []string
- func IdentityForm(value string) string
- func IsEvidenceQualifierKey(key string) bool
- func SplitEcosystemName(ecosystem, ecosystemName string) (org, name string)
- func TypeForValues(values ...string) string
- func Validate(p PURL) error
- func ValidateString(value string) error
- func WithoutVersion(value string) string
- type IdentitySplit
- type PURL
- type Qualifier
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Canonicalize normalizes a package URL string, returning "" when the value does not parse. Signature-compatible with the root CanonicalizePackageURL.
func EcosystemForType ¶
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
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
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 ¶
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 ¶
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
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
ValidateString parses and profile-validates an untrusted package URL string in one step.
func WithoutVersion ¶ added in v0.6.0
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.