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 SplitEcosystemName(ecosystem, ecosystemName string) (org, name string)
- func TypeForValues(values ...string) string
- 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 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.
Types ¶
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.