Skip to Content

Rust API

The hatchery crate is one Client, one trait for each extension point, and plain data types. A tool extends it with its own trait implementations and never changes the crate.

[dependencies]
hatchery = { git = "https://github.com/aiviarium/hatchery", tag = "v0.1.0", features = ["http"] }
FeatureAdds
httphatchery::fetch::HttpFetch, a Fetch over HTTP(S) with ureq. Without it, you bring your own
blockinghatchery::blocking, a blocking wrapper around Client

Both are off by default. The library has no async runtime. hatchery::block_on runs a future to completion on the current thread.

The futures block the thread they run on. They run git and wait for it, and HttpFetch waits for ureq. An async caller runs each client call on a thread for blocking work, such as tokio::task::spawn_blocking, and drives it there with block_on. A Fetch of your own that does not block doesn't help with a git registry, since git still blocks.

A usage example

use std::path::Path;

use hatchery::fetch::HttpFetch;
use hatchery::{Client, Config, Spec, StaticTarget, block_on};

fn install(dir: &Path) -> hatchery::Result<()> {
    let config = Config::load(Path::new("hatchery.kdl"))?;
    let client = Client::builder()
        .config(config)
        .target(StaticTarget::new("crow").fact("crow", "1.2.0"))
        .fetch(HttpFetch::new())
        .build()?;

    let spec = Spec::parse("aiviarium/claude@^1.4")?;
    let report = block_on(client.add(&spec, dir))?;
    for change in &report.packages {
        println!("{} {}", change.name, change.version);
    }
    Ok(())
}

Target

What a tool tells Hatchery about itself.

pub trait Target: Send + Sync {
    fn name(&self) -> &str;
    fn fact(&self, name: &str) -> Option<String>;
    fn variants(&self) -> Variants { /* the variant for this machine */ }
    fn check(&self, files: &TargetFiles) -> Result<(), Vec<Problem>> { Ok(()) }
    fn derive(&self, dir: &Path) -> Result<Option<Manifest>> { Ok(None) }
}
MethodMeaning
nameThe name under targets this tool installs, such as crow
factAnswers a name from a requires block. None means it is absent. os and arch fall back to the platform of variants, or this machine
variantsVariants::Matching(Platform) fetches the variant for that platform at install, and is the default with Platform::current(). Variants::OnDemand fetches none, and Client::variant fetches each when it is first needed
checkCalled at pack and at install with the target's files. It reads the tool's own manifest and returns a list of Problems
deriveFor a folder without a package.kdl: derive one from the tool's own manifest

TargetFiles holds the files of one target by path, relative to the target's folder. The variants folder is not part of it. StaticTarget is a Target that answers from a fixed table. The hatchery command uses it for --target and --fact.

Source

Where packages come from. Git repositories, static registries, single git folders, folders and files are built in.

pub trait Source: Send + Sync {
    fn label(&self) -> &str;
    fn is_local(&self) -> bool { false }
    fn warnings(&self) -> Vec<String> { Vec::new() }
    fn names(&self) -> BoxFuture<'_, Result<Vec<Name>>>;
    fn versions<'a>(&'a self, name: &'a Name) -> BoxFuture<'a, Result<Vec<Offer>>>;
    fn details<'a>(&'a self, offer: &'a Offer) -> BoxFuture<'a, Result<Details>>;
    fn fetch<'a>(&'a self, offer: &'a Offer) -> BoxFuture<'a, Result<Egg>>;
    fn fetch_variant<'a>(&'a self, offer: &'a Offer, target: &'a str, key: &'a str)
        -> BoxFuture<'a, Result<Egg>>;
}

names, details, fetch_variant and warnings have default bodies. warnings reports what the source skipped, such as a package whose package.kdl it cannot read. The client adds them to its reports and listings. Source::fetch returns an egg whose checksum and signature the source has verified, and whose manifest names the offered package and version.

A tool adds a kind of registry with ClientBuilder::kind(name, factory). A registry line of that node name is then served by the factory's source.

ItemMeaning
OfferOne version a source offers, with its registry label, times, checksum and signature, and for git its commit, ref and path. needs_signature marks a version of a keyed registry that has only a tag. It is never installed
DetailsDisplay data and the targets of a version, so that resolving a version can skip the egg
StaticRegistryA static registry, from StaticRegistry::dir, ::http or ::new over any RegistryFiles
GitRegistry, GitFolder, FolderSource, FileSourceThe other built-in sources. GitRegistry::unsigned_tags(true) lets a keyed registry install tag-only versions

Fetch

How bytes are fetched over HTTP. The tool passes its own client.

pub trait Fetch: Send + Sync {
    fn get<'a>(&'a self, url: &'a Url, auth: Option<&'a Token>)
        -> BoxFuture<'a, Result<Option<Bytes>>>;
}

A 404 is Ok(None) so that search order works. Any other failure is Error::Http. Token is a bearer token. Token::from_env reads it from a variable, and Debug doesn't show it.

Client

Built with Client::builder():

