Clarify manifest deletion as sync or async

[jcarter3]

In the section around deleting manifests, the following statements are made:

Upon success, the registry MUST respond with a 202 Accepted code.

Once deleted, a GET to /v2/<name>/manifests/<digest> and any tag pointing to that digest will return a 404.

A 202 Accepted is defined as:

request has been accepted for processing, but processing has not been completed or may not have started

Additionally, in the conformance tests, after performing a delete call, it is valid to receive back a 404 OR a 200 when immediately trying to GET that same manifest.

By this, it seems that it is perfectly fine for a registry implementation to delete manifests via an "eventually consistent" process, though it would be reasonable to expect this to happen quickly. Is this a proper interpretation?

[sudo-bmitch]

Additionally, in the conformance tests, after performing a delete call, it is valid to receive back a 404 OR a 200 when immediately trying to GET that same manifest.

From the description on that conformance test:

GET request to deleted manifest URL should yield 404 response, unless delete is disallowed

I'm guessing the "OR 200" was to support registries that blocked delete requests in a very loose way.

Looking over the HTTP status codes, it appears we should have required a 200 or 204 response if we expected the delete to happen synchronously. From the client perspective, receiving a 202 from the DELETE and then a 200 from a subsequent GET request could be interpreted as a failed delete request. I could imagine this breaking some scripts.

And yet, any tool working with a registry should also tolerate having content being deleted out from under it, or recreated, since there can be other users performing concurrent requests (e.g. a cleanup job running simultaneously with a mirroring job). So while I'm not thrilled with the idea of asynchronous deletes, if this breaks client tooling I think the client tooling should be expected to improve their error handling.

As someone that frequently answers questions from end users, it would be very useful for a registry that performs requests async to publicly document this behavior, including the maximum expected time a request should take to complete.

[jcarter3]

The spec seems to detail an async implementation, so I don't think it's necessary for a registry to specify as such. I agree it might lead to some confusion by users, but maybe that's reason for updating the spec (hence raising the issue)