verify

package
v0.14.2 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package verify extracts a generated asset to decide whether its registry.json can be merged without a human looking at it.

Everything else in registry.json is resolved from metadata the release exposes, so it either matches reality or the generation fails. files[].src is different: it names a path inside the archive, and nothing but the archive can say whether that path is still right. When it isn't, carrying the template over would produce a registry.json that resolves cleanly and fails at install time.

So the archive decides the merge policy. A package whose files all resolve is carried over unchanged. One whose file is elsewhere in the archive under the same name has moved rather than changed -- the directory an upstream adds around what it packs, or drops -- and recording where it is now says what the definition said, so that merges on its own too. What needs a human is a guess: a file found under a name the definition didn't give it, a name the archive holds more than one of, or a name the archive doesn't hold at all.

Index

Constants

View Source
const ChecksumAlgorithm = "sha256"

ChecksumAlgorithm is the algorithm of every checksum ar2 records.

Variables

This section is empty.

Functions

func Extractable

func Extractable(format string) bool

Extractable reports whether this machine can open the asset.

A dmg on Linux isn't a broken package, it is a package this machine can't look inside. Saying so lets the caller carry on with what it can establish instead of failing the version over where it happens to be running.

func Refused added in v0.8.0

func Refused(err error) bool

Refused reports whether the error is the server saying there is nothing there, rather than something that may answer differently in a minute.

The 4xx range, because that is the range about the request: the asset isn't there, or isn't ours to have. 429 is the exception -- it is a rate limit, which is the moment rather than the asset.

Types

type Excluded added in v0.8.0

type Excluded struct {
	// Asset is the entry as it was resolved, which is what makes the exclusion
	// checkable: it is what 'ar2 test' takes.
	Asset *generate.Asset
	// Reason is what happened, in a line.
	Reason string
}

Excluded is one environment the registry doesn't offer this version for.

func (*Excluded) Environment added in v0.8.0

func (e *Excluded) Environment() string

Environment is the environment the entry was for.

type Filled added in v0.8.0

type Filled struct {
	// NeedsReview says the file can't be merged without somebody looking at it.
	NeedsReview bool
	// Unresolved names the environments whose entry points at a file the archive doesn't
	// hold, as "<os>/<arch>: <file>, <file>". They are also in Excluded; this is the
	// wording a pull request waiting for a definition is opened with.
	Unresolved []string
	// Excluded are the environments left out of the file, with the entry each had and
	// why it went. The file no longer says anything about them, so this is the only
	// record of what was tried.
	Excluded []*Excluded
	// Offered is how many environments the file is left offering. Zero is a version
	// there is nothing to publish for, and then the entries are left as they were
	// generated: what becomes of such a version is the caller's, and what it has to
	// work with is what was tried.
	Offered int
}

Filled is what completing a registry.json came to.

type Result

type Result struct {
	// Checksum is the SHA256 of the downloaded bytes. It is filled in whether or not
	// the release reported a digest, so a release published before GitHub started
	// reporting them still gets a checksum.
	Checksum string
	// Files is the files list to record. It is the input list when every src was
	// found, and a relocated one otherwise.
	Files []*generate.File
	// NeedsReview is set when resolving a src took a guess: the archive holds the file
	// under another name, holds that name more than once, or doesn't hold it at all. A
	// pull request carrying such a result must not be merged automatically.
	NeedsReview bool
	// Unresolved names the files that aren't anywhere in the archive.
	Unresolved []string
	// Holds is what the archive does hold, when something couldn't be resolved. It is the
	// one thing that says what the definition should have said, and the archive is gone as
	// soon as the run ends.
	Holds []string
	// LinkedLibc is the libc the executables need, read from the binaries. It is
	// empty when the asset holds nothing that can be read that way.
	LinkedLibc string
}

Result is what extracting one asset established.

type Signatures

type Signatures interface {
	Check(ctx context.Context, logger *slog.Logger, pkgName, version string, asset *generate.Asset, path string) error
}

Signatures verifies an asset against the signatures its entry claims and reports whether they all held.

type StatusError added in v0.8.0

type StatusError struct {
	Code int
}

StatusError is what a download the server refused comes back as.

Which status it was decides what happens to the entry. A 404 is the release saying it has no such asset, which is about the release and will be true next time; a 500 or a reset connection is about the moment, and an entry dropped over one would be an environment the registry stopped offering because a server hiccupped.

func (*StatusError) Error added in v0.8.0

func (e *StatusError) Error() string

type Verifier

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

Verifier downloads and extracts assets.

func New

func New(httpClient *http.Client, signatures Signatures) *Verifier

New creates a Verifier.

The unarchiver gets an executor, so dmg and pkg assets can be extracted where the tools that open them exist. Whether they do is asked before extracting rather than assumed from the format: the same code runs on a macOS laptop and a Linux runner, and only one of them can open a dmg.

func (*Verifier) Checksum

func (v *Verifier) Checksum(ctx context.Context, logger *slog.Logger, version string, asset *generate.Asset) (string, error)

Checksum downloads the asset and returns its SHA256, without extracting it.

It is used for a release published before 2025-06-03, when GitHub started reporting a digest for release assets. Those digests are not backfilled, so the only way to get a checksum for an older release is to hash the bytes. A registry.json without a checksum would defeat the point of the lock file, so this isn't optional the way extracting is.

func (*Verifier) Complete added in v0.8.0

func (v *Verifier) Complete(ctx context.Context, logger *slog.Logger, pkgName, version string, reg *generate.Registry, extract bool) (*Filled, error)

Complete is Fill, saying also which environments it left out.

An environment the release doesn't publish, or publishes something the definition can't be read against, is left out rather than taking the version with it: the environments that do work get the version, and what was left out is reported so that it doesn't quietly stay that way. A file that offers nothing at all is not a file, so a version with every environment excluded is the caller's to refuse.

func (*Verifier) Fill

func (v *Verifier) Fill(ctx context.Context, logger *slog.Logger, pkgName, version string, reg *generate.Registry, extract bool) (bool, []string, error)

Fill completes a registry.json.

Every asset that needs a checksum and doesn't have one is downloaded and hashed. When extract is set, each asset is also extracted and its files are checked against the archive; the result says whether the outcome can be merged without review.

Extracting is optional because it costs a download per asset even when the release reports digests, which is what makes a backfill bandwidth-bound. Hashing is not optional: a registry.json without a checksum would defeat the lock file.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, logger *slog.Logger, pkgName, version string, asset *generate.Asset) (*Result, error)

Verify downloads the asset, extracts it, and resolves its files against the archive's actual contents.

func (*Verifier) VerifySignatures added in v0.13.0

func (v *Verifier) VerifySignatures(ctx context.Context, logger *slog.Logger, pkgName, version string, asset *generate.Asset) (string, error)

VerifySignatures downloads the asset and checks the signatures its entry claims, without extracting it, and returns the asset's checksum. It is for an asset this machine can't open.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL