feat: support --platform for oras attach

cmd/oras/internal/option/platform.go

@@ -24,28 +24,35 @@ import (
 	"github.com/spf13/pflag"
 )
 
+const (
+	PlatformFlagName = "platform"
+)
+
 // Platform option struct.
 type Platform struct {
-	platform string
-	Platform *ocispec.Platform
+	PlatformFlag string
+	Platform     *ocispec.Platform
 }
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Platform) ApplyFlags(fs *pflag.FlagSet) {
-	fs.StringVarP(&opts.platform, "platform", "", "", "request platform in the form of `os[/arch][/variant][:os_version]`")
+	if fs.Lookup(PlatformFlagName) != nil {
+		return
+	}
+	fs.StringVarP(&opts.PlatformFlag, PlatformFlagName, "", "", "request platform in the form of `os[/arch][/variant][:os_version]`")
 }
 
 // parse parses the input platform flag to an oci platform type.
 func (opts *Platform) Parse() error {
-	if opts.platform == "" {
+	if opts.PlatformFlag == "" {
 		return 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, ":")
+	platformStr, p.OSVersion, _ = strings.Cut(opts.PlatformFlag, ":")
 	parts := strings.Split(platformStr, "/")
 	switch len(parts) {
 	case 3:
@@ -56,7 +63,7 @@ func (opts *Platform) Parse() error {
 	case 1:
 		p.Architecture = runtime.GOARCH
 	default:
-		return fmt.Errorf("failed to parse platform %q: expected format os[/arch[/variant]]", opts.platform)
+		return fmt.Errorf("failed to parse platform %q: expected format os[/arch[/variant]]", opts.PlatformFlag)
 	}
 	p.OS = parts[0]
 	if p.OS == "" {

cmd/oras/internal/option/platform_test.go

@@ -25,8 +25,8 @@ import (
 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)
+	if test.Platform.PlatformFlag != "" {
+		t.Fatalf("expecting platform to be empty but got: %v", test.Platform.PlatformFlag)
 	}
 }
 
@@ -58,13 +58,13 @@ func TestPlatform_Parse(t *testing.T) {
 		opts *Platform
 		want *ocispec.Platform
 	}{
-		{name: "empty", opts: &Platform{platform: ""}, want: nil},
-		{name: "default arch", opts: &Platform{platform: "os"}, want: &ocispec.Platform{OS: "os", Architecture: runtime.GOARCH}},
-		{name: "os&arch", opts: &Platform{platform: "os/aRcH"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH"}},
-		{name: "empty variant", opts: &Platform{platform: "os/aRcH/"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: ""}},
-		{name: "os&arch&variant", opts: &Platform{platform: "os/aRcH/vAriAnt"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: "vAriAnt"}},
-		{name: "os version", opts: &Platform{platform: "os/aRcH/vAriAnt:osversion"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: "vAriAnt", OSVersion: "osversion"}},
-		{name: "long os version", opts: &Platform{platform: "os/aRcH"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH"}},
+		{name: "empty", opts: &Platform{PlatformFlag: ""}, want: nil},
+		{name: "default arch", opts: &Platform{PlatformFlag: "os"}, want: &ocispec.Platform{OS: "os", Architecture: runtime.GOARCH}},
+		{name: "os&arch", opts: &Platform{PlatformFlag: "os/aRcH"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH"}},
+		{name: "empty variant", opts: &Platform{PlatformFlag: "os/aRcH/"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: ""}},
+		{name: "os&arch&variant", opts: &Platform{PlatformFlag: "os/aRcH/vAriAnt"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: "vAriAnt"}},
+		{name: "os version", opts: &Platform{PlatformFlag: "os/aRcH/vAriAnt:osversion"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH", Variant: "vAriAnt", OSVersion: "osversion"}},
+		{name: "long os version", opts: &Platform{PlatformFlag: "os/aRcH"}, want: &ocispec.Platform{OS: "os", Architecture: "aRcH"}},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

cmd/oras/root/attach.go

@@ -39,6 +39,7 @@ type attachOptions struct {
 	option.Packer
 	option.Target
 	option.Format
+	option.Platform
 
 	artifactType string
 	concurrency  int
@@ -56,6 +57,9 @@ func attachCmd() *cobra.Command {
 Example - Attach file 'hi.txt' with aritifact type 'doc/example' to manifest 'hello:v1' in registry 'localhost:5000':
   oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt
 
+Example - Attach file 'hi.txt' to a specific artifact with platform 'linux/amd64' in multi-arch index 'hello:v1'
+  oras attach --artifact-type doc/example --platform linux/amd64 localhost:5000/hello:v1 hi.txt
+
 Example - Push file "hi.txt" with the custom layer media type 'application/vnd.me.hi':
   oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt:application/vnd.me.hi
 
@@ -94,6 +98,7 @@ Example - Attach file to the manifest tagged 'v1' in an OCI image layout folder
 
 	cmd.Flags().StringVarP(&opts.artifactType, "artifact-type", "", "", "artifact type")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 5, "concurrency level")
+	cmd.Flags().StringVarP(&opts.PlatformFlag, option.PlatformFlagName, "", "", "attach to an arch specific subject, in the form of `os[/arch][/variant][:os_version]`")
 	_ = cmd.MarkFlagRequired("artifact-type")
 	opts.EnableDistributionSpecFlag()
 	option.ApplyFlags(&opts, cmd.Flags())
@@ -132,7 +137,9 @@ func runAttach(cmd *cobra.Command, opts *attachOptions) error {
 	// add both pull and push scope hints for dst repository
 	// to save potential push-scope token requests during copy
 	ctx = registryutil.WithScopeHint(ctx, dst, auth.ActionPull, auth.ActionPush)
-	subject, err := dst.Resolve(ctx, opts.Reference)
+	fetchOpts := oras.DefaultResolveOptions
+	fetchOpts.TargetPlatform = opts.Platform.Platform
+	subject, err := oras.Resolve(ctx, dst, opts.Reference, fetchOpts)
 	if err != nil {
 		return err
 	}

test/e2e/suite/command/attach.go

@@ -29,6 +29,7 @@ import (
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras/test/e2e/internal/testdata/feature"
 	"oras.land/oras/test/e2e/internal/testdata/foobar"
+	"oras.land/oras/test/e2e/internal/testdata/multi_arch"
 	. "oras.land/oras/test/e2e/internal/utils"
 	"oras.land/oras/test/e2e/internal/utils/match"
 )
@@ -99,6 +100,21 @@ var _ = Describe("1.1 registry users:", func() {
 				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
 		})
 
+		It("should attach a file to an arch-specific subject", func() {
+			testRepo := attachTestRepo("arch-specific")
+			// Below line will cause unexpected 500
+			// pending for https://github.com/project-zot/zot/pull/2351 to be released
+			// CopyZOTRepo(ImageRepo, testRepo)
+			subjectRef := RegistryRef(ZOTHost, testRepo, multi_arch.Tag)
+			ORAS("cp", RegistryRef(ZOTHost, ImageRepo, multi_arch.Tag), subjectRef).Exec()
+			artifactType := "test/attach"
+			// test
+			out := ORAS("attach", "--artifact-type", artifactType, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), "--format", "{{.Digest}}", "--platform", "linux/amd64").
+				WithWorkDir(PrepareTempFiles()).Exec().Out.Contents()
+			// validate
+			ORAS("discover", "--artifact-type", artifactType, RegistryRef(ZOTHost, testRepo, multi_arch.LinuxAMD64.Digest.String())).MatchKeyWords(string(out)).Exec()
+		})
+
 		It("should attach a file to a subject and export the built manifest", func() {
 			// prepare
 			testRepo := attachTestRepo("export-manifest")
@@ -282,6 +298,18 @@ var _ = Describe("OCI image layout users:", func() {
 			fetched := ORAS("manifest", "fetch", Flags.Layout, LayoutRef(root, index.Manifests[0].Digest.String())).Exec().Out.Contents()
 			MatchFile(filepath.Join(root, exportName), string(fetched), DefaultTimeout)
 		})
+
+		It("should attach a file to an arch-specific subject", func() {
+			root := PrepareTempOCI(ImageRepo)
+			subjectRef := LayoutRef(root, multi_arch.Tag)
+			artifactType := "test/attach"
+			// test
+			out := ORAS("attach", Flags.Layout, "--artifact-type", artifactType, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), "--format", "{{.Digest}}", "--platform", "linux/amd64").
+				WithWorkDir(PrepareTempFiles()).Exec().Out.Contents()
+			// validate
+			ORAS("discover", Flags.Layout, "--artifact-type", artifactType, LayoutRef(root, multi_arch.LinuxAMD64.Digest.String())).MatchKeyWords(string(out)).Exec()
+		})
+
 		It("should attach a file via a OCI Image", func() {
 			root := PrepareTempOCI(ImageRepo)
 			subjectRef := LayoutRef(root, foobar.Tag)