deprecate reference package, migrate to github.com/distribution/refer…

…ence

This integrates the new module, which was extracted from this repository
at commit b9b1940;

    # install filter-repo (https://github.com/newren/git-filter-repo/blob/main/INSTALL.md)
    brew install git-filter-repo

    # create a temporary clone of docker
    cd ~/Projects
    git clone https://github.com/distribution/distribution.git reference
    cd reference

    # commit taken from
    git rev-parse --verify HEAD
    b9b1940

    # remove all code, except for general files, 'reference/', and rename to /
    git filter-repo \
      --path .github/workflows/codeql-analysis.yml \
      --path .github/workflows/fossa.yml \
      --path .golangci.yml \
      --path distribution-logo.svg \
      --path CODE-OF-CONDUCT.md \
      --path CONTRIBUTING.md \
      --path GOVERNANCE.md \
      --path README.md \
      --path LICENSE \
      --path MAINTAINERS \
      --path-glob 'reference/*.*' \
      --path-rename reference/:

    # initialize go.mod
    go mod init github.com/distribution/reference
    go mod tidy -go=1.20

This commit is based on 152af63 in the main branch,
but adjusted for the 2.8 branch, with some differences:

- the Sort functions have not been kept, as they were not part of the v2 package,
  and introduced in 1052518
- the ParseAnyReferenceWithSet and ShortIdentifierRegexp were kept (but deprecated)
  as removing happened in 6d4f62d, which is not
  in the 2.8 branch.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

blobs.go

@@ -8,7 +8,7 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/docker/distribution/reference"
+	"github.com/distribution/reference"
 	"github.com/opencontainers/go-digest"
 	v1 "github.com/opencontainers/image-spec/specs-go/v1"
 )

manifest/schema1/config_builder.go

@@ -8,9 +8,9 @@ import (
 	"fmt"
 	"time"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution"
 	"github.com/docker/distribution/manifest"
-	"github.com/docker/distribution/reference"
 	"github.com/docker/libtrust"
 	"github.com/opencontainers/go-digest"
 )

manifest/schema1/config_builder_test.go

@@ -8,9 +8,9 @@ import (
 	"reflect"
 	"testing"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution"
 	dcontext "github.com/docker/distribution/context"
-	"github.com/docker/distribution/reference"
 	"github.com/docker/libtrust"
 	"github.com/opencontainers/go-digest"
 )

manifest/schema1/reference_builder.go

@@ -5,9 +5,9 @@ import (
 	"errors"
 	"fmt"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution"
 	"github.com/docker/distribution/manifest"
-	"github.com/docker/distribution/reference"
 	"github.com/docker/libtrust"
 	"github.com/opencontainers/go-digest"
 )

manifest/schema1/reference_builder_test.go

@@ -3,9 +3,9 @@ package schema1
 import (
 	"testing"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution/context"
 	"github.com/docker/distribution/manifest"
-	"github.com/docker/distribution/reference"
 	"github.com/docker/libtrust"
 	"github.com/opencontainers/go-digest"
 )

notifications/bridge.go

@@ -4,9 +4,9 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution"
 	"github.com/docker/distribution/context"
-	"github.com/docker/distribution/reference"
 	"github.com/docker/distribution/uuid"
 	"github.com/opencontainers/go-digest"
 )

notifications/bridge_test.go

