/ 
App-FuguBench-0.1.1
/ App::FuguBench::Update

NAME

App::FuguBench::Update - the update verb of fugubench

SYNOPSIS

$ fugubench update
fugubench 0.2.0

$ fugubench update --version v0.1.0 --allow-downgrade
fugubench 0.1.0

DESCRIPTION

App::FuguBench::Update holds the update verb. The verb fetches a release of the organization, verifies it in this process, and puts it in the place of the running program.

The first fetch of the shim trusts HTTPS to GitHub. Every later download verifies against the release key of the organization, and this verb is one of them. The keys come from App::FuguBench::Keys, and the keys of a consumer never enter. A release decides what it trusts, and no file of the host decides it.

The verb reads no checkout, so an operator runs it in any directory.

command

command($verb) returns the entry of the Fugu::CLI table. The module holds one verb, so it ignores the name.

THE COMMAND LINE

The usage is update [--version <tag>] [--allow-downgrade], and the verb takes no argument.

--version names one release tag. Without it, the verb takes the latest release. A tag must read v<MAJOR>.<MINOR>.<PATCH>, and the verb prints the usage and exits 2 for a value of another shape. That value reaches a download address, and it must name one path segment.

--allow-downgrade takes a release below the running version.

THE STEPS

The verb runs these steps in order, and it stops at the first failure.

  1. It resolves the running file. A file under the shim cache is a refusal, and the message names the sync of the org pack as the path to a new version. An unset or an empty HOME is a refusal as well, because the cache path starts with that value.

  2. It downloads SHA256 and SHA256.sig into a temporary directory.

  3. It writes each embedded key as a signify public key file, in trust order, and it verifies the manifest against that list. A failure of that check names the install command, because a rotation of the release key can leave this program without the key of the release.

  4. It reads the version from the versioned tarball name of the manifest. A version below the running one is a refusal without --allow-downgrade.

  5. It downloads the packed file and holds it to the digest of the manifest.

  6. It writes the bytes over the running file, atomically and with mode 755, and it prints the result line fugubench <version>.

The signature check sits in front of the download of the packed file. A release that no embedded key signed then costs the manifest and its signature, and nothing more.

THE ADDRESS

The release directory is https://github.com/FuguBSD/FuguBench/releases/latest/download/, or the directory of the named tag under https://github.com/FuguBSD/FuguBench/releases/download/.

FUGUBENCH_RELEASE_URL replaces the host and the repository of that address. A developer and a test point the verb at another server with it. A trailing solidus of the value is not part of the address.

Each of the three downloads passes the URL shape check of App::FuguBench::Fetch. Fugu::Curl places the URL last and writes no -- separator, so an address that starts with a dash would reach the downloader as an option.

THE SANDBOX

The row of update pledges stdio rpath wpath cpath fattr proc exec inet dns. The file promises serve the replace, fattr serves the mode, and proc exec serves the downloader child. The row unveils nothing, because unveil(2) holds across an exec and no list names the files of a child.

RETURN VALUES

command returns a hash reference. The body returns 0 after the replace. It returns 1 for a failed download, a signature that no embedded key verifies, a manifest that names no single versioned tarball, a refused downgrade, a digest that does not match, a running file under the shim cache, an unset or an empty HOME, and a failed write. It returns 2 for a command line that holds an argument, and for a tag of another shape.

SEE ALSO

App::FuguBench, App::FuguBench::Dist, App::FuguBench::Fetch, App::FuguBench::Keys, Fugu::CLI, Fugu::Curl, Fugu::File, Fugu::Signify

AUTHORS

Dick Olsson <hi@senzilla.io>