feat: add oras restore command (#1792)

Signed-off-by: Lixia (Sylvia) Lei <[email protected]>

Author: Wwwsylvia

cmd/oras/internal/display/handler.go

@@ -238,6 +238,14 @@ func NewBackupHandler(printer *output.Printer, tty *os.File, repo string, fetche
 	return status.NewTextBackupHandler(printer, fetcher), text.NewBackupHandler(repo, printer)
 }
 
+// NewRestoreHandler returns restore handlers.
+func NewRestoreHandler(printer *output.Printer, tty *os.File, fetcher fetcher.Fetcher, dryRun bool) (status.RestoreHandler, metadata.RestoreHandler) {
+	if tty != nil {
+		return status.NewTTYRestoreHandler(tty, fetcher), text.NewRestoreHandler(printer, dryRun)
+	}
+	return status.NewTextRestoreHandler(printer, fetcher), text.NewRestoreHandler(printer, dryRun)
+}
+
 // NewBlobPushHandler returns blob push handlers.
 func NewBlobPushHandler(printer *output.Printer, outputDescriptor bool, pretty bool, desc ocispec.Descriptor, tty *os.File) (status.BlobPushHandler, metadata.BlobPushHandler) {
 	if outputDescriptor {

cmd/oras/internal/display/handler_test.go

@@ -161,3 +161,28 @@ func TestNewBackupHandler(t *testing.T) {
 		}
 	})
 }
+
+func TestNewRestoreHandler(t *testing.T) {
+	printer := output.NewPrinter(os.Stdout, os.Stderr)
+	mockFetcher := testutils.NewMockFetcher()
+
+	t.Run("with TTY", func(t *testing.T) {
+		statusHandler, metadataHandler := NewRestoreHandler(printer, os.Stdout, mockFetcher.Fetcher, false)
+		if _, ok := statusHandler.(*status.TTYRestoreHandler); !ok {
+			t.Errorf("expected *status.TTYRestoreHandler actual %v", reflect.TypeOf(statusHandler))
+		}
+		if _, ok := metadataHandler.(*text.RestoreHandler); !ok {
+			t.Errorf("expected *text.RestoreHandler actual %v", reflect.TypeOf(metadataHandler))
+		}
+	})
+
+	t.Run("without TTY", func(t *testing.T) {
+		statusHandler, metadataHandler := NewRestoreHandler(printer, nil, mockFetcher.Fetcher, false)
+		if _, ok := statusHandler.(*status.TextRestoreHandler); !ok {
+			t.Errorf("expected *status.TextRestoreHandler actual %v", reflect.TypeOf(statusHandler))
+		}
+		if _, ok := metadataHandler.(*text.RestoreHandler); !ok {
+			t.Errorf("expected *text.RestoreHandler actual %v", reflect.TypeOf(metadataHandler))
+		}
+	})
+}

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

@@ -119,6 +119,16 @@ type BackupHandler interface {
 	OnBackupCompleted(tagsCount int, path string, duration time.Duration) error
 }
 
