Documentation
¶
Overview ¶
Package ossfunding resolves an OSS package (by PURL) to a payout target — where the money for that package should go. It is the "who do we pay?" half of the payout system, orthogonal to the "how much?" half (ossattr).
Resolution is best-effort and layered, cheapest/most-certain first:
- PURL structure: most Go/npm PURLs encode a GitHub (or GitLab) owner/repo in their name (pkg:golang/github.com/gin-gonic/gin -> github owner "gin-gonic"). That owner is a strong default target — GitHub Sponsors and a repo FUNDING.yml are keyed by owner/repo.
- FUNDING.yml lookup (network): fetch the repo's .github/FUNDING.yml to get the exact funding platforms the maintainer declared (github sponsors, open collective, ko-fi, custom). This is the authoritative target.
- Registry maintainers (network): for ecosystems without a VCS coordinate in the PURL (some npm/pypi), the package registry's maintainer record.
When nothing resolves, the result is Unresolved -> the accrual is HELD (its money waits in a held pool, never lost) until a later resolution pass.
This package's pure core (FromPURL) is offline and deterministic — it derives the candidate target from the PURL alone. The network enrichment (FUNDING.yml / registry) is behind the Resolver interface so the accrual path never blocks on I/O and tests run without a network.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type PURLResolver ¶
type PURLResolver struct{}
PURLResolver is the always-available offline resolver: it only uses FromPURL. It is the default the accrual engine uses inline (deterministic, no network), so accruals get a candidate target immediately; a richer network Resolver can run later over held lines.
func (PURLResolver) Resolve ¶
func (PURLResolver) Resolve(purl string) Target
type Resolver ¶
type Resolver interface {
// Resolve returns the best target for the PURL. It must never error fatally:
// on any failure it returns Unresolved so the amount is held, not dropped.
Resolve(purl string) Target
}
Resolver enriches a PURL-derived candidate with authoritative funding info (FUNDING.yml, registry maintainers). Implementations may perform network I/O and SHOULD be called OUT of the request hot path (e.g. a periodic resolution pass over held accruals), never blocking usage recording.
type Target ¶
type Target struct {
Kind Kind `json:"kind"`
// Handle is the rail-specific identifier:
// github_sponsors -> the sponsorable login (user/org), e.g. "gin-gonic"
// opencollective -> the collective slug
// kofi -> the ko-fi handle
// custom -> the full URL
Handle string `json:"handle"`
// Repo is the owner/repo the target was derived from, for audit.
Repo string `json:"repo,omitempty"`
// Source records how this was resolved: "purl" | "funding.yml" | "registry".
Source string `json:"source"`
}
Target is a resolved payout destination for a package.
func FromPURL ¶
FromPURL is the pure, offline resolver: it derives a candidate funding target from the PURL's embedded VCS coordinate. For PURLs whose name is a github.com/<owner>/<repo> path (the common case for Go modules, and many npm/others), it returns a GitHub Sponsors target for <owner> with Source "purl". When no VCS owner can be extracted it returns Unresolved.
Examples:
pkg:golang/github.com/gin-gonic/gin@v1.12.0 -> github_sponsors:gin-gonic pkg:golang/golang.org/x/sys@v0.20.0 -> github_sponsors:golang (x/* -> golang org) pkg:npm/react@18.3.1 -> unresolved (no VCS in PURL) pkg:golang/github.com/google/uuid@v1.6.0 -> github_sponsors:google
Source Files