feat: add fetch command to get manifest of an artifact

cmd/oras/discover.go

@@ -23,14 +23,14 @@ import (
 	"strings"
 
 	"oras.land/oras-go/v2/registry/remote"
+	"oras.land/oras/cmd/oras/internal/errors"
 	"oras.land/oras/cmd/oras/internal/option"
 
 	"github.com/need-being/go-tree"
 	digest "github.com/opencontainers/go-digest"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	artifactspec "github.com/oras-project/artifacts-spec/specs-go/v1"
 	"github.com/spf13/cobra"
-	"oras.land/oras/cmd/oras/internal/errors"
 )
 
 type discoverOptions struct {

cmd/oras/internal/errors/errors.go

@@ -21,7 +21,7 @@ import (
 	"oras.land/oras-go/v2/registry"
 )
 
-// NewErrInvalidReference  creates a new error based on the reference string.
+// NewErrInvalidReference creates a new error based on the reference string.
 func NewErrInvalidReference(ref registry.Reference) error {
 	return fmt.Errorf("%s: invalid image reference, expecting <name:tag|name@digest>", ref)
 }

cmd/oras/internal/option/platform.go

@@ -0,0 +1,68 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package option
+
+import (
+	"fmt"
+	"runtime"
+	"strings"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/spf13/pflag"
+)
+
+// Platform option struct.
+type Platform struct {
+	Platform string
+}
+
+// ApplyFlags applies flags to a command flag set.
+func (opts *Platform) ApplyFlags(fs *pflag.FlagSet) {
+	fs.StringVarP(&opts.Platform, "platform", "", "", "fetch the manifest of a specific platform if target is multi-platform capable")
+}
+
+// parse parses the input platform flag to an oci platform type.
+func (opts *Platform) Parse() (*ocispec.Platform, error) {
+	if opts.Platform == "" {
+		return nil, nil
+	}
+
+	// OS[/Arch[/Variant]][:OSVersion]
+	// If Arch is not provided, will use GOARCH instead
+	var platformStr string
+	var p ocispec.Platform
+	platformStr, p.OSVersion, _ = strings.Cut(opts.Platform, ":")
+	parts := strings.Split(platformStr, "/")
+	switch len(parts) {
+	case 3:
+		p.Variant = parts[2]
+		fallthrough
+	case 2:
+		p.Architecture = parts[1]
+	case 1:
+		p.Architecture = runtime.GOARCH
+	default:
+		return nil, fmt.Errorf("failed to parse platform %q: expected format os[/arch[/variant]]", opts.Platform)
+	}
+	p.OS = parts[0]
+	if p.OS == "" {
+		return nil, fmt.Errorf("invalid platform: OS cannot be empty")
+	}
+	if p.Architecture == "" {
+		return nil, fmt.Errorf("invalid platform: Architecture cannot be empty")
+	}
+	return &p, nil
+}

cmd/oras/internal/option/platform_test.go

@@ -0,0 +1,83 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package option
+
+import (
+	"reflect"
+	"runtime"
+	"testing"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/spf13/pflag"
+)
+
+func TestPlatform_ApplyFlags(t *testing.T) {
+	var test struct{ Platform }
+	ApplyFlags(&test, pflag.NewFlagSet("oras-test", pflag.ExitOnError))
+	if test.Platform.Platform != "" {
+		t.Fatalf("expecting platform to be empty but got: %v", test.Platform.Platform)
+	}
+}
+
+func TestPlatform_Parse_err(t *testing.T) {
+	tests := []struct {
+		name string
+		opts *Platform
+	}{
+		{name: "empty arch 1", opts: &Platform{"os/"}},
+		{name: "empty arch 2", opts: &Platform{"os//variant"}},
+		{name: "empty os", opts: &Platform{"/arch"}},
+		{name: "empty os with variant", opts: &Platform{"/arch/variant"}},
+		{name: "trailing slash", opts: &Platform{"os/arch/variant/llama"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := tt.opts.Parse()
+			if err == nil {
+				t.Errorf("Platform.Parse() error = %v, wantErr %v", err, true)
+				return
+			}
+		})
+	}
+}
+
+func TestPlatform_Parse(t *testing.T) {
+	tests := []struct {
+		name string
+		opts *Platform
+		want *ocispec.Platform
+	}{
+		{name: "empty", opts: &Platform{""}, want: nil},
+		{name: "default arch", opts: &Platform{"os"}, want: &ocispec.Platform{OS: "os", Architecture: runtime.GOARCH}},
+		{name: "os&arch", opts: &Platform{"os/aRcH"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH"}},
+		{name: "empty variant", opts: &Platform{"os/aRcH/"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: ""}},
+		{name: "os&arch&variant", opts: &Platform{"os/aRcH/vAriAnt"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: "vAriAnt"}},
+		{name: "os version", opts: &Platform{"os/aRcH/vAriAnt:osversion"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: "vAriAnt", OSVersion: "osversion"}},
+		{name: "long os version", opts: &Platform{"os/aRcH"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := tt.opts.Parse()
+			if err != nil {
+				t.Errorf("Platform.Parse() error = %v", err)
+				return
+			}
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("Platform.Parse() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

cmd/oras/main.go

@@ -4,6 +4,7 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+	"oras.land/oras/cmd/oras/manifest"
 )
 
 func main() {
@@ -20,6 +21,7 @@ func main() {
 		discoverCmd(),
 		copyCmd(),
 		attachCmd(),
+		manifest.Cmd(),
 	)
 	if err := cmd.Execute(); err != nil {
 		os.Exit(1)

cmd/oras/manifest/cmd.go

@@ -0,0 +1,32 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package manifest
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func Cmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "manifest [fetch]",
+		Short: "[Preview] Manifest operations",
+	}
+
+	cmd.AddCommand(
+		fetchCmd(),
+	)
+	return cmd
+}

cmd/oras/manifest/fetch.go

@@ -0,0 +1,116 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package manifest
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+	"oras.land/oras/cmd/oras/internal/errors"
+	"oras.land/oras/cmd/oras/internal/option"
+	"oras.land/oras/internal/cas"
+)
+
+type fetchOptions struct {
+	option.Common
+	option.Remote
+	option.Platform
+
+	targetRef       string
+	pretty          bool
+	mediaTypes      []string
+	fetchDescriptor bool
+}
+
+func fetchCmd() *cobra.Command {
+	var opts fetchOptions
+	cmd := &cobra.Command{
+		Use:   "fetch [flags] <name:tag|name@digest>",
+		Short: "[Preview] Fetch manifest of the target artifact",
+		Long: `[Preview] Fetch manifest of the target artifact
+** This command is in preview and under development. **
+
+Example - Fetch raw manifest:
+  oras manifest fetch localhost:5000/hello:latest
+
+Example - Fetch the descriptor of a manifest:
+  oras manifest fetch --descriptor localhost:5000/hello:latest
+
+Example - Fetch manifest with specified media type:
+  oras manifest fetch --media-type 'application/vnd.oci.image.manifest.v1+json' localhost:5000/hello:latest
+
+Example - Fetch manifest with certain platform:
+  oras manifest fetch --platform 'linux/arm/v5' localhost:5000/hello:latest
+
+Example - Fetch manifest with prettified json result:
+  oras manifest fetch --pretty localhost:5000/hello:latest
+`,
+		Args: cobra.ExactArgs(1),
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			return opts.ReadPassword()
+		},
+		Aliases: []string{"get"},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.targetRef = args[0]
+			return fetchManifest(opts)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&opts.pretty, "pretty", "", false, "output prettified manifest")
+	cmd.Flags().BoolVarP(&opts.fetchDescriptor, "descriptor", "", false, "fetch a descriptor of the manifest")
+	cmd.Flags().StringSliceVarP(&opts.mediaTypes, "media-type", "", nil, "accepted media types")
+	option.ApplyFlags(&opts, cmd.Flags())
+	return cmd
+}
+
+func fetchManifest(opts fetchOptions) error {
+	ctx, _ := opts.SetLoggerLevel()
+	tagetPlatform, err := opts.Parse()
+	if err != nil {
+		return err
+	}
+	repo, err := opts.NewRepository(opts.targetRef, opts.Common)
+	if err != nil {
+		return err
+	}
+	if repo.Reference.Reference == "" {
+		return errors.NewErrInvalidReference(repo.Reference)
+	}
+	repo.ManifestMediaTypes = opts.mediaTypes
+
+	// Fetch and output
+	var content []byte
+	if opts.fetchDescriptor {
+		content, err = cas.FetchDescriptor(ctx, repo, opts.targetRef, tagetPlatform)
+	} else {
+		content, err = cas.FetchManifest(ctx, repo, opts.targetRef, tagetPlatform)
+	}
+	if err != nil {
+		return err
+	}
+	if opts.pretty {
+		buf := bytes.NewBuffer(nil)
+		if err = json.Indent(buf, content, "", "  "); err != nil {
+			return fmt.Errorf("failed to prettify: %w", err)
+		}
+		content = buf.Bytes()
+	}
+	_, err = os.Stdout.Write(content)
+	return err
+}