Baller supports multiple package sources with a configurable fallback chain.
The RegistryClient in src/core/registry.rs coordinates all sources.
Queries the GitHub Releases API at api.github.com/repos/{owner}/{repo}/releases/latest.
- Matches assets by platform (Linux/Windows) and architecture (x86_64/aarch64),
understanding Rust target triples, Go-style
os_archnames and bare arch tokens, and excluding distro packages, checksums, signatures and foreign OS/arch builds. A release with no host build is a hardNoMatchingAsseterror — there is no arbitrary "first asset" fallback. See error-handling.md - Parses owner/repo from the package source metadata
- Falls back to search via repository topic tags
A custom registry API at a configurable base URL (default https://registry.baller.dev/api).
- Versioned package metadata endpoint
- Search endpoint for scouting packages
- Structured JSON responses with dependency information
Queries a NuGet OData v2 feed (default https://community.chocolatey.org/api/v2).
- Accept header must be
application/json;odata=verbose— the OData v2 endpoint rejects plainapplication/jsonwith HTTP 406 Not Acceptable - Uses OData protocol for package lookup
- Normalizes NuGet version schemes to semver (strips trailing
.0build revisions) - Parses dependency strings from NuGet package metadata
- Download URL is derived from
__metadata.media_srcin the OData response (theDownloadUrlproperty does not exist on the v2 feed and requests that include it in$selectare rejected). Whenmedia_srcis absent, the URL falls back tohttps://community.chocolatey.org/api/package/{id}/{version}. - Hash verification uses the algorithm reported by Chocolatey
(
PackageHashAlgorithmfield). The hash is base64-encoded — it is decoded and compared against the SHA-512 (or SHA-256) hex digest of the downloaded archive. Thehash_algorithmfield on thePackagestruct carries the algorithm name so the downloader selects the correct verification path.
Wraps the system's native Linux package manager (apt, dnf, or pacman) via CLI commands.
Only active on Linux systems; auto-detects distro from /etc/os-release.
- Distro detection: Reads
IDfield from/etc/os-release, maps to apt/dnf/pacman - Detection table:
- Ubuntu, Debian, Linux Mint, Pop!_OS, Elementary OS, Zorin, Kali, Raspbian →
apt - Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux, Oracle Linux, Nobara →
dnf - Arch Linux, Manjaro, EndeavourOS, Garuda Linux, Arco Linux →
pacman
- Ubuntu, Debian, Linux Mint, Pop!_OS, Elementary OS, Zorin, Kali, Raspbian →
- Fetch: Shells to
apt-cache show,dnf info, orpacman -Sifor package metadata - Search: Shells to
apt-cache search,dnf search, orpacman -Ssfor package listings - Dependencies: Parses native dependency lists (comma-separated for apt, space-separated for dnf/pacman)
- Install: Runs
sudo <pm> install -y <name>to install packages via the native manager - No HTTP client needed — operates entirely via local CLI
// Package source metadata includes the detected manager
PackageSource::System { manager: "apt" } // or "dnf" or "pacman"
RegistrySource::System // registry-level source enumWraps the locally installed cargo toolchain to resolve and install crates from
crates.io. Enabled by default on Linux; available everywhere cargo is on PATH.
-
Detection: Probes
cargo --version; an absent toolchain degrades to a source that reportsPackageManagerErrorinstead of failing the build -
Command table:
Purpose Command Fetch cargo info <name>, falling back tocargo search <name> --limit 20Search cargo search <query> --limit 20Install cargo install <crate> -
No
sudo— cargo compiles into the user's~/.cargo/bin -
No version pinning:
cargo installalways takes the latest release, so--versionagainst this source returns aPackageManagerError -
No HTTP client needed — operates entirely via local CLI
// Package source metadata carries the crate name
PackageSource::Cargo { crate_name: "ripgrep" }
RegistrySource::Cargo // registry-level source enumSources are tried in the order specified by source_order in the config.
The first source to return a successful result wins. When all sources
fail, the error message lists every source that was tried and the reason
it failed (so you can see why GitHub returned "not found" and why
Chocolatey returned 406, not just the last one).
Windows: request → [Baller Registry] ?→ [Chocolatey] ?→ [GitHub]
Linux: request → [Baller Registry] ?→ [System PM] ?→ [Cargo] ?→ [GitHub]
↓ failure ↓ failure ↓ failure ↓ failure
try next try next try next return error
The default source_order is platform-derived:
| Platform | Default source_order |
|---|---|
| Windows | baller, chocolatey, github |
| Linux | baller, system, cargo, github |
The Baller registry comes first (it is not implemented yet, so it currently fails fast and falls through), the platform's native ecosystem comes next, and GitHub is always the last-resort fallback so GitHub-based installs keep working everywhere.
A source that does not belong to the platform is disabled by default —
chocolatey_enabled is false on Linux, and system_enabled and
cargo_enabled are false on Windows — and SystemRegistry detection is
skipped entirely off Linux. All three remain available as an explicit opt-in via
the _enabled flags below.
Entries in source_order that match no known source are ignored.
Every source declares which hosts it can serve, and the chain is unchanged by it — the scoping applies to what a source resolves, not to the order sources are tried in:
| Source | Serves |
|---|---|
chocolatey |
Windows only (a .nupkg payload is Windows-targeted) |
system |
Linux only (reads /etc/os-release, drives apt/dnf/pacman) |
github |
Any host; the asset is picked per OS/arch by the release selector |
baller |
Any host; the registry decides server-side |
cargo |
Any host; cargo install builds for whatever host runs it |
A package that resolves to a source the host cannot use is a hard error,
not a fallback to the next source: draft, substitute, update and build
check every package they would install before the dry-run report, before any
hook and before anything is downloaded, and fail with UnsupportedOs. That
covers every way a source is reached — the configured chain (say,
chocolatey_enabled = true on Linux), --source, and a manifest's
[source]. --source is checked before anything is fetched from it at all.
Behind that check, the binary every install extracts is inspected byte-wise:
a PE/Windows executable on Linux (or an ELF on Windows) fails with
PlatformMismatch whichever source supplied it. See
docs/error-handling.md.
[registry]
# Source resolution order (comma-separated), overrides the platform default
source_order = baller,system,cargo,github
# Custom registry URLs
baller_registry_url = https://registry.baller.dev/api
chocolatey_feed_url = https://community.chocolatey.org/api/v2
# Per-source enable/disable flags (defaults follow the platform)
github_enabled = true
baller_enabled = true
chocolatey_enabled = true
system_enabled = true
cargo_enabled = trueEach source has an _enabled boolean flag. When disabled, the source is skipped
entirely during the fallback chain — useful for offline work or isolating issues.
Disabling a source takes precedence over source_order — a disabled source is
silently dropped from the resolved list.
# Use only the baller registry, skip GitHub and Chocolatey
source_order = baller,chocolatey,github
github_enabled = false
chocolatey_enabled = false// Fetch the latest version of a package (tries sources in order)
let pkg = client.fetch_package("ripgrep")?;
// Search across all sources
let results = client.search("rip")?;
// Fetch from a specific source
let pkg = client.fetch_package_from_source(&RegistrySource::GitHub, "ripgrep")?;To add a new registry source:
- Create a new module in
src/http/(e.g.,src/http/my_registry.rs) - Implement the
RegistryIndextrait (fetch_package+search) - Add a variant to the
PackageSourceenum insrc/core/package.rs - Add a variant to the
RegistrySourceenum insrc/core/registry.rs - Wire it into
RegistryClientinsrc/core/registry.rs - Add config keys for the new source in
src/config/config.rs - Add the enabled flag filter in
AppContext::new()insrc/context.rs
The System registry (src/http/system.rs) and the Cargo registry
(src/http/cargo.rs) demonstrate non-HTTP registry sources — Cargo follows the
same local-CLI pattern the System source established. Key differences from
HTTP-based sources:
- No
HttpClientdependency — usestd::process::Commandfor CLI calls - Auto-detects capability at construction time via
detect()(returnsNoneif no PM found) - Gracefully returns
BallError::PackageManagerErrorwhen no manager is available - Stores detected manager in
PackageSource::System { manager: "apt" }for provenance (Cargo stores the crate name inPackageSource::Cargo { crate_name: "ripgrep" })
See docs/system-registry.md for the complete reference.
See docs/cargo-registry.md for the complete reference.