Holger living inside another program — for idiots
Class:
idiot. No jargon. What "embedding" means and why it's a marriage, not a phone call. The code walk-through isembed-guide.md.
The idea
Holger doesn't have to be a separate server you talk to over the network. Another program (written in Rust) can link holger as a library and run a little package registry right inside its own process. No socket, no waiting on the network — it just calls holger's functions directly: "list the repos," "give me this package's bytes," "store these bytes."
Picture it as a marriage
Instead of two programs phoning each other across a network, holger and its host program live in one house. When the host wants to know "what crates are in this registry?", it just calls holger's function — no network hop, no packing the question into a message and unpacking the answer again. holger hands back the very same data it holds internally. The program that marries holger this way is nornir; its package-browser pane lists what's inside the registries by calling holger's list function directly.
The two little registries (the shared rooms)
The reference setup is a dev pair — two tiny registries holger can spin up for local development:
/cache— a transparent mirror of crates.io. Ask it for a crate; if it doesn't have it yet, it fetches it from the internet once and keeps a copy./sparring— a practice registry for rehearsing a package release before it goes anywhere real.
These two are the rooms nornir and holger share.
One bug worth knowing about (already fixed)
When a registry was the writable dev kind (like /cache and /sparring), asking it "what's inside you?" used to come back empty even when it held packages — it was peeking at the wrong handle. It now re-opens the live view, so the list is correct (commit 8c9e458). If you ever see an embedded dev registry look empty, that's the fix you need.
Why marry instead of phone?
Two reasons. Speed — a function call is instant; a network round-trip is not. And simplicity — there's no server to start, no port to open, no certificate to configure. The host program already owns its own security; holger just rides along inside it. The trade-off is that only that one program can use this registry — if independent machines need to reach it, run the real holger-server instead.