Summary

When Cargo is performing an API operation (yank/login/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.

Motivation

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 publish with a replaced crates-io source, the crates-io credentials 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).

Guide-level explanation

When the 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 [registries] table.

Example scenarios

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.

Reference-level explanation

Change 1: respect --registry

When running an API operation (login, logout, owner, publish, search, 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-io has been replaced by a remote-registry source.
  • command line argument --registry <NAME> is not present.
  • command line argument --index <URL> is not present.
  • Cargo.toml manifest key 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

If the crates-io source is replaced with another remote registry, the credentials for crates-io are never sent to the replacement registry. This makes crates-io consistent with alternative registries and ensures credentials are only sent to the registry they are associated with.

Change 4: [source] table can reference [registries] table

The replace-with key in the [source] table can reference a registry defined in the [registries] table.

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 [registries] and [source] tables.

Drawbacks

Behavior is changed around where credentials are sent, which could break some workflows.

If a mirror of crates.io is set up with config.json containing "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 crates-io, 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 cargo vendor).

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

Prior art

Other package managers don’t seem to have a source replacement feature.

Unresolved questions

Should the --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.

Future possibilities

Can’t think of anything.