Module pinned_programs

Expand description

The program store, ~/.murmur/programs/: the pinned downloads a tool’s programs: block names (murmur_artifact::parse_program_downloads), fetched once by mur install, and which copy of each pinned program a session runs.

~/.murmur/programs/
  <sha256>/              content-addressed by the declared sha256, shared by every artifact
    record.json          PinnedRecord
    files/               the unpacked zip, or the single downloaded file
    bin/<program>        relative symlink to ../files/<run>, one per program name
  .partial-<random>/     an install in flight; never read, removed on any failure

Every directory is 0700; every file 0700 when it is executable and 0600 otherwise. An entry is assembled in a .partial-* folder and moved into place by one rename, so a reader sees a whole entry or none.

The store is written by mur install alone (commit_download). Staging only reads it (resolve_pinned_programs): a host program of the same name on PATH wins; otherwise a copy whose record.json pins the declared sha256 and whose bin/<program> resolves to an executable file is used, without re-hashing the tree, so launch time does not grow with the download. mur install and mur doctor verify the whole tree (verify_entry).

Structs§

CommittedEntry: What commit_download left in the store.
DeclaredToolDownloads: One staged tool’s pinned downloads, with the lock origin of its pin.
PartialDownload: An install in flight: ~/.murmur/programs/.partial-<random>/, removed when dropped uncommitted.
PinnedRecord: record.json: what an entry was fetched from, and the digest of what it holds.
ResolvedPinnedProgram: One gated program’s source choice.
TreeFile: One regular file under an entry’s files/.

Enums§

EntryState: What the store holds for one download.
PinnedSource: Which copy of a pinned program a session runs.
PinnedStoreError: Why committing a download failed.

Constants§

BIN_DIR: The folder of an entry holding one link per program name, appended to a session’s PATH.
EXECUTABLE_FILE_MODE: The mode of an executable file in the store; every other file is crate::murmur_home::PRIVATE_FILE_MODE and every directory crate::murmur_home::MURMUR_HOME_DIR_MODE.
FILES_DIR: The folder of an entry holding the downloaded program.
MAX_PINNED_DOWNLOAD_BYTES: The most bytes a download, and the tree unpacked from it, may hold: 2 GiB.
PARTIAL_PREFIX: The name prefix of an install in flight.
PROGRAMS_DIR: The store’s name under ~/.murmur.
RECORD_FILE: An entry’s record of what was fetched.

Functions§

commit_download: Unpacks a download whose bytes already hash to download.sha256 and moves it into <store_root>/<sha256>/ with its record and bin/<program> link.
derive_pinned_programs: The source of each program tools pin a download of for this host, for the programs shell_allow grants, against mur’s own PATH and ~/.murmur/programs.
ensure_bin_link: Adds bin/<program> to the verified entry for download when it is missing or points elsewhere. Ok(true) when a link was written.
ensure_program_store: ~/.murmur/programs, created owner-only (and ~/.murmur with it) when missing.
gated_programs: The programs of tools a session may run a pinned copy of, whatever the platform: only from a tool whose origin is LockOrigin::Operator, and only for a program key equal to an entry of shell_allow. Tools in the order given, programs in declaration order.
host_path_dirs: mur’s own PATH, split.
host_program: The first executable named program in path_dirs, canonical: the one execvp would run.
pinned_bin_dirs: The bin/ folder of every PinnedSource::Pinned choice, distinct, in order.
pinned_trees: The entry of every PinnedSource::Pinned choice, distinct, in order.
program_store_root: ~/.murmur/programs, whether or not it exists. Creates nothing.
read_record: Reads an entry’s record.json.
remove_entry: Removes the entry for sha256, whatever state it is in.
resolve_pinned_programs: derive_pinned_programs with the host injected.
tree_digest: The SHA-256 over files as sorted <path>\t<x|->\t<sha256>\n lines.
verify_entry: Verifies the entry for download.sha256 in full: reads its record, re-hashes every file under files/ and compares. Reads only.