docs: add e2e examples for oras-go

Signed-off-by: Xiaoxuan Wang <[email protected]>

go.mod

@@ -5,5 +5,6 @@ go 1.19
 require (
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.0-rc4
+	github.com/oras-project/oras-credentials-go v0.3.0
 	golang.org/x/sync v0.3.0
 )

go.sum

@@ -2,5 +2,7 @@ github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8
 github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/opencontainers/image-spec v1.1.0-rc4 h1:oOxKUJWnFC4YGHCCMNql1x4YaDfYBTS5Y4x/Cgeo1E0=
 github.com/opencontainers/image-spec v1.1.0-rc4/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
+github.com/oras-project/oras-credentials-go v0.3.0 h1:Bg1d9iAmgo50RlaIy2XI5MQs7qL00DB3R9Q4JRP1VWs=
+github.com/oras-project/oras-credentials-go v0.3.0/go.mod h1:fFCebDQo0Do+gnM96uV9YUnRay0pwuRQupypvofsp4s=
 golang.org/x/sync v0.3.0 h1:ftCYgMx6zT/asHUrPw8BLLscYtGznsLAnjq5RH9P66E=
 golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=

pull_files_from_remote_test.go

@@ -0,0 +1,53 @@
+package oras_test
+
+import (
+	"context"
+	"fmt"
+
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content/file"
+	"oras.land/oras-go/v2/registry/remote"
+	"oras.land/oras-go/v2/registry/remote/auth"
+	"oras.land/oras-go/v2/registry/remote/retry"
+)
+
+func pullFiles() error {
+	// 0. Create a file store
+	fs, err := file.New("/tmp/")
+	if err != nil {
+		return err
+	}
+	defer fs.Close()
+
+	// 1. Connect to a remote repository
+	ctx := context.Background()
+	reg := "myregistry.example.com"
+	repo, err := remote.NewRepository(reg + "/myrepo")
+	if err != nil {
+		return err
+	}
+	// Note: The below code can be omitted if authentication is not required
+	repo.Client = &auth.Client{
+		Client: retry.DefaultClient,
+		Cache:  auth.DefaultCache,
+		Credential: auth.StaticCredential(reg, auth.Credential{
+			Username: "username",
+			Password: "password",
+		}),
+	}
+
+	// 2. Copy from the remote repository to the file store
+	tag := "latest"
+	manifestDescriptor, err := oras.Copy(ctx, repo, tag, fs, tag, oras.DefaultCopyOptions)
+	if err != nil {
+		return err
+	}
+	fmt.Println("manifest descriptor:", manifestDescriptor)
+	return nil
+}
+
+func Example_pullFilesFromRemoteRepository() {
+	if err := pullFiles(); err != nil {
+		panic(err)
+	}
+}

pull_image_from_remote_test.go

@@ -0,0 +1,60 @@
+package oras_test
+
+import (
+	"context"
+	"fmt"
+
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/content/oci"
+	"oras.land/oras-go/v2/registry/remote"
+	"oras.land/oras-go/v2/registry/remote/auth"
+	"oras.land/oras-go/v2/registry/remote/retry"
+)
+
+func pullImageFromRemote() error {
+	// 0. Create an OCI layout store
+	store, err := oci.New("/tmp/oci-layout-root")
+	if err != nil {
+		return err
+	}
+
+	// 1. Connect to a remote repository
+	ctx := context.Background()
+	reg := "myregistry.example.com"
+	repo, err := remote.NewRepository(reg + "/myrepo")
+	if err != nil {
+		return err
+	}
+	// Note: The below code can be omitted if authentication is not required
+	repo.Client = &auth.Client{
+		Client: retry.DefaultClient,
+		Cache:  auth.DefaultCache,
+		Credential: auth.StaticCredential(reg, auth.Credential{
+			Username: "username",
+			Password: "password",
+		}),
+	}
+
+	// 2. Copy from the remote repository to the OCI layout store
+	tag := "latest"
+	manifestDescriptor, err := oras.Copy(ctx, repo, tag, store, tag, oras.DefaultCopyOptions)
+	if err != nil {
+		return err
+	}
+	fmt.Println("manifest pulled:", manifestDescriptor.Digest, manifestDescriptor.MediaType)
+
+	// 3. Fetch from OCI layout store to verify
+	fetched, err := content.FetchAll(ctx, store, manifestDescriptor)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("manifest content:\n%s", fetched)
+	return nil
+}
+
+func Example_pullImageFromRemoteRepository() {
+	if err := pullImageFromRemote(); err != nil {
+		panic(err)
+	}
+}

