feat: store multiplexer (#31)

Signed-off-by: Shiwei Zhang <[email protected]>

example_test.go

@@ -0,0 +1,155 @@
+/*
+Copyright The Ratify 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 ratify_test
+
+import (
+	"context"
+	"crypto/tls"
+	"net/http"
+	"testing/fstest"
+
+	"github.com/ratify-project/ratify-go"
+)
+
+func ExampleStoreMux() {
+	// Create stores for demonstration.
+	// Each store is an OCI image layout with a single artifact with a different
+	// tag.
+	ctx := context.Background()
+	var stores []ratify.Store
+	for _, tag := range []string{"foo", "bar", "hello", "world"} {
+		fsys := fstest.MapFS{
+			"blob/sha256/03c6d9dcb63b03c5489db13cedbc549f2de807f43440df549644866a24a3561b": &fstest.MapFile{
+				Data: []byte(`{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","artifactType":"application/vnd.unknown.artifact.v1","config":{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="},"layers":[{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="}],"annotations":{"org.opencontainers.image.created":"2025-01-26T07:32:59Z"}}`),
+			},
+			"blob/sha256/44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a": &fstest.MapFile{
+				Data: []byte(`{}`),
+			},
+			"index.json": &fstest.MapFile{
+				Data: []byte(`{"schemaVersion":2,"manifests":[{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:03c6d9dcb63b03c5489db13cedbc549f2de807f43440df549644866a24a3561b","size":535,"annotations":{"org.opencontainers.image.created":"2025-01-26T07:32:59Z","org.opencontainers.image.ref.name":"` + tag + `"},"artifactType":"application/vnd.unknown.artifact.v1"}]}`),
+			},
+			"oci-layout": &fstest.MapFile{
+				Data: []byte(`{"imageLayoutVersion": "1.0.0"}`),
+			},
+		}
+		store, err := ratify.NewOCIStoreFromFS(ctx, tag, fsys)
+		if err != nil {
+			panic(err)
+		}
+		stores = append(stores, store)
+	}
+
+	// Create a new store multiplexer
+	store := ratify.NewStoreMux("multiplexer")
+
+	// Register store with exact repository name match.
+	store.Register("registry.example/test", stores[0])
+
+	// Register store for an registry.
+	store.Register("registry.example", stores[1])
+
+	// Register store with wildcard DNS record.
+	store.Register("*.example", stores[2])
+
+	// Register a fallback store for unmatched requests.
+	store.RegisterFallback(stores[3])
+
+	// Reference should be resolvable by the matching store.
+	_, err := store.Resolve(ctx, "registry.example/test:foo")
+	if err != nil {
+		panic(err)
+	}
+	_, err = store.Resolve(ctx, "registry.example/another-test:bar")
+	if err != nil {
+		panic(err)
+	}
+	_, err = store.Resolve(ctx, "test.example/test:hello")
+	if err != nil {
+		panic(err)
+	}
+	_, err = store.Resolve(ctx, "another.registry.example/test:world")
+	if err != nil {
+		panic(err)
+	}
+	// Output:
+}
+
+// ExampleStoreMux_mixRegistryStore demonstrates how to access different
+// registries with different network configurations using a single store by
+// multiplexing.
+func ExampleStoreMux_mixRegistryStore() {
+	// Create a new store multiplexer
+	mux := ratify.NewStoreMux("multiplexer")
+
+	// Create a global registry store with default options.
+	// Developers should replace the default options with actual configuration.
+	store, err := ratify.NewRegistryStore("registry", ratify.RegistryStoreOptions{})
+	if err != nil {
+		panic(err)
+	}
+	if err := mux.RegisterFallback(store); err != nil {
+		panic(err)
+	}
+
+	// Create a registry store for local registry.
+	// A local registry is accessed over plain HTTP unlike the global registry.
+	store, err = ratify.NewRegistryStore("local", ratify.RegistryStoreOptions{
+		PlainHTTP: true,
+	})
+	if err != nil {
+		panic(err)
+	}
+	if err := mux.Register("localhost:5000", store); err != nil {
+		panic(err)
+	}
+
+	// Create a registry store with client certificate authentication.
+	store, err = ratify.NewRegistryStore("cert", ratify.RegistryStoreOptions{
+		HTTPClient: &http.Client{
+			Transport: &http.Transport{
+				TLSClientConfig: &tls.Config{
+					Certificates: []tls.Certificate{
+						// add client certificate with private key
+					},
+				},
+			},
+		},
+	})
+	if err != nil {
+		panic(err)
+	}
+	if err := mux.Register("private.registry.example", store); err != nil {
+		panic(err)
+	}
+
+	// Create a registry store for an insecure registry.
+	store, err = ratify.NewRegistryStore("insecure", ratify.RegistryStoreOptions{
+		HTTPClient: &http.Client{
+			Transport: &http.Transport{
+				TLSClientConfig: &tls.Config{
+					InsecureSkipVerify: true,
+				},
+			},
+		},
+	})
+	if err != nil {
+		panic(err)
+	}
+	if err := mux.Register("insecure.registry.example", store); err != nil {
+		panic(err)
+	}
+	// Output:
+}