+// RestoreHandler handles metadata output for restore events.
+type RestoreHandler interface {
+	Renderer
+
+	OnTarLoaded(path string, size int64) error
+	OnTagsFound(tags []string) error
+	OnArtifactPushed(tag string, referrerCount int) error
+	OnRestoreCompleted(tagsCount int, repo string, duration time.Duration) error
+}
+
 // BlobPushHandler handles metadata output for blob push events.
 type BlobPushHandler interface {
 	Renderer

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

@@ -56,15 +56,28 @@ func (bh *BackupHandler) OnTarExporting(path string) error {
 // OnArtifactPulled implements metadata.BackupHandler.
 func (bh *BackupHandler) OnArtifactPulled(tag string, referrerCount int) error {
 	// represent duration in a human-readable format
-	return bh.printer.Printf("Pulled tag %s and %d referrer(s)\n", tag, referrerCount)
+	return bh.printer.Printf("Pulled tag %s with %d referrer(s)\n", tag, referrerCount)
 }
 
 // OnTagsFound implements metadata.BackupHandler.
 func (bh *BackupHandler) OnTagsFound(tags []string) error {
 	if len(tags) == 0 {
 		return bh.printer.Printf("No tags found in %s\n", bh.repo)
 	}
-	return bh.printer.Printf("Found %d tag(s) in %s: %s\n", len(tags), bh.repo, strings.Join(tags, ", "))
+	if len(tags) <= 5 {
+		// print small number of tags in one line
+		return bh.printer.Printf("Found %d tag(s) in %s: %s\n", len(tags), bh.repo, strings.Join(tags, ", "))
+	}
+	// print large number of tags line by line
+	if err := bh.printer.Printf("Found %d tag(s) in %s:\n", len(tags), bh.repo); err != nil {
+		return err
+	}
+	for _, tag := range tags {
+		if err := bh.printer.Println(tag); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
 // Render implements metadata.BackupHandler.

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

@@ -112,7 +112,7 @@ func TestBackupHandler_OnArtifactPulled(t *testing.T) {
 			name:    "good path",
 			out:     &bytes.Buffer{},
 			wantErr: false,
-			want:    fmt.Sprintf("Pulled tag %s and %d referrer(s)\n", tag, referrerCount),
+			want:    fmt.Sprintf("Pulled tag %s with %d referrer(s)\n", tag, referrerCount),
 		},
 	}
 	for _, tt := range tests {
@@ -142,12 +142,26 @@ func TestBackupHandler_OnTagsFound(t *testing.T) {
 		want    string
 	}{
 		{
-			name:    "good path with tags",
+			name:    "good path with few tags",
 			tags:    []string{"t1", "t2"},
 			out:     &bytes.Buffer{},
 			wantErr: false,
 			want:    fmt.Sprintf("Found 2 tag(s) in %s: t1, t2\n", repo),
 		},
+		{
+			name:    "good path with exactly 5 tags",
+			tags:    []string{"t1", "t2", "t3", "t4", "t5"},
+			out:     &bytes.Buffer{},
+			wantErr: false,
+			want:    fmt.Sprintf("Found 5 tag(s) in %s: t1, t2, t3, t4, t5\n", repo),
+		},
+		{
+			name:    "good path with more than 5 tags",
+			tags:    []string{"t1", "t2", "t3", "t4", "t5", "t6"},
+			out:     &bytes.Buffer{},
+			wantErr: false,
+			want:    fmt.Sprintf("Found 6 tag(s) in %s:\nt1\nt2\nt3\nt4\nt5\nt6\n", repo),
+		},
 		{
 			name:    "good path with no tags",
 			tags:    []string{},

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

@@ -0,0 +1,85 @@
+/*
+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 (
+	"strings"
+	"time"
+
+	"oras.land/oras/cmd/oras/internal/display/status/progress/humanize"
+	"oras.land/oras/cmd/oras/internal/output"
+)
+
+// RestoreHandler handles text metadata output for restore command.
+type RestoreHandler struct {
+	printer *output.Printer
+	dryRun  bool
+}
+
+// NewRestoreHandler creates a new RestoreHandler.
+func NewRestoreHandler(printer *output.Printer, dryRun bool) *RestoreHandler {
+	return &RestoreHandler{
+		printer: printer,
+		dryRun:  dryRun,
+	}
+}
+
+// OnTarLoaded implements metadata.RestoreHandler.
+func (rh *RestoreHandler) OnTarLoaded(path string, size int64) error {
+	return rh.printer.Printf("Loaded backup archive: %s (%s)\n", path, humanize.ToBytes(size))
+}
+
+// OnTagsFound implements metadata.RestoreHandler.
+func (rh *RestoreHandler) OnTagsFound(tags []string) error {
+	if len(tags) == 0 {
+		return rh.printer.Printf("No tags found in the backup\n")
+	}
+	if len(tags) <= 5 {
+		// print small number of tags in one line
+		return rh.printer.Printf("Found %d tag(s) in the backup: %s\n", len(tags), strings.Join(tags, ", "))
+	}
+	// print large number of tags line by line
+	if err := rh.printer.Printf("Found %d tag(s) in the backup:\n", len(tags)); err != nil {
+		return err
+	}
+	for _, tag := range tags {
+		if err := rh.printer.Println(tag); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// OnArtifactPushed implements metadata.RestoreHandler.
+func (rh *RestoreHandler) OnArtifactPushed(tag string, referrerCount int) error {
+	if rh.dryRun {
+		return rh.printer.Printf("Dry run: would push tag %s with %d referrer(s)\n", tag, referrerCount)
+	}
+	return rh.printer.Printf("Pushed tag %s with %d referrer(s)\n", tag, referrerCount)
+}
+
+// OnRestoreCompleted implements metadata.RestoreHandler.
+func (rh *RestoreHandler) OnRestoreCompleted(tagsCount int, repo string, duration time.Duration) error {
+	if rh.dryRun {
+		return rh.printer.Printf("Dry run complete: %d tag(s) would be restored to %q (no data pushed)\n", tagsCount, repo)
+	}
+	return rh.printer.Printf("Successfully restored %d tag(s) to %q in %s\n", tagsCount, repo, humanize.FormatDuration(duration))
+}
+
+// Render implements metadata.RestoreHandler.
+func (rh *RestoreHandler) Render() error {
+	return nil
+}