Provide a namespacing facility which addresses the following requirements:
Allow claiming a namespace exclusively, thereby restricting which crates can be published under this namespace. This allows addressing the squatting issue.
Avoid disputes over namespaces, which can take massive amounts of time and resources to manage.
Guarantee that namespaces are unique, solving the issue of “clashing” namespaces. Non-unique namespaces work poorly and cause disputes, as demonstrated by npm’s
Avoid creating a hard dependency on external services. The recent GitHub service interruption is a good example why this is important.
Make receiving a namespace as seamless as possible for users. Namespaces should be an additional benefit crate authors receive, not some annoying bureaucratic hurdle they have to jump over.
- Use (sub)domains as namespaces. Maven has shown that this approach has been working exceedingly well for more than a decade.
- Control of a (sub)domain is established using domain validation (DV) and RFC5785. Let’s Encrypt is successfully using this approach to generate millions of certificates each year.
- Crates.io maintainer will never need to get involved in namespace disputes, as ICANN’s Uniform Domain-Name Dispute-Resolution Policy deal with this.
Basic User Experience
Basic task: I want to publish my
dirs crate under the
- I add
organization = "soc.github.io"to my Cargo.toml.
- I run
- The command prints the following text to the console:
Crates.io couldn’t verify that you own
soc.github.io. To prove ownership, place a file with the following contents
- I place the file “cargo-publishers” with the randomly generated string from crates.io at the specified address.
- I rerun
cargo publish. crates.io checks that the string matches and publishes the crate under the namespace.
Upon the first request to publish a crate with a namespace, crates.io generates a random string that is user-, crate- and domain-specific.
On each following request crates.io checks whether a file named “domain-owner” at the given domain exists and verifies that the contents are identical to what crates.io has on file for the specific user/crate/domain combination.
The ability to publish a crate is not limited to one person: If a different person wants to publish a crate to a domain, crates.io returns a similar reply:
Crates.io couldn’t verify that you own
soc.github.io. To prove ownership, add the following text to the “domain-owner” file at your domain root: Io3487xY3tjg54Ef9Opz
This person would then contact the owner of the domain, who could decide whether to accept or reject this request (by adding or not adding the line to his “domain-owner” file).
This also serves as a very easy way to allow external contributors to publish add-on crates to a crate in an organization, without allowing them to publish to the main crate. E.g. authors of serde could publish their own crate under
serde.rs/serde and allow vetted, “official” add-on crates to be published by external contributors under e. g.
serde.rs/serde-xyz by adding those users’ verification line to their “domain-owner” file.
This requires some changes to cargo and crates.io:
cargo needs to support
organizationkeys to Cargo.toml files and treat them correctly
- adding dependencies on namespaced crates to Cargo.toml files
crates.io needs to be extended
- to understand
organizationkeys and namespacing
- to validate control of (sub)domains as specified above
- to correctly display such crates on the web
- to understand
No changes to the language are required. Source code of crates does not need to be changed to enable namespaces.
It is recommended that
/ is used as a separator between the namespace and the crate name.
This would mean that a fully-qualified crate would look like an URL, making it easy to find further documentation or the project’s homepage:
Consider a crate called
dirs with the namespace
soc.github.io. The fully-qualified name would be
soc.github.io/dirs. The namespace owner could then place documentation under this URL, forward to the crates GitHub page, or redirect to doc.rs.
This proposal does not discuss what should happen with the global namespace. This is intentional – there are plenty of policy decisions that can be made with various advantages and disadvantages.
There are valuable discussions to be had about this, but I think it makes sense to discuss this separately, so that disagreement about how to handle the global namespace doesn’t impede the debate about making namespaces as good as possible.
This FAQ is not meant as a complete enumeration of all possible scenarios, but is intended to show how this proposal functions, and which potential policy decisions can be made:
Do I need my own domain?
No. Any subdomain is sufficient. Everyone participating here already owns one, and they are not hard to come by.
I no longer care about maintaining the domain, what should I do?
Ask your maintainers or contributors to take over the domain. (This is not much different from a situation where the original author loses interest in maintaining his/her crate.)
My domain was hacked!
Use your domain registry’s support channels to resolve this issue. In the meantime, it might make sense to let crates.io maintainers know, so that the publication of new crates or versions can be disabled until the issue is resolved. (This is not much different from your crates.io account being compromised.)
Someone else owns my domain now!
Pick a new domain. If there is an acute danger of misuse, let crates.io maintainers know, so that publications of newer versions of existing crates under that namespace can be blocked.