reference: implement Sort()

This upstreams `Sort()` as originally implemented in containerd in
https://github.com/containerd/containerd/0886ceaea2470edc7339dfc5ebe0e3257ae84d06

From that commit:

> Fix reference ordering in CRI image store
>
> Currently image references end up being stored in a
> random order due to the way maps are iterated through
> in Go. This leads to inconsistent identifiers being
> resolved when a single reference is needed to identify
> an image and the ordering of the references is used for
> the selection.
>
> Sort references in a consistent and ranked manner,
> from higher information formats to lower.
>
> Note: A `name + tag` reference is considered higher
> information than a `name + digest` reference since a
> registry may be used to resolve the digest from a
> `name + tag` reference.

Co-Authored-by: Derek McGowan <derek@mcg.dev>
Co-Authored-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

reference/sort.go

@@ -0,0 +1,73 @@
+/*
+   Copyright The containerd 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 reference
+
+import (
+	"sort"
+)
+
+// Sort sorts string references preferring higher information references
+// The precedence is as follows:
+// 1. Name + Tag + Digest
+// 2. Name + Tag
+// 3. Name + Digest
+// 4. Name
+// 5. Digest
+// 6. Parse error
+func Sort(references []string) []string {
+	var prefs []Reference
+	var bad []string
+
+	for _, ref := range references {
+		pref, err := ParseAnyReference(ref)
+		if err != nil {
+			bad = append(bad, ref)
+		} else {
+			prefs = append(prefs, pref)
+		}
+	}
+	sort.Slice(prefs, func(a, b int) bool {
+		ar := refRank(prefs[a])
+		br := refRank(prefs[b])
+		if ar == br {
+			return prefs[a].String() < prefs[b].String()
+		}
+		return ar < br
+	})
+	sort.Strings(bad)
+	var refs []string
+	for _, pref := range prefs {
+		refs = append(refs, pref.String())
+	}
+	return append(refs, bad...)
+}
+
+func refRank(ref Reference) uint8 {
+	if _, ok := ref.(Named); ok {
+		if _, ok = ref.(Tagged); ok {
+			if _, ok = ref.(Digested); ok {
+				return 1
+			}
+			return 2
+		}
+		if _, ok = ref.(Digested); ok {
+			return 3
+		}
+		return 4
+	}
+	return 5
+}

reference/sort_test.go

@@ -0,0 +1,83 @@
+/*
+   Copyright The containerd 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 reference
+
+import (
+	"io"
+	"math/rand"
+	"testing"
+
+	"github.com/opencontainers/go-digest"
+)
+
+func TestReferenceSorting(t *testing.T) {
+	digested := func(seed int64) string {
+		b, err := io.ReadAll(io.LimitReader(rand.New(rand.NewSource(seed)), 64))
+		if err != nil {
+			panic(err)
+		}
+		return digest.FromBytes(b).String()
+	}
+	// Add z. prefix to string sort after "sha256:"
+	r1 := func(name, tag string, seed int64) string {
+		return "z.containerd.io/" + name + ":" + tag + "@" + digested(seed)
+	}
+	r2 := func(name, tag string) string {
+		return "z.containerd.io/" + name + ":" + tag
+	}
+	r3 := func(name string, seed int64) string {
+		return "z.containerd.io/" + name + "@" + digested(seed)
+	}
+
+	for i, tc := range []struct {
+		unsorted []string
+		expected []string
+	}{
+		{
+			unsorted: []string{r2("name", "latest"), r3("name", 1), r1("name", "latest", 1)},
+			expected: []string{r1("name", "latest", 1), r2("name", "latest"), r3("name", 1)},
+		},
+		{
+			unsorted: []string{"can't parse this:latest", r3("name", 1), r2("name", "latest")},
+			expected: []string{r2("name", "latest"), r3("name", 1), "can't parse this:latest"},
+		},
+		{
+			unsorted: []string{digested(1), r3("name", 1), r2("name", "latest")},
+			expected: []string{r2("name", "latest"), r3("name", 1), digested(1)},
+		},
+		{
+			unsorted: []string{r2("name", "tag2"), r2("name", "tag3"), r2("name", "tag1")},
+			expected: []string{r2("name", "tag1"), r2("name", "tag2"), r2("name", "tag3")},
+		},
+		{
+			unsorted: []string{r2("name-2", "tag"), r2("name-3", "tag"), r2("name-1", "tag")},
+			expected: []string{r2("name-1", "tag"), r2("name-2", "tag"), r2("name-3", "tag")},
+		},
+	} {
+		sorted := Sort(tc.unsorted)
+		if len(sorted) != len(tc.expected) {
+			t.Errorf("[%d]: Mismatched sized, got %d, expected %d", i, len(sorted), len(tc.expected))
+			continue
+		}
+		for j := range sorted {
+			if sorted[j] != tc.expected[j] {
+				t.Errorf("[%d]: Wrong value at %d, got %q, expected %q", i, j, sorted[j], tc.expected[j])
+				break
+			}
+		}
+	}
+}