feat: support formatted output in oras attach and push (#1237)

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

cmd/oras/internal/display/handler.go

@@ -0,0 +1,74 @@
+/*
+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 display
+
+import (
+	"os"
+
+	"oras.land/oras/cmd/oras/internal/display/metadata"
+	"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"
+	"oras.land/oras/cmd/oras/internal/display/status"
+)
+
+// NewPushHandler returns status and metadata handlers for push command.
+func NewPushHandler(format string, tty *os.File, verbose bool) (status.PushHandler, metadata.PushHandler) {
+	var statusHandler status.PushHandler
+	if tty != nil {
+		statusHandler = status.NewTTYPushHandler(tty)
+	} else if format == "" {
+		statusHandler = status.NewTextPushHandler(verbose)
+	} else {
+		statusHandler = status.NewDiscardHandler()
+	}
+
+	var metadataHandler metadata.PushHandler
+	switch format {
+	case "":
+		metadataHandler = text.NewPushHandler()
+	case "json":
+		metadataHandler = json.NewPushHandler()
+	default:
+		metadataHandler = template.NewPushHandler(format)
+	}
+
+	return statusHandler, metadataHandler
+}
+
+// NewAttachHandler returns status and metadata handlers for attach command.
+func NewAttachHandler(format string, tty *os.File, verbose bool) (status.AttachHandler, metadata.AttachHandler) {
+	var statusHandler status.AttachHandler
+	if tty != nil {
+		statusHandler = status.NewTTYAttachHandler(tty)
+	} else if format == "" {
+		statusHandler = status.NewTextAttachHandler(verbose)
+	} else {
+		statusHandler = status.NewDiscardHandler()
+	}
+
+	var metadataHandler metadata.AttachHandler
+	switch format {
+	case "":
+		metadataHandler = text.NewAttachHandler()
+	case "json":
+		metadataHandler = json.NewAttachHandler()
+	default:
+		metadataHandler = template.NewAttachHandler(format)
+	}
+
+	return statusHandler, metadataHandler
+}

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

@@ -0,0 +1,32 @@
+/*
+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"
+	"oras.land/oras/cmd/oras/internal/option"
+)
+
+// PushHandler handles metadata output for push events.
+type PushHandler interface {
+	OnCopied(opts *option.Target) error
+	OnCompleted(root ocispec.Descriptor) error
+}
+
+// AttachHandler handles metadata output for attach events.
+type AttachHandler interface {
+	OnCompleted(opts *option.Target, root, subject ocispec.Descriptor) error
+}

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

@@ -0,0 +1,36 @@
+/*
+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"
+)
+
+// AttachHandler handles json metadata output for attach events.
+type AttachHandler struct{}
+
+// NewAttachHandler creates a new handler for attach events.
+func NewAttachHandler() metadata.AttachHandler {
+	return AttachHandler{}
+}
+
+// OnCompleted is called when the attach command is completed.
+func (AttachHandler) OnCompleted(opts *option.Target, root, subject ocispec.Descriptor) error {
+	return printJSON(model.NewPush(root, opts.Path))
+}

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

@@ -0,0 +1,27 @@
+/*
+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"
+	"os"
+)
+
+func printJSON(object any) error {
+	encoder := json.NewEncoder(os.Stdout)
+	encoder.SetIndent("", "  ")
+	return encoder.Encode(object)
+}

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

@@ -0,0 +1,44 @@
+/*
+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"
+)
+
+// PushHandler handles JSON metadata output for push events.
+type PushHandler struct {
+	path string
+}
+
+// NewPushHandler creates a new handler for push events.
+func NewPushHandler() metadata.PushHandler {
+	return &PushHandler{}
+}
+
+// OnCopied is called after files are copied.
+func (ph *PushHandler) OnCopied(opts *option.Target) error {
+	ph.path = opts.Path
+	return nil
+}
+
+// OnCompleted is called after the push is completed.
+func (ph *PushHandler) OnCompleted(root ocispec.Descriptor) error {
+	return printJSON(model.NewPush(root, ph.path))
+}

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

@@ -0,0 +1,72 @@
+/*
+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 (
+	"github.com/opencontainers/go-digest"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
+
+// DigestReference is a reference to an artifact with digest.
+type DigestReference struct {
+	Ref string
+}
+
+// NewDigestReference creates a new digest reference.
+func NewDigestReference(name string, digest string) DigestReference {
+	return DigestReference{
+		Ref: name + "@" + digest,
+	}
+}
+
+// Descriptor is a descriptor with digest reference.
+// We cannot use ocispec.Descriptor here since the first letter of the json
+// annotation key is not uppercase.
+type Descriptor struct {
+	DigestReference
+
+	// MediaType is the media type of the object this schema refers to.
+	MediaType string
+
+	// Digest is the digest of the targeted content.
+	Digest digest.Digest
+
+	// Size specifies the size in bytes of the blob.
+	Size int64
+
+	// URLs specifies a list of URLs from which this object MAY be downloaded
+	URLs []string `json:",omitempty"`
+
+	// Annotations contains arbitrary metadata relating to the targeted content.
+	Annotations map[string]string `json:",omitempty"`
+
+	// ArtifactType is the IANA media type of this artifact.
+	ArtifactType string
+}
+
+// FromDescriptor converts a OCI descriptor to a descriptor with digest reference.
+func FromDescriptor(name string, desc ocispec.Descriptor) Descriptor {
+	ret := Descriptor{
+		DigestReference: NewDigestReference(name, desc.Digest.String()),
+		MediaType:       desc.MediaType,
+		Digest:          desc.Digest,
+		Size:            desc.Size,
+		URLs:            desc.URLs,
+		Annotations:     desc.Annotations,
+		ArtifactType:    desc.ArtifactType,
+	}
+	return ret
+}

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

@@ -0,0 +1,28 @@
+/*
+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"
+
+// push contains metadata formatted by oras push.
+type push struct {
+	Descriptor
+}
+
+// NewPush returns a metadata getter for push command.
+func NewPush(desc ocispec.Descriptor, path string) any {
+	return push{FromDescriptor(path, desc)}
+}

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

@@ -0,0 +1,38 @@
+/*
+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"
+)
+
+// AttachHandler handles go-template metadata output for attach events.
+type AttachHandler struct {
+	template string
+}
+
+// NewAttachHandler returns a new handler for attach metadata events.
+func NewAttachHandler(template string) metadata.AttachHandler {
+	return &AttachHandler{template: template}
+}
+
+// OnCompleted formats the metadata of attach command.
+func (ah *AttachHandler) OnCompleted(opts *option.Target, root, subject ocispec.Descriptor) error {
+	return parseAndWrite(model.NewPush(root, opts.Path), ah.template)
+}