feat: support --format in manifest fetch command (#1295)

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

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

@@ -0,0 +1,30 @@
+/*
+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 content
+
+import ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+
+type discardHandler struct{}
+
+// OnContentFetched implements ManifestFetchHandler.
+func (discardHandler) OnContentFetched(ocispec.Descriptor, []byte) error {
+	return nil
+}
+
+// NewDiscardHandler returns a new discard handler.
+func NewDiscardHandler() ManifestFetchHandler {
+	return discardHandler{}
+}

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

@@ -0,0 +1,26 @@
+/*
+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 content
+
+import (
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
+
+// ManifestFetchHandler handles raw output for manifest fetch events.
+type ManifestFetchHandler interface {
+	// OnContentFetched is called after the manifest content is fetched.
+	OnContentFetched(desc ocispec.Descriptor, content []byte) error
+}

cmd/oras/internal/display/content/manifest_fetch.go

@@ -0,0 +1,54 @@
+/*
+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 content
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/cmd/oras/internal/display/utils"
+)
+
+// manifestFetch handles raw content output.
+type manifestFetch struct {
+	pretty     bool
+	stdout     io.Writer
+	outputPath string
+}
+
+func (h *manifestFetch) OnContentFetched(desc ocispec.Descriptor, manifest []byte) error {
+	out := h.stdout
+	if h.outputPath != "-" && h.outputPath != "" {
+		f, err := os.Create(h.outputPath)
+		if err != nil {
+			return fmt.Errorf("failed to open %q: %w", h.outputPath, err)
+		}
+		defer f.Close()
+		out = f
+	}
+	return utils.PrintJSON(out, manifest, h.pretty)
+}
+
+// NewManifestFetchHandler creates a new handler.
+func NewManifestFetchHandler(out io.Writer, pretty bool, outputPath string) ManifestFetchHandler {
+	return &manifestFetch{
+		pretty:     pretty,
+		stdout:     out,
+		outputPath: outputPath,
+	}
+}

cmd/oras/internal/display/handler.go

@@ -19,7 +19,9 @@ import (
 	"io"
 	"os"
 
+	"oras.land/oras/cmd/oras/internal/display/content"
 	"oras.land/oras/cmd/oras/internal/display/metadata"
+	"oras.land/oras/cmd/oras/internal/display/metadata/descriptor"
 	"oras.land/oras/cmd/oras/internal/display/metadata/json"
 	"oras.land/oras/cmd/oras/internal/display/metadata/template"
 	"oras.land/oras/cmd/oras/internal/display/metadata/text"
@@ -94,3 +96,36 @@ func NewPullHandler(format string, path string, tty *os.File, out io.Writer, ver
 	}
 	return statusHandler, metadataHandler
 }
+
+// NewManifestFetchHandler returns a manifest fetch handler.
+func NewManifestFetchHandler(out io.Writer, format string, outputDescriptor, pretty bool, outputPath string) (metadata.ManifestFetchHandler, content.ManifestFetchHandler) {
+	var metadataHandler metadata.ManifestFetchHandler
+	var contentHandler content.ManifestFetchHandler
+
+	switch format {
+	case "":
+		// raw
+		if outputDescriptor {
+			metadataHandler = descriptor.NewManifestFetchHandler(out, pretty)
+		} else {
+			metadataHandler = metadata.NewDiscardHandler()
+		}
+	case "json":
+		// json
+		metadataHandler = json.NewManifestFetchHandler(out)
+		if outputPath == "" {
+			contentHandler = content.NewDiscardHandler()
+		}
+	default:
+		// go template
+		metadataHandler = template.NewManifestFetchHandler(out, format)
+		if outputPath == "" {
+			contentHandler = content.NewDiscardHandler()
+		}
+	}
+
+	if contentHandler == nil {
+		contentHandler = content.NewManifestFetchHandler(out, pretty, outputPath)
+	}
+	return metadataHandler, contentHandler
+}

cmd/oras/internal/display/metadata/descriptor/manifest_fetch.go

@@ -0,0 +1,49 @@
+/*
+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 (
+	"encoding/json"
+	"fmt"
+	"io"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/cmd/oras/internal/display/metadata"
+	"oras.land/oras/cmd/oras/internal/display/utils"
+)
+
+// manifestFetchHandler handles metadata descriptor output.
+type manifestFetchHandler struct {
+	pretty bool
+	out    io.Writer
+}
+
+// OnFetched implements ManifestFetchHandler.
+func (h *manifestFetchHandler) OnFetched(_ string, desc ocispec.Descriptor, _ []byte) error {
+	descBytes, err := json.Marshal(desc)
+	if err != nil {
+		return fmt.Errorf("invalid descriptor: %w", err)
+	}
+	return utils.PrintJSON(h.out, descBytes, h.pretty)
+}
+
+// NewManifestFetchHandler creates a new handler.
+func NewManifestFetchHandler(out io.Writer, pretty bool) metadata.ManifestFetchHandler {
+	return &manifestFetchHandler{
+		pretty: pretty,
+		out:    out,
+	}
+}

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

@@ -0,0 +1,30 @@
+/*
+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 metadata
+
+import ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+
+type discard struct{}
+
+// NewDiscardHandler creates a new handler that discards output for all events.
+func NewDiscardHandler() ManifestFetchHandler {
+	return discard{}
+}
+
+// OnFetched implements ManifestFetchHandler.
+func (discard) OnFetched(string, ocispec.Descriptor, []byte) error {
+	return nil
+}

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

@@ -31,6 +31,12 @@ type AttachHandler interface {
 	OnCompleted(opts *option.Target, root, subject ocispec.Descriptor) error
 }
 
+// ManifestFetchHandler handles metadata output for manifest fetch events.
+type ManifestFetchHandler interface {
+	// OnFetched is called after the manifest content is fetched.
+	OnFetched(path string, desc ocispec.Descriptor, content []byte) error
+}
+
 // PullHandler handles metadata output for pull events.
 type PullHandler interface {
 	// OnLayerSkipped is called when a layer is skipped.

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

@@ -0,0 +1,46 @@
+/*
+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 (
+	"encoding/json"
+	"io"
+
+	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"
+)
+
+// manifestFetchHandler handles JSON metadata output for manifest fetch events.
+type manifestFetchHandler struct {
+	out io.Writer
+}
+
+// NewManifestFetchHandler creates a new handler for manifest fetch events.
+func NewManifestFetchHandler(out io.Writer) metadata.ManifestFetchHandler {
+	return &manifestFetchHandler{
+		out: out,
+	}
+}
+
+// OnFetched is called after the manifest fetch is completed.
+func (h *manifestFetchHandler) OnFetched(path string, desc ocispec.Descriptor, content []byte) error {
+	var manifest map[string]any
+	if err := json.Unmarshal(content, &manifest); err != nil {
+		manifest = nil
+	}
+	return printJSON(h.out, model.NewFetched(path, desc, manifest))
+}

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

@@ -0,0 +1,31 @@
+/*
+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 ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+
+type fetched struct {
+	Descriptor
+	Content any
+}
+
+// NewFetched creates a new fetched metadata.
+func NewFetched(path string, desc ocispec.Descriptor, content any) any {
+	return &fetched{
+		Descriptor: FromDescriptor(path, desc),
+		Content:    content,
+	}
+}

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

@@ -0,0 +1,48 @@
+/*
+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 (
+	"encoding/json"
+	"io"
+
+	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"
+)
+
+// manifestFetchHandler handles JSON metadata output for manifest fetch events.
+type manifestFetchHandler struct {
+	template string
+	out      io.Writer
+}
+
+// NewManifestFetchHandler creates a new handler for manifest fetch events.
+func NewManifestFetchHandler(out io.Writer, template string) metadata.ManifestFetchHandler {
+	return &manifestFetchHandler{
+		template: template,
+		out:      out,
+	}
+}
+
+// OnFetched is called after the manifest fetch is completed.
+func (h *manifestFetchHandler) OnFetched(path string, desc ocispec.Descriptor, content []byte) error {
+	var manifest map[string]any
+	if err := json.Unmarshal(content, &manifest); err != nil {
+		manifest = nil
+	}
+	return parseAndWrite(h.out, model.NewFetched(path, desc, manifest), h.template)
+}