feat(referrer): add cursor-based pagination to discover endpoints (#2896)

Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev>

Author: migmartri

app/cli/cmd/referrer_discover.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2023 The Chainloop Authors.
+// Copyright 2023-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ package cmd
 import (
 	"context"
 
+	"github.com/chainloop-dev/chainloop/app/cli/cmd/options"
 	"github.com/chainloop-dev/chainloop/app/cli/cmd/output"
 	"github.com/chainloop-dev/chainloop/app/cli/pkg/action"
 	"github.com/spf13/cobra"
@@ -26,18 +27,24 @@ import (
 func newReferrerDiscoverCmd() *cobra.Command {
 	var digest, kind string
 	var fromPublicIndex bool
+	paginationOpts := &options.PaginationOpts{DefaultLimit: 20}
 
 	cmd := &cobra.Command{
 		Use:   "discover",
 		Short: "(Preview) inspect pieces of evidence or artifacts stored through Chainloop",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			var res *action.ReferrerItem
+			pagination := &action.PaginationOpts{
+				Limit:      paginationOpts.Limit,
+				NextCursor: paginationOpts.NextCursor,
+			}
+
+			var res *action.ReferrerDiscoverResult
 			var err error
 
 			if fromPublicIndex {
-				res, err = action.NewReferrerDiscoverPublicIndex(ActionOpts).Run(context.Background(), digest, kind)
+				res, err = action.NewReferrerDiscoverPublicIndex(ActionOpts).Run(context.Background(), digest, kind, pagination)
 			} else {
-				res, err = action.NewReferrerDiscoverPrivate(ActionOpts).Run(context.Background(), digest, kind)
+				res, err = action.NewReferrerDiscoverPrivate(ActionOpts).Run(context.Background(), digest, kind, pagination)
 			}
 
 			if err != nil {
@@ -55,6 +62,7 @@ func newReferrerDiscoverCmd() *cobra.Command {
 	cmd.Flags().StringVarP(&kind, "kind", "k", "", "optional kind of the referrer, used to disambiguate between multiple referrers with the same digest")
 	cobra.CheckErr(err)
 	cmd.Flags().BoolVar(&fromPublicIndex, "public", false, "discover from public shared index instead of your organizations'")
+	paginationOpts.AddFlags(cmd)
 
 	return cmd
 }

app/cli/documentation/cli-reference.mdx

@@ -1518,6 +1518,8 @@ Options
 -d, --digest string   hash of the attestation, piece of evidence or artifact, i.e sha256:deadbeef
 -h, --help            help for discover
 -k, --kind string     optional kind of the referrer, used to disambiguate between multiple referrers with the same digest
+--limit int       number of items to show (default 20)
+--next string     cursor to load the next page
 --public          discover from public shared index instead of your organizations'
 ```
 

app/cli/pkg/action/referrer_discover.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2023 The Chainloop Authors.
+// Copyright 2023-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -40,36 +40,62 @@ type ReferrerItem struct {
 	Annotations  map[string]string `json:"annotations,omitempty"`
 }
 
+type ReferrerDiscoverResult struct {
+	Item       *ReferrerItem `json:"result"`
+	NextCursor string        `json:"nextCursor,omitempty"`
+}
+
 func NewReferrerDiscoverPrivate(cfg *ActionsOpts) *ReferrerDiscover {
 	return &ReferrerDiscover{cfg}
 }
 
-func (action *ReferrerDiscover) Run(ctx context.Context, digest, kind string) (*ReferrerItem, error) {
+func (action *ReferrerDiscover) Run(ctx context.Context, digest, kind string, p *PaginationOpts) (*ReferrerDiscoverResult, error) {
 	client := pb.NewReferrerServiceClient(action.cfg.CPConnection)
 	resp, err := client.DiscoverPrivate(ctx, &pb.ReferrerServiceDiscoverPrivateRequest{
-		Digest: digest, Kind: kind,
+		Digest:     digest,
+		Kind:       kind,
+		Pagination: paginationOptsToPb(p),
 	})
 	if err != nil {
 		return nil, err
 	}
 
-	return pbReferrerItemToAction(resp.Result), nil
+	return newReferrerDiscoverResult(resp.Result, resp.GetPagination()), nil
 }
 
 func NewReferrerDiscoverPublicIndex(cfg *ActionsOpts) *ReferrerDiscoverPublic {
 	return &ReferrerDiscoverPublic{cfg}
 }
 
-func (action *ReferrerDiscoverPublic) Run(ctx context.Context, digest, kind string) (*ReferrerItem, error) {
+func (action *ReferrerDiscoverPublic) Run(ctx context.Context, digest, kind string, p *PaginationOpts) (*ReferrerDiscoverResult, error) {
 	client := pb.NewReferrerServiceClient(action.cfg.CPConnection)
 	resp, err := client.DiscoverPublicShared(ctx, &pb.DiscoverPublicSharedRequest{
-		Digest: digest, Kind: kind,
+		Digest:     digest,
+		Kind:       kind,
+		Pagination: paginationOptsToPb(p),
 	})
 	if err != nil {
 		return nil, err
 	}
 
-	return pbReferrerItemToAction(resp.Result), nil
+	return newReferrerDiscoverResult(resp.Result, resp.GetPagination()), nil
+}
+
+func paginationOptsToPb(p *PaginationOpts) *pb.CursorPaginationRequest {
+	if p == nil {
+		return nil
+	}
+	return &pb.CursorPaginationRequest{
+		Limit:  int32(p.Limit),
+		Cursor: p.NextCursor,
+	}
+}
+
+func newReferrerDiscoverResult(item *pb.ReferrerItem, p *pb.CursorPaginationResponse) *ReferrerDiscoverResult {
+	return &ReferrerDiscoverResult{
+		Item:       pbReferrerItemToAction(item),
+		NextCursor: p.GetNextCursor(),
+	}
 }
 
 func pbReferrerItemToAction(in *pb.ReferrerItem) *ReferrerItem {

app/controlplane/api/controlplane/v1/referrer.pb.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2024 The Chainloop Authors.
+// Copyright 2024-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ syntax = "proto3";
 package controlplane.v1;
 
 import "buf/validate/validate.proto";
+import "controlplane/v1/pagination.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/timestamp.proto";
 import "protoc-gen-openapiv2/options/annotations.proto";
@@ -57,6 +58,8 @@ message ReferrerServiceDiscoverPrivateRequest {
   // Kind is the optional type of referrer, i.e CONTAINER_IMAGE, GIT_HEAD, ...
   // Used to filter and resolve ambiguities
   string kind = 2;
+  // Pagination options for the references list
+  CursorPaginationRequest pagination = 3;
 
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     json_schema: {
@@ -73,6 +76,8 @@ message DiscoverPublicSharedRequest {
   // Kind is the optional type of referrer, i.e CONTAINER_IMAGE, GIT_HEAD, ...
   // Used to filter and resolve ambiguities
   string kind = 2;
+  // Pagination options for the references list
+  CursorPaginationRequest pagination = 3;
 
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     json_schema: {
@@ -86,6 +91,8 @@ message DiscoverPublicSharedRequest {
 message DiscoverPublicSharedResponse {
   // Result is the discovered referrer item
   ReferrerItem result = 1;
+  // Pagination information for the references list
+  CursorPaginationResponse pagination = 2;
 
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     json_schema: {
@@ -99,6 +106,8 @@ message DiscoverPublicSharedResponse {
 message ReferrerServiceDiscoverPrivateResponse {
   // Result is the discovered referrer item
   ReferrerItem result = 1;
+  // Pagination information for the references list
+  CursorPaginationResponse pagination = 2;
 
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     json_schema: {