feat!: support showing indirect referrers for all formats of oras discover (#1653)

Signed-off-by: Xiaoxuan Wang <[email protected]>

Author: wangxiaoxuan273

cmd/oras/internal/display/metadata/interface.go

@@ -44,9 +44,6 @@ type AttachHandler interface {
 type DiscoverHandler interface {
 	Renderer
 
-	// MultiLevelSupported returns true if the handler supports multi-level
-	// discovery.
-	MultiLevelSupported() bool
 	// OnDiscovered is called after a referrer is discovered.
 	OnDiscovered(referrer, subject ocispec.Descriptor) error
 }

cmd/oras/internal/display/metadata/json/discover.go

@@ -16,48 +16,36 @@ limitations under the License.
 package json
 
 import (
-	"fmt"
 	"io"
 
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
-	"oras.land/oras-go/v2/content"
 	"oras.land/oras/cmd/oras/internal/display/metadata"
 	"oras.land/oras/cmd/oras/internal/display/metadata/model"
 	"oras.land/oras/cmd/oras/internal/output"
 )
 
 // discoverHandler handles json metadata output for discover events.
 type discoverHandler struct {
-	out       io.Writer
-	root      ocispec.Descriptor
-	path      string
-	referrers []ocispec.Descriptor
+	out   io.Writer
+	path  string
+	model model.Discover
 }
 
 // NewDiscoverHandler creates a new handler for discover events.
-func NewDiscoverHandler(out io.Writer, root ocispec.Descriptor, path string) metadata.DiscoverHandler {
+func NewDiscoverHandler(out io.Writer, subject ocispec.Descriptor, path string) metadata.DiscoverHandler {
 	return &discoverHandler{
-		out:  out,
-		root: root,
-		path: path,
+		out:   out,
+		path:  path,
+		model: model.NewDiscover(path, subject),
 	}
 }
 
-// MultiLevelSupported implements metadata.DiscoverHandler.
-func (h *discoverHandler) MultiLevelSupported() bool {
-	return false
-}
-
 // OnDiscovered implements metadata.DiscoverHandler.
 func (h *discoverHandler) OnDiscovered(referrer, subject ocispec.Descriptor) error {
-	if !content.Equal(subject, h.root) {
-		return fmt.Errorf("unexpected subject descriptor: %v", subject)
-	}
-	h.referrers = append(h.referrers, referrer)
-	return nil
+	return h.model.AddReferrer(referrer, subject)
 }
 
 // Render implements metadata.DiscoverHandler.
 func (h *discoverHandler) Render() error {
-	return output.PrintPrettyJSON(h.out, model.NewDiscover(h.path, h.root, h.referrers))
+	return output.PrintPrettyJSON(h.out, h.model.Root)
 }

cmd/oras/internal/display/metadata/model/discover.go

@@ -15,21 +15,53 @@ limitations under the License.
 
 package model
 
-import ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+import (
+	"fmt"
 
-type discover struct {
+	"github.com/opencontainers/go-digest"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
+
+// Discover is a model for discovered referrers.
+type Discover struct {
+	name  string
+	nodes map[digest.Digest]*Node
+	Root  *Node
+}
+
+// Node represents a node in the discovered reference tree.
+type Node struct {
 	Descriptor
-	Referrers []Descriptor `json:"referrers"`
+	Referrers []*Node `json:"referrers,omitempty"`
+}
+
+// AddReferrer adds a node to the discovered referrers tree.
+func (d *Discover) AddReferrer(referrer, subject ocispec.Descriptor) error {
+	to, ok := d.nodes[subject.Digest]
+	if !ok {
+		return fmt.Errorf("unexpected subject descriptor: %v", subject)
+	}
+	from := NewNode(d.name, referrer)
+	d.nodes[from.Digest] = from
+	to.Referrers = append(to.Referrers, from)
+	return nil
 }
 
 // NewDiscover creates a new discover model.
-func NewDiscover(name string, subject ocispec.Descriptor, referrers []ocispec.Descriptor) discover {
-	discover := discover{
-		Descriptor: FromDescriptor(name, subject),
-		Referrers:  make([]Descriptor, 0, len(referrers)),
+func NewDiscover(path string, root ocispec.Descriptor) Discover {
+	treeRoot := NewNode(path, root)
+	return Discover{
+		name: path,
+		nodes: map[digest.Digest]*Node{
+			root.Digest: treeRoot,
+		},
+		Root: treeRoot,
 	}
-	for _, referrer := range referrers {
-		discover.Referrers = append(discover.Referrers, FromDescriptor(name, referrer))
+}
+
+// NewNode creates a new node.
+func NewNode(name string, desc ocispec.Descriptor) *Node {
+	return &Node{
+		Descriptor: FromDescriptor(name, desc),
 	}
-	return discover
 }

cmd/oras/internal/display/metadata/table/discover.go

@@ -45,11 +45,6 @@ func NewDiscoverHandler(out io.Writer, rawReference string, root ocispec.Descrip
 	}
 }
 
-// MultiLevelSupported implements metadata.DiscoverHandler.
-func (h *discoverHandler) MultiLevelSupported() bool {
-	return false
-}
-
 // OnDiscovered implements metadata.DiscoverHandler.
 func (h *discoverHandler) OnDiscovered(referrer, subject ocispec.Descriptor) error {
 	if !content.Equal(subject, h.root) {

cmd/oras/internal/display/metadata/template/discover.go

@@ -16,50 +16,38 @@ limitations under the License.
 package template
 
 import (
-	"fmt"
 	"io"
 
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
-	"oras.land/oras-go/v2/content"
 	"oras.land/oras/cmd/oras/internal/display/metadata"
 	"oras.land/oras/cmd/oras/internal/display/metadata/model"
 	"oras.land/oras/cmd/oras/internal/output"
 )
 
 // discoverHandler handles json metadata output for discover events.
 type discoverHandler struct {
-	referrers []ocispec.Descriptor
-	template  string
-	path      string
-	root      ocispec.Descriptor
-	out       io.Writer
+	template string
+	path     string
+	out      io.Writer
+	model    model.Discover
 }
 
 // NewDiscoverHandler creates a new handler for discover events.
 func NewDiscoverHandler(out io.Writer, root ocispec.Descriptor, path string, template string) metadata.DiscoverHandler {
 	return &discoverHandler{
 		out:      out,
-		root:     root,
 		path:     path,
 		template: template,
+		model:    model.NewDiscover(path, root),
 	}
 }
 
-// MultiLevelSupported implements metadata.DiscoverHandler.
-func (h *discoverHandler) MultiLevelSupported() bool {
-	return false
-}
-
 // OnDiscovered implements metadata.DiscoverHandler.
 func (h *discoverHandler) OnDiscovered(referrer, subject ocispec.Descriptor) error {
-	if !content.Equal(subject, h.root) {
-		return fmt.Errorf("unexpected subject descriptor: %v", subject)
-	}
-	h.referrers = append(h.referrers, referrer)
-	return nil
+	return h.model.AddReferrer(referrer, subject)
 }
 
 // Render implements metadata.DiscoverHandler.
 func (h *discoverHandler) Render() error {
-	return output.ParseAndWrite(h.out, model.NewDiscover(h.path, h.root, h.referrers), h.template)
+	return output.ParseAndWrite(h.out, h.model.Root, h.template)
 }

cmd/oras/internal/display/metadata/tree/discover.go

@@ -50,11 +50,6 @@ func NewDiscoverHandler(out io.Writer, path string, root ocispec.Descriptor, ver
 	}
 }
 
-// MultiLevelSupported implements metadata.DiscoverHandler.
-func (h *discoverHandler) MultiLevelSupported() bool {
-	return true
-}
-
 // OnDiscovered implements metadata.DiscoverHandler.
 func (h *discoverHandler) OnDiscovered(referrer, subject ocispec.Descriptor) error {
 	node, ok := h.nodes[subject.Digest]

cmd/oras/internal/option/format.go

@@ -59,11 +59,11 @@ var (
 	// the table format is deprecated
 	FormatTypeTable = &FormatType{
 		Name:  "table",
-		Usage: "[Deprecated] Get direct referrers and output in table format",
+		Usage: "[Deprecated] Get referrers and output in table format",
 	}
 	FormatTypeTree = &FormatType{
 		Name:  "tree",
-		Usage: "Get referrers recursively and print in tree format",
+		Usage: "Get referrers and print in tree format",
 	}
 	FormatTypeText = &FormatType{
 		Name:  "text",

cmd/oras/root/discover.go

@@ -41,6 +41,7 @@ type discoverOptions struct {
 
 	artifactType string
 	verbose      bool
+	depth        int
 }
 
 func discoverCmd() *cobra.Command {
@@ -67,6 +68,9 @@ Example - [Experimental] Discover referrers and display in a table view:
 Example - [Experimental] Discover referrers and format output with Go template:
   oras discover localhost:5000/hello:v1 --format go-template --template "{{.referrers}}"
 
+Example - [Experimental] Discover only direct referrers, displayed in json view:
+  oras discover localhost:5000/hello:v1 --format json --depth 1
+
 Example - Discover all the referrers of manifest with annotations, displayed in a tree view:
   oras discover -v localhost:5000/hello:v1
 
@@ -81,13 +85,20 @@ Example - Discover referrers of the manifest tagged 'v1' in an OCI image layout
 			if err := oerrors.CheckMutuallyExclusiveFlags(cmd.Flags(), "format", "output"); err != nil {
 				return err
 			}
+			if cmd.Flags().Changed("depth") && opts.depth < 1 {
+				return errors.New("depth value should be at least 1")
+			}
+			// only show direct referrers for table format
+			if opts.FormatFlag == option.FormatTypeTable.Name {
+				opts.depth = 1
+			}
 			opts.RawReference = args[0]
 			if err := option.Parse(cmd, &opts); err != nil {
 				return err
 			}
 			if cmd.Flags().Changed("output") {
 				switch opts.Format.Type {
-				case "tree", "json", "table":
+				case option.FormatTypeTree.Name, option.FormatTypeJSON.Name, option.FormatTypeTable.Name:
 					_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "[DEPRECATED] --output is deprecated, try `--format %s` instead\n", opts.Template)
 				default:
 					return errors.New("output type can only be tree, table or json")
@@ -101,13 +112,14 @@ Example - Discover referrers of the manifest tagged 'v1' in an OCI image layout
 	}
 
 	cmd.Flags().StringVarP(&opts.artifactType, "artifact-type", "", "", "artifact type")
-	cmd.Flags().StringVarP(&opts.Format.FormatFlag, "output", "o", "tree", "[Deprecated] format in which to display referrers (table, json, or tree). tree format will also show indirect referrers")
+	cmd.Flags().StringVarP(&opts.Format.FormatFlag, "output", "o", "tree", "[Deprecated] format in which to display referrers (table, json, or tree).")
 	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "display full metadata of referrers")
+	cmd.Flags().IntVarP(&opts.depth, "depth", "", 0, "[Experimental] level of referrers to display, if unused shows referrers of all levels")
 	opts.SetTypes(
 		option.FormatTypeTree,
 		option.FormatTypeTable,
-		option.FormatTypeJSON.WithUsage("Get direct referrers and output in JSON format"),
-		option.FormatTypeGoTemplate.WithUsage("Print direct referrers using the given Go template"),
+		option.FormatTypeJSON.WithUsage("Get referrers and output in JSON format"),
+		option.FormatTypeGoTemplate.WithUsage("Print referrers using the given Go template"),
 	)
 	opts.EnableDistributionSpecFlag()
 	option.ApplyFlags(&opts, cmd.Flags())
@@ -136,39 +148,34 @@ func runDiscover(cmd *cobra.Command, opts *discoverOptions) error {
 	if err != nil {
 		return err
 	}
-	if handler.MultiLevelSupported() {
-		if err := fetchAllReferrers(ctx, repo, desc, opts.artifactType, handler); err != nil {
-			return err
-		}
-	} else {
-		refs, err := registry.Referrers(ctx, repo, desc, opts.artifactType)
-		if err != nil {
-			return err
-		}
-		for _, ref := range refs {
-			if err := handler.OnDiscovered(ref, desc); err != nil {
-				return err
-			}
-		}
+	if err := fetchAllReferrers(ctx, repo, desc, opts.artifactType, handler, opts.depth); err != nil {
+		return err
 	}
 	return handler.Render()
 }
 
-func fetchAllReferrers(ctx context.Context, repo oras.ReadOnlyGraphTarget, desc ocispec.Descriptor, artifactType string, handler metadata.DiscoverHandler) error {
+func fetchAllReferrers(ctx context.Context, repo oras.ReadOnlyGraphTarget, desc ocispec.Descriptor, artifactType string, handler metadata.DiscoverHandler, depth int) error {
 	results, err := registry.Referrers(ctx, repo, desc, artifactType)
 	if err != nil {
 		return err
 	}
 
+	var nextDepth int
+	if depth > 0 {
+		nextDepth = depth - 1
+	}
 	for _, r := range results {
 		if err := handler.OnDiscovered(r, desc); err != nil {
 			return err
 		}
+		if depth == 1 {
+			continue
+		}
 		if err := fetchAllReferrers(ctx, repo, ocispec.Descriptor{
 			Digest:    r.Digest,
 			Size:      r.Size,
 			MediaType: r.MediaType,
-		}, artifactType, handler); err != nil {
+		}, artifactType, handler, nextDepth); err != nil {
 			return err
 		}
 	}

test/e2e/internal/testdata/foobar/const.go

@@ -130,6 +130,10 @@ var (
 		MediaType: "application/vnd.oci.image.manifest.v1+json",
 		Digest:    digest.Digest("sha256:0cb8c4da7e9ff2e7eefca33141091b9239218e3125a35e17e8bcd05fa3a5e714"),
 		Size:      670,
+		Annotations: map[string]string{
+			"org.opencontainers.image.created": "2023-01-18T08:37:57Z",
+		},
+		ArtifactType: "test/signature.file",
 	}
 	SBOMArtifactReferrer = ocispec.Descriptor{
 		MediaType: "application/vnd.oci.artifact.manifest.v1+json",