pull_image_with_docker_store_test.go

@@ -0,0 +1,68 @@
+package oras_test
+
+import (
+	"context"
+	"fmt"
+
+	credentials "github.com/oras-project/oras-credentials-go"
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/content/oci"
+	"oras.land/oras-go/v2/registry/remote"
+	"oras.land/oras-go/v2/registry/remote/auth"
+	"oras.land/oras-go/v2/registry/remote/retry"
+)
+
+func pullImageUsingDockerCredentialStore() error {
+
+	// 0. Create an OCI layout store
+	store, err := oci.New("/tmp/oci-layout-root")
+	if err != nil {
+		return err
+	}
+
+	// 1. Connect to a remote repository
+	ctx := context.Background()
+	reg := "docker.io"
+	repo, err := remote.NewRepository(reg + "/user/my-repo")
+	if err != nil {
+		return err
+	}
+
+	// 2. Get credentials from the docker credential store
+	storeOpts := credentials.StoreOptions{}
+	credStore, err := credentials.NewStoreFromDocker(storeOpts)
+	if err != nil {
+		return err
+	}
+
+	// Prepare the auth client for the registry and credential store
+	repo.Client = &auth.Client{
+		Client:     retry.DefaultClient,
+		Cache:      auth.DefaultCache,
+		Credential: credentials.Credential(credStore), // Use the credential store
+	}
+
+	// 3. Copy from the remote repository to the OCI layout store
+	tag := "latest"
+	manifestDescriptor, err := oras.Copy(ctx, repo, tag, store, tag, oras.DefaultCopyOptions)
+	if err != nil {
+		return err
+	}
+
+	fmt.Println("manifest pulled:", manifestDescriptor.Digest, manifestDescriptor.MediaType)
+
+	// 3. Fetch from OCI layout store to verify
+	fetched, err := content.FetchAll(ctx, store, manifestDescriptor)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("manifest content:\n%s", fetched)
+	return nil
+}
+
+func Example_pullImageUsingDockerCredentialStore() {
+	if err := pullImageUsingDockerCredentialStore(); err != nil {
+		panic(err)
+	}
+}

push_files_to_remote_test.go

@@ -0,0 +1,77 @@
+package oras_test
+
+import (
+	"context"
+	"fmt"
+
+	v1 "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content/file"
+	"oras.land/oras-go/v2/registry/remote"
+	"oras.land/oras-go/v2/registry/remote/auth"
+	"oras.land/oras-go/v2/registry/remote/retry"
+)
+
+func pushFiles() error {
+	// 0. Create a file store
+	fs, err := file.New("/tmp/")
+	if err != nil {
+		return err
+	}
+	defer fs.Close()
+	ctx := context.Background()
+
+	// 1. Add files to a file store
+	mediaType := "example/file"
+	fileNames := []string{"/tmp/myfile"}
+	fileDescriptors := make([]v1.Descriptor, 0, len(fileNames))
+	for _, name := range fileNames {
+		fileDescriptor, err := fs.Add(ctx, name, mediaType, "")
+		if err != nil {
+			return err
+		}
+		fileDescriptors = append(fileDescriptors, fileDescriptor)
+		fmt.Printf("file descriptor for %s: %v\n", name, fileDescriptor)
+	}
+
+	// 2. Pack the files and tag the packed manifest
+	artifactType := "example/files"
+	manifestDescriptor, err := oras.Pack(ctx, fs, artifactType, fileDescriptors, oras.PackOptions{
+		PackImageManifest: true,
+	})
+	if err != nil {
+		return err
+	}
+	fmt.Println("manifest descriptor:", manifestDescriptor)
+
+	tag := "latest"
+	if err = fs.Tag(ctx, manifestDescriptor, tag); err != nil {
+		return err
+	}
+
+	// 3. Connect to a remote repository
+	reg := "myregistry.example.com"
+	repo, err := remote.NewRepository(reg + "/myrepo")
+	if err != nil {
+		panic(err)
+	}
+	// Note: The below code can be omitted if authentication is not required
+	repo.Client = &auth.Client{
+		Client: retry.DefaultClient,
+		Cache:  auth.DefaultCache,
+		Credential: auth.StaticCredential(reg, auth.Credential{
+			Username: "username",
+			Password: "password",
+		}),
+	}
+
+	// 3. Copy from the file store to the remote repository
+	_, err = oras.Copy(ctx, fs, tag, repo, tag, oras.DefaultCopyOptions)
+	return err
+}
+
+func Example_pushFilesToRemoteRepository() {
+	if err := pushFiles(); err != nil {
+		panic(err)
+	}
+}