@@ -3,9 +3,9 @@ package notifications
 import (
 	"testing"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution"
 	"github.com/docker/distribution/manifest/schema1"
-	"github.com/docker/distribution/reference"
 	v2 "github.com/docker/distribution/registry/api/v2"
 	"github.com/docker/distribution/uuid"
 	"github.com/docker/libtrust"

notifications/listener.go

@@ -6,8 +6,8 @@ import (
 
 	"github.com/docker/distribution"
 
+	"github.com/distribution/reference"
 	dcontext "github.com/docker/distribution/context"
-	"github.com/docker/distribution/reference"
 	"github.com/opencontainers/go-digest"
 )
 

notifications/listener_test.go

@@ -5,11 +5,11 @@ import (
 	"reflect"
 	"testing"
 
+	"github.com/distribution/reference"
 	"github.com/docker/distribution"
 	"github.com/docker/distribution/context"
 	"github.com/docker/distribution/manifest"
 	"github.com/docker/distribution/manifest/schema1"
-	"github.com/docker/distribution/reference"
 	"github.com/docker/distribution/registry/storage"
 	"github.com/docker/distribution/registry/storage/cache/memory"
 	"github.com/docker/distribution/registry/storage/driver/inmemory"

reference/helpers_deprecated.go

@@ -0,0 +1,34 @@
+package reference
+
+import "github.com/distribution/reference"
+
+// IsNameOnly returns true if reference only contains a repo name.
+//
+// Deprecated: use [reference.IsNameOnly].
+func IsNameOnly(ref reference.Named) bool {
+	return reference.IsNameOnly(ref)
+}
+
+// FamiliarName returns the familiar name string
+// for the given named, familiarizing if needed.
+//
+// Deprecated: use [reference.FamiliarName].
+func FamiliarName(ref reference.Named) string {
+	return reference.FamiliarName(ref)
+}
+
+// FamiliarString returns the familiar string representation
+// for the given reference, familiarizing if needed.
+//
+// Deprecated: use [reference.FamiliarString].
+func FamiliarString(ref reference.Reference) string {
+	return reference.FamiliarString(ref)
+}
+
+// FamiliarMatch reports whether ref matches the specified pattern.
+// See [path.Match] for supported patterns.
+//
+// Deprecated: use [reference.FamiliarMatch].
+func FamiliarMatch(pattern string, ref reference.Reference) (bool, error) {
+	return reference.FamiliarMatch(pattern, ref)
+}

reference/normalize_deprecated.go

@@ -0,0 +1,92 @@
+package reference
+
+import (
+	"regexp"
+
+	"github.com/distribution/reference"
+	"github.com/docker/distribution/digestset"
+	"github.com/opencontainers/go-digest"
+)
+
+// ParseNormalizedNamed parses a string into a named reference
+// transforming a familiar name from Docker UI to a fully
+// qualified reference. If the value may be an identifier
+// use ParseAnyReference.
+//
+// Deprecated: use [reference.ParseNormalizedNamed].
+func ParseNormalizedNamed(s string) (reference.Named, error) {
+	return reference.ParseNormalizedNamed(s)
+}
+
+// ParseDockerRef normalizes the image reference following the docker convention,
+// which allows for references to contain both a tag and a digest.
+//
+// Deprecated: use [reference.ParseDockerRef].
+func ParseDockerRef(ref string) (reference.Named, error) {
+	return reference.ParseDockerRef(ref)
+}
+
+// TagNameOnly adds the default tag "latest" to a reference if it only has
+// a repo name.
+//
+// Deprecated: use [reference.TagNameOnly].
+func TagNameOnly(ref reference.Named) reference.Named {
+	return reference.TagNameOnly(ref)
+}
+
+// ParseAnyReference parses a reference string as a possible identifier,
+// full digest, or familiar name.
+//
+// Deprecated: use [reference.ParseAnyReference].
+func ParseAnyReference(ref string) (reference.Reference, error) {
+	return reference.ParseAnyReference(ref)
+}
+
+// Functions and types below have been removed in distribution v3 and
+// have not been ported to github.com/distribution/reference. See
+// https://github.com/distribution/distribution/pull/3774
+
+var (
+	// ShortIdentifierRegexp is the format used to represent a prefix
+	// of an identifier. A prefix may be used to match a sha256 identifier
+	// within a list of trusted identifiers.
+	//
+	// Deprecated: support for short-identifiers is deprecated, and will be removed in v3.
+	ShortIdentifierRegexp = regexp.MustCompile(shortIdentifier)
+
+	shortIdentifier = `([a-f0-9]{6,64})`
+
+	// anchoredShortIdentifierRegexp is used to check if a value
+	// is a possible identifier prefix, anchored at start and end
+	// of string.
+	anchoredShortIdentifierRegexp = regexp.MustCompile(`^` + shortIdentifier + `$`)
+)
+
+type digestReference digest.Digest
+
+func (d digestReference) String() string {
+	return digest.Digest(d).String()
+}
+
+func (d digestReference) Digest() digest.Digest {
+	return digest.Digest(d)
+}
+
+// ParseAnyReferenceWithSet parses a reference string as a possible short
+// identifier to be matched in a digest set, a full digest, or familiar name.
+//
+// Deprecated: support for short-identifiers is deprecated, and will be removed in v3.
+func ParseAnyReferenceWithSet(ref string, ds *digestset.Set) (Reference, error) {
+	if ok := anchoredShortIdentifierRegexp.MatchString(ref); ok {
+		dgst, err := ds.Lookup(ref)
+		if err == nil {
+			return digestReference(dgst), nil
+		}
+	} else {
+		if dgst, err := digest.Parse(ref); err == nil {
+			return digestReference(dgst), nil
+		}
+	}
+
+	return reference.ParseNormalizedNamed(ref)
+}