- Feature Name: source_replacement_ambiguity
- Start Date: 2022-07-05
- RFC PR: rust-lang/rfcs#3289
- Tracking Issue: rust-lang/cargo#10894
When Cargo is performing an API operation (
publish/etc.) to a source-replaced
crates-io, require the user to pass
--registry <NAME> to specify exactly which registry to use. Additionally, ensure that the token for
crates-io is never sent to a replacement registry.
There are multiple issues that this RFC attempts to resolve around source-replacement.
- When Cargo is performing an API operation, source replacement is only respected for
crates-io, not alternative registries. This is inconsistent.
- The error message for attempting to publish to a replaced crates-io is confusing, and there is no workaround other than temporarily removing the source replacement configuration.
- When performing an API operation other than
publishwith a replaced
crates-iocredentials are sent to the replacement registry's API. This is a security risk.
- It's unclear which credentials should be used when fetching a source-replaced authenticated alternate registry (RFC 3139).
crates-io source is replaced, the user needs to specify
--registry <NAME> when running an API operation to disambiguate which registry to use. Otherwise,
cargo will issue an error.
cargo only sends the token associated with a given registry to that registry and no other (even if source replacement is configured).
When replacing a source with a registry, the
replace-with key can reference the name of a registry in the
Local source replacement (vendoring)
A repository has a local
.cargo/config.toml that vendors all dependencies from crates.io. Fetching and building within the repository would work as expected with the vendored sources.
If the user decides to publish the crate,
cargo publish --registry crates-io will ignore the source-replacement and publish to crates.io.
crates-io mirror registry
A server has been set up that provides a complete mirror of crates.io. The user has configured a
~/.cargo/config.toml that points to the mirror registry in the
[registries] table. The mirror requires authentication to access (based on RFC 3139).
The user can log in to the mirror using
cargo login --registry mirror. Fetching and building use the mirror.
The user decides to publish the crate to crates.io, and does
cargo login --registry crates-io to log in to crates.io. Source replacement is ignored, and the token is saved.
Next, the user runs
cargo publish --registry crates-io to publish to crates.io. Cargo ignores source replacement when building and publishing the crate to crates.io.
Change 1: respect
When running an API operation (
yank), Cargo always uses the registry specified by
--registry <NAME>, and never a source-replacement.
Change 2: error for replaced crates-io
When running an API operation (as defined above) and ALL of the following are true:
crates-iohas been replaced by a remote-registry source.
- command line argument
--registry <NAME>is not present.
- command line argument
--index <URL>is not present.
publish = <NAME>is not set (only applies for publishing).
cargo issues an error:
error: crates-io is replaced: use `--registry replacement` or `--registry crates-io`
Change 3: credentials are only sent to the same registry
crates-io source is replaced with another remote registry, the credentials for
crates-io are never sent to the replacement registry. This makes
with alternative registries and ensures credentials are only sent to the registry they are
[source] table can reference
replace-with key in the
[source] table can reference a registry defined in the
For example, the following configuration would be valid:
[source.crates-io] replace-with = "my-registry" [registries.my-registry] index = "https://my-registry-index/"
This is necessary to allow the
--registry <NAME> command-line argument to work with source-replaced registries. It also allows additional configuration (such as a token) to be specified for a source-replacement registry without duplicating configuration between
Behavior is changed around where credentials are sent, which could break some workflows.
If a mirror of crates.io is set up with
"api": "https://crates.io", then the current system of sending the crates.io token to the replaced source would work correctly, and this RFC would break it.
Rationale and alternatives
Alternative: ignore source replacement for API operations
When doing an API operation with a replaced
cargo would ignore source replacement without additional arguments. This is how alternative registries currently work.
If the user wants to use the replacement, they could pass
--registry <NAME>, but would not be required to do so.
A new option
--respect-source-config could be added to make cargo follow the source replacement for API operations (similar to what we already have for
This may be too confusing for users since it silently changes behavior. The RFC proposes a solution that requires the user to be explicit about which registry to use in the ambiguous situation (crates-io replacement).
Alternative: disallow source replacement for API operations
Attempting an API operation on a replaced source would be an error. The user could use
--registry crates-io to explicitly bypass the source replacement.
Error: <operation> is not supported on replaced source `crates-io-mirror`; use `--registry crates-io` for the original source
Other package managers don't seem to have a source replacement feature.
--registry <NAME> command line argument be allowed to reference the name of a
source from the
[source] table as well? This makes it more flexible, but adds potentially unnecessary complexity.
Cargo's tests rely on the ability to replace the crates.io source and have the crates.io credentials go to the replaced source. We need a way for these tests to continue working.
Can't think of anything.