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 and can be merged automatically. One whose files moved is relocated by name and must be reviewed, because relocating is a guess.
Index ¶
- Constants
- func Extractable(format string) bool
- type Result
- type Signatures
- type Verifier
- func (v *Verifier) Checksum(ctx context.Context, logger *slog.Logger, version string, ...) (string, error)
- func (v *Verifier) Fill(ctx context.Context, logger *slog.Logger, pkgName, version string, ...) (bool, []string, error)
- func (v *Verifier) Verify(ctx context.Context, logger *slog.Logger, pkgName, version string, ...) (*Result, error)
Constants ¶
const ChecksumAlgorithm = "sha256"
ChecksumAlgorithm is the algorithm of every checksum ar2 records.
Variables ¶
This section is empty.
Functions ¶
func Extractable ¶
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.
Types ¶
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 a src had to be relocated or couldn't be found 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 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) 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.
Source Files