release

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package release implements the unpacker that decomposes software releases. A release is understood as a build from a commit that publishes a number of software artifacts on a hosting system (a "forge") such as GitHub or GitLab.

Index

Constants

View Source 
const (
	ForgeGitHub = "github"
	ForgeGitLab = "gitlab"
)

Identifiers of the forge types with builtin support.

View Source 
const SubjectType = "release"

SubjectType is the DecomposableSubject type routed to the release unpacker.

Variables

This section is empty.

Functions

This section is empty.

Types

type Artifact 

type Artifact struct {
	// Name is the file name of the artifact.
	Name string

	// DownloadURL is the URL the artifact can be retrieved from.
	DownloadURL string

	// Size is the size of the artifact in bytes (0 when not reported).
	Size int64

	// ContentType is the media type the forge reports for the artifact.
	ContentType string

	// Digests are the hex-encoded hashes the forge reports for the artifact,
	// keyed by algorithm.
	Digests map[sbom.HashAlgorithm]string
}

Artifact captures the data the forge reports about one of the artifacts published in a release.

type Backend 

type Backend interface {
	// FetchReleaseMetadata retrieves from the forge the metadata of the
	// release the reference points to.
	FetchReleaseMetadata(ctx context.Context, ref *Reference) (*Metadata, error)

	// FetchArtifactData gathers the data of the artifacts published in the
	// release that md describes.
	FetchArtifactData(ctx context.Context, ref *Reference, md *Metadata) ([]*Artifact, error)
}

Backend abstracts a release hosting system (a "forge") such as GitHub or GitLab. The release decomposer drives a backend in two steps: fetch the release metadata, then gather the data of the artifacts published in it.

Implementations must be safe for concurrent use and keep no state between calls: anything FetchArtifactData needs from the metadata fetch travels in the Metadata struct (see Metadata.BackendData).

type Decomposer 

type Decomposer struct {
	// contains filtered or unexported fields
}

Decomposer renders a software release into a protobom NodeList. It drives the Backend registered for the reference's forge type to fetch the release metadata and the data of the published artifacts, then expresses them as a graph: one package node for the release with one file node per artifact.

func NewDecomposer 

func NewDecomposer() *Decomposer

NewDecomposer returns a release decomposer with the builtin forge backends preregistered. Additional (or replacement) backends can be plugged in with RegisterBackend.

func (*Decomposer) DefaultOptions 

func (d *Decomposer) DefaultOptions() any

DefaultOptions returns the driver-level options used when none are set on DecomposerOptions.

func (*Decomposer) Extract 

func (d *Decomposer) Extract(opts *api.DecomposerOptions) (*sbom.NodeList, error)

Extract satisfies api.Decomposer by reading the release reference from the driver options and delegating to ExtractRelease. Callers that have a context should call ExtractRelease directly.

func (*Decomposer) ExtractRelease 

func (d *Decomposer) ExtractRelease(ctx context.Context, ref *Reference, _ *api.DecomposerOptions) (*sbom.NodeList, error)

ExtractRelease fetches the release the reference points to through the backend registered for its forge type and returns it as a NodeList.

func (*Decomposer) RegisterBackend 

func (d *Decomposer) RegisterBackend(forge string, b Backend)

RegisterBackend registers the backend that handles the given forge type. Registering a second backend for the same forge replaces the previous one.

func (*Decomposer) Requirements 

func (d *Decomposer) Requirements(opts *api.DecomposerOptions) []api.Requirement

Requirements returns the decomposer's runtime requirements. Talking to a forge always needs the network, so when the options carry a release reference this returns a requirement to reach the forge host over https.

type GitHubBackend 

type GitHubBackend struct {
	// contains filtered or unexported fields
}

GitHubBackend implements the release Backend on top of the GitHub REST API. It works against the public github.com instance and against GitHub Enterprise hosts, authenticating with the GITHUB_TOKEN environment variable when it is set.

func NewGitHubBackend 

func NewGitHubBackend() *GitHubBackend

NewGitHubBackend creates a new GitHub release backend.

func (*GitHubBackend) FetchArtifactData 

func (b *GitHubBackend) FetchArtifactData(ctx context.Context, ref *Reference, md *Metadata) ([]*Artifact, error)

FetchArtifactData gathers the data of the artifacts published in the release that md describes. The asset list stashed in the metadata by FetchReleaseMetadata is reused when present, avoiding a second API call.

func (*GitHubBackend) FetchReleaseMetadata 

func (b *GitHubBackend) FetchReleaseMetadata(ctx context.Context, ref *Reference) (*Metadata, error)

FetchReleaseMetadata retrieves from the GitHub API the metadata of the release the reference points to, resolving the commit the release tag points to and the repository license along the way.

type GitLabBackend 

type GitLabBackend struct {
	// contains filtered or unexported fields
}

GitLabBackend implements the release Backend on top of the GitLab REST API (v4). It works against gitlab.com and self-managed instances, authenticating with the GITLAB_TOKEN environment variable when it is set.

