1## Registries 2 3Cargo installs crates and fetches dependencies from a "registry". The default 4registry is [crates.io]. A registry contains an "index" which contains a 5searchable list of available crates. A registry may also provide a web API to 6support publishing new crates directly from Cargo. 7 8> Note: If you are interested in mirroring or vendoring an existing registry, 9> take a look at [Source Replacement]. 10 11### Using an Alternate Registry 12 13To use a registry other than [crates.io], the name and index URL of the 14registry must be added to a [`.cargo/config.toml` file][config]. The `registries` 15table has a key for each registry, for example: 16 17```toml 18[registries] 19my-registry = { index = "https://my-intranet:8080/git/index" } 20``` 21 22The `index` key should be a URL to a git repository with the registry's index. 23A crate can then depend on a crate from another registry by specifying the 24`registry` key and a value of the registry's name in that dependency's entry 25in `Cargo.toml`: 26 27```toml 28# Sample Cargo.toml 29[package] 30name = "my-project" 31version = "0.1.0" 32 33[dependencies] 34other-crate = { version = "1.0", registry = "my-registry" } 35``` 36 37As with most config values, the index may be specified with an environment 38variable instead of a config file. For example, setting the following 39environment variable will accomplish the same thing as defining a config file: 40 41```ignore 42CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index 43``` 44 45> Note: [crates.io] does not accept packages that depend on crates from other 46> registries. 47 48### Publishing to an Alternate Registry 49 50If the registry supports web API access, then packages can be published 51directly to the registry from Cargo. Several of Cargo's commands such as 52[`cargo publish`] take a `--registry` command-line flag to indicate which 53registry to use. For example, to publish the package in the current directory: 54 551. `cargo login --registry=my-registry` 56 57 This only needs to be done once. You must enter the secret API token 58 retrieved from the registry's website. Alternatively the token may be 59 passed directly to the `publish` command with the `--token` command-line 60 flag or an environment variable with the name of the registry such as 61 `CARGO_REGISTRIES_MY_REGISTRY_TOKEN`. 62 632. `cargo publish --registry=my-registry` 64 65Instead of always passing the `--registry` command-line option, the default 66registry may be set in [`.cargo/config.toml`][config] with the `registry.default` 67key. 68 69Setting the `package.publish` key in the `Cargo.toml` manifest restricts which 70registries the package is allowed to be published to. This is useful to 71prevent accidentally publishing a closed-source package to [crates.io]. The 72value may be a list of registry names, for example: 73 74```toml 75[package] 76# ... 77publish = ["my-registry"] 78``` 79 80The `publish` value may also be `false` to restrict all publishing, which is 81the same as an empty list. 82 83The authentication information saved by [`cargo login`] is stored in the 84`credentials.toml` file in the Cargo home directory (default `$HOME/.cargo`). It 85has a separate table for each registry, for example: 86 87```toml 88[registries.my-registry] 89token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy" 90``` 91 92### Running a Registry 93 94A minimal registry can be implemented by having a git repository that contains 95an index, and a server that contains the compressed `.crate` files created by 96[`cargo package`]. Users won't be able to use Cargo to publish to it, but this 97may be sufficient for closed environments. 98 99A full-featured registry that supports publishing will additionally need to 100have a web API service that conforms to the API used by Cargo. The web API is 101documented below. 102 103Commercial and community projects are available for building and running a 104registry. See <https://github.com/rust-lang/cargo/wiki/Third-party-registries> 105for a list of what is available. 106 107### Index Format 108 109The following defines the format of the index. New features are occasionally 110added, which are only understood starting with the version of Cargo that 111introduced them. Older versions of Cargo may not be able to use packages that 112make use of new features. However, the format for older packages should not 113change, so older versions of Cargo should be able to use them. 114 115The index is stored in a git repository so that Cargo can efficiently fetch 116incremental updates to the index. In the root of the repository is a file 117named `config.json` which contains JSON information used by Cargo for 118accessing the registry. This is an example of what the [crates.io] config file 119looks like: 120 121```javascript 122{ 123 "dl": "https://crates.io/api/v1/crates", 124 "api": "https://crates.io" 125} 126``` 127 128The keys are: 129- `dl`: This is the URL for downloading crates listed in the index. The value 130 may have the following markers which will be replaced with their 131 corresponding value: 132 133 - `{crate}`: The name of crate. 134 - `{version}`: The crate version. 135 - `{prefix}`: A directory prefix computed from the crate name. For example, 136 a crate named `cargo` has a prefix of `ca/rg`. See below for details. 137 - `{lowerprefix}`: Lowercase variant of `{prefix}`. 138 - `{sha256-checksum}`: The crate's sha256 checksum. 139 140 If none of the markers are present, then the value 141 `/{crate}/{version}/download` is appended to the end. 142- `api`: This is the base URL for the web API. This key is optional, but if it 143 is not specified, commands such as [`cargo publish`] will not work. The web 144 API is described below. 145 146The download endpoint should send the `.crate` file for the requested package. 147Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2. 148The exact specifics of TLS support depend on the platform that Cargo is 149running on, the version of Cargo, and how it was compiled. 150 151The rest of the index repository contains one file for each package, where the 152filename is the name of the package in lowercase. Each version of the package 153has a separate line in the file. The files are organized in a tier of 154directories: 155 156- Packages with 1 character names are placed in a directory named `1`. 157- Packages with 2 character names are placed in a directory named `2`. 158- Packages with 3 character names are placed in the directory 159 `3/{first-character}` where `{first-character}` is the first character of 160 the package name. 161- All other packages are stored in directories named 162 `{first-two}/{second-two}` where the top directory is the first two 163 characters of the package name, and the next subdirectory is the third and 164 fourth characters of the package name. For example, `cargo` would be stored 165 in a file named `ca/rg/cargo`. 166 167> Note: Although the index filenames are in lowercase, the fields that contain 168> package names in `Cargo.toml` and the index JSON data are case-sensitive and 169> may contain upper and lower case characters. 170 171The directory name above is calculated based on the package name converted to 172lowercase; it is represented by the marker `{lowerprefix}`. When the original 173package name is used without case conversion, the resulting directory name is 174represented by the marker `{prefix}`. For example, the package `MyCrate` would 175have a `{prefix}` of `My/Cr` and a `{lowerprefix}` of `my/cr`. In general, 176using `{prefix}` is recommended over `{lowerprefix}`, but there are pros and 177cons to each choice. Using `{prefix}` on case-insensitive filesystems results 178in (harmless-but-inelegant) directory aliasing. For example, `crate` and 179`CrateTwo` have `{prefix}` values of `cr/at` and `Cr/at`; these are distinct on 180Unix machines but alias to the same directory on Windows. Using directories 181with normalized case avoids aliasing, but on case-sensitive filesystems it's 182harder to support older versions of Cargo that lack `{prefix}`/`{lowerprefix}`. 183For example, nginx rewrite rules can easily construct `{prefix}` but can't 184perform case-conversion to construct `{lowerprefix}`. 185 186Registries should consider enforcing limitations on package names added to 187their index. Cargo itself allows names with any [alphanumeric], `-`, or `_` 188characters. [crates.io] imposes its own limitations, including the following: 189 190- Only allows ASCII characters. 191- Only alphanumeric, `-`, and `_` characters. 192- First character must be alphabetic. 193- Case-insensitive collision detection. 194- Prevent differences of `-` vs `_`. 195- Under a specific length (max 64). 196- Rejects reserved names, such as Windows special filenames like "nul". 197 198Registries should consider incorporating similar restrictions, and consider 199the security implications, such as [IDN homograph 200attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack) and other 201concerns in [UTR36](https://www.unicode.org/reports/tr36/) and 202[UTS39](https://www.unicode.org/reports/tr39/). 203 204Each line in a package file contains a JSON object that describes a published 205version of the package. The following is a pretty-printed example with comments 206explaining the format of the entry. 207 208```javascript 209{ 210 // The name of the package. 211 // This must only contain alphanumeric, `-`, or `_` characters. 212 "name": "foo", 213 // The version of the package this row is describing. 214 // This must be a valid version number according to the Semantic 215 // Versioning 2.0.0 spec at https://semver.org/. 216 "vers": "0.1.0", 217 // Array of direct dependencies of the package. 218 "deps": [ 219 { 220 // Name of the dependency. 221 // If the dependency is renamed from the original package name, 222 // this is the new name. The original package name is stored in 223 // the `package` field. 224 "name": "rand", 225 // The semver requirement for this dependency. 226 // This must be a valid version requirement defined at 227 // https://github.com/steveklabnik/semver#requirements. 228 "req": "^0.6", 229 // Array of features (as strings) enabled for this dependency. 230 "features": ["i128_support"], 231 // Boolean of whether or not this is an optional dependency. 232 "optional": false, 233 // Boolean of whether or not default features are enabled. 234 "default_features": true, 235 // The target platform for the dependency. 236 // null if not a target dependency. 237 // Otherwise, a string such as "cfg(windows)". 238 "target": null, 239 // The dependency kind. 240 // "dev", "build", or "normal". 241 // Note: this is a required field, but a small number of entries 242 // exist in the crates.io index with either a missing or null 243 // `kind` field due to implementation bugs. 244 "kind": "normal", 245 // The URL of the index of the registry where this dependency is 246 // from as a string. If not specified or null, it is assumed the 247 // dependency is in the current registry. 248 "registry": null, 249 // If the dependency is renamed, this is a string of the actual 250 // package name. If not specified or null, this dependency is not 251 // renamed. 252 "package": null, 253 } 254 ], 255 // A SHA256 checksum of the `.crate` file. 256 "cksum": "d867001db0e2b6e0496f9fac96930e2d42233ecd3ca0413e0753d4c7695d289c", 257 // Set of features defined for the package. 258 // Each feature maps to an array of features or dependencies it enables. 259 "features": { 260 "extras": ["rand/simd_support"] 261 }, 262 // Boolean of whether or not this version has been yanked. 263 "yanked": false, 264 // The `links` string value from the package's manifest, or null if not 265 // specified. This field is optional and defaults to null. 266 "links": null 267} 268``` 269 270The JSON objects should not be modified after they are added except for the 271`yanked` field whose value may change at any time. 272 273### Web API 274 275A registry may host a web API at the location defined in `config.json` to 276support any of the actions listed below. 277 278Cargo includes the `Authorization` header for requests that require 279authentication. The header value is the API token. The server should respond 280with a 403 response code if the token is not valid. Users are expected to 281visit the registry's website to obtain a token, and Cargo can store the token 282using the [`cargo login`] command, or by passing the token on the 283command-line. 284 285Responses use a 200 response code for both success and errors. Cargo looks at 286the JSON response to determine if there was success or failure. Failure 287responses have a JSON object with the following structure: 288 289```javascript 290{ 291 // Array of errors to display to the user. 292 "errors": [ 293 { 294 // The error message as a string. 295 "detail": "error message text" 296 } 297 ] 298} 299``` 300 301Servers may also respond with a 404 response code to indicate the requested 302resource is not found (for example, an unknown crate name). However, using a 303200 response with an `errors` object allows a registry to provide a more 304detailed error message if desired. 305 306For backwards compatibility, servers should ignore any unexpected query 307parameters or JSON fields. If a JSON field is missing, it should be assumed to 308be null. The endpoints are versioned with the `v1` component of the path, and 309Cargo is responsible for handling backwards compatibility fallbacks should any 310be required in the future. 311 312Cargo sets the following headers for all requests: 313 314- `Content-Type`: `application/json` 315- `Accept`: `application/json` 316- `User-Agent`: The Cargo version such as `cargo 1.32.0 (8610973aa 317 2019-01-02)`. This may be modified by the user in a configuration value. 318 Added in 1.29. 319 320#### Publish 321 322- Endpoint: `/api/v1/crates/new` 323- Method: PUT 324- Authorization: Included 325 326The publish endpoint is used to publish a new version of a crate. The server 327should validate the crate, make it available for download, and add it to the 328index. 329 330The body of the data sent by Cargo is: 331 332- 32-bit unsigned little-endian integer of the length of JSON data. 333- Metadata of the package as a JSON object. 334- 32-bit unsigned little-endian integer of the length of the `.crate` file. 335- The `.crate` file. 336 337The following is a commented example of the JSON object. Some notes of some 338restrictions imposed by [crates.io] are included only to illustrate some 339suggestions on types of validation that may be done, and should not be 340considered as an exhaustive list of restrictions [crates.io] imposes. 341 342```javascript 343{ 344 // The name of the package. 345 "name": "foo", 346 // The version of the package being published. 347 "vers": "0.1.0", 348 // Array of direct dependencies of the package. 349 "deps": [ 350 { 351 // Name of the dependency. 352 // If the dependency is renamed from the original package name, 353 // this is the original name. The new package name is stored in 354 // the `explicit_name_in_toml` field. 355 "name": "rand", 356 // The semver requirement for this dependency. 357 "version_req": "^0.6", 358 // Array of features (as strings) enabled for this dependency. 359 "features": ["i128_support"], 360 // Boolean of whether or not this is an optional dependency. 361 "optional": false, 362 // Boolean of whether or not default features are enabled. 363 "default_features": true, 364 // The target platform for the dependency. 365 // null if not a target dependency. 366 // Otherwise, a string such as "cfg(windows)". 367 "target": null, 368 // The dependency kind. 369 // "dev", "build", or "normal". 370 "kind": "normal", 371 // The URL of the index of the registry where this dependency is 372 // from as a string. If not specified or null, it is assumed the 373 // dependency is in the current registry. 374 "registry": null, 375 // If the dependency is renamed, this is a string of the new 376 // package name. If not specified or null, this dependency is not 377 // renamed. 378 "explicit_name_in_toml": null, 379 } 380 ], 381 // Set of features defined for the package. 382 // Each feature maps to an array of features or dependencies it enables. 383 // Cargo does not impose limitations on feature names, but crates.io 384 // requires alphanumeric ASCII, `_` or `-` characters. 385 "features": { 386 "extras": ["rand/simd_support"] 387 }, 388 // List of strings of the authors. 389 // May be empty. 390 "authors": ["Alice <a@example.com>"], 391 // Description field from the manifest. 392 // May be null. crates.io requires at least some content. 393 "description": null, 394 // String of the URL to the website for this package's documentation. 395 // May be null. 396 "documentation": null, 397 // String of the URL to the website for this package's home page. 398 // May be null. 399 "homepage": null, 400 // String of the content of the README file. 401 // May be null. 402 "readme": null, 403 // String of a relative path to a README file in the crate. 404 // May be null. 405 "readme_file": null, 406 // Array of strings of keywords for the package. 407 "keywords": [], 408 // Array of strings of categories for the package. 409 "categories": [], 410 // String of the license for the package. 411 // May be null. crates.io requires either `license` or `license_file` to be set. 412 "license": null, 413 // String of a relative path to a license file in the crate. 414 // May be null. 415 "license_file": null, 416 // String of the URL to the website for the source repository of this package. 417 // May be null. 418 "repository": null, 419 // Optional object of "status" badges. Each value is an object of 420 // arbitrary string to string mappings. 421 // crates.io has special interpretation of the format of the badges. 422 "badges": { 423 "travis-ci": { 424 "branch": "master", 425 "repository": "rust-lang/cargo" 426 } 427 }, 428 // The `links` string value from the package's manifest, or null if not 429 // specified. This field is optional and defaults to null. 430 "links": null 431} 432``` 433 434A successful response includes the JSON object: 435 436```javascript 437{ 438 // Optional object of warnings to display to the user. 439 "warnings": { 440 // Array of strings of categories that are invalid and ignored. 441 "invalid_categories": [], 442 // Array of strings of badge names that are invalid and ignored. 443 "invalid_badges": [], 444 // Array of strings of arbitrary warnings to display to the user. 445 "other": [] 446 } 447} 448``` 449 450#### Yank 451 452- Endpoint: `/api/v1/crates/{crate_name}/{version}/yank` 453- Method: DELETE 454- Authorization: Included 455 456The yank endpoint will set the `yank` field of the given version of a crate to 457`true` in the index. 458 459A successful response includes the JSON object: 460 461```javascript 462{ 463 // Indicates the delete succeeded, always true. 464 "ok": true, 465} 466``` 467 468#### Unyank 469 470- Endpoint: `/api/v1/crates/{crate_name}/{version}/unyank` 471- Method: PUT 472- Authorization: Included 473 474The unyank endpoint will set the `yank` field of the given version of a crate 475to `false` in the index. 476 477A successful response includes the JSON object: 478 479```javascript 480{ 481 // Indicates the delete succeeded, always true. 482 "ok": true, 483} 484``` 485 486#### Owners 487 488Cargo does not have an inherent notion of users and owners, but it does 489provide the `owner` command to assist managing who has authorization to 490control a crate. It is up to the registry to decide exactly how users and 491owners are handled. See the [publishing documentation] for a description of 492how [crates.io] handles owners via GitHub users and teams. 493 494##### Owners: List 495 496- Endpoint: `/api/v1/crates/{crate_name}/owners` 497- Method: GET 498- Authorization: Included 499 500The owners endpoint returns a list of owners of the crate. 501 502A successful response includes the JSON object: 503 504```javascript 505{ 506 // Array of owners of the crate. 507 "users": [ 508 { 509 // Unique unsigned 32-bit integer of the owner. 510 "id": 70, 511 // The unique username of the owner. 512 "login": "github:rust-lang:core", 513 // Name of the owner. 514 // This is optional and may be null. 515 "name": "Core", 516 } 517 ] 518} 519``` 520 521##### Owners: Add 522 523- Endpoint: `/api/v1/crates/{crate_name}/owners` 524- Method: PUT 525- Authorization: Included 526 527A PUT request will send a request to the registry to add a new owner to a 528crate. It is up to the registry how to handle the request. For example, 529[crates.io] sends an invite to the user that they must accept before being 530added. 531 532The request should include the following JSON object: 533 534```javascript 535{ 536 // Array of `login` strings of owners to add. 537 "users": ["login_name"] 538} 539``` 540 541A successful response includes the JSON object: 542 543```javascript 544{ 545 // Indicates the add succeeded, always true. 546 "ok": true, 547 // A string to be displayed to the user. 548 "msg": "user ehuss has been invited to be an owner of crate cargo" 549} 550``` 551 552##### Owners: Remove 553 554- Endpoint: `/api/v1/crates/{crate_name}/owners` 555- Method: DELETE 556- Authorization: Included 557 558A DELETE request will remove an owner from a crate. The request should include 559the following JSON object: 560 561```javascript 562{ 563 // Array of `login` strings of owners to remove. 564 "users": ["login_name"] 565} 566``` 567 568A successful response includes the JSON object: 569 570```javascript 571{ 572 // Indicates the remove succeeded, always true. 573 "ok": true 574} 575``` 576 577#### Search 578 579- Endpoint: `/api/v1/crates` 580- Method: GET 581- Query Parameters: 582 - `q`: The search query string. 583 - `per_page`: Number of results, default 10, max 100. 584 585The search request will perform a search for crates, using criteria defined on 586the server. 587 588A successful response includes the JSON object: 589 590```javascript 591{ 592 // Array of results. 593 "crates": [ 594 { 595 // Name of the crate. 596 "name": "rand", 597 // The highest version available. 598 "max_version": "0.6.1", 599 // Textual description of the crate. 600 "description": "Random number generators and other randomness functionality.\n", 601 } 602 ], 603 "meta": { 604 // Total number of results available on the server. 605 "total": 119 606 } 607} 608``` 609 610#### Login 611 612- Endpoint: `/me` 613 614The "login" endpoint is not an actual API request. It exists solely for the 615[`cargo login`] command to display a URL to instruct a user to visit in a web 616browser to log in and retrieve an API token. 617 618[Source Replacement]: source-replacement.md 619[`cargo login`]: ../commands/cargo-login.md 620[`cargo package`]: ../commands/cargo-package.md 621[`cargo publish`]: ../commands/cargo-publish.md 622[alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric 623[config]: config.md 624[crates.io]: https://crates.io/ 625[publishing documentation]: publishing.md#cargo-owner 626