Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
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.goindex 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.goindex 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[netreturn []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.goindex 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.goindex 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 *testassert.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.goindex 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.goindex 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) (ResponsesortDirection = "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 paginationdiff --git a/backend/pkg/pagination/reflect_test.go b/backend/pkg/pagination/reflect_test.gonew file mode 100644index 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.goindex 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.goindex a61fa641e..3d79829e3 100644--- a/backend/pkg/pagination/sort_test.go+++ b/backend/pkg/pagination/sort_test.go@@ -1,6 +1,10 @@package paginationimport (+ "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)+ }+ })+ }+}