Builder methodMeaning
config(Config)The registries and the default minimum release age
target(impl Target), target_arcA tool this client installs for. Call it once per target
fetch(impl Fetch), fetch_arcHow HTTP registries and egg addresses are fetched. Without one, they fail
cache_dir(path)Where git checkouts are cached. $HATCHERY_CACHE by default, or hatchery in the user's cache folder when it is not set
clock(Clock)The time source, for tests
git(Git)The git program to run
kind(name, factory)Registry lines of this node name
build()Returns the Client
Client methodMeaning
offered(dir).awaitA Listing: the packages the registries offer, each with its about data, versions, installed version and available update, and when a held version can be installed. Its warnings say what a registry skipped
add(spec, dir).await, add_with(spec, dir, &Options)Resolves, verifies, unpacks and locks a package and its dependencies. Options::allow_young skips the minimum release age for the package you add
update(name, dir).awaitUpdates one package, or all with None
install(dir).awaitInstalls exactly what eggs.lock lists
remove(name, dir)Removes a package. Refuses while a dependent is installed
installed(dir)The packages in a folder, as Installed
withdrawn(dir).awaitThe installed packages whose version their registry has withdrawn since, with the reason
variant(&Installed, &Platform).awaitThe files of one variant. Downloads and verifies its egg on first use
fetch(spec, variants, &Options).awaitFetches the base egg and variant eggs without installing. variants are named <target>.<key>, all when None

add, update and install return a Report. It has the folder and the Changes, with dependencies first. It also has warnings, such as a withdrawn version that stays installed. A Change has the name, the version, the version before, the SHA-256, the registry label and the Egg.

A Spec is parsed from text with Spec::parse: Registry(Wanted), Git { url, path, git_ref }, Folder or File. A Name is group/id.

Egg

An opened archive. Egg::open checks each entry.

MethodMeaning
Egg::open(bytes), Egg::read(path)Opens an egg of any kind. Refuses unsafe entries
Egg::pack(dir, targets)Packs a folder into a base egg without a build, checking each target
Egg::from_entries(entries)Builds an egg from Entry values, written deterministically. Entry::new(path, data) makes one
manifest()The package, about, targets and origin
variant()The header of a variant egg, None for others
is_fat()Whether variant eggs are inside
target(name)The shared files of one target, as TargetFiles
subset(&[targets])The same egg with only those targets. None when it has none of them
sha256(), bytes(), file_name()The checksum, the archive and the egg's name
embedded_variants(), embedded_variant(target, key)The variant eggs inside a fat egg
base()A fat egg without its variants, byte for byte the base egg it was made from
fatten(&[variants])A fat egg made of this base egg and the variant eggs you pass
unpack(dest)Unpacks into a package folder

hatchery::pack(dir, &PackOptions) is hatchery pack. It returns the variant eggs first and the base or fat egg last. PackOptions::new() starts the options, and its methods set them: base, variant(VariantPick), fat, no_build and check. defaults, origin and now replace what is otherwise read from packages.kdl, git and the clock. git(Git) sets how pack runs git.

let opts = PackOptions::new()
    .no_build(true)
    .variant(VariantPick::new("rookery").os("linux").arch("x86_64"));
let eggs = hatchery::pack(dir, &opts)?;

Publishing and tree_digest

pub fn publish(egg: &Egg, to: &PublishTo, key: Option<&SigningKey>) -> Result<Published>;
pub fn tree_digest(dir: &Path) -> Result<String>;

PublishTo::Dir(path) publishes into a static registry folder. PublishTo::Git { url, branch, path } publishes to a branch of a git repository, creating the branch when it does not exist. Published reports the file name, SHA-256, whether it was signed and the publish time. publish_at takes the time as an argument. publish::withdraw_dir marks a version withdrawn.

tree_digest is a checksum of a folder's files. It covers the paths, the executable bit of each file and the contents. The same files give the same digest on any machine. A tool can compare the digest of an installed package with what a host applied.

Signing

The sign module has parse_signing_key, parse_verifying_key, format_signing_key, format_verifying_key, message, sign and verify. Keys are written ed25519: and 64 hex digits.

Data types

The structs with public fields and the enums other than Error are marked non_exhaustive, so a later version can add a field or a variant. Read their fields and match with ... To make one, use its constructor or its builder:

TypeMade with
PackOptions, VariantPick, Options, Originnew() and setter methods
Offer, Details, TargetInfo, VariantInfo, Withdrawnnew(…), then set the public fields. For a Source of your own
Problem, TargetFiles, Manifest, Requirement, VariantSpec, Dependencynew(…). For a Target of your own
EntryEntry::new(path, data), and .executable(true)
Name, Spec, Config, RegistryConfigName::new and parse, Spec::parse and Spec::git, Config::load and parse, RegistryConfig::new

Errors

hatchery::Error is one enum, marked non_exhaustive. Match on the variants below. Each variant that gives a reason a package cannot be installed has an At with the package, version and registry, and its Display text is a sentence a person can read. Error::at() returns the At when there is one.

VariantMeaning
ChecksumMismatchThe bytes do not have the checksum the index or the lock file gives
SignatureInvalidThe registry has a key and the egg is not signed by it
UnmetA line of a target's requires block does not hold. Names the target, the fact, what was wanted and what was found
NoVariantThe target declares variants and none is for this platform
TooYoungThe version is younger than the minimum release age. Carries the time it becomes installable
WithdrawnThe version was pulled, with an optional reason
NotBuiltA git registry has no built egg and a wanted target needs a build
TagMovedA tag points at a different commit than the lock file records
RequiredByA package cannot be removed while dependents are installed
NotFoundNo registry has the package, or no version in the range
AmbiguousAn id alone matches packages of several groups
ConflictNo set of versions fits all the ranges
InvalidA manifest, configuration, lock file or index is not valid
UnsafeArchiveAn egg has an entry that unpacking refuses
CheckA target's own check refused its files, with the list of Problems
BuildA build command failed
Git, Http, Io, OtherA failed git command, a failed fetch, an I/O error with its path, and anything else
Edit on GitHub

Last updated on

On this page