feat: add manifest fetch-config

cmd/oras/internal/descriptor/descriptor.go

@@ -0,0 +1,25 @@
+/*
+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 descriptor
+
+import (
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/internal/docker"
+)
+
+func IsImageManifest(mediaType string) bool {
+	return mediaType == docker.MediaTypeManifest || mediaType == ocispec.MediaTypeImageManifest
+}

cmd/oras/internal/descriptor/descriptor_test.go

@@ -0,0 +1,35 @@
+/*
+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 descriptor
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestIsImageManifest(t *testing.T) {
+	mediaType := "application/vnd.oci.image.manifest.v1+json"
+	got := IsImageManifest(mediaType)
+	if !reflect.DeepEqual(got, true) {
+		t.Fatalf("IsImageManifest() got %v, want %v", got, true)
+	}
+
+	mediaType = "application/vnd.cncf.oras.artifact.manifest.v1+json"
+	got = IsImageManifest(mediaType)
+	if !reflect.DeepEqual(got, false) {
+		t.Fatalf("IsImageManifest() got %v, want %v", got, false)
+	}
+}

cmd/oras/manifest/cmd.go

@@ -27,6 +27,7 @@ func Cmd() *cobra.Command {
 
 	cmd.AddCommand(
 		fetchCmd(),
+		fetchConfigCmd(),
 	)
 	return cmd
 }

cmd/oras/manifest/fetchConfig.go

@@ -0,0 +1,176 @@
+/*
+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 (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/spf13/cobra"
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/content/oci"
+	"oras.land/oras/cmd/oras/internal/descriptor"
+	oerrors "oras.land/oras/cmd/oras/internal/errors"
+	"oras.land/oras/cmd/oras/internal/option"
+	"oras.land/oras/internal/cache"
+)
+
+type fetchConfigOptions struct {
+	option.Common
+	option.Descriptor
+	option.Pretty
+	option.Remote
+
+	cacheRoot  string
+	mediaType  string
+	outputPath string
+	targetRef  string
+}
+
+func fetchConfigCmd() *cobra.Command {
+	var opts fetchConfigOptions
+	cmd := &cobra.Command{
+		Use:   "fetch-config [flag] name<:tag|@digest>",
+		Short: "[Preview] Fetch the config of a manifest from a remote registry",
+		Long: `[Preview] Fetch the config of a manifest from a remote registry
+
+** This command is in preview and under development. **
+
+Example - Fetch the config:
+  oras manifest fetch-config localhost:5000/hello:latest
+
+Example - Fetch the config and save it to a local file:
+  oras manifest fetch-config --output config.json localhost:5000/hello:latest
+
+Example - Fetch the descriptor of the config:
+oras manifest fetch-config --descriptor localhost:5000/hello:latest
+`,
+		Args: cobra.ExactArgs(1),
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			if opts.outputPath == "-" && opts.OutputDescriptor {
+				return errors.New("`--output -` cannot be used with `--descriptor` at the same time")
+			}
+
+			opts.cacheRoot = os.Getenv("ORAS_CACHE")
+			return opts.ReadPassword()
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.targetRef = args[0]
+			return fetchConfig(opts)
+		},
+	}
+
+	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "output file path")
+	cmd.Flags().StringVarP(&opts.mediaType, "media-type", "", "", "media type of the manifest config")
+	option.ApplyFlags(&opts, cmd.Flags())
+	return cmd
+}
+
+func fetchConfig(opts fetchConfigOptions) (fetchErr error) {
+	ctx, _ := opts.SetLoggerLevel()
+
+	repo, err := opts.NewRepository(opts.targetRef, opts.Common)
+	if err != nil {
+		return err
+	}
+
+	if repo.Reference.Reference == "" {
+		return oerrors.NewErrInvalidReference(repo.Reference)
+	}
+
+	var src oras.ReadOnlyTarget = repo
+	if opts.cacheRoot != "" {
+		ociStore, err := oci.New(opts.cacheRoot)
+		if err != nil {
+			return err
+		}
+		src = cache.New(repo, ociStore)
+	}
+
+	configDesc, err := fetchConfigDesc(ctx, src, opts.targetRef, opts.mediaType)
+	if err != nil {
+		return err
+	}
+
+	// output config's descriptor if `--descriptor` is used
+	if opts.OutputDescriptor {
+		descBytes, err := json.Marshal(configDesc)
+		if err != nil {
+			return err
+		}
+		err = opts.Output(os.Stdout, descBytes)
+		if err != nil {
+			return err
+		}
+	}
+
+	contentBytes, err := content.FetchAll(ctx, src, configDesc)
+	if err != nil {
+		return err
+	}
+
+	// save config into the local file if the output path is provided
+	if opts.outputPath != "" && opts.outputPath != "-" {
+		file, err := os.Create(opts.outputPath)
+		if err != nil {
+			return err
+		}
+		defer func() {
+			if err := file.Close(); fetchErr == nil {
+				fetchErr = err
+			}
+		}()
+
+		if _, err = file.Write(contentBytes); err != nil {
+			return err
+		}
+	}
+
+	// output config
+	if (opts.outputPath == "" && !opts.OutputDescriptor) || opts.outputPath == "-" {
+		err = opts.Output(os.Stdout, contentBytes)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func fetchConfigDesc(ctx context.Context, src oras.ReadOnlyTarget, reference string, configMediaType string) (ocispec.Descriptor, error) {
+	// fetch manifest descriptor
+	manifestDesc, err := oras.Resolve(ctx, src, reference, oras.ResolveOptions{})
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+
+	// fetch config descriptor
+	successors, err := content.Successors(ctx, src, manifestDesc)
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	for i, s := range successors {
+		if s.MediaType == configMediaType || (configMediaType == "" && i == 0 && descriptor.IsImageManifest(manifestDesc.MediaType)) {
+			return s, nil
+		}
+	}
+	return ocispec.Descriptor{}, fmt.Errorf("%s does not have a config", reference)
+}

cmd/oras/pull.go

@@ -27,11 +27,11 @@ import (
 	"oras.land/oras-go/v2/content"
 	"oras.land/oras-go/v2/content/file"
 	"oras.land/oras-go/v2/content/oci"
+	"oras.land/oras/cmd/oras/internal/descriptor"
 	"oras.land/oras/cmd/oras/internal/display"
 	"oras.land/oras/cmd/oras/internal/errors"
 	"oras.land/oras/cmd/oras/internal/option"
 	"oras.land/oras/internal/cache"
-	"oras.land/oras/internal/docker"
 )
 
 type pullOptions struct {
@@ -121,7 +121,7 @@ func runPull(opts pullOptions) error {
 			// 2) MediaType not specified and current node is config.
 			// Note: For a manifest, the 0th indexed element is always a
 			// manifest config.
-			if (s.MediaType == configMediaType || (configMediaType == "" && i == 0 && isManifestMediaType(desc.MediaType))) && configPath != "" {
+			if (s.MediaType == configMediaType || (configMediaType == "" && i == 0 && descriptor.IsImageManifest(desc.MediaType))) && configPath != "" {
 				// Add annotation for manifest config
 				if s.Annotations == nil {
 					s.Annotations = make(map[string]string)
@@ -181,7 +181,3 @@ func runPull(opts pullOptions) error {
 	fmt.Println("Digest:", desc.Digest)
 	return nil
 }
-
-func isManifestMediaType(mediaType string) bool {
-	return mediaType == docker.MediaTypeManifest || mediaType == ocispec.MediaTypeImageManifest
-}