1. Proposed title of this feature request

OCI-compliant tag listing pagination

2. What is the nature and description of the request?

In short, implement the OCI tag listing pagination specification as outlined in https://github.com/opencontainers/distribution-spec/blob/main/spec.md including the pending amends proposed in https://github.com/opencontainers/distribution-spec/pull/470

This will allow the use of the n parameter in the API endpoint /v2/<name>/tags/list?n=<integer> and optionally return a Link header in the response that is structured like this

Link: </v2/<name>/tags/list?n=<n from the request>&last=<last tag value from previous response>; rel="next"

The notable change to the current OCI spec here is that the client should now expect the registry to respond with HTTP 413 TAG_LIMIT_EXCEEDED when the registry determines the required amount of requested tags per page is too high.

As a result, we will adopt the last parameter to drive pagination in combination with the n parameter to be compliant with OCI spec. We will return HTTP 413 if n is higher than our configured limit for tags per page, but never when n is below 100. 

The existing next_page parameter will remain available to retain compatibility with existing client implementations, but its use is mutually exclusive with last.

3. Why does the customer need this? (List the business requirements here)

Some clients do not honor the Link header we currently send in the response and want to rely solely on the n and last parameter as proposed by the optional OCI pagination spec. Yet, we must also protect the registry against clients requesting arbitrarily large tag lists.

Quay(.io) currently uses custom implementation using the RFC5988 standard to paginate the result set of the /v2/<name>/tags/list OCI endpoint, leveraging a token called next_page containing an encrypted, time-limited token containing the database row identifier of the last tag in the result set. While several clients have adopted this, this is not covered by the current OCI listing spec: https://github.com/opencontainers/distribution-spec/blob/v1.0/spec.md#content-discovery

This spec in its current form is difficult for public registry services like Quay.io to implement because the pagination is optional and it forces the registry to return an arbitrary amount, if not all, tags depending on the client request, effectively allowing the omission of any pagination, which will lead to an easily exploitable DoS vector.

Fortunately, there are changes in OCI being discussed to formally allow a registry to deny listing too many tags at once. As a result, pagination will be non-optional but not a performance/safety concern anymore.

4. List any affected packages or components.

Quay.io and Red Hat Quay.