Hubs and sources
The public hub, private hubs, which hub a package comes from, --hub and --from
As soon as you log in to a private hub, there are two places a package can come from: your team's hub and the public one. You need to know which one Gritpack asks, in what order, and what it will never do behind your back. You also want a way to say "this time, use only that hub". This chapter covers both, and how the lock file keeps every package tied to the hub it came from.
What you will be able to do
- predict which hub a package will come from;
- explain why Gritpack refuses to fall back to the public hub after an error;
- use one hub only, for one command, with
--from; - point a command at a hub and credential of your choosing, with
--hubor--profile; - understand why a locked package always comes back from the same hub.
The chain of hubs
Gritpack has one built-in hub, the public get.gritpack.org. Which hubs it
asks depends on your logins:
| Your logins | Gritpack asks |
|---|---|
| none | the public hub |
| a login to a private hub, as the default profile | the private hub first, then the public hub |
| several logins | the hub of the default profile (or the one --profile names) first, then the public hub |
This list is the chain. add, update, upgrade, sync, outdated and
install use it.
Here a project on a private hub adds an application that only the public hub has:
$ gritpack add @frogfish/scroll-throttle
added @frogfish/scroll-throttle and installed 3 packages into ./packages
$ gritpack list
@ada/greet 2.0.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/strings
@ada/strings 1.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
@frogfish/scroll-throttle 1.0.0 dialect=application/cli direct source=https://get.gritpack.org:443 dependencies=-
Gritpack asked the private hub first. The private hub said it has no package of that name at all, so Gritpack asked the public hub, found it there, and recorded that in the lock. The chain is applied to each package separately, including dependencies of dependencies.
When Gritpack does not fall back
The public hub is asked only when the private hub answers, with your valid login, that it has never heard of that exact name. Every other answer stops the command:
- the private hub cannot be reached, or its certificate is wrong;
- your login is expired, revoked or refused;
- the private hub has the name, but not a version that matches your requirement;
- the private hub has the name, but cannot offer it right now, for example because an administrator quarantined it.
$ gritpack add @ada/greet 9.0
cannot resolve @ada/greet: root requires @ada/greet ^9.0
Here the private hub owns @ada/greet and has no 9.x, so Gritpack stopped
with exit code 5. It did not go looking for an @ada/greet 9.0 on the public
hub.
This matters. If a broken connection or a missing version made Gritpack try the public hub, anyone who published a package there under your internal package's name could slip into your build. That trick is called dependency confusion, and the chain is built so it cannot happen: an outage is an outage, not a reason to install something else.
search and info do not use the chain at all. They read one hub: your
default profile's, or the public hub if you have none.
One hub only: --from
Sometimes you want one particular hub, ignoring the chain. Perhaps you want
the public package even though a private one shadows its name, or you want to
look at the public hub while your default login is a private one. --from
names the only hub to use, for this one command:
$ gritpack add @frogfish/scroll-throttle --from get.gritpack.org
added @frogfish/scroll-throttle and installed 1 packages into ./packages
$ gritpack search throttle --from get.gritpack.org
@frogfish/scroll-throttle 1.0.0 ecosystem=native score=250 dialect=application/cli variants=1 — Rate-limits X11 scroll-wheel events; ...
--from never falls back to anything. A login that --from does not use is
not even read, so a broken or expired profile cannot block it.
A private hub needs your credential. Give it with --from-cert, --from-key
and --from-ca:
gritpack search greet --from packages.example.com \
--from-cert ~/.frogfish/gritpack/credentials/<id>/client.pem \
--from-key ~/.frogfish/gritpack/credentials/<id>/client-key.pem \
--from-ca ~/.frogfish/gritpack/credentials/<id>/server-ca.pem
Without them, the command has no credential and no certificate authority for
that hub, and fails. Against a private hub whose certificate your system does
not trust, that is a connection failure, exit code 8. For everyday use,
--profile (below) is simpler.
--from applies to the whole operation. In a project whose lock already has
packages from another hub, add --from stops, because it may not use that
other hub to keep them:
$ gritpack add @frogfish/gritpack-bootstrap --from get.gritpack.org
locked package source https://packages.example.com:443 is not configured for this operation
In such a project, add without --from, or move the package deliberately as
described at the end of this chapter.
Choosing the hub and login: --profile and --hub
Without connection options, a command uses your default login profile.
gritpack auth list shows them, and gritpack auth use <name> changes the
default (chapter 21). For one command, choose another profile:
gritpack search greet --profile work
gritpack add @ada/greet --profile work
--profile changes the first hub in the chain; the public hub still follows
it.
--hub names the hub directly instead of a profile. It takes host,
host:port or https://host:port:
gritpack search greet --hub packages.example.com
With --hub alone, Gritpack looks in your credentials folder for a login to
that hub and uses it, provided there is exactly one that has not expired. With
none, or several, it stops rather than guess. You can also give the credential
yourself:
gritpack search greet --hub packages.example.com \
--cert client.pem --key client-key.pem --ca server-ca.pem
--profile and --hub cannot be combined:
$ gritpack search greet --hub packages.example.com --profile work
invalid package connection: --profile cannot be combined with explicit --hub/--cert/--key/--ca
Each option has an environment variable, for scripts and CI:
| Option | Environment variable |
|---|---|
--profile | GRITPACK_PROFILE |
--hub | GRITPACK_SERVER |
--cert | GRITPACK_CERT |
--key | GRITPACK_KEY |
--ca | GRITPACK_CA |
A flag on the command line always wins over its variable.
| You want | Use |
|---|---|
| your usual hub, with public fallback | nothing |
| another of your logins, with public fallback | --profile <name> |
| a hub by address, with a login saved for it | --hub <host> |
| exactly one hub, no fallback, for this command | --from <host> |
A locked package stays where it came from
The lock records each package's hub in source_server:
[[packages]]
name = "@frogfish/scroll-throttle"
version = "1.0.0"
...
source_server = "https://get.gritpack.org:443"
From then on, that package belongs to that hub. sync downloads it only from
there. update, upgrade and outdated look for newer versions only there,
and never swap it for a package of the same name on another hub, even one
earlier in the chain.
If the hub a package was locked from is not one Gritpack may use, the command stops and says so:
$ gritpack sync
locked package source https://packages.example.com:443 is not configured for this operation
That happens when the login for that hub is missing from this machine (exit code 2). Log in to it (chapter 20) and run the command again.
--offline is the exception that proves the rule: it uses no hub at all, so it
works with no logins, from the cache (chapter 6).
Moving a package to another hub on purpose
Because a locked package never changes hubs by itself, moving one is a deliberate act:
- Delete its line from
gritpack.tomland rungritpack sync, so it leaves the lock. - Add it again from the hub you want: plainly, so the chain decides, or with
--from <hub>in a project that has no packages from other hubs. - Review and commit the changed
gritpack.lock.
Ecosystem tools have their own registries
Everything above is about Gritpack's own resolution. Cargo, npm and Go keep deciding where their packages come from, and Gritpack only configures them: the hub becomes an extra Cargo registry next to crates.io, an npm registry for the scopes you route to it, and a Go proxy for your private module paths. Chapters 10 to 12 show each.
What just happened
With no login, everything comes from the public hub. With a private login, the
private hub is asked first and the public hub only for names the private hub
has never heard of, so an outage or a missing version can never turn into a
stranger's package. --from uses exactly one hub, --profile and --hub
choose the first hub and the credential, and the lock pins every package to
the hub it came from.
You can stop here
You have finished the everyday part of the guide. If you use packages in your own projects, you know everything you need. Readers who use Cargo, npm, Go or C and C++ can go to their chapter next; the rest of the guide is for publishing, teams and automation.
Next
- Your language: Rust and Cargo, npm, Go modules or C and C++.
- Optional: logins, profiles and several hubs in depth, in Logins and profiles.