Add oras.Pack

pack.go

@@ -0,0 +1,98 @@
+/*
+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 oras
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/opencontainers/go-digest"
+	specs "github.com/opencontainers/image-spec/specs-go"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/errdef"
+)
+
+// MediaTypeUnknownConfig is the default mediaType used when no
+// config media type is specified.
+const MediaTypeUnknownConfig = "application/vnd.unknown.config.v1+json"
+
+// PackOptions contains parameters for oras.Pack.
+type PackOptions struct {
+	ConfigDescriptor    *ocispec.Descriptor
+	ConfigMediaType     string
+	ConfigAnnotations   map[string]string
+	ManifestAnnotations map[string]string
+}
+
+// Pack packs the given layers, generates a manifest for the pack,
+// and pushes it to a content storage. If succeeded, returns a descriptor of the manifest.
+func Pack(ctx context.Context, pusher content.Pusher, layers []ocispec.Descriptor, opts PackOptions) (ocispec.Descriptor, error) {
+	configMediaType := MediaTypeUnknownConfig
+	if opts.ConfigMediaType != "" {
+		configMediaType = opts.ConfigMediaType
+	}
+
+	var configDesc ocispec.Descriptor
+	if opts.ConfigDescriptor != nil {
+		configDesc = *opts.ConfigDescriptor
+	} else {
+		configBytes := []byte("{}")
+		configDesc = ocispec.Descriptor{
+			MediaType:   configMediaType,
+			Digest:      digest.FromBytes(configBytes),
+			Size:        int64(len(configBytes)),
+			Annotations: opts.ConfigAnnotations,
+		}
+
+		// push config.
+		if err := pusher.Push(ctx, configDesc, bytes.NewReader(configBytes)); err != nil && !errors.Is(err, errdef.ErrAlreadyExists) {
+			return ocispec.Descriptor{}, fmt.Errorf("failed to push config: %w", err)
+		}
+	}
+
+	if layers == nil {
+		layers = []ocispec.Descriptor{} // make it an empty array to prevent potential server-side bugs
+	}
+
+	manifest := ocispec.Manifest{
+		Versioned: specs.Versioned{
+			SchemaVersion: 2, // historical value. does not pertain to OCI or docker version
+		},
+		Config:      configDesc,
+		MediaType:   ocispec.MediaTypeImageManifest,
+		Layers:      layers,
+		Annotations: opts.ManifestAnnotations,
+	}
+	manifestBytes, err := json.Marshal(manifest)
+	if err != nil {
+		return ocispec.Descriptor{}, fmt.Errorf("failed to marshal manifest: %w", err)
+	}
+	manifestDesc := ocispec.Descriptor{
+		MediaType: ocispec.MediaTypeImageManifest,
+		Digest:    digest.FromBytes(manifestBytes),
+		Size:      int64(len(manifestBytes)),
+	}
+
+	// push manifest.
+	if err := pusher.Push(ctx, manifestDesc, bytes.NewReader(manifestBytes)); err != nil && !errors.Is(err, errdef.ErrAlreadyExists) {
+		return ocispec.Descriptor{}, fmt.Errorf("failed to push manifest: %w", err)
+	}
+
+	return manifestDesc, nil
+}

pack_test.go

@@ -0,0 +1,137 @@
+/*
+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 oras
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"reflect"
+	"testing"
+
+	"github.com/opencontainers/go-digest"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2/content/memory"
+)
+
+func Test_Pack_Default(t *testing.T) {
+	s := memory.New()
+
+	layer_1 := []byte("hello world")
+	desc_1 := ocispec.Descriptor{
+		MediaType: "test",
+		Digest:    digest.FromBytes(layer_1),
+		Size:      int64(len(layer_1)),
+	}
+
+	layer_2 := []byte("goodbye world")
+	desc_2 := ocispec.Descriptor{
+		MediaType: "test",
+		Digest:    digest.FromBytes(layer_2),
+		Size:      int64(len(layer_2)),
+	}
+	layers := []ocispec.Descriptor{
+		desc_1,
+		desc_2,
+	}
+
+	ctx := context.Background()
+	manifestDesc, err := Pack(ctx, s, layers, PackOptions{})
+	if err != nil {
+		t.Fatal("Oras.Pack() error =", err)
+	}
+
+	// test manifest
+	var manifest ocispec.Manifest
+	rc, err := s.Fetch(ctx, manifestDesc)
+	if err != nil {
+		t.Fatal("Store.Fetch() error =", err)
+	}
+	if err := json.NewDecoder(rc).Decode(&manifest); err != nil {
+		t.Fatal("error decoding manifest, error =", err)
+	}
+	if err := rc.Close(); err != nil {
+		t.Fatal("Store.Fetch().Close() error =", err)
+	}
+	if !reflect.DeepEqual(manifest.Layers, layers) {
+		t.Errorf("Store.Fetch() = %v, want %v", manifest.Layers, layers)
+	}
+
+	// test config
+	config := manifest.Config
+	expected := []byte("{}")
+	rc, err = s.Fetch(ctx, config)
+	if err != nil {
+		t.Fatal("Store.Fetch() error =", err)
+	}
+	got, err := io.ReadAll(rc)
+	if err != nil {
+		t.Fatal("Store.Fetch().Read() error =", err)
+	}
+	err = rc.Close()
+	if err != nil {
+		t.Error("Store.Fetch().Close() error =", err)
+	}
+	if !bytes.Equal(got, expected) {
+		t.Errorf("Store.Fetch() = %v, want %v", got, expected)
+	}
+}
+
+func Test_Pack_NoLayer(t *testing.T) {
+	s := memory.New()
+
+	ctx := context.Background()
+	manifestDesc, err := Pack(ctx, s, nil, PackOptions{})
+	if err != nil {
+		t.Fatal("Oras.Pack() error =", err)
+	}
+
+	// test manifest
+	var manifest ocispec.Manifest
+	rc, err := s.Fetch(ctx, manifestDesc)
+	if err != nil {
+		t.Fatal("Store.Fetch() error =", err)
+	}
+	if err := json.NewDecoder(rc).Decode(&manifest); err != nil {
+		t.Fatal("error decoding manifest, error =", err)
+	}
+	if err := rc.Close(); err != nil {
+		t.Fatal("Store.Fetch().Close() error =", err)
+	}
+	expectedLayers := []ocispec.Descriptor{}
+	if !reflect.DeepEqual(manifest.Layers, expectedLayers) {
+		t.Errorf("Store.Fetch() = %v, want %v", manifest.Layers, expectedLayers)
+	}
+
+	// test config
+	config := manifest.Config
+	expectedConfig := []byte("{}")
+	rc, err = s.Fetch(ctx, config)
+	if err != nil {
+		t.Fatal("Store.Fetch() error =", err)
+	}
+	got, err := io.ReadAll(rc)
+	if err != nil {
+		t.Fatal("Store.Fetch().Read() error =", err)
+	}
+	err = rc.Close()
+	if err != nil {
+		t.Error("Store.Fetch().Close() error =", err)
+	}
+	if !bytes.Equal(got, expectedConfig) {
+		t.Errorf("Store.Fetch() = %v, want %v", got, expectedConfig)
+	}
+}