From 5e38e751eac63ae848db61b809ae33e557ea091a Mon Sep 17 00:00:00 2001
From: Xiaoxuan Wang <103478229+wangxiaoxuan273@users.noreply.github.com>
Date: Wed, 19 Jul 2023 16:56:09 +0800
Subject: [PATCH] docs: add an example for trace (#86)

Resolves #85

Signed-off-by: Xiaoxuan Wang <wangxiaoxuan119@gmail.com>
---
 trace/example_test.go | 65 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 trace/example_test.go

diff --git a/trace/example_test.go b/trace/example_test.go
new file mode 100644
index 0000000..307d627
--- /dev/null
+++ b/trace/example_test.go
@@ -0,0 +1,65 @@
+/*
+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 trace_test
+
+import (
+	"context"
+	"fmt"
+
+	credentials "github.com/oras-project/oras-credentials-go"
+	"github.com/oras-project/oras-credentials-go/trace"
+	"oras.land/oras-go/v2/registry/remote/auth"
+)
+
+// An example on how to use ExecutableTrace with Stores.
+func Example() {
+	// ExecutableTrace works with all Stores that may invoke executables, for
+	// example the Store returned from NewStore and NewNativeStore.
+	store, err := credentials.NewStore("example/path/config.json", credentials.StoreOptions{})
+	if err != nil {
+		panic(err)
+	}
+
+	// Define ExecutableTrace and add it to the context. The 'action' argument
+	// refers to one of 'store', 'get' and 'erase' defined by the docker
+	// credential helper protocol.
+	// Reference: https://docs.docker.com/engine/reference/commandline/login/#credential-helper-protocol
+	traceHooks := &trace.ExecutableTrace{
+		ExecuteStart: func(executableName string, action string) {
+			fmt.Printf("executable %s, action %s started", executableName, action)
+		},
+		ExecuteDone: func(executableName string, action string, err error) {
+			fmt.Printf("executable %s, action %s finished", executableName, action)
+		},
+	}
+	ctx := trace.WithExecutableTrace(context.Background(), traceHooks)
+
+	// Get, Put and Delete credentials from store. If any credential helper
+	// executable is run, traceHooks is executed.
+	err = store.Put(ctx, "localhost:5000", auth.Credential{Username: "testUsername", Password: "testPassword"})
+	if err != nil {
+		panic(err)
+	}
+
+	cred, err := store.Get(ctx, "localhost:5000")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(cred)
+
+	err = store.Delete(ctx, "localhost:5000")
+	if err != nil {
+		panic(err)
+	}
+}