From d987c5cd1cb1c139887a099297af31530bc9ec8d Mon Sep 17 00:00:00 2001 From: Chandler Swift Date: Tue, 25 Aug 2026 11:40:42 -0500 Subject: [PATCH] file_server: Add natural sort option for browse templates For files with regions of numbers and other characters, it's intuitive to have the numbers sorted by increasing numeric value rather than by ASCII code. (Jeff Atwood has a nice article here: https://blog.codinghorror.com/sorting-for-humans-natural-sort-order/) For example, the listing for a directory containing `foo1`, `foo2`, and `foo10` would sort in that order, rather than putting `foo10` between `foo1` and `foo2`. This isn't enabled by default, but rather as a new argument to `sort` which can be opted into in the Caddyfile. This is currently not user- configurable. Closes #7226 --- modules/caddyhttp/fileserver/browse.go | 15 ++-- .../caddyhttp/fileserver/browsetplcontext.go | 62 +++++++++++--- .../fileserver/browsetplcontext_bench_test.go | 2 +- modules/caddyhttp/fileserver/caddyfile.go | 2 +- modules/caddyhttp/fileserver/natsort.go | 65 +++++++++++++++ modules/caddyhttp/fileserver/natsort_test.go | 80 +++++++++++++++++++ modules/caddyhttp/fileserver/staticfiles.go | 32 +++++--- .../fileserver/testdata/natsort/foo1.txt | 1 + .../fileserver/testdata/natsort/foo10.txt | 1 + .../fileserver/testdata/natsort/foo2.txt | 1 + 10 files changed, 233 insertions(+), 28 deletions(-) create mode 100644 modules/caddyhttp/fileserver/natsort.go create mode 100644 modules/caddyhttp/fileserver/natsort_test.go create mode 100644 modules/caddyhttp/fileserver/testdata/natsort/foo1.txt create mode 100644 modules/caddyhttp/fileserver/testdata/natsort/foo10.txt create mode 100644 modules/caddyhttp/fileserver/testdata/natsort/foo2.txt diff --git a/modules/caddyhttp/fileserver/browse.go b/modules/caddyhttp/fileserver/browse.go index 97f1fc128..404a537b7 100644 --- a/modules/caddyhttp/fileserver/browse.go +++ b/modules/caddyhttp/fileserver/browse.go @@ -61,10 +61,12 @@ type Browse struct { // It includes the following options: // - sort_by: name(default), namedirfirst, size, time // - order: asc(default), desc + // - sort_method: lex(default), natural // eg.: // - `sort time desc` will sort by time in descending order // - `sort size` will sort by size in ascending order - // The first option must be `sort_by` and the second option must be `order` (if exists). + // - `sort name natural` will sort by name using "natural sort", so e.g. + // "9th Grade" sorts before "10th Grade", although '9' > '1' char-wise SortOptions []string `json:"sort,omitempty"` // FileLimit limits the number of up to n DirEntry values in directory order. @@ -238,19 +240,18 @@ func (fsrv *FileServer) loadDirectoryContents(ctx context.Context, fileSystem fs // It mutates the listing and may set cookies. func (fsrv *FileServer) browseApplyQueryParams(w http.ResponseWriter, r *http.Request, listing *browseTemplateContext) { var orderParam, sortParam string + methodParam := sortMethodLexicographic // The configs in Caddyfile have lower priority than Query params, // so put it at first. - for idx, item := range fsrv.Browse.SortOptions { - // Only `sort` & `order`, 2 params are allowed - if idx >= 2 { - break - } + for _, item := range fsrv.Browse.SortOptions { switch item { case sortByName, sortByNameDirFirst, sortBySize, sortByTime: sortParam = item case sortOrderAsc, sortOrderDesc: orderParam = item + case sortMethodLexicographic, sortMethodNatural: + methodParam = item } } @@ -308,7 +309,7 @@ func (fsrv *FileServer) browseApplyQueryParams(w http.ResponseWriter, r *http.Re } // finally, apply the sorting and limiting - listing.applySortAndLimit(sortParam, orderParam, limitParam, offsetParam) + listing.applySortAndLimit(sortParam, orderParam, methodParam, limitParam, offsetParam) } // makeBrowseTemplate creates the template to be used for directory listings. diff --git a/modules/caddyhttp/fileserver/browsetplcontext.go b/modules/caddyhttp/fileserver/browsetplcontext.go index 112d8caec..754c53e2f 100644 --- a/modules/caddyhttp/fileserver/browsetplcontext.go +++ b/modules/caddyhttp/fileserver/browsetplcontext.go @@ -188,6 +188,9 @@ type browseTemplateContext struct { // Sorting order Order string `json:"order,omitempty"` + // Sort method (lexicographic or natural) + SortMethod string `json:"method,omitempty"` + // Display format (list or grid) Layout string `json:"layout,omitempty"` @@ -225,9 +228,10 @@ func (l browseTemplateContext) Breadcrumbs() []crumb { return result } -func (l *browseTemplateContext) applySortAndLimit(sortParam, orderParam, limitParam string, offsetParam string) { +func (l *browseTemplateContext) applySortAndLimit(sortParam, orderParam, methodParam, limitParam string, offsetParam string) { l.Sort = sortParam l.Order = orderParam + l.SortMethod = methodParam // Only compute lowercase names when the selected sort comparator needs it; // avoid O(n) work when sorting by time or when no sorting is requested. @@ -240,9 +244,17 @@ func (l *browseTemplateContext) applySortAndLimit(sortParam, orderParam, limitPa if l.Order == "desc" { switch l.Sort { case sortByName: - sort.Sort(sort.Reverse(byName(*l))) + if l.SortMethod == sortMethodNatural { + sort.Sort(sort.Reverse(byNameNatural(*l))) + } else { + sort.Sort(sort.Reverse(byName(*l))) + } case sortByNameDirFirst: - sort.Sort(sort.Reverse(byNameDirFirst(*l))) + if l.SortMethod == sortMethodNatural { + sort.Sort(sort.Reverse(byNameDirFirstNatural(*l))) + } else { + sort.Sort(sort.Reverse(byNameDirFirst(*l))) + } case sortBySize: sort.Sort(sort.Reverse(bySize(*l))) case sortByTime: @@ -251,9 +263,17 @@ func (l *browseTemplateContext) applySortAndLimit(sortParam, orderParam, limitPa } else { switch l.Sort { case sortByName: - sort.Sort(byName(*l)) + if l.SortMethod == sortMethodNatural { + sort.Sort(byNameNatural(*l)) + } else { + sort.Sort(byName(*l)) + } case sortByNameDirFirst: - sort.Sort(byNameDirFirst(*l)) + if l.SortMethod == sortMethodNatural { + sort.Sort(byNameDirFirstNatural(*l)) + } else { + sort.Sort(byNameDirFirst(*l)) + } case sortBySize: sort.Sort(bySize(*l)) case sortByTime: @@ -340,10 +360,12 @@ func (fi fileInfo) HumanModTime(format string) string { } type ( - byName browseTemplateContext - byNameDirFirst browseTemplateContext - bySize browseTemplateContext - byTime browseTemplateContext + byName browseTemplateContext + byNameNatural browseTemplateContext + byNameDirFirst browseTemplateContext + byNameDirFirstNatural browseTemplateContext + bySize browseTemplateContext + byTime browseTemplateContext ) func (l byName) Len() int { return len(l.Items) } @@ -353,6 +375,13 @@ func (l byName) Less(i, j int) bool { return l.Items[i].nameLower < l.Items[j].nameLower } +func (l byNameNatural) Len() int { return len(l.Items) } +func (l byNameNatural) Swap(i, j int) { l.Items[i], l.Items[j] = l.Items[j], l.Items[i] } + +func (l byNameNatural) Less(i, j int) bool { + return naturalLess(l.Items[i].nameLower, l.Items[j].nameLower) +} + func (l byNameDirFirst) Len() int { return len(l.Items) } func (l byNameDirFirst) Swap(i, j int) { l.Items[i], l.Items[j] = l.Items[j], l.Items[i] } @@ -365,6 +394,18 @@ func (l byNameDirFirst) Less(i, j int) bool { return l.Items[i].IsDir } +func (l byNameDirFirstNatural) Len() int { return len(l.Items) } +func (l byNameDirFirstNatural) Swap(i, j int) { l.Items[i], l.Items[j] = l.Items[j], l.Items[i] } + +func (l byNameDirFirstNatural) Less(i, j int) bool { + // sort by name if both are dir or file + if l.Items[i].IsDir == l.Items[j].IsDir { + return naturalLess(l.Items[i].nameLower, l.Items[j].nameLower) + } + // sort dir ahead of file + return l.Items[i].IsDir +} + func (l bySize) Len() int { return len(l.Items) } func (l bySize) Swap(i, j int) { l.Items[i], l.Items[j] = l.Items[j], l.Items[i] } @@ -401,4 +442,7 @@ const ( sortOrderAsc = "asc" sortOrderDesc = "desc" + + sortMethodLexicographic = "lex" + sortMethodNatural = "natural" ) diff --git a/modules/caddyhttp/fileserver/browsetplcontext_bench_test.go b/modules/caddyhttp/fileserver/browsetplcontext_bench_test.go index a895264bc..c0c5ebc1a 100644 --- a/modules/caddyhttp/fileserver/browsetplcontext_bench_test.go +++ b/modules/caddyhttp/fileserver/browsetplcontext_bench_test.go @@ -216,7 +216,7 @@ func BenchmarkDirectoryListingAndSort(b *testing.B) { b.Run(fmt.Sprintf("entries=%d", n), func(b *testing.B) { benchmarkDirectoryListingAndSort(b, n, func(fsrv *FileServer, ctx context.Context, fileSystem fs.FS, entries []fs.DirEntry, root string) *browseTemplateContext { listing := fsrv.directoryListing(ctx, fileSystem, time.Time{}, entries, true, root, "/", caddy.NewReplacer()) - listing.applySortAndLimit(sortByNameDirFirst, sortOrderAsc, "", "") + listing.applySortAndLimit(sortByNameDirFirst, sortOrderAsc, sortMethodLexicographic, "", "") return listing }) }) diff --git a/modules/caddyhttp/fileserver/caddyfile.go b/modules/caddyhttp/fileserver/caddyfile.go index 4000690b9..c2b6b715a 100644 --- a/modules/caddyhttp/fileserver/caddyfile.go +++ b/modules/caddyhttp/fileserver/caddyfile.go @@ -128,7 +128,7 @@ func (fsrv *FileServer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error { for d.NextArg() { dVal := d.Val() switch dVal { - case sortByName, sortByNameDirFirst, sortBySize, sortByTime, sortOrderAsc, sortOrderDesc: + case sortByName, sortByNameDirFirst, sortBySize, sortByTime, sortOrderAsc, sortOrderDesc, sortMethodLexicographic, sortMethodNatural: fsrv.Browse.SortOptions = append(fsrv.Browse.SortOptions, dVal) default: return d.Errf("unknown sort option '%s'", dVal) diff --git a/modules/caddyhttp/fileserver/natsort.go b/modules/caddyhttp/fileserver/natsort.go new file mode 100644 index 000000000..65f6a161b --- /dev/null +++ b/modules/caddyhttp/fileserver/natsort.go @@ -0,0 +1,65 @@ +package fileserver + +func isDigit(b byte) bool { return '0' <= b && b <= '9' } + +// naturalLess compares two strings using natural ordering. This means that e.g. +// "abc2" < "abc12". +// +// Non-digit sequences and numbers are compared separately. The former are +// compared bytewise, while digits are compared numerically (except that +// the number of leading zeros is used as a tie-breaker, so e.g. "2" < "02") +// +// Limitation: only ASCII digits (0-9) are considered. +// +// This implementation is copied from https://github.com/fvbommel/sortorder, +// which is MIT licensed. +func naturalLess(str1, str2 string) bool { + idx1, idx2 := 0, 0 + for idx1 < len(str1) && idx2 < len(str2) { + c1, c2 := str1[idx1], str2[idx2] + dig1, dig2 := isDigit(c1), isDigit(c2) + switch { + case dig1 != dig2: // Digits before other characters. + return dig1 // True if LHS is a digit, false if the RHS is one. + case !dig1: // && !dig2, because dig1 == dig2 + // UTF-8 compares bytewise-lexicographically, no need to decode + // codepoints. + if c1 != c2 { + return c1 < c2 + } + idx1++ + idx2++ + default: // Digits + // Eat zeros. + for ; idx1 < len(str1) && str1[idx1] == '0'; idx1++ { + } + for ; idx2 < len(str2) && str2[idx2] == '0'; idx2++ { + } + // Eat all digits. + nonZero1, nonZero2 := idx1, idx2 + for ; idx1 < len(str1) && isDigit(str1[idx1]); idx1++ { + } + for ; idx2 < len(str2) && isDigit(str2[idx2]); idx2++ { + } + // If lengths of numbers with non-zero prefix differ, the shorter + // one is less. + if len1, len2 := idx1-nonZero1, idx2-nonZero2; len1 != len2 { + return len1 < len2 + } + // If they're equally long, string comparison is correct. + if nr1, nr2 := str1[nonZero1:idx1], str2[nonZero2:idx2]; nr1 != nr2 { + return nr1 < nr2 + } + // Otherwise, the one with less zeros is less. + // Because everything up to the number is equal, comparing the index + // after the zeros is sufficient. + if nonZero1 != nonZero2 { + return nonZero1 < nonZero2 + } + } + // They're identical so far, so continue comparing. + } + // So far they are identical. At least one is ended. If the other continues, + // it sorts last. + return len(str1) < len(str2) +} diff --git a/modules/caddyhttp/fileserver/natsort_test.go b/modules/caddyhttp/fileserver/natsort_test.go new file mode 100644 index 000000000..0077a82d1 --- /dev/null +++ b/modules/caddyhttp/fileserver/natsort_test.go @@ -0,0 +1,80 @@ +// Copyright 2015 Matthew Holt and The Caddy 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 fileserver + +import ( + "context" + "io/fs" + "net/http/httptest" + "os" + "testing" + + "github.com/caddyserver/caddy/v2/modules/caddyhttp" +) + +// TestNatLexSort confirms that both sort methods work: For "lex", a +// lexicographic sort returns "foo1.txt" < "foo10.txt" < "foo2.txt", while a +// "natural" sort returns a human-intuitive order: "foo2.txt" < "foo10.txt" +func TestNatLexSort(t *testing.T) { + fsrv := &FileServer{Browse: &Browse{}} + + base := "./testdata" + dirName := "natsort" + + fsys := os.DirFS(base) + f, err := fsys.Open(dirName) + if err != nil { + t.Fatalf("opening testdata dir: %v", err) + } + defer f.Close() + + repl := caddyhttp.NewTestReplacer(httptest.NewRequest("GET", "/", nil)) + + listing, err := fsrv.loadDirectoryContents(context.Background(), fsys, f.(fs.ReadDirFile), base, "/natsort/", repl) + if err != nil { + t.Fatalf("loadDirectoryContents returned error: %v", err) + } + + if len(listing.Items) != 3 { + t.Fatalf("expected 3 items in listing, got %d", len(listing.Items)) + } + + cases := []struct { + Method string + Want []string + }{ + {sortMethodNatural, []string{"foo1.txt", "foo2.txt", "foo10.txt"}}, + {sortMethodLexicographic, []string{"foo1.txt", "foo10.txt", "foo2.txt"}}, + } + + for _, c := range cases { + listing.applySortAndLimit(sortByNameDirFirst, sortOrderAsc, c.Method, "", "") + + got := []string{} + for _, item := range listing.Items { + got = append(got, item.Name) + } + + if len(got) != len(c.Want) { + t.Fatalf("expected %v items, got %v", len(got), len(c.Want)) + } + + for i := range c.Want { + if got[i] != c.Want[i] { + t.Fatalf("unexpected item at index %v: got %v, want %v", i, got, c.Want) + } + } + } +} diff --git a/modules/caddyhttp/fileserver/staticfiles.go b/modules/caddyhttp/fileserver/staticfiles.go index bd9df8223..c39d5aeb1 100644 --- a/modules/caddyhttp/fileserver/staticfiles.go +++ b/modules/caddyhttp/fileserver/staticfiles.go @@ -247,20 +247,32 @@ func (fsrv *FileServer) Provision(ctx caddy.Context) error { if fsrv.Browse != nil { // check sort options - for idx, sortOption := range fsrv.Browse.SortOptions { - switch idx { - case 0: - if sortOption != sortByName && sortOption != sortByNameDirFirst && sortOption != sortBySize && sortOption != sortByTime { - return fmt.Errorf("the first option must be one of the following: %s, %s, %s, %s, but got %s", sortByName, sortByNameDirFirst, sortBySize, sortByTime, sortOption) + var sortBy, sortOrder, sortMethod string + for _, sortOption := range fsrv.Browse.SortOptions { + switch sortOption { + case sortByName, sortByNameDirFirst, sortBySize, sortByTime: + if sortBy != "" { + return fmt.Errorf("multiple contradictory sort types given: %s and %s", sortBy, sortOption) + } else { + sortBy = sortOption } - case 1: - if sortOption != sortOrderAsc && sortOption != sortOrderDesc { - return fmt.Errorf("the second option must be one of the following: %s, %s, but got %s", sortOrderAsc, sortOrderDesc, sortOption) + case sortOrderAsc, sortOrderDesc: + if sortOrder != "" { + return fmt.Errorf("multiple contradictory sort orders given: %s and %s", sortOrder, sortOption) + } else { + sortOrder = sortOption + } + case sortMethodLexicographic, sortMethodNatural: + if sortMethod != "" { + return fmt.Errorf("multiple contradictory sort methods given: %s and %s", sortMethod, sortOption) + } else { + sortMethod = sortOption } - default: - return fmt.Errorf("only max 2 sort options are allowed, but got %d", idx+1) } } + if len(fsrv.Browse.SortOptions) > 0 && sortBy == "" { // If sort options are passed, we expect one of them to be sortBy + return fmt.Errorf("no sort type passed, expected one of %s, %s, %s, %s", sortByName, sortByNameDirFirst, sortBySize, sortByTime) + } } return nil diff --git a/modules/caddyhttp/fileserver/testdata/natsort/foo1.txt b/modules/caddyhttp/fileserver/testdata/natsort/foo1.txt new file mode 100644 index 000000000..b0a92ba4e --- /dev/null +++ b/modules/caddyhttp/fileserver/testdata/natsort/foo1.txt @@ -0,0 +1 @@ +foo1.txt diff --git a/modules/caddyhttp/fileserver/testdata/natsort/foo10.txt b/modules/caddyhttp/fileserver/testdata/natsort/foo10.txt new file mode 100644 index 000000000..ade2a424e --- /dev/null +++ b/modules/caddyhttp/fileserver/testdata/natsort/foo10.txt @@ -0,0 +1 @@ +foo10.txt diff --git a/modules/caddyhttp/fileserver/testdata/natsort/foo2.txt b/modules/caddyhttp/fileserver/testdata/natsort/foo2.txt new file mode 100644 index 000000000..6aab57b17 --- /dev/null +++ b/modules/caddyhttp/fileserver/testdata/natsort/foo2.txt @@ -0,0 +1 @@ +foo2.txt