Documentation
¶
Overview ¶
Package artifacts reads goreleaser's build manifest and says which of the things it produced belong on a release.
Why a manifest rather than a directory listing ¶
goreleaser writes `dist/artifacts.json` describing every artefact it made, with a type for each. Globbing `dist/` instead would work today and change meaning silently the first time goreleaser's layout does, or the first time a repository adds a target — and it would happily publish intermediate build output alongside the archives.
Reading the manifest means an artefact colophon does not recognise is a visible failure rather than a silent inclusion.
What is NOT read from it ¶
The manifest records where an artefact is on disk. It does not record where the bytes were uploaded to, because the upload is a separate goreleaser pipe. So the NAMES come from here and the location is built from the caller's upload target — which is colophon's own configuration rather than goreleaser's naming, and is the only part safe to construct.
Index ¶
Constants ¶
const ManifestFile = "artifacts.json"
ManifestFile is the name goreleaser always writes, inside its dist directory.
Variables ¶
var ErrBadBase = errors.New("artifacts: the asset base must be an absolute http or https URL")
ErrBadBase reports a base that is not an absolute http or https URL.
var ErrCheckRefused = errors.New("artifacts: the check for an asset was refused")
ErrCheckRefused reports a check the server turned away, which says nothing about whether the asset is there.
var ErrNoPublishable = errors.New("artifacts: the manifest names nothing publishable")
ErrNoPublishable reports a manifest that parsed but named nothing a release should carry.
That is a failure rather than an empty success: a build that produced no archive has gone wrong, and publishing a release with no assets is the exact outcome this whole change exists to prevent.
var ErrNotThere = errors.New("artifacts: an asset is not at the location it would be published as")
ErrNotThere reports an asset that does not resolve where it was said to be.
var ErrUnreadable = errors.New("artifacts: cannot read the manifest")
ErrUnreadable reports a manifest that could not be read or parsed.
Functions ¶
func Verify ¶
Verify checks that every asset actually resolves before anything is published.
Why this is colophon's job and not the forge's ¶
go/forge states it plainly: it records a location without fetching it, HEADing it or resolving it, because a request made on a caller's behalf to a host it does not control is a capability nobody asked for. Its guarantee is that no observer sees a release before its assets are attached — not that the bytes are there.
So a release can be published complete, correct by that contract, and every link on it 404. That is the ORIGINAL bug through a different door: the release exists, so a consumer is told yes and then gets a 404 that reads as a missing file rather than a race.
It also breaks the check this estate adopted for the first version of that bug. Counting a release's assets no longer distinguishes a good release from a bad one, because a broken one has a full set of links. Resolving one does.
colophon can make this check honestly because it is not a stranger to the address: it is publishing to a registry it just uploaded to. It sends no credential unless WithCredential gives it one, and then only to the forge.
Types ¶
type Asset ¶
type Asset struct {
// Name is the filename as it should appear on the release.
Name string
// Kind is goreleaser's type for it, kept so a caller can report what it is
// publishing rather than only how many.
Kind string
}
Asset is one artefact that belongs on the release.
func Named ¶ added in v0.10.0
Named turns a list of file names into the assets a release should carry.
The other half of Read: where that one learns from goreleaser what was built and filters it by type, this takes a project's own statement of what it publishes (spec 0017 D1). Both hand the same []Asset to Locate and Verify, which is why nothing downstream of here knows the difference.
These names are not filtered ¶
Read's allow-list exists because goreleaser produces build output nobody wants on a release, and a type it invents tomorrow should not be published by accident. A named list has no such problem and gets no such protection: every entry is on the release because somebody wrote it down, which is the same reason this package reads a manifest rather than globbing a directory.
Kind is left EMPTY rather than given an invented value. It means "goreleaser said this was a Checksum", and there is no goreleaser here to have said it (spec 0017 D4).
type Doer ¶
Doer is the part of an HTTP client Verify needs. Injected so a test never reaches the network and never races on a package-level client.
type Located ¶
type Located struct {
Asset
// URL is where the bytes live. It becomes the release asset's link.
URL string
}
Located is an asset and the URL its bytes were uploaded to.
func Locate ¶
Locate places each asset under base.
base is supplied rather than derived, and that is deliberate. colophon does not know where goreleaser was told to upload — that is goreleaser's own `uploads:` target — so guessing it would encode one tool's configuration inside another. The SAME value is written in both places, which makes a mismatch a configuration error a human can see rather than a silent 404.
type VerifyOption ¶ added in v0.15.0
type VerifyOption func(*verifier)
VerifyOption adjusts how Verify makes its attempts.
func WithCredential ¶ added in v0.21.3
func WithCredential(origin, token string) VerifyOption
WithCredential presents token as a Bearer token to assets on the forge's origin, and to nothing else, redirects included (spec 0033). An empty token sends nothing.