GitLab reports no digests, sizes or media types for release asset links, so the artifacts read through this backend carry their name and download location only. The autogenerated source archives are not considered release artifacts and are ignored.

func NewGitLabBackend 

func NewGitLabBackend() *GitLabBackend

NewGitLabBackend creates a new GitLab release backend.

func (*GitLabBackend) FetchArtifactData 

func (b *GitLabBackend) FetchArtifactData(ctx context.Context, ref *Reference, md *Metadata) ([]*Artifact, error)

FetchArtifactData gathers the data of the asset links published in the release that md describes. The link list stashed in the metadata by FetchReleaseMetadata is reused when present, avoiding a second API call.

func (*GitLabBackend) FetchReleaseMetadata 

func (b *GitLabBackend) FetchReleaseMetadata(ctx context.Context, ref *Reference) (*Metadata, error)

FetchReleaseMetadata retrieves from the GitLab API the metadata of the release the reference points to. The commit the release was cut from comes embedded in the release payload, so resolving it needs no extra calls.

type Metadata 

type Metadata struct {
	// Name is the human title of the release (may match the tag).
	Name string

	// Tag is the tag the release was cut from, doubling as its version.
	Tag string

	// URL points to the human-readable release page.
	URL string

	// Commit is the hex-encoded SHA-1 digest of the commit the release was
	// built from.
	Commit string

	// License is the SPDX identifier of the repository license, when the
	// forge reports one.
	License string

	// RepoURL is the https URL of the repository the release lives in.
	RepoURL string

	// Published is the timestamp the release was published at.
	Published *time.Time

	// BackendData is a private stash for the backend that produced the
	// metadata, letting FetchArtifactData reuse anything already retrieved
	// (e.g. the artifact list embedded in the release API response).
	BackendData any
}

Metadata is the forge-neutral description of a software release. Backends fill it from their forge's API and the decomposer renders it into the root node of the release graph.

type Options 

type Options struct {
	// Reference points at the release to decompose.
	Reference *Reference
}

Options is the driver-level options set of the release decomposer, carried in the DecomposerOptions driver options bag.

type Reference 

type Reference struct {
	// Forge identifies the hosting system type, e.g. "github" or "gitlab".
	Forge string

	// Host is the hostname of the forge instance, e.g. "github.com" or the
	// domain of a self-managed instance.
	Host string

	// Repo is the repository path in the forge, e.g. "org/repo". GitLab
	// paths may nest subgroups ("group/subgroup/project").
	Repo string

	// Tag is the tag the release was cut from. Empty means the repository's
	// latest release.
	Tag string
}

Reference is the DecomposableSubject consumed by the release unpacker. It locates one release through three coordinates: the forge type that knows how to talk to the hosting system, the host of the (possibly self-managed) instance, and the repository the release was published in. An empty Tag points the reference at the repository's latest release.

func ParseReference 

func ParseReference(s string) (*Reference, error)

ParseReference parses a string into a release Reference. Three forms are understood:

  • Canonical: "github+https://github.com/org/repo@v1.0.0". The forge type, the instance URL and the repository path are all explicit.
  • Shorthand: "github:org/repo@v1.0.0". The host defaults to the forge's public instance; name other instances explicitly, as in "github:ghe.example.com/org/repo@v1.0.0". The first path segment is taken as a host when it contains a dot and at least two more segments follow (dotted GitLab namespaces holding nested subgroups need the canonical form).
  • Release page URL: "https://github.com/org/repo/releases/tag/v1.0.0". The forge type is inferred from the well-known public hosts.

In all forms, omitting "@tag" points the reference at the repository's latest release.

func (*Reference) DecomposableType 

func (r *Reference) DecomposableType() string

DecomposableType identifies this subject as a software release, routing it to the release unpacker through the registry.

func (*Reference) RepoURL 

func (r *Reference) RepoURL() string

RepoURL returns the https URL of the repository the release lives in.

func (*Reference) String 

func (r *Reference) String() string

String returns the canonical string form of the reference: 

forge+https://host/repo[@tag]

func (*Reference) Validate 

func (r *Reference) Validate() error

Validate checks that the reference coordinates are complete and well formed.

type Unpacker 

type Unpacker struct {
	// contains filtered or unexported fields
}

Unpacker is the release unpacker. It runs each registered decomposer against the release the subject points to and aggregates the resulting NodeLists.

func NewUnpacker 

func NewUnpacker() *Unpacker

NewUnpacker returns a release unpacker pre-loaded with the default release decomposer.

func (*Unpacker) Extract 

func (u *Unpacker) Extract(ctx context.Context, subject api.DecomposableSubject) ([]*sbom.NodeList, error)

Extract reads the release the given subject points to and returns the NodeLists produced by the registered decomposers.

func (*Unpacker) RegisterDecomposer 

func (u *Unpacker) RegisterDecomposer(d api.Decomposer)

RegisterDecomposer adds a decomposer to the unpacker.

func (*Unpacker) UnregisterDecomposer 

func (u *Unpacker) UnregisterDecomposer(d api.Decomposer)

UnregisterDecomposer removes a decomposer from the unpacker.

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.