valis / Reference / API reference
Release - API reference
Exported surface for the release subsystem. Part of the API reference.
Package valis/src/release/admission
Conditions
release-vouch-unreadable
Signalled when a release's publisher-vouch member is present but cannot be read as a vouch.
Generic functions
release-vouch-unreadable-reason
(release-vouch-unreadable-reason condition)
Undocumented: this exported symbol needs a docstring.
Functions
admit-or-jail-release
(admit-or-jail-release directory &key release-root store owner-credential expiry-judged-at)
Judge the staged release in DIRECTORY, directly under RELEASE-ROOT's staging/, as verify-release-admission does. Admitted, it stays where it is and (values t nil designation) is returned. Refused, it is moved whole into the release jail with a why record naming its designation and the reason, and (values nil reason designation entry) is returned, ENTRY the jail entry's directory. When the jailing itself is refused the bytes stay staged, the failure is logged, and ENTRY is NIL. Nothing refused is deleted.
read-release-vouch
(read-release-vouch directory)
The text of the publisher-vouch member of the release in DIRECTORY, surrounding whitespace removed, or NIL when it holds no such member. Signals release-vouch-unreadable when the member is a link or not a regular file, holds more than release-vouch-size-limit octets, or is not UTF-8 text.
verify-release-admission
(verify-release-admission directory &key store owner-credential expiry-judged-at (admission-kind :install))
Decide whether the release in DIRECTORY may be admitted, as a module would be: its publisher-vouch member must vouch, through a delegation from a publisher anchor filed in STORE, the vouch store, for exactly the release's /release/<hex> designation; nothing the publisher revoked may lie on the vouch's chain; and OWNER-CREDENTIAL, or when it is NIL the standing grant STORE holds for that publisher, must grant :admit over the designation or over /publisher/<the anchor>. The identity is minted over the release's files as staging minted it. STORE is read and never written. ADMISSION-KIND is :install, a fresh install: a list from that publisher issued in the last seven days must be held and must not withdraw the vouch, and the standing grant must be active. At :restart, as a restart judges a module, neither the list's age nor a withdrawal is consulted, and a held standing grant no longer active stands in when no active one is held. Returns (values t nil designation), or (values nil reason designation) where REASON names the release and what refused it; DESIGNATION is NIL when no identity could be minted. Expiry is judged at EXPIRY-JUDGED-AT, a Unix time, or now when it is NIL. Fail-closed: no signal escapes.
Variables
+release-designation-kind+
The kind of a release's identity: designations under release.
+release-vouch-size-limit+
The most octets a release's publisher-vouch member may hold.
Package valis/src/release/identity
Conditions
release-designation-bad-length
The designation's digest is not the length its algorithm fixes.
release-designation-invalid
Signalled when text offered as a release designation does not name a release identity valis mints.
release-designation-unknown-algorithm
The designation names a hash function valis does not mint identities with.
Generic functions
release-designation-invalid-designation
(release-designation-invalid-designation condition)
Undocumented: this exported symbol needs a docstring.
release-designation-invalid-reason
(release-designation-invalid-reason condition)
Undocumented: this exported symbol needs a docstring.
release-designation-unknown-algorithm-code
(release-designation-unknown-algorithm-code condition)
Undocumented: this exported symbol needs a docstring.
Functions
mint-release-identity
(mint-release-identity root files)
The identity of the release tree rooted at ROOT whose members are FILES, a list of pathnames under ROOT: the multihash module-bundle-identity mints over the same framing.
parse-release-designation
(parse-release-designation designation)
The identity octets DESIGNATION, a release/<lowercase hex> designation, names. Signals release-designation-unknown-algorithm for a hash function valis does not mint, release-designation-bad-length for a digest of the wrong length, and release-designation-invalid for any other text, a /module designation included. The hex is checked by the same rules a module designation is, so the two kinds accept exactly the same identities.
release-designation
(release-designation identity)
IDENTITY, a release's multihash, rendered as /release/<lowercase hex>, never truncated.
release-tree-designation
(release-tree-designation directory)
The /release/<hex> designation of the release tree in DIRECTORY.
release-tree-files
(release-tree-files directory)
The regular files directly in DIRECTORY that a release's identity covers, every one but release-vouch-member, sorted by name.
Variables
+release-designation-prefix+
Reserved designation prefix under which a release is named.
+release-vouch-member+
The tree member that carries the publisher's vouch beside a release, left out of its identity.
Package valis/src/release/jail
Conditions
release-jail-refused
Signalled when a staged release cannot be jailed. Nothing was moved.
Generic functions
release-jail-refused-directory
(release-jail-refused-directory condition)
Undocumented: this exported symbol needs a docstring.
release-jail-refused-reason
(release-jail-refused-reason condition)
Undocumented: this exported symbol needs a docstring.
Functions
jail-release-directory
(jail-release-directory directory &key release-root designation reason detail)
Move DIRECTORY, a staging directory directly under RELEASE-ROOT's staging/, whole by one rename to bytes/ of a fresh entry <release-root>/jail/<n>/, after writing the entry's why record naming DESIGNATION, REASON (one line) and the UTC time, then DETAIL, a plist of further scalar lines. Returns the entry's directory pathname. Logs the jailing at error level. Signals release-jail-refused, moving nothing, when RELEASE-ROOT is NIL or not a directory, DIRECTORY is a link or not in that place, or the record or the move fails.
read-release-jail-why
(read-release-jail-why entry)
The why record of the jail ENTRY as a list of (key . value) strings, one per line, in order; a line with no space is a key with an empty value. The record is read as UTF-8 text and nothing in it is evaluated. Signals release-jail-refused when it is a link, not a regular file, or larger than why-size-limit.
release-jail-directory
(release-jail-directory release-root)
The jail under RELEASE-ROOT: <release-root>/jail/.
release-jail-entries
(release-jail-entries release-root)
The entry directories of RELEASE-ROOT's jail, in the order they were made; NIL when there is no jail.
Package valis/src/release/lifetime
Classes
launch-facts
What the host agent launched: LAUNCHED, base or a hex; REASON, a keyword of launch-reasons; FAILED-TRIAL, NIL, base or a hex; FAILED-TRIAL-END, NIL or its end as text.
release-lifetime
The binary lifetime record.
- BOOTED, LAUNCH-REASON, PREVIOUS, FAILED-TRIAL and FAILED-TRIAL-END: each text or NIL.
- FAILED-TRIALS: an alist (id . end) of every trial reported failed, oldest first.
- STORE-FORMAT-HIGH: the highest store format any boot ran with, or NIL.
- BASE-STORE-FORMAT: the store format the last boot of base ran with, or NIL.
- RAN: the release hexes booted on this node, oldest first.
- ADMITTED: an alist (hex . Unix time) of each release's admission by apply.
- OVERRIDES: rollback override lines, each (id kind time), oldest first.
- EXTRA: the lines this reader does not know, in order, written back as read.
Functions
launch-facts-failed-trial
(launch-facts-failed-trial instance)
Undocumented: this exported symbol needs a docstring.
launch-facts-failed-trial-end
(launch-facts-failed-trial-end instance)
Undocumented: this exported symbol needs a docstring.
launch-facts-launched
(launch-facts-launched instance)
Undocumented: this exported symbol needs a docstring.
launch-facts-reason
(launch-facts-reason instance)
Undocumented: this exported symbol needs a docstring.
make-launch-facts
(make-launch-facts &key ((:launched launched) +release-base+) ((:reason reason) :default) ((:failed-trial failed-trial) nil) ((:failed-trial-end failed-trial-end) nil))
Undocumented: this exported symbol needs a docstring.
parse-launch-facts
(parse-launch-facts args)
The launch-facts ARGS, the resident's argv, carry. A flag whose value cannot be read is logged as release.launch-refused; an unreadable launch or reason gives a default launch of base, and an unreadable failed trial gives none. Never signals.
promote-passed-release-trial
(promote-passed-release-trial &key release-root (facts *launch-facts*))
The boot health gate's pass for a release trial: when this boot runs the selection record's pending trial, rewrite the record to name it the default with no trial, keep the default it replaced as previous in the lifetime record, log release.trial-passed, and prune placed releases. Then record a module generation, cause binary, under the promoted binary's stamp, unless the image runs a tentative module generation; a skip or a failure to record it is logged and the promotion stands. Returns the promoted hex, or NIL when this boot is no pending release trial.
read-release-lifetime
(read-release-lifetime release-root)
The lifetime record under RELEASE-ROOT, or NIL when there is none or it cannot be read; an unreadable record is logged. A known line that is malformed is passed over; a line led by an unknown word is kept in the record's extra lines.
record-launch-facts
(record-launch-facts &key release-root (facts *launch-facts*) (store-format +node-store-format+))
Record FACTS, this boot's launch facts, in RELEASE-ROOT's lifetime record, with STORE-FORMAT, the store format this binary runs with. Returns the record written, or NIL.
- Raises the record's store-format high-water to STORE-FORMAT when it is lower or absent; never lowers it.
- When FACTS launched base, records STORE-FORMAT as base's store format.
- When FACTS launched a release, records that release as one this node ran.
- Logs release.trial-failed when FACTS name a failed trial the record did not already hold with the same end.
- When a fallback launch reports the selection record's pending trial failed, removes that trial from the selection record.
- Does nothing when RELEASE-ROOT or FACTS is NIL.
- Never signals: a failure is logged and the boot goes on.
record-release-admission
(record-release-admission release-root hex time)
Record in RELEASE-ROOT's lifetime record that apply admitted the release HEX at TIME, Unix seconds, replacing an earlier admission of HEX. Call with release-record-lock held. Signals when the record cannot be written.
record-rollback-override
(record-rollback-override release-root id kind time)
Record in RELEASE-ROOT's lifetime record a rollback to ID committed past the refusal KIND names, downgrade the one kind, at TIME, Unix seconds. Call with release-record-lock held. Signals when the record cannot be written.
release-lifetime-admitted
(release-lifetime-admitted instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-base-store-format
(release-lifetime-base-store-format instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-booted
(release-lifetime-booted instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-failed-trial
(release-lifetime-failed-trial instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-failed-trial-end
(release-lifetime-failed-trial-end instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-failed-trials
(release-lifetime-failed-trials instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-launch-reason
(release-lifetime-launch-reason instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-overrides
(release-lifetime-overrides instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-previous
(release-lifetime-previous instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-ran
(release-lifetime-ran instance)
Undocumented: this exported symbol needs a docstring.
release-lifetime-store-format-high
(release-lifetime-store-format-high instance)
Undocumented: this exported symbol needs a docstring.
release-retained-ids
(release-retained-ids release-root selection &key (facts *launch-facts*))
The binaries retention keeps besides the newest predecessors: SELECTION's default and trial, the lifetime record's previous default, and what this boot runs.
release-trial-boot-p
(release-trial-boot-p &key release-root (facts *launch-facts*))
True when this boot is a release trial still pending in the selection record, so the boot health gate must judge it.
release-trial-failure
(release-trial-failure id &key release-root)
The end of ID's failed trial as the lifetime record under RELEASE-ROOT holds it, or NIL when no trial of ID is recorded failed or there is no readable record.
release-trial-under-way
(release-trial-under-way &key release-root (facts *launch-facts*))
The hex of the release trial this boot runs while the selection record still names it the pending trial, or NIL. An unreadable record gives NIL.
Variables
*launch-facts*
This boot's launch-facts, or NIL when the node was not launched by a release-selecting host agent.
+lifetime-file-name+
The name of the lifetime record directly under the release root.
Package valis/src/release/manifest
Conditions
release-manifest-refused
Signalled when a manifest's text is not a format 1 manifest: a missing or unknown format line, a missing or repeated key, an empty value, or a store-format that is not a whole number.
Generic functions
release-manifest-refused-reason
(release-manifest-refused-reason condition)
Undocumented: this exported symbol needs a docstring.
Functions
parse-release-manifest
(parse-release-manifest text)
The manifest TEXT as a plist of :version, :commit, :compiler (strings) and :store-format (an integer). Unknown keys are passed over. Signals release-manifest-refused when:
- the first line is not valis-release-manifest 1;
- a key of
release-manifest-keysis missing, repeated, or has an empty value; - store-format is not a whole number.
read-release-manifest-file
(read-release-manifest-file path)
The manifest in the file at PATH, parsed as parse-release-manifest does. Signals release-manifest-refused for a file larger than release-manifest-octet-limit or not valid UTF-8, and as parse-release-manifest does; a missing file signals as opening it does.
render-release-manifest
(render-release-manifest &key version commit compiler (store-format +node-store-format+))
The manifest text for VERSION, COMMIT, COMPILER and STORE-FORMAT, each line ended by a newline. A NIL or empty COMMIT is written as unknown.
Variables
*release-manifest-octet-limit*
The most octets a manifest file may hold; a larger file is refused unread.
+node-store-format+
The node store format this binary reads and writes, declared in every manifest it prints. Format 2 adds the binary generation cause, which a format 1 build refuses as corrupt.
+release-manifest-format+
The manifest format this image writes and the one format it reads.
+release-manifest-keys+
The keys every format 1 manifest carries, in the order written.
+release-manifest-member+
The name of the manifest member in a release tree and beside the binary in a delivery archive.
Package valis/src/release/report
Functions
release-report-lines
(release-report-lines &key release-root (facts *launch-facts*))
The release report as (key . value) strings in the order of release-report-keys. RELEASE-ROOT is the node's release root or NIL; FACTS, this boot's launch facts or NIL. development-listener is what development-listener-report answers. Never signals: a fact that cannot be read is unknown.
render-release-report
(render-release-report &rest arguments &key release-root facts)
The release report text for RELEASE-ROOT and FACTS, as release-report-lines takes them: one line per key, each ended by a newline.
Variables
*development-listener-report*
NIL, or a function of no arguments answering the development-listener value: closed, or open followed by the socket, the route and the since time. Set by the resident's bring-up; the value reads unknown while NIL. A seam, not an import, because the development listener's status text reads this report.
+release-report-keys+
The release report's keys, in the order served.
Package valis/src/release/rollback
Generic functions
release-rollback-refused-kind
(release-rollback-refused-kind condition)
Undocumented: this exported symbol needs a docstring.
release-rollback-refused-reason
(release-rollback-refused-reason condition)
Undocumented: this exported symbol needs a docstring.
Functions
release-id-name
(release-id-name id)
ID, base or a release hex, as the owner names it: base, or /release/<hex>.
roll-back-release
(roll-back-release target &key release-root store override-downgrade (store-format +node-store-format+))
Record TARGET, base or a release hex, or the lifetime record's previous default when NIL, as the next boot's trial in RELEASE-ROOT's selection record. The default stays unchanged, and a pending trial is replaced. STORE is the vouch store the target's signatures are judged against; STORE-FORMAT, the store format this binary runs with, takes part in the high-water. OVERRIDE-DOWNGRADE clears the downgrade refusal only. Once the selection record is on disk:
- logs release.rollback-committed;
- when the override was used, keeps it in the lifetime record and logs release.rollback-override; a failed lifetime write is logged, and the rollback stands.
Asks for no restart. Returns (values id replaced overrides): ID the trial recorded, REPLACED the pending trial it replaced or NIL, and OVERRIDES (:downgrade) when the override was used, else NIL. Signals release-rollback-refused, recording nothing, as this file's header lists, and when there is no previous default to return to. Signals release-selection-malformed when the selection record cannot be read.
Package valis/src/release/staging
Conditions
release-upload-refused
A request against a release upload was refused; nothing it asked for was written.
Generic functions
release-upload-refused-reason
(release-upload-refused-reason condition)
Undocumented: this exported symbol needs a docstring.
Functions
append-upload-member
(append-upload-member upload name offset data)
Write DATA, an octet vector, to UPLOAD's member NAME at OFFSET, and return its length. Signals release-upload-refused, writing nothing, when the member has no writer, when OFFSET is not the count of octets the member holds, and when the upload would pass release-upload-bound.
begin-upload-member
(begin-upload-member upload name)
Take the writer of UPLOAD's member NAME, creating its file mode 0600 when it has none, and return NAME. Signals release-upload-refused for a name that cannot name a member and for a member that already has a writer.
discard-release-upload
(discard-release-upload upload)
Close every writer of UPLOAD and delete its staging directory.
end-upload-member
(end-upload-member upload name)
Release the writer of UPLOAD's member NAME, flushing what it wrote to the file. Does nothing for a member with no writer.
open-release-upload
(open-release-upload release-root)
A fresh upload staged under RELEASE-ROOT/staging/<n>/, the directory made mode 0700. Signals release-upload-refused when RELEASE-ROOT is not an existing directory.
release-member-name-p
(release-member-name-p name)
True when NAME can name a tree member: one path element of letters, digits, dot, hyphen and underscore, not . or .., at most 255 characters.
release-upload-directory
(release-upload-directory instance)
Undocumented: this exported symbol needs a docstring.
release-upload-total
(release-upload-total instance)
Undocumented: this exported symbol needs a docstring.
upload-member-names
(upload-member-names upload)
The names of UPLOAD's members, sorted.
upload-member-octets
(upload-member-octets upload name)
The octets UPLOAD's member NAME holds, or NIL when it has no such member.
upload-member-open-p
(upload-member-open-p upload)
True while any member of UPLOAD has a writer.
Variables
*release-root*
The directory this node keeps releases in, from –release-root on the resident's argv; NIL when the node was launched without one, and then the node holds no releases.
*release-upload-bound*
The most octets one upload may hold across all its members: several times a valis binary, and a ceiling on what one owner session can put on the disk.
Package valis/src/release/store
Classes
release-selection
One selection record: DEFAULT, base or a hex; TRIAL, NIL, base or a hex; DIGESTS, an alist of (hex . sha256 hex).
Conditions
release-placement-refused
Signalled when a staged release cannot be placed under the release root. Nothing under the root changed.
release-selection-malformed
Signalled when a selection record cannot be read as version 1 of the record.
Generic functions
release-placement-refused-reason
(release-placement-refused-reason condition)
Undocumented: this exported symbol needs a docstring.
release-selection-malformed-reason
(release-selection-malformed-reason condition)
Undocumented: this exported symbol needs a docstring.
Functions
make-release-selection
(make-release-selection &key ((:default default) +release-base+) ((:trial trial) nil) ((:digests digests) (quote nil)))
Undocumented: this exported symbol needs a docstring.
parse-release-selection
(parse-release-selection text)
The release-selection TEXT holds. Signals release-selection-malformed on anything version 1 of the record does not allow.
place-release
(place-release staged release-root hex)
Place the release staged in STAGED, a directory under RELEASE-ROOT, as RELEASE-ROOT/HEX/ by one rename, after setting valis to 0555, release-manifest and any publisher-vouch member to 0444, and the directory to 0555; then sync the root. Returns (values directory digest), DIGEST the lowercase SHA-256 hex of the placed valis. A release already placed under HEX is kept as it is, write-once, and STAGED is removed; its digest is returned. Signals release-placement-refused, placing nothing, when any of these holds:
- HEX is not a release identity
- valis or release-manifest is missing or not a regular file
- valis or release-manifest is a link, or has more than one link
- the staged directory is not under RELEASE-ROOT
placed-release-directory
(placed-release-directory release-root hex)
The directory RELEASE-ROOT/HEX/ a placed release lives in.
placed-release-hexes
(placed-release-hexes release-root)
The identity hexes of the releases placed directly under RELEASE-ROOT, newest placement first. Only a directory named by a release identity counts, never a link.
prune-placed-releases
(prune-placed-releases release-root &key keep (predecessors *retained-predecessors*))
Remove placed releases under RELEASE-ROOT beyond those KEEP names (base and NIL are ignored) and the PREDECESSORS newest others. Only whole identity directories directly under the root are removed; the jail, staging, the records, and anything that is not an identity directory are never touched. A removal that fails is logged and the rest are still tried. Returns the hexes removed, logged as release.retention-pruned when any.
read-release-selection
(read-release-selection release-root)
The selection record under RELEASE-ROOT, or NIL when there is none. Signals release-selection-malformed when it cannot be read as version 1.
release-id-p
(release-id-p text)
True when TEXT names a binary the selection record can name: base or a release identity hex.
release-identity-hex-p
(release-identity-hex-p text)
True when TEXT is a release identity as the release root names it: 68 lowercase hex digits, the SHA-256 multihash prefix 1220 first.
release-record-path
(release-record-path release-root name)
The pathname of the record NAME directly under RELEASE-ROOT.
release-selection-default
(release-selection-default instance)
Undocumented: this exported symbol needs a docstring.
release-selection-digest
(release-selection-digest selection hex)
The SHA-256 hex SELECTION records for HEX, or NIL.
release-selection-digests
(release-selection-digests instance)
Undocumented: this exported symbol needs a docstring.
release-selection-trial
(release-selection-trial instance)
Undocumented: this exported symbol needs a docstring.
render-release-selection
(render-release-selection selection)
SELECTION as the text of a version 1 selection record, with a sha256 line for each hex it names and no other.
write-release-record
(write-release-record release-root name text)
Replace the record NAME under RELEASE-ROOT with TEXT durably: a sibling written and synced, renamed over it, and the root synced. A failed sync of the root after the rename is logged and the write stands.
write-release-selection
(write-release-selection release-root selection)
Replace RELEASE-ROOT's selection record with SELECTION. Call with release-record-lock held.
Variables
*release-record-lock*
Held by every writer of the selection record and the lifetime record, across its read, its change and its write.
+release-base+
The selection name of the launcher's configured command.
+release-selection-version-line+
The first line of a selection record this node writes and reads.