fix(publish): Block until it is in index

[epage]

Originally, crates.io would block on publish requests until the publish
was complete, giving cargo publish this behavior by extension. When
crates.io switched to asynchronous publishing, this intermittently broke
people's workflows when publishing multiple crates. I say interittent
because it usually works until it doesn't and it is unclear why to the
end user because it will be published by the time they check. In the
end, callers tend to either put in timeouts (and pray), poll the
server's API, or use crates-index crate to poll the index.

This isn't sufficient because

• For any new interested party, this is a pit of failure they'll fall
  into
• crates-index has re-implemented index support incorrectly in the past,
  currently doesn't handle auth, doesn't support git-cli, etc.
• None of these previous options work if we were to implement
  workspace-publish support (cargo publish multiple packages at once #1169)
• The new sparse registry might increase the publish times, making the
  delay easier to hit manually
• The new sparse registry goes through CDNs so checking the server's API
  might not be sufficient
• Once the sparse registry is available, crates-index users will find
  out when the package is ready in git but it might not be ready through
  the sparse registry because of CDNs

So now cargo will block until it sees the package in the index.

• This is checking via the index instead of server APIs in case there
  are propagation delays. This has the side effect of being noisy
  because of all of the "Updating index" messages.
• This blocks by default but there is an unstable publish.timeout config field that will disable blocking when set to 0. See Tracking Issue for publish-timeout #11222 for stablization

Blocking is opt-out as that is the less error prone case for casual users while those doing larger integrations are also likely to do the testing needed to make more complicated scenarios work where blocking is disabled.

Right now we block after the publish. An alternative would be to block until all dependencies are in the index which makes the blocking only happen when needed

• Blocking on dependencies can be imprecise to detect when to block vs propagate an error up
• This is the less error prone case for users. For example I recently publish a crate in one tab and immediately switched to another tab to use it and this only worked because cargo-release blocked until it was ready to use

In reviewing this change, be sure to look at the individual commits

• The first makes it possible to write the tests for this
• The second adds a test that shows the current behavior
• The third updates the test to the expected behavior, showing all of this works

In addition to the publish tests:

• We want to maximize the nightly-to-stable time to collect feedback
• We will put this in TWiR's testing section to raise visibility

Fixes #9507

[rust-highfive]

r? @weihanglo

(rust-highfive has picked a reviewer for you, use r? to override)

[epage]

Hmm, hadn't run all of the tests before posting and hadn't considered there isn't a functioning-enough registry to pull from.

Open to people's thoughts on doing some kind of hack for this (env variable, unstable flag to not block, etc) or to try to add an insta-stable flag for controlling blocking.

[ehuss]

Hmm, hadn't run all of the tests before posting and hadn't considered there isn't a functioning-enough registry to pull from.

How hard would it be to implement a real publish API? I suspect a simplified implementation should be relatively short (maybe 40-50 lines?). I think the steps would roughly be:

1. Read the data sent by cargo, and deserialize the JSON.
2. Save the .crate file into the correct directory.
3. Convert the publish JSON to the index JSON. I think this should be relatively basic copy of fields into a new serde_json::Value. The only one I think that needs real translation is the registry field of a dependency. I think the cksum would also need to be computed. EDIT: or just use Cargo's types like NewCrate directly (would need Deserialize derives).
4. Add that JSON to the index, and commit it.

[Eh2406]

The fact that almost all of our tests do not require actually running a web server, it's kind of nice for performance and reliability. An alternative implementation to support the tests, would be to add a flag for skipping the new delay.

We should also keep in mind in designing this that not all registries necessarily publish promptly. it is perfectly reasonable for a registry that accepts the publish API to require some kind of intervention before it appears in the index. I could see a registry requiring a user to review the package they just uploaded to verify that it looks correct before adding it to the index. A registry could also do an automated or manual security audit before it is added.

[epage]

We should also keep in mind in designing this that not all registries necessarily publish promptly.

For this use case, it seems like we'd want this to be part of registry configuration as passing in a --wait=no every time doesn't seem right.

Maybe we should start out with both an unstable flag and an unstable config value so any users can unblock themselves and we can also use this as a way to collect feedback on what is needed and not block this on naming or other details like that.

[arlosi]

Should we have a --no-wait option for cargo publish? When users are just publishing single crates, they might not care about waiting until it's available.

[epage]

We are talking about potentially adding a --no-wait for other reasons but I'm personally not as sympathetic to this case. They would need to know, not matter, and pass in a flag. That seems like a fairly specialized case to add a flag for.

[Eh2406]

We should also keep in mind in designing this that not all registries necessarily publish promptly.

To start speculating on an RFC...
Thinking about this more, I think the right place for a registry to tell us how long to wait is in the response to the /api/v1/crates/new call. Either in the response object or in headers.
I see a couple of reasonable things a registry could want to tell a user about how long to wait:

• Retry for some expected period of time (the behavior you're adding here) possibly with the ability for a registry to estimate how long the retries should run for.
• A URL that needs to be interacted with in order for progress to be made. For the cases where it requires the author to do a manual review.
• A URL that can be used to track the progress of publication. (Possibly with some specification for how cargo can use it as a retry loop.)
• Clarification that the retry loop is unlikely to be productive. Say if all publishes require manual review by the registry.

On the other hand, we can change the default behavior now and add such configurability in a backwards compatible way in the future.

[jonhoo]

I wonder if we could express all of these with semi-standard HTTP response codes + headers:

Retry for some expected period of time (the behavior you're adding here) possibly with the ability for a registry to estimate how long the retries should run for.

202 Accepted
Retry-After: Fri, 07 Nov 2022 23:59:59 GMT
Content-Location: https://crates.io/api/v1/crates/$crate/$new_version

A URL that needs to be interacted with in order for progress to be made. For the cases where it requires the author to do a manual review.

202 Accepted
Location: https://registry.example.com/approve/$crate/$new_version

A URL that can be used to track the progress of publication. (Possibly with some specification for how cargo can use it as a retry loop.)

202 Accepted
X-Cargo-Track-Progress: v1
Content-Location: https://crates.io/api/v1/crates/$crate/$new_version

Clarification that the retry loop is unlikely to be productive. Say if all publishes require manual review by the registry.

202 Accepted

And to add one: "available now" could be

201 Created
Location: https://crates.io/api/v1/crates/$crate/$new_version

[ehuss]

I was curious why this waits after publish, instead of waiting for dependencies to be available? The original intent I had for #9507 is to only block publishing to wait for dependencies to become available. That way, it doesn't affect the majority of cases where someone is publishing a single package. Do you have any thoughts on those approaches?

I'm a little concerned about always blocking until it is available. There are times where there can be a significant delay, and the user may not care, but would be bothered if publishing gets "stuck".

I can see some benefit of blocking before finishing, such as someone wanting to publish an announcement. But I'm a bit wary of forcing that behavior.

[bors]

⌛ Testing commit f2fc5ca with merge 7e484fc...

[bors]

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing 7e484fc to master...