Backport of tag listing to v1 (#89)

Signed-off-by: Andrew Block <andy.block@gmail.com>

pkg/content/errors.go

@@ -23,6 +23,7 @@ var (
 	ErrNoName             = errors.New("no_name")
 	ErrUnsupportedSize    = errors.New("unsupported_size")
 	ErrUnsupportedVersion = errors.New("unsupported_version")
+	ErrInvalidReference   = errors.New("invalid_reference")
 )
 
 // FileStore errors

pkg/registry/reference.go

@@ -0,0 +1,177 @@
+/*
+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 registry
+
+import (
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"github.com/opencontainers/go-digest"
+	errdef "oras.land/oras-go/pkg/content"
+)
+
+// regular expressions for components.
+var (
+	// repositoryRegexp is adapted from the distribution implementation.
+	// The repository name set under OCI distribution spec is a subset of the
+	// the docker spec. For maximum compability, the docker spec is verified at
+	// the client side. Further check is left to the server side.
+	// References:
+	// - https://github.com/distribution/distribution/blob/v2.7.1/reference/regexp.go#L53
+	// - https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests
+	repositoryRegexp = regexp.MustCompile(`^[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*)*$`)
+
+	// tagRegexp checks the tag name.
+	// The docker and OCI spec have the same regular expression.
+	// Reference: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests
+	tagRegexp = regexp.MustCompile(`^[\w][\w.-]{0,127}$`)
+)
+
+// Reference references to a descriptor in the registry.
+type Reference struct {
+	// Registry is the name of the registry.
+	// It is usually the domain name of the registry optionally with a port.
+	Registry string
+
+	// Repository is the name of the repository.
+	Repository string
+
+	// Reference is the reference of the object in the repository.
+	// A reference can be a tag or a digest.
+	Reference string
+}
+
+// ParseReference parses a string into a artifact reference.
+// If the reference contains both the tag and the digest, the tag will be
+// dropped.
+// Digest is recognized only if the corresponding algorithm is available.
+func ParseReference(raw string) (Reference, error) {
+	parts := strings.SplitN(raw, "/", 2)
+	if len(parts) == 1 {
+		return Reference{}, fmt.Errorf("%w: missing repository", errdef.ErrInvalidReference)
+	}
+	registry, path := parts[0], parts[1]
+	var repository string
+	var reference string
+	if index := strings.Index(path, "@"); index != -1 {
+		// digest found
+		repository = path[:index]
+		reference = path[index+1:]
+
+		// drop tag since the digest is present.
+		if index := strings.Index(repository, ":"); index != -1 {
+			repository = repository[:index]
+		}
+	} else if index := strings.Index(path, ":"); index != -1 {
+		// tag found
+		repository = path[:index]
+		reference = path[index+1:]
+	} else {
+		// empty reference
+		repository = path
+	}
+	res := Reference{
+		Registry:   registry,
+		Repository: repository,
+		Reference:  reference,
+	}
+	if err := res.Validate(); err != nil {
+		return Reference{}, err
+	}
+	return res, nil
+}
+
+// Validate validates the entire reference.
+func (r Reference) Validate() error {
+	err := r.ValidateRegistry()
+	if err != nil {
+		return err
+	}
+	err = r.ValidateRepository()
+	if err != nil {
+		return err
+	}
+	return r.ValidateReference()
+}
+
+// ValidateRegistry validates the registry.
+func (r Reference) ValidateRegistry() error {
+	uri, err := url.ParseRequestURI("dummy://" + r.Registry)
+	if err != nil || uri.Host != r.Registry {
+		return fmt.Errorf("%w: invalid registry", errdef.ErrInvalidReference)
+	}
+	return nil
+}
+
+// ValidateRepository validates the repository.
+func (r Reference) ValidateRepository() error {
+	if !repositoryRegexp.MatchString(r.Repository) {
+		return fmt.Errorf("%w: invalid repository", errdef.ErrInvalidReference)
+	}
+	return nil
+}
+
+// ValidateReference validates the reference.
+func (r Reference) ValidateReference() error {
+	if r.Reference == "" {
+		return nil
+	}
+	if _, err := r.Digest(); err == nil {
+		return nil
+	}
+	if !tagRegexp.MatchString(r.Reference) {
+		return fmt.Errorf("%w: invalid tag", errdef.ErrInvalidReference)
+	}
+	return nil
+}
+
+// Host returns the host name of the registry.
+func (r Reference) Host() string {
+	if r.Registry == "docker.io" {
+		return "registry-1.docker.io"
+	}
+	return r.Registry
+}
+
+// ReferenceOrDefault returns the reference or the default reference if empty.
+func (r Reference) ReferenceOrDefault() string {
+	if r.Reference == "" {
+		return "latest"
+	}
+	return r.Reference
+}
+
+// Digest returns the reference as a digest.
+func (r Reference) Digest() (digest.Digest, error) {
+	return digest.Parse(r.Reference)
+}
+
+// String implements `fmt.Stringer` and returns the reference string.
+// The resulted string is meaningful only if the reference is valid.
+func (r Reference) String() string {
+	if r.Repository == "" {
+		return r.Registry
+	}
+	ref := r.Registry + "/" + r.Repository
+	if r.Reference == "" {
+		return ref
+	}
+	if d, err := r.Digest(); err == nil {
+		return ref + "@" + d.String()
+	}
+	return ref + ":" + r.Reference
+}

pkg/registry/remote/auth/cache.go

@@ -0,0 +1,158 @@
+/*
+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 auth
+
+import (
+	"context"
+	"strings"
+	"sync"
+
+	errdef "oras.land/oras-go/pkg/content"
+	"oras.land/oras-go/pkg/registry/remote/internal/syncutil"
+)
+
+// DefaultCache is the sharable cache used by DefaultClient.
+var DefaultCache Cache = NewCache()
+
+// Cache caches the auth-scheme and auth-token for the "Authorization" header in
+// accessing the remote registry.
+// Precisely, the header is `Authorization: auth-scheme auth-token`.
+// The `auth-token` is a generic term as `token68` in RFC 7235 section 2.1.
+type Cache interface {
+	// GetScheme returns the auth-scheme part cached for the given registry.
+	// A single registry is assumed to have a consistent scheme.
+	// If a registry has different schemes per path, the auth client is still
+	// workable. However, the cache may not be effective as the cache cannot
+	// correctly guess the scheme.
+	GetScheme(ctx context.Context, registry string) (Scheme, error)
+
+	// GetToken returns the auth-token part cached for the given registry of a
+	// given scheme.
+	// The underlying implementation MAY cache the token for all schemes for the
+	// given registry.
+	GetToken(ctx context.Context, registry string, scheme Scheme, key string) (string, error)
+
+	// Set fetches the token using the given fetch function and caches the token
+	// for the given scheme with the given key for the given registry.
+	// The return values of the fetch function is returned by this function.
+	// The underlying implementation MAY combine the fetch operation if the Set
+	// function is invoked multiple times at the same time.
+	Set(ctx context.Context, registry string, scheme Scheme, key string, fetch func(context.Context) (string, error)) (string, error)
+}
+
+// cacheEntry is a cache entry for a single registry.
+type cacheEntry struct {
+	scheme Scheme
+	tokens sync.Map // map[string]string
+}
+
+// concurrentCache is a cache suitable for concurrent invocation.
+type concurrentCache struct {
+	status sync.Map // map[string]*syncutil.Once
+	cache  sync.Map // map[string]*cacheEntry
+}
+
+// NewCache creates a new go-routine safe cache instance.
+func NewCache() Cache {
+	return &concurrentCache{}
+}
+
+// GetScheme returns the auth-scheme part cached for the given registry.
+func (cc *concurrentCache) GetScheme(ctx context.Context, registry string) (Scheme, error) {
+	entry, ok := cc.cache.Load(registry)
+	if !ok {
+		return SchemeUnknown, errdef.ErrNotFound
+	}
+	return entry.(*cacheEntry).scheme, nil
+}
+
+// GetToken returns the auth-token part cached for the given registry of a given
+// scheme.
+func (cc *concurrentCache) GetToken(ctx context.Context, registry string, scheme Scheme, key string) (string, error) {
+	entryValue, ok := cc.cache.Load(registry)
+	if !ok {
+		return "", errdef.ErrNotFound
+	}
+	entry := entryValue.(*cacheEntry)
+	if entry.scheme != scheme {
+		return "", errdef.ErrNotFound
+	}
+	if token, ok := entry.tokens.Load(key); ok {
+		return token.(string), nil
+	}
+	return "", errdef.ErrNotFound
+}
+
+// Set fetches the token using the given fetch function and caches the token
+// for the given scheme with the given key for the given registry.
+// Set combines the fetch operation if the Set is invoked multiple times at the
+// same time.
+func (cc *concurrentCache) Set(ctx context.Context, registry string, scheme Scheme, key string, fetch func(context.Context) (string, error)) (string, error) {
+	// fetch token
+	statusKey := strings.Join([]string{
+		registry,
+		scheme.String(),
+		key,
+	}, " ")
+	statusValue, _ := cc.status.LoadOrStore(statusKey, syncutil.NewOnce())
+	fetchOnce := statusValue.(*syncutil.Once)
+	fetchedFirst, result, err := fetchOnce.Do(ctx, func() (interface{}, error) {
+		return fetch(ctx)
+	})
+	if fetchedFirst {
+		cc.status.Delete(statusKey)
+	}
+	if err != nil {
+		return "", err
+	}
+	token := result.(string)
+	if !fetchedFirst {
+		return token, nil
+	}
+
+	// cache token
+	newEntry := &cacheEntry{
+		scheme: scheme,
+	}
+	entryValue, exists := cc.cache.LoadOrStore(registry, newEntry)
+	entry := entryValue.(*cacheEntry)
+	if exists && entry.scheme != scheme {
+		// there is a scheme change, which is not expected in most scenarios.
+		// force invalidating all previous cache.
+		entry = newEntry
+		cc.cache.Store(registry, entry)
+	}
+	entry.tokens.Store(key, token)
+
+	return token, nil
+}
+
+// noCache is a cache implementation that does not do cache at all.
+type noCache struct{}
+
+// GetScheme always returns not found error as it has no cache.
+func (noCache) GetScheme(ctx context.Context, registry string) (Scheme, error) {
+	return SchemeUnknown, errdef.ErrNotFound
+}
+
+// GetToken always returns not found error as it has no cache.
+func (noCache) GetToken(ctx context.Context, registry string, scheme Scheme, key string) (string, error) {
+	return "", errdef.ErrNotFound
+}
+
+// Set calls fetch directly without caching.
+func (noCache) Set(ctx context.Context, registry string, scheme Scheme, key string, fetch func(context.Context) (string, error)) (string, error) {
+	return fetch(ctx)
+}