README.md

@@ -10,7 +10,7 @@ Go library to handle references to container images.
 [![codecov](https://codecov.io/gh/distribution/reference/branch/main/graph/badge.svg)](https://codecov.io/gh/distribution/reference)
 [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B162%2Fgithub.com%2Fdistribution%2Freference.svg?type=shield)](https://app.fossa.com/projects/custom%2B162%2Fgithub.com%2Fdistribution%2Freference?ref=badge_shield)
 
-This repository contains a library for handling refrences to container images held in container registries. Please see [godoc](https://pkg.go.dev/github.com/distribution/reference) for details.
+This repository contains a library for handling references to container images held in container registries. Please see [godoc](https://pkg.go.dev/github.com/distribution/reference) for details.
 
 ## Contribution
 

normalize.go

@@ -123,20 +123,51 @@ func ParseDockerRef(ref string) (Named, error) {
 // splitDockerDomain splits a repository name to domain and remote-name.
 // If no valid domain is found, the default domain is used. Repository name
 // needs to be already validated before.
-func splitDockerDomain(name string) (domain, remainder string) {
-	i := strings.IndexRune(name, '/')
-	if i == -1 || (!strings.ContainsAny(name[:i], ".:") && name[:i] != localhost && strings.ToLower(name[:i]) == name[:i]) {
-		domain, remainder = defaultDomain, name
-	} else {
-		domain, remainder = name[:i], name[i+1:]
-	}
-	if domain == legacyDefaultDomain {
-		domain = defaultDomain
-	}
-	if domain == defaultDomain && !strings.ContainsRune(remainder, '/') {
-		remainder = officialRepoPrefix + remainder
-	}
-	return
+func splitDockerDomain(name string) (domain, remoteName string) {
+	maybeDomain, maybeRemoteName, ok := strings.Cut(name, "/")
+	if !ok {
+		// Fast-path for single element ("familiar" names), such as "ubuntu"
+		// or "ubuntu:latest". Familiar names must be handled separately, to
+		// prevent them from being handled as "hostname:port".
+		//
+		// Canonicalize them as "docker.io/library/name[:tag]"
+
+		// FIXME(thaJeztah): account for bare "localhost" or "example.com" names, which SHOULD be considered a domain.
+		return defaultDomain, officialRepoPrefix + name
+	}
+
+	switch {
+	case maybeDomain == localhost:
+		// localhost is a reserved namespace and always considered a domain.
+		domain, remoteName = maybeDomain, maybeRemoteName
+	case maybeDomain == legacyDefaultDomain:
+		// canonicalize the Docker Hub and legacy "Docker Index" domains.
+		domain, remoteName = defaultDomain, maybeRemoteName
+	case strings.ContainsAny(maybeDomain, ".:"):
+		// Likely a domain or IP-address:
+		//
+		// - contains a "." (e.g., "example.com" or "127.0.0.1")
+		// - contains a ":" (e.g., "example:5000", "::1", or "[::1]:5000")
+		domain, remoteName = maybeDomain, maybeRemoteName
+	case strings.ToLower(maybeDomain) != maybeDomain:
+		// Uppercase namespaces are not allowed, so if the first element
+		// is not lowercase, we assume it to be a domain-name.
+		domain, remoteName = maybeDomain, maybeRemoteName
+	default:
+		// None of the above: it's not a domain, so use the default, and
+		// use the name input the remote-name.
+		domain, remoteName = defaultDomain, name
+	}
+
+	if domain == defaultDomain && !strings.ContainsRune(remoteName, '/') {
+		// Canonicalize "familiar" names, but only on Docker Hub, not
+		// on other domains:
+		//
+		// "docker.io/ubuntu[:tag]" => "docker.io/library/ubuntu[:tag]"
+		remoteName = officialRepoPrefix + remoteName
+	}
+
+	return domain, remoteName
 }
 
 // familiarizeName returns a shortened version of the name familiar

normalize_test.go

@@ -13,6 +13,10 @@ func TestValidateReferenceName(t *testing.T) {
 		"docker/docker",
 		"library/debian",
 		"debian",
+		"localhost/library/debian",
+		"localhost/debian",
+		"LOCALDOMAIN/library/debian",
+		"LOCALDOMAIN/debian",
 		"docker.io/docker/docker",
 		"docker.io/library/debian",
 		"docker.io/debian",
@@ -147,6 +151,34 @@ func TestParseRepositoryInfo(t *testing.T) {
 	}
 
 	tests := []tcase{
+		{
+			RemoteName:    "fooo",
+			FamiliarName:  "localhost/fooo",
+			FullName:      "localhost/fooo",
+			AmbiguousName: "localhost/fooo",
+			Domain:        "localhost",
+		},
+		{
+			RemoteName:    "fooo/bar",
+			FamiliarName:  "localhost/fooo/bar",
+			FullName:      "localhost/fooo/bar",
+			AmbiguousName: "localhost/fooo/bar",
+			Domain:        "localhost",
+		},
+		{
+			RemoteName:    "fooo",
+			FamiliarName:  "LOCALDOMAIN/fooo",
+			FullName:      "LOCALDOMAIN/fooo",
+			AmbiguousName: "LOCALDOMAIN/fooo",
+			Domain:        "LOCALDOMAIN",
+		},
+		{
+			RemoteName:    "fooo/bar",
+			FamiliarName:  "LOCALDOMAIN/fooo/bar",
+			FullName:      "LOCALDOMAIN/fooo/bar",
+			AmbiguousName: "LOCALDOMAIN/fooo/bar",
+			Domain:        "LOCALDOMAIN",
+		},
 		{
 			RemoteName:    "fooo/bar",
 			FamiliarName:  "fooo/bar",
@@ -466,62 +498,62 @@ func TestNormalizedSplitHostname(t *testing.T) {
 	tests := []struct {
 		input  string
 		domain string
-		name   string
+		path   string
 	}{
 		{
 			input:  "test.com/foo",
 			domain: "test.com",
-			name:   "foo",
+			path:   "foo",
 		},
 		{
 			input:  "test_com/foo",
 			domain: "docker.io",
-			name:   "test_com/foo",
+			path:   "test_com/foo",
 		},
 		{
 			input:  "docker/migrator",
 			domain: "docker.io",
-			name:   "docker/migrator",
+			path:   "docker/migrator",
 		},
 		{
 			input:  "test.com:8080/foo",
 			domain: "test.com:8080",
-			name:   "foo",
+			path:   "foo",
 		},
 		{
 			input:  "test-com:8080/foo",
 			domain: "test-com:8080",
-			name:   "foo",
+			path:   "foo",
 		},
 		{
 			input:  "foo",
 			domain: "docker.io",
-			name:   "library/foo",
+			path:   "library/foo",
 		},
 		{
 			input:  "xn--n3h.com/foo",
 			domain: "xn--n3h.com",
-			name:   "foo",
+			path:   "foo",
 		},
 		{
 			input:  "xn--n3h.com:18080/foo",
 			domain: "xn--n3h.com:18080",
-			name:   "foo",
+			path:   "foo",
 		},
 		{
 			input:  "docker.io/foo",
 			domain: "docker.io",
-			name:   "library/foo",
+			path:   "library/foo",
 		},
 		{
 			input:  "docker.io/library/foo",
 			domain: "docker.io",
-			name:   "library/foo",
+			path:   "library/foo",
 		},
 		{
 			input:  "docker.io/library/foo/bar",
 			domain: "docker.io",
-			name:   "library/foo/bar",
+			path:   "library/foo/bar",
 		},
 	}
 	for _, tc := range tests {
@@ -532,12 +564,12 @@ func TestNormalizedSplitHostname(t *testing.T) {
 			if err != nil {
 				t.Errorf("error parsing name: %s", err)
 			}
-			domain, name := SplitHostname(named) //nolint:staticcheck // Ignore SA1019: SplitHostname is deprecated.
-			if domain != tc.domain {
+
+			if domain := Domain(named); domain != tc.domain {
 				t.Errorf("unexpected domain: got %q, expected %q", domain, tc.domain)
 			}
-			if name != tc.name {
-				t.Errorf("unexpected name: got %q, expected %q", name, tc.name)
+			if path := Path(named); path != tc.path {
+				t.Errorf("unexpected name: got %q, expected %q", path, tc.path)
 			}
 		})
 	}

reference.go

@@ -35,8 +35,13 @@ import (
 )
 
 const (
+	// RepositoryNameTotalLengthMax is the maximum total number of characters in a repository name.
+	RepositoryNameTotalLengthMax = 255
+
 	// NameTotalLengthMax is the maximum total number of characters in a repository name.
-	NameTotalLengthMax = 255
+	//
+	// Deprecated: use [RepositoryNameTotalLengthMax] instead.
+	NameTotalLengthMax = RepositoryNameTotalLengthMax
 )
 
 var (
@@ -55,8 +60,8 @@ var (
 	// ErrNameEmpty is returned for empty, invalid repository names.
 	ErrNameEmpty = errors.New("repository name must have at least one component")
 
-	// ErrNameTooLong is returned when a repository name is longer than NameTotalLengthMax.
-	ErrNameTooLong = fmt.Errorf("repository name must not be more than %v characters", NameTotalLengthMax)
+	// ErrNameTooLong is returned when a repository name is longer than RepositoryNameTotalLengthMax.
+	ErrNameTooLong = fmt.Errorf("repository name must not be more than %v characters", RepositoryNameTotalLengthMax)
 
 	// ErrNameNotCanonical is returned when a name is not canonical.
 	ErrNameNotCanonical = errors.New("repository name must be canonical")
@@ -165,6 +170,9 @@ func Path(named Named) (name string) {
 	return path
 }
 
+// splitDomain splits a named reference into a hostname and path string.
+// If no valid hostname is found, the hostname is empty and the full value
+// is returned as name
 func splitDomain(name string) (string, string) {
 	match := anchoredNameRegexp.FindStringSubmatch(name)
 	if len(match) != 3 {
@@ -173,19 +181,6 @@ func splitDomain(name string) (string, string) {
 	return match[1], match[2]
 }
 
-// SplitHostname splits a named reference into a
-// hostname and name string. If no valid hostname is
-// found, the hostname is empty and the full value
-// is returned as name
-//
-// Deprecated: Use [Domain] or [Path].
-func SplitHostname(named Named) (string, string) {
-	if r, ok := named.(namedRepository); ok {
-		return r.Domain(), r.Path()
-	}
-	return splitDomain(named.Name())
-}
-
 // Parse parses s and returns a syntactically valid Reference.
 // If an error was encountered it is returned, along with a nil Reference.
 func Parse(s string) (Reference, error) {
@@ -200,10 +195,6 @@ func Parse(s string) (Reference, error) {
 		return nil, ErrReferenceInvalidFormat
 	}
 
-	if len(matches[1]) > NameTotalLengthMax {
-		return nil, ErrNameTooLong
-	}
-
 	var repo repository
 
 	nameMatch := anchoredNameRegexp.FindStringSubmatch(matches[1])
@@ -215,6 +206,10 @@ func Parse(s string) (Reference, error) {
 		repo.path = matches[1]
 	}
 
+	if len(repo.path) > RepositoryNameTotalLengthMax {
+		return nil, ErrNameTooLong
+	}
+
 	ref := reference{
 		namedRepository: repo,
 		tag:             matches[2],
@@ -253,14 +248,15 @@ func ParseNamed(s string) (Named, error) {
 // WithName returns a named object representing the given string. If the input
 // is invalid ErrReferenceInvalidFormat will be returned.
 func WithName(name string) (Named, error) {
-	if len(name) > NameTotalLengthMax {
-		return nil, ErrNameTooLong
-	}
-
 	match := anchoredNameRegexp.FindStringSubmatch(name)
 	if match == nil || len(match) != 3 {
 		return nil, ErrReferenceInvalidFormat
 	}
+
+	if len(match[2]) > RepositoryNameTotalLengthMax {
+		return nil, ErrNameTooLong
+	}
+
 	return repository{
 		domain: match[1],
 		path:   match[2],