Hubs and sources

The public hub, private hubs, which hub a package comes from, --hub and --from

Chapter 9 of 34Current for Gritpack 1.2.63Source: docs/guide/09-hubs-and-sources.md

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 --hub or --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 loginsGritpack asks
nonethe public hub
a login to a private hub, as the default profilethe private hub first, then the public hub
several loginsthe 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:

OptionEnvironment variable
--profileGRITPACK_PROFILE
--hubGRITPACK_SERVER
--certGRITPACK_CERT
--keyGRITPACK_KEY
--caGRITPACK_CA

A flag on the command line always wins over its variable.

You wantUse
your usual hub, with public fallbacknothing
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:

  1. Delete its line from gritpack.toml and run gritpack sync, so it leaves the lock.
  2. 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.
  3. 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