Document Conditional Requests

[jonjohnsonjr]

Here's a first stab at https://github.com/opencontainers/distribution-spec/issues/250

This isn't complete, but I wanted to get something together so we can start bikeshedding.

A couple other use cases we should add are deleting tags (untagging) and interactions with caches.

[jonjohnsonjr]

@sargun had a comment about registry support for this. Many registries supply ETags today, but it's unclear if they already support conditional requests.

One simple idea would be defining an HTTP header such that registries can positively indicate support for conditional requests.

E.g. something dumb like:

OCI-Distribution-RFC7232: yes

If a client sees that header, they could rely on conditional request semantics. If they don't see that header, they could choose to alter their behavior to work around potential race conditions (if possible), log a warning, return an error, etc.

[sargun]

@sargun had a comment about registry support for this. Many registries supply ETags today, but it's unclear if they already support conditional requests.

One simple idea would be defining an HTTP header such that registries can positively indicate support for conditional requests.

E.g. something dumb like:

OCI-Distribution-RFC7232: yes

If a client sees that header, they could rely on conditional request semantics. If they don't see that header, they could choose to alter their behavior to work around potential race conditions (if possible), log a warning, return an error, etc.

What API would the registry have to add this header for -- all? It seems like to me, the client can be optimistic, and if the registry doesn't support it, it can return some known error value.

[jonjohnsonjr]

What API would the registry have to add this header for -- all?

I would say anywhere that includes an Etag header? It would indicate that the client can rely on that Etag for conditional requests. Its absence would (likely) indicate a lack of support, so clients would have to proceed with caution.

It seems like to me, the client can be optimistic, and if the registry doesn't support it, it can return some known error value.

I don't think that works. If a registry doesn't implement conditional requests, the registry would happily just allow any requests to go through and not return any errors for conflicts. We need the registry to signal positive support, because by default there is no way to determine the lack of support beyond probing the registry's behavior by sending a request you would expect to fail.

[jdolitsky]

@jonjohnsonjr - can you address @vbatts and @jzelinskie comments above and we can merge?

Also - are these things we can realistically add to the conformance suite?

[imjasonh]

Friendly ping. Some of the recent discussion in the reference types WG has bumped into this as a blocker, and even regardless of how/whether that work uses and updates indexes, it would be great to have this formally spelled out.

@opencontainers/distribution-spec-maintainers any more comments and/or approvals?

cc @chris-crone @tonistiigi

[tonistiigi]

If a registry doesn't implement conditional requests, the registry would happily just allow any requests to go through and not return any errors for conflicts.

Can we be sure that there isn't a case where the current registry only uses etags for GET and fails on all If-Match because it doesn't understand the condition(eg. PUT/GET are managed by different internal services)? I guess even in that case client could do a GET again, and see that the etag has not changed so the server must be misbehaving.