Skip to content

Modern Docker Management, Designed for Everyone

fix: stable ordering for page walks without an explicit sort (#3648)

Kyle Mendellbf783a828ef8
diff --git a/backend/internal/image/image.go b/backend/internal/image/image.go
index e84466210..6b3810d2a 100644
--- a/backend/internal/image/image.go
+++ b/backend/internal/image/image.go
@@ -1098,7 +1098,13 @@ func (s *ImageService) getImagePaginationConfig() pagination.Config[imagetypes.S
{
Key: "repo",
Fn: func(a, b imagetypes.Summary) int {
- return strings.Compare(a.Repo, b.Repo)
+ if cmp := strings.Compare(a.Repo, b.Repo); cmp != 0 {
+ return cmp
+ }
+ if cmp := strings.Compare(a.Tag, b.Tag); cmp != 0 {
+ return cmp
+ }
+ return strings.Compare(a.ID, b.ID)
},
},
{
diff --git a/backend/internal/network/service.go b/backend/internal/network/service.go
index c4d61146b..7348ac0ec 100644
--- a/backend/internal/network/service.go
+++ b/backend/internal/network/service.go
@@ -364,7 +364,14 @@ func (s *NetworkService) buildNetworkSortBindings() []pagination.SortBinding[net
return []pagination.SortBinding[networktypes.Summary]{
{
Key: "name",
- Fn: func(a, b networktypes.Summary) int { return strings.Compare(a.Name, b.Name) },
+ // Docker allows duplicate network names, so tie-break on ID to keep
+ // pagination deterministic.
+ Fn: func(a, b networktypes.Summary) int {
+ if c := strings.Compare(a.Name, b.Name); c != 0 {
+ return c
+ }
+ return strings.Compare(a.ID, b.ID)
+ },
},
{
Key: "driver",
diff --git a/backend/internal/port/service.go b/backend/internal/port/service.go
index 97fb8e058..92f7fefd0 100644
--- a/backend/internal/port/service.go
+++ b/backend/internal/port/service.go
@@ -73,10 +73,16 @@ func (s *PortService) buildPortSortBindings() []pagination.SortBinding[porttypes
{
Key: "hostPort",
Fn: func(a, b porttypes.PortMapping) int {
- return compareOptionalIntInternal(a.HostPort, b.HostPort, a.ContainerName, b.ContainerName)
+ if cmp := compareOptionalIntInternal(a.HostPort, b.HostPort, a.ContainerName, b.ContainerName); cmp != 0 {
+ return cmp
+ }
+ return strings.Compare(a.ID, b.ID)
},
DescFn: func(a, b porttypes.PortMapping) int {
- return compareOptionalIntDescInternal(a.HostPort, b.HostPort, a.ContainerName, b.ContainerName)
+ if cmp := compareOptionalIntDescInternal(a.HostPort, b.HostPort, a.ContainerName, b.ContainerName); cmp != 0 {
+ return cmp
+ }
+ return strings.Compare(a.ID, b.ID)
},
},
{
diff --git a/backend/internal/port/service_test.go b/backend/internal/port/service_test.go
index 0d82860a4..59d7bb0c0 100644
--- a/backend/internal/port/service_test.go
+++ b/backend/internal/port/service_test.go
@@ -70,14 +70,16 @@ func TestPortService_ListPortsPaginated_FlattensPublishedAndExposedPorts(t *test
assert.True(t, items[0].IsPublished)
assert.Equal(t, "container-published:0.0.0.0:8080:80:tcp", items[0].ID)
- assert.Equal(t, "web", items[1].ContainerName)
- assert.Equal(t, 0, items[1].HostPort)
- assert.Equal(t, 443, items[1].ContainerPort)
+ // No sort requested: the default sort (hostPort, the first binding) places
+ // published ports first and orders unpublished ones by container name.
+ assert.Equal(t, "api", items[1].ContainerName)
+ assert.Equal(t, 9000, items[1].ContainerPort)
+ assert.Equal(t, "udp", items[1].Protocol)
assert.False(t, items[1].IsPublished)
- assert.Equal(t, "api", items[2].ContainerName)
- assert.Equal(t, 9000, items[2].ContainerPort)
- assert.Equal(t, "udp", items[2].Protocol)
+ assert.Equal(t, "web", items[2].ContainerName)
+ assert.Equal(t, 0, items[2].HostPort)
+ assert.Equal(t, 443, items[2].ContainerPort)
assert.False(t, items[2].IsPublished)
}
diff --git a/backend/pkg/pagination/filters.go b/backend/pkg/pagination/filters.go
index b4caf524d..eca171f1d 100644
--- a/backend/pkg/pagination/filters.go
+++ b/backend/pkg/pagination/filters.go
@@ -15,6 +15,9 @@ type FilterAccessor[T any] struct {
type Config[T any] struct {
SearchAccessors []SearchAccessor[T]
+ // SortBindings order matters: the first binding is the default sort when the
+ // requested key is empty or unknown, and serves as the tie-break for every
+ // other binding so pagination is deterministic.
SortBindings []SortBinding[T]
FilterAccessors []FilterAccessor[T]
}
diff --git a/backend/pkg/pagination/reflect.go b/backend/pkg/pagination/reflect.go
index 209c39317..351e7da94 100644
--- a/backend/pkg/pagination/reflect.go
+++ b/backend/pkg/pagination/reflect.go
@@ -17,20 +17,34 @@ func PaginateAndSortDB(params QueryParams, query *gorm.DB, result any) (Response
sortDirection = "asc"
}
+ modelType := reflect.TypeOf(result).Elem().Elem()
capitalizedSortColumn := stringutils.CapitalizeFirstLetter(sortColumn)
- sortField, sortFieldFound := reflect.TypeOf(result).Elem().Elem().FieldByName(capitalizedSortColumn)
+ sortField, sortFieldFound := modelType.FieldByName(capitalizedSortColumn)
isSortable, _ := strconv.ParseBool(sortField.Tag.Get("sortable"))
sortDirection = normalizeSortDirection(sortDirection)
+ var orderColumns []clause.OrderByColumn
+ columnName := ""
if sortFieldFound && isSortable {
- columnName := stringutils.CamelCaseToSnakeCase(sortColumn)
- query = query.Clauses(clause.OrderBy{
- Columns: []clause.OrderByColumn{
- {Column: clause.Column{Name: columnName}, Desc: sortDirection == "desc"},
- },
+ columnName = stringutils.CamelCaseToSnakeCase(sortColumn)
+ orderColumns = append(orderColumns, clause.OrderByColumn{
+ Column: clause.Column{Name: columnName},
+ Desc: sortDirection == "desc",
})
}
+ // Without a total order the page cut is undefined: rows can repeat or go
+ // missing across pages when the requested column has ties (or no sort was
+ // requested at all) and the database reorders a plain scan. Tie-break on the
+ // primary key whenever the model has one.
+ if _, hasID := modelType.FieldByName("ID"); hasID && columnName != "id" {
+ orderColumns = append(orderColumns, clause.OrderByColumn{
+ Column: clause.Column{Table: clause.CurrentTable, Name: "id"},
+ })
+ }
+ if len(orderColumns) > 0 {
+ query = query.Clauses(clause.OrderBy{Columns: orderColumns})
+ }
limit := params.Limit
// limit = -1 means "show all" - skip pagination
diff --git a/backend/pkg/pagination/reflect_test.go b/backend/pkg/pagination/reflect_test.go
new file mode 100644
index 000000000..22273f4bf
--- /dev/null
+++ b/backend/pkg/pagination/reflect_test.go
@@ -0,0 +1,58 @@
+package pagination
+
+import (
+ "testing"
+
+ "github.com/libtnb/sqlite"
+ "github.com/stretchr/testify/require"
+ "gorm.io/gorm"
+ "gorm.io/gorm/logger"
+)
+
+// Widgets with duplicate names, inserted in neither id nor name order, so that
+// only a deterministic ORDER BY yields a stable page walk.
+func newTieBreakTestDB(t *testing.T) *gorm.DB {
+ t.Helper()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+ require.NoError(t, err)
+ require.NoError(t, db.AutoMigrate(&widget{}))
+ for _, w := range []widget{
+ {ID: "c", Name: "X"},
+ {ID: "a", Name: "X"},
+ {ID: "e", Name: "Y"},
+ {ID: "b", Name: "X"},
+ {ID: "d", Name: "Y"},
+ } {
+ require.NoError(t, db.Create(&w).Error)
+ }
+ return db
+}
+
+func walkWidgetPages(t *testing.T, db *gorm.DB, sort string) []string {
+ t.Helper()
+ var ids []string
+ for start := 0; start < 5; start += 2 {
+ var got []widget
+ _, err := PaginateAndSortDB(QueryParams{
+ Params: Params{Start: start, Limit: 2},
+ SortParams: SortParams{Sort: sort, Order: "asc"},
+ }, db.Model(&widget{}), &got)
+ require.NoError(t, err)
+ for _, w := range got {
+ ids = append(ids, w.ID)
+ }
+ }
+ return ids
+}
+
+func TestPaginateAndSortDB_NoSortFallsBackToIDOrder(t *testing.T) {
+ db := newTieBreakTestDB(t)
+
+ require.Equal(t, []string{"a", "b", "c", "d", "e"}, walkWidgetPages(t, db, ""))
+}
+
+func TestPaginateAndSortDB_SortTiesBrokenByID(t *testing.T) {
+ db := newTieBreakTestDB(t)
+
+ require.Equal(t, []string{"a", "b", "c", "d", "e"}, walkWidgetPages(t, db, "name"))
+}
diff --git a/backend/pkg/pagination/sort.go b/backend/pkg/pagination/sort.go
index e2a36a1f6..69f9cc53c 100644
--- a/backend/pkg/pagination/sort.go
+++ b/backend/pkg/pagination/sort.go
@@ -23,23 +23,52 @@ type (
}
)
+// sortFunction always sorts: when params.Sort is empty or matches no binding it
+// falls back to the first binding, and when a non-first binding is used its ties
+// are broken by the first binding's ascending comparator. Pagination slices the
+// sorted result by index, so an unsorted (or tie-ambiguous) order would make
+// page walks skip and duplicate items whenever the source order shifts between
+// requests (e.g. Docker's map-iteration order for volumes and networks).
func sortFunction[T any](items []T, params SortParams, sorts []SortBinding[T]) []T {
+ if len(sorts) == 0 {
+ return items
+ }
+
+ binding := sorts[0]
for _, sort := range sorts {
if sort.Key == params.Sort {
- fn := sort.Fn
- if params.Order == SortDesc {
- if sort.DescFn != nil {
- fn = sort.DescFn
- } else {
- fn = reverSortFn(fn)
- }
- }
- slices.SortStableFunc(items, fn)
+ binding = sort
+ break
+ }
+ }
+
+ fn := binding.Fn
+ if params.Order == SortDesc {
+ if binding.DescFn != nil {
+ fn = binding.DescFn
+ } else {
+ fn = reverSortFn(fn)
}
}
+ if binding.Key != sorts[0].Key {
+ fn = chainSortFn(fn, sorts[0].Fn)
+ }
+ slices.SortStableFunc(items, fn)
return items
}
+// chainSortFn falls through to tieBreak when primary considers two items equal.
+// The tie-break is applied after any desc adjustment and always ascending: its
+// job is a deterministic total order, not a meaningful secondary sort.
+func chainSortFn[T any](primary, tieBreak SortOption[T]) SortOption[T] {
+ return func(a, b T) int {
+ if c := primary(a, b); c != 0 {
+ return c
+ }
+ return tieBreak(a, b)
+ }
+}
+
func reverSortFn[T any](fn SortOption[T]) SortOption[T] {
return func(a, b T) int {
return -1 * fn(a, b)
diff --git a/backend/pkg/pagination/sort_test.go b/backend/pkg/pagination/sort_test.go
index a61fa641e..3d79829e3 100644
--- a/backend/pkg/pagination/sort_test.go
+++ b/backend/pkg/pagination/sort_test.go
@@ -1,6 +1,10 @@
package pagination
import (
+ "fmt"
+ "math/rand/v2"
+ "slices"
+ "strings"
"testing"
"github.com/stretchr/testify/require"
@@ -45,3 +49,113 @@ func TestSortFunctionUsesCustomDescendingComparatorWhenProvided(t *testing.T) {
require.Equal(t, []int{2, 1, 0}, sorted)
}
+
+type sortItem struct {
+ ID string
+ Group string
+}
+
+func sortItemBindings() []SortBinding[sortItem] {
+ return []SortBinding[sortItem]{
+ {
+ Key: "id",
+ Fn: func(a, b sortItem) int { return strings.Compare(a.ID, b.ID) },
+ },
+ {
+ Key: "group",
+ Fn: func(a, b sortItem) int { return strings.Compare(a.Group, b.Group) },
+ },
+ }
+}
+
+func sortItemIDs(items []sortItem) []string {
+ ids := make([]string, len(items))
+ for i, item := range items {
+ ids[i] = item.ID
+ }
+ return ids
+}
+
+func TestSortFunctionFallsBackToFirstBindingWhenSortEmpty(t *testing.T) {
+ items := []sortItem{{ID: "b"}, {ID: "c"}, {ID: "a"}}
+
+ sorted := sortFunction(items, SortParams{}, sortItemBindings())
+
+ require.Equal(t, []string{"a", "b", "c"}, sortItemIDs(sorted))
+}
+
+func TestSortFunctionFallsBackToFirstBindingWhenSortUnknown(t *testing.T) {
+ items := []sortItem{{ID: "b"}, {ID: "c"}, {ID: "a"}}
+
+ sorted := sortFunction(items, SortParams{Sort: "bogus"}, sortItemBindings())
+
+ require.Equal(t, []string{"a", "b", "c"}, sortItemIDs(sorted))
+}
+
+func TestSortFunctionHonoursDescendingOrderOnFallback(t *testing.T) {
+ items := []sortItem{{ID: "b"}, {ID: "c"}, {ID: "a"}}
+
+ sorted := sortFunction(items, SortParams{Order: SortDesc}, sortItemBindings())
+
+ require.Equal(t, []string{"c", "b", "a"}, sortItemIDs(sorted))
+}
+
+func TestSortFunctionBreaksTiesWithFirstBinding(t *testing.T) {
+ items := []sortItem{
+ {ID: "d", Group: "y"},
+ {ID: "b", Group: "x"},
+ {ID: "c", Group: "y"},
+ {ID: "a", Group: "x"},
+ }
+
+ sorted := sortFunction(items, SortParams{Sort: "group"}, sortItemBindings())
+ require.Equal(t, []string{"a", "b", "c", "d"}, sortItemIDs(sorted))
+
+ // Descending reverses the requested key only; the tie-break stays ascending.
+ sorted = sortFunction(items, SortParams{Sort: "group", Order: SortDesc}, sortItemBindings())
+ require.Equal(t, []string{"c", "d", "a", "b"}, sortItemIDs(sorted))
+}
+
+func TestSortFunctionWithoutBindingsReturnsItemsUnchanged(t *testing.T) {
+ items := []sortItem{{ID: "b"}, {ID: "a"}}
+
+ sorted := sortFunction(items, SortParams{Sort: "id"}, nil)
+
+ require.Equal(t, []string{"b", "a"}, sortItemIDs(sorted))
+}
+
+// A page walk must return every item exactly once even when the source order
+// changes between requests, as Docker's map-iteration order does for volumes
+// and networks — both with no sort param and with a low-cardinality sort key.
+func TestSearchOrderAndPaginateStablePageWalkAcrossReorderedInput(t *testing.T) {
+ source := make([]sortItem, 0, 25)
+ for i := range 25 {
+ source = append(source, sortItem{ID: fmt.Sprintf("%02d", i), Group: fmt.Sprintf("g%d", i%3)})
+ }
+ config := Config[sortItem]{SortBindings: sortItemBindings()}
+
+ for _, sort := range []string{"", "group"} {
+ t.Run("sort="+sort, func(t *testing.T) {
+ r := rand.New(rand.NewPCG(7, 11))
+ seen := map[string]int{}
+ const limit = 4
+ for start := 0; start < len(source); start += limit {
+ shuffled := slices.Clone(source)
+ r.Shuffle(len(shuffled), func(i, j int) { shuffled[i], shuffled[j] = shuffled[j], shuffled[i] })
+
+ result := SearchOrderAndPaginate(shuffled, QueryParams{
+ SortParams: SortParams{Sort: sort},
+ Params: Params{Start: start, Limit: limit},
+ }, config)
+ for _, item := range result.Items {
+ seen[item.ID]++
+ }
+ }
+
+ require.Len(t, seen, len(source), "every item must appear in the walk")
+ for id, count := range seen {
+ require.Equal(t, 1, count, "item %s must appear exactly once", id)
+ }
+ })
+ }
+}