Unspecified Referrers API Behavior on Non-Existing Manifest

[shizhMSFT]

In the section Listing Referrers, the spec states

Assuming a repository is found, this request MUST return a 200 OK response code. If the registry supports the referrers API, the registry MUST NOT return a 404 Not Found to a referrers API requests.

However, it does not specify what the behavior is if the repository is found but the manifest that the <digest> points to does not exist. Since the registry MUST NOT return a 404 and other 4xx errors are not appropriate, I would like to suggest always returning an empty list for non-existing manifest in an existing repository.

As a byproduct, the empty list for non-existing manifest allows the clients to check the Referrers API efficiently by querying a zero digest where the probability of collision is negligible.

/v2/<name>/referrers/sha256:0000000000000000000000000000000000000000000000000000000000000000

[shizhMSFT]

In addition, if a repository is not found (i.e. not exist), what is the return status code of the referrers API?

[sudo-bmitch]

Both of these should return an empty index:

If a query results in no matching referrers, an empty manifest list MUST be returned.

What's the use case for checking if the API exists without querying the API for a specific digest?

As a byproduct, the empty list for non-existing manifest allows the clients to check the Referrers API efficiently by querying a zero digest where the probability of collision is negligible.

[shizhMSFT]

What's the use case for checking if the API exists without querying the API for a specific digest?

When querying the referrers API for pushing manifests with subject and deleting manifests, we actually do not need the returned index result but the status code 200 or 404. Based on this, we can try to query the referrers list of a non-existing manifest so that the remote server can cost less and response more quickly.

[sudo-bmitch]

... we actually do not need the returned index result but the status code 200 or 404. Based on this, we can try to query the referrers list of a non-existing manifest so that the remote server can cost less and response more quickly.

Perhaps a HEAD request would be more appropriate for those. My hope is that the responses become cached so there isn't much server overhead after the first query following any change. For your use cases, an unknown digest will work on registries following the spec and we should include that in any compliance tests.

[shizhMSFT]

A HEAD request is a good idea but it won't reduce the server cost since the server still needs to load everything to compute the Content-Length header.

[sudo-bmitch]

Since this was opened, we added the OCI-Subject header that should help with the push scenario. For deleting manifests, you'd only want to delete the referrers when deleting by digest rather than deleting a tag (since there may be other tags pointing to the manifest, and an untagged manifest could be retained). What that doesn't help with are referrers to GC'd manifests, so a periodic cleanup process run by clients looking for referrers tags to digests that don't exist could be useful.

It's been a while since this was asked. Is this issue okay to close?