config.trb

config.trb belongs to a machine, not to a project: it says where this machine fetches the files of a registry from. Today it has one setting, mirror. A build machine behind a firewall, a team with a copy of the registry in its own network, or a laptop with a copy on a disk names its mirrors here, and every project on the machine uses them without a line of its own changing. Like project.lock.trb, it is a receiver script of literals that the toolchain reads statically and never evaluates.

Synopsis#

// ~/.torb/config.trb

mirror "https://packages.internal.test"
mirror "file:../registry-copy"

There is no file by default, and no file means no mirror.

What it does#

A mirror line#

mirror "<url>" names a directory of the same files as a registry - index/<owner>/<name>.trb, index/config.trb and archives/<owner>/<name>/<version>.tar.gz - as an https: or http: URL, or as file: and a directory. A relative file: path is relative to the directory of config.trb, not to the project. A / at the end of a URL makes no difference.

The file is strict, so a typo never turns a mirror off without a word. Each of these is an error at its line, and the package command stops before it fetches anything:

$ torb install
error: /home/ada/.torb/config.trb:2: `mirrors` is not a setting of config.trb, which has `mirror "<url>"` lines

• a line that is not mirror "<url>" - another word, a computed value, a second argument or a label;
• a URL that is neither https:, http: nor file: and a directory;
• a mirror named twice, which names the line it was named on first.

Where a file comes from#

torb add, torb update, torb install and every other command that fetches asks the mirrors in the order of the file, and the registry itself last. The first source that has the file answers it:

• a mirror that answers 404 or 410, a file: mirror without the file, and a mirror that cannot be reached are passed over, and the next source is asked;
• where no source has the file and one could not be reached, the error names every source and what it answered:

$ torb install
error: archives/acme/json/1.2.0.tar.gz of https://packages.torb.dev could be fetched from none of its sources: the mirror https://packages.internal.test has no archives/acme/json/1.2.0.tar.gz; https://packages.torb.dev/archives/acme/json/1.2.0.tar.gz: curl answered 000 curl: (6) Could not resolve host: packages.torb.dev

Only a registry on the network is mirrored. A file: registry is already a directory of this machine and is read as it stands, and torb publish always writes to or uploads to the registry itself.

A mirror is never trusted#

A mirror can withhold a release, but it can never change one. What it serves is checked exactly like what the registry serves:

• the index/config.trb it serves is checked against the keys torb ships with or has pinned for the registry, and a list that names none of them, or a key none of them endorsed, is refused;
• every record of an index file it serves is checked against those keys (the signatures of the index);
• every archive it serves is checked against the tree hash the lock pins.

A refusal names the mirror, and nothing it served is written into the cache:

$ torb update
error: the index of acme/json from the mirror https://packages.internal.test of https://packages.torb.dev/ is refused: the signature of the release 1.2.0 does not verify with a key of the registry

The first contact with a registry - the one that pins its keys - happens only with the registry itself. Before torb trusts any key of a registry, it does not read that registry's index/config.trb from a mirror.

What stays the same#

• The lock names the registry, never a mirror. A lock written through a mirror is byte for byte the lock written without it, so a project's lock does not depend on the machine that wrote it.
• The cache keeps the copy of an index file under the registry it belongs to, whichever source served it.
• --offline reads the cache and contacts no mirror.

Pitfalls#

A mirror cannot introduce a registry. For a registry whose keys this machine has neither shipped nor pinned, the first command has to reach the registry itself. After that, its mirrors are enough.

A stale mirror is not an error. A mirror that does not have a new release yet answers 404 for its archive, and the registry answers instead. A mirror whose index is older than the lock may make torb update see fewer releases than the registry has.

Examples#

A copy of the registry on a disk, tried before the network:

// ~/.torb/config.trb
mirror "file:/mnt/torb-registry"

A build machine that uses a configuration of its own for one run:

$ TORB_CONFIG=ci/config.trb torb install
installed acme/json 1.2.0
1 package installed, 0 of them already in the cache

Related#

• torb add, torb install - the commands that fetch through the mirrors.
• project.lock.trb - what a mirror never changes.
• RELEASE.md section 7.5 - the design.