feat: support --format for oras pull

cmd/oras/internal/display/handler.go

@@ -72,3 +72,26 @@
 
 	return statusHandler, metadataHandler
 }
+
+// NewPullHandler returns status and metadata handlers for pull command.
+func NewPullHandler(format string, path string, tty *os.File, verbose bool) (status.PullHandler, metadata.PullHandler) {
+	var statusHandler status.PullHandler
+	if tty != nil {
+		statusHandler = status.NewTTYPullHandler(tty)
+	} else if format == "" {
+		statusHandler = status.NewTextPullHandler(verbose)
+	} else {
+		statusHandler = status.NewDiscardHandler()
+	}
+
+	var metadataHandler metadata.PullHandler
+	switch format {
+	case "":
+		metadataHandler = text.NewPullHandler()
+	case "json":
+		metadataHandler = json.NewPullHandler(path)
+	default:
+		metadataHandler = template.NewPullHandler(path, format)
+	}
+	return statusHandler, metadataHandler
+}

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

@@ -17,6 +17,7 @@ package metadata
 
 import (
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/cmd/oras/internal/display/metadata/model"
 	"oras.land/oras/cmd/oras/internal/option"
 )
 
@@ -30,3 +31,9 @@ type PushHandler interface {
 type AttachHandler interface {
 	OnCompleted(opts *option.Target, root, subject ocispec.Descriptor) error
 }
+
+// PullHandler handles metadata output for attach events.
+type PullHandler interface {
+	// OnCompleted is called when the pull cmd execution is completed.
+	OnCompleted(opts *option.Target, desc ocispec.Descriptor, layerSkipped bool, _ []model.File) error
+}

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

@@ -0,0 +1,40 @@
+/*
+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 json
+
+import (
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/cmd/oras/internal/display/metadata"
+	"oras.land/oras/cmd/oras/internal/display/metadata/model"
+	"oras.land/oras/cmd/oras/internal/option"
+)
+
+// PullHandler handles JSON metadata output for pull events.
+type PullHandler struct {
+	path string
+}
+
+// NewPullHandler returns a new handler for Pull events.
+func NewPullHandler(path string) metadata.PullHandler {
+	return &PullHandler{
+		path: path,
+	}
+}
+
+// OnCompleted implements metadata.PullHandler.
+func (ph *PullHandler) OnCompleted(opts *option.Target, desc ocispec.Descriptor, _ bool, files []model.File) error {
+	return printJSON(model.NewPull(ph.path+"@"+desc.Digest.String(), files))
+}

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

@@ -0,0 +1,62 @@
+/*
+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 model
+
+import (
+	"fmt"
+	"path/filepath"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2/content/file"
+)
+
+// File records pulled files.
+type File struct {
+	// Absolute path of the pulled file.
+	Path string
+	Descriptor
+}
+
+// NewFile creates a new file metadata.
+func NewFile(name string, outputDir string, desc ocispec.Descriptor, descPath string) File {
+	path := name
+	if !filepath.IsAbs(name) {
+		// ignore error since it's successfully written to file store
+		path, _ = filepath.Abs(filepath.Join(outputDir, name))
+	}
+	if desc.Annotations[file.AnnotationUnpack] == "true" {
+		path = fmt.Sprintf("%s%c", path, filepath.Separator)
+	}
+	return File{
+		Path:       path,
+		Descriptor: FromDescriptor(descPath, desc),
+	}
+}
+
+type pull struct {
+	DigestReference
+	Files []File `json:"Files"`
+}
+
+// NewPull creates a new metadata struct for pull command.
+func NewPull(digestReference string, files []File) pull {
+	return pull{
+		DigestReference: DigestReference{
+			Ref: digestReference,
+		},
+		Files: files,
+	}
+}

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

@@ -0,0 +1,42 @@
+/*
+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 template
+
+import (
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/cmd/oras/internal/display/metadata"
+	"oras.land/oras/cmd/oras/internal/display/metadata/model"
+	"oras.land/oras/cmd/oras/internal/option"
+)
+
+// PullHandler handles text metadata output for pull events.
+type PullHandler struct {
+	template string
+	path     string
+}
+
+// OnCompleted implements metadata.PullHandler.
+func (ph *PullHandler) OnCompleted(opts *option.Target, desc ocispec.Descriptor, _ bool, files []model.File) error {
+	return parseAndWrite(model.NewPull(ph.path+"@"+desc.Digest.String(), files), ph.template)
+}
+
+// NewPullHandler returns a new handler for Pull events.
+func NewPullHandler(path string, template string) metadata.PullHandler {
+	return &PullHandler{
+		path:     path,
+		template: template,
+	}
+}

cmd/oras/internal/display/metadata/text/pull.go

@@ -0,0 +1,45 @@
+/*
+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 text
+
+import (
+	"fmt"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/cmd/oras/internal/display/metadata"
+	"oras.land/oras/cmd/oras/internal/display/metadata/model"
+	"oras.land/oras/cmd/oras/internal/option"
+)
+
+// PullHandler handles text metadata output for pull events.
+type PullHandler struct{}
+
+// OnCompleted implements metadata.PullHandler.
+func (p *PullHandler) OnCompleted(opts *option.Target, desc ocispec.Descriptor, layerSkipped bool, _ []model.File) error {
+	if layerSkipped {
+		_, _ = fmt.Printf("Skipped pulling layers without file name in %q\n", ocispec.AnnotationTitle)
+		_, _ = fmt.Printf("Use 'oras copy %s --to-oci-layout <layout-dir>' to pull all layers.\n", opts.RawReference)
+	} else {
+		_, _ = fmt.Println("Pulled", opts.AnnotatedReference())
+		_, _ = fmt.Println("Digest:", desc.Digest)
+	}
+	return nil
+}
+
+// NewPullHandler returns a new handler for Pull events.
+func NewPullHandler() metadata.PullHandler {
+	return &PullHandler{}
+}

cmd/oras/internal/display/status/discard.go

@@ -16,6 +16,9 @@
 package status
 
 import (
+	"sync"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras-go/v2"
 	"oras.land/oras-go/v2/content"
 )
@@ -43,5 +46,33 @@
 	return gt, nil
 }
 
+// StopTracking stops tracking the status of the target.
+func (DiscardHandler) StopTracking() {}
+
 // UpdateCopyOptions updates the copy options for the artifact push.
 func (DiscardHandler) UpdateCopyOptions(opts *oras.CopyGraphOptions, fetcher content.Fetcher) {}
+
+// OnNodeDownloading implements PullHandler.
+func (DiscardHandler) OnNodeDownloading(desc ocispec.Descriptor) error {
+	return nil
+}
+
+// OnNodeDownloaded implements PullHandler.
+func (DiscardHandler) OnNodeDownloaded(desc ocispec.Descriptor) error {
+	return nil
+}
+
+// OnNodeRestored implements PullHandler.
+func (DiscardHandler) OnNodeRestored(_ *sync.Map, _ ocispec.Descriptor) error {
+	return nil
+}
+
+// OnNodeProcessing implements PullHandler.
+func (DiscardHandler) OnNodeProcessing(desc ocispec.Descriptor) error {
+	return nil
+}
+
+// OnNodeProcessing implements PullHandler.
+func (DiscardHandler) OnNodeSkipped(printed *sync.Map, desc ocispec.Descriptor) error {
+	return nil
+}

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

@@ -16,6 +16,9 @@ limitations under the License.
 package status
 
 import (
+	"sync"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras-go/v2"
 	"oras.land/oras-go/v2/content"
 )
@@ -30,3 +33,22 @@ type PushHandler interface {
 
 // AttachHandler handles text status output for attach command.
 type AttachHandler PushHandler
+
+// PullHandler handles status output for pull command.
+type PullHandler interface {
+	// TrackTarget returns a tracked target.
+	// If no TTY is available, it returns the original target.
+	TrackTarget(gt oras.GraphTarget) (oras.GraphTarget, error)
+	// StopTracking stops tracking the target if available.
+	StopTracking()
+	// OnNodeProcessing is called when processing a manifest.
+	OnNodeProcessing(desc ocispec.Descriptor) error
+	// OnNodeDownloading is called before downloading a node.
+	OnNodeDownloading(desc ocispec.Descriptor) error
+	// OnNodeDownloaded is called after a node is downloaded.
+	OnNodeDownloaded(desc ocispec.Descriptor) error
+	// OnNodeRestored is called after a deduplicated node is restored.
+	OnNodeRestored(printed *sync.Map, desc ocispec.Descriptor) error
+	// OnNodeSkipped is called when a node is skipped.
+	OnNodeSkipped(printed *sync.Map, desc ocispec.Descriptor) error
+}

cmd/oras/internal/display/status/text.go

@@ -23,6 +23,7 @@ import (
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras-go/v2"
 	"oras.land/oras-go/v2/content"
+	utils "oras.land/oras/cmd/oras/internal/display/utils"
 )
 
 // TextPushHandler handles text status output for push events.
@@ -86,3 +87,57 @@ func (ph *TextPushHandler) UpdateCopyOptions(opts *oras.CopyGraphOptions, fetche
 func NewTextAttachHandler(verbose bool) AttachHandler {
 	return NewTextPushHandler(verbose)
 }
+
+// TextPullHandler handles text status output for pull events.
+type TextPullHandler struct {
+	fetcher content.Fetcher
+	verbose bool
+}
+
+func (ph *TextPullHandler) printOnce(printed *sync.Map, s ocispec.Descriptor, msg string) error {
+	if _, loaded := printed.LoadOrStore(utils.GenerateContentKey(s), true); loaded {
+		return nil
+	}
+	return PrintStatus(s, msg, ph.verbose)
+}
+
+// TrackTarget returns a tracked target.
+func (ph *TextPullHandler) TrackTarget(gt oras.GraphTarget) (oras.GraphTarget, error) {
+	ph.fetcher = gt
+	return gt, nil
+}
+
+// StopTracking stop tracked target.
+func (ph *TextPullHandler) StopTracking() {}
+
+// OnNodeDownloading implements PullHandler.
+func (ph *TextPullHandler) OnNodeDownloading(desc ocispec.Descriptor) error {
+	return PrintStatus(desc, utils.PullPromptDownloading, ph.verbose)
+}
+
+// OnNodeDownloaded implements PullHandler.
+func (ph *TextPullHandler) OnNodeDownloaded(desc ocispec.Descriptor) error {
+	return PrintStatus(desc, utils.PullPromptDownloaded, ph.verbose)
+}
+
+// OnNodeRestored implements PullHandler.
+func (ph *TextPullHandler) OnNodeRestored(printed *sync.Map, desc ocispec.Descriptor) error {
+	return ph.printOnce(printed, desc, utils.PullPromptRestored)
+}
+
+// OnNodeProcessing implements PullHandler.
+func (ph *TextPullHandler) OnNodeProcessing(desc ocispec.Descriptor) error {
+	return PrintStatus(desc, utils.PullPromptProcessing, ph.verbose)
+}
+
+// OnNodeProcessing implements PullHandler.
+func (ph *TextPullHandler) OnNodeSkipped(printed *sync.Map, desc ocispec.Descriptor) error {
+	return ph.printOnce(printed, desc, utils.PullPromptSkipped)
+}
+
+// NewTextPullHandler returns a new handler for pull command.
+func NewTextPullHandler(verbose bool) PullHandler {
+	return &TextPullHandler{
+		verbose: verbose,
+	}
+}