Mirrors

A mirror registry serves crates that come from an upstream registry instead of from cargo publish. Haven pulls crates through on demand, caches them, and applies your registry policy on top: what the upstream serves is what exists; what your policy promotes is what your builds get.

Upstream kinds

The upstream is declared at creation and is immutable:

• crates.io: the default upstream. Consumers can use the mirror as a drop-in replacement for crates.io (see Consuming crates). crates.io mirrors also get ecosystem metadata: catalog imports from the public database dump, RUSTSEC advisories, and publisher facts.
• Another sparse registry: any registry that speaks the sparse index protocol, by URL. Consumed as a named registry. Metadata sources are limited to what the registry itself serves.

Subset mode and the allowlist

By default a mirror exposes the whole upstream. Turning on subset mode flips it to an allowlist: only listed crate names exist in the registry. You can add names one by one, or import the exact set your project already uses from a Cargo.lock file. The allowlist records who added each entry and how.

Subset mode is how you run a curated registry: nothing enters the build’s universe without someone putting it on the list.

The catalog and the dump

For crates.io mirrors, Haven loads the upstream catalog from the crates.io database dump so the registry can list and count crates without hammering the upstream:

• Full load: the entire catalog.
• Subset load: only allowlisted crates.

The registry shows the dump’s “as of” time. Haven refreshes the dump automatically (every 6 hours by default, skipping unchanged dumps), and owners can trigger a refresh manually.

First seen and quarantine

A mirror cannot trust upstream publish times for gating, so Haven stamps each version when the mirror first sees it. The quarantine policy rule counts from that stamp: a new upstream release spends its quarantine being watched by the ecosystem before your builds can pick it up. Versions that existed before the mirror was created pass quarantine immediately; enabling a quarantine never freezes history you already depend on.

Advisories

For crates.io mirrors, Haven syncs the RUSTSEC advisory database on a schedule and files advisories against affected versions automatically, including withdrawals and reclassifications. Whether an advisory holds a version is controlled by the advisory_levels policy rule; with no levels selected, advisories are recorded and displayed but never block. See the Policy rules reference.

Owners can also raise an advisory manually on any version, in any registry kind.

The upstream watchdog

Every download through a mirror is verified against the checksum its upstream publishes, so bytes that do not match are refused. The watchdog is the longer memory. It records the checksum of each version the first time it sees one, and rechecks it later; if the upstream serves a different checksum for a version it already published, or drops that version entirely, Haven files an advisory on the affected crate and writes an audit event.

A disappearance has to be seen twice before it is reported. An upstream that 404s a crate during a CDN purge or a redeploy has not withdrawn anything, and an advisory outlives the glitch that caused it, so the first miss is only noted and the recheck after it decides. An upstream Haven cannot reach at all, or that answers with something it cannot read, is never treated as a withdrawal either.

The advisory is filed at level notice, so by default it is recorded and displayed without holding anything. That is deliberate: a rewritten version is already resolved into lockfiles and already downloaded, so there is nothing to un-ship, and treating it as a hold would hide an incident behind a build failure. An operator who wants the hold adds notice to advisory_levels.

Rechecking means requests to somebody else’s registry, so the rate is yours to set: the registry’s settings page takes a requests-per-minute figure, 0 turns it off for your mirror, and blank takes the instance default. Registries that mirror the same upstream share one sweep, and the slowest rate anybody asked for governs it — turning yours off only removes your vote, it never stops a sweep somebody else wants. The watchdog covers what your mirror has actually served rather than an upstream’s whole catalog, and only mirrors that pulled a crate are told about an incident on it. Mirrors of a registry on the same Haven are not watched: nothing there can be rewritten in the first place.

Operators enable it with [mirror_watchdog], on one instance.

Version pins

The pinned policy rule freezes a crate to a version requirement, org-wide: only matching versions of that crate serve from the mirror, and everything else — including versions upstream publishes after the pin is set — is held on sight. Unlike a Cargo.lock, which pins one repository and drifts on cargo update, the pin is enforced at resolution for every project and CI job consuming the mirror. Versions newer than the latest dump are judged from the first-seen clock, so a fresh upstream release never slips through while a refresh is pending. Pins cannot be waived; editing or removing the pin is the release. Details are in the Policy rules reference.

Publisher trust

The new_publisher rule defends against maintainer-change attacks: a crate whose new release comes from a publisher who had never released it before your chosen cutoff is held until enough owners vouch for that publisher. The Held tab offers Trust publisher on affected versions. Details are in the Policy rules reference.