Support pagination as default option in notation list CLI.

[priteshbandi]

IMO default behavior should be paginated as ORAS referrers API is paginated. Not having pagination will result in an unnecessary load on servers when 1st returned item in the list is what the user wanted. Also, it's usually good practice to have a paginated list API.

Maybe we can create another issue to address your comments. The implementation depends on the behavior of oras-go library. IMO, the current spec is good enough for rc.1 release.

Originally posted by @yizha1 in https://github.com/notaryproject/notation/pull/362#discussion_r991009489

[shizhMSFT]

The Referrers() API in oras-go is paginated.

[rgnote]

Here is the proposal for supporting pagination in notation list command

The default experience for this command will be to list ALL signatures for a given reference. This is the provided behavior in notation rc.1

After rc.1, notation list command will support two new switches

• first-page :
• next-page : <marker to the next page>

Users will be able to paginate through the entire result set of signatures for a given reference. These two will be optional switches. If --next-page is not provided, notation will return the first page.

Examples:

1. notation list - list all signatures
2. notation list --first-page - lists the first page and a token to the next page (token is included only if there are signatures in the second page)
3. notation list --next-page <token> - the page referring to the given

[shizhMSFT]

@rgnote As specified in the distribution-spec, the Referrers API does not support listing from the middle of the list. Also, the Referrers API does not support specifying the number of max results to be returned.

[rgnote]

@shizhMSFT You are right. I was looking at Oras spec. I will update my comment accordingly.

[iamsamirzon]

@rgnote and @shizhMSFT will discuss this and then likely move it out of RC-1 into RC-2

cc: @vaninrao10

[yizha1]

Confirmed to move this issue out of rc-1 scope. Now moved to "Discuss". We will review all the issues later for rc-2 release scope.

[yizha1]

Close this issue as no activities for more than 8 months. Referrers API defined by distribution spec supports pagination and Notation has experimental feature --allow-referrers that supports it. Please open new issue if you still see any issues.