feat(local): sequential fstatat(dirfd) for linux/amd64 listing

Replace per-entry path-based os.Lstat with fstatat(dirfd, name,
AT_SYMLINK_NOFOLLOW) on linux/amd64. The directory fd is duplicated
once per ReadDir batch via F_DUPFD_CLOEXEC through SyscallConn.Control,
carried with the batch to the consumer, and closed asynchronously after
stat completes.

Key design points:
- unix.Stat_t → syscall.Stat_t field copy preserves readDevice/readTime
  contract without unsafe.Pointer
- SyscallConn.Control for both fd duplication and stat calls prevents
  Fd()-induced deadline damage and fd-number reuse races
- Combined cancel-before-drain defer prevents pipeline deadlock on
  early consumer exit
- Nil-guard fallback to entry.Info() on clone failure or non-linux/amd64
- All existing behavioral contracts preserved: SkipRecent, ExcludeFile,
  TranslateSymlinks, timer patterns, errReopen reset

Reviewed across 3 rounds (24 independent review agents). One post-review
fix: added explicit S_IFREG case to prevent regular files hitting the
ModeIrregular default branch.

Signed-off-by: Anagh Kumar Baranwal <6824881+darthShadow@users.noreply.github.com>

Author: darthShadow

backend/local/list.go

@@ -31,6 +31,7 @@ const (
 type cachedDirEntry struct {
 	os.DirEntry
 	newRemote string
+	statDir   *os.File
 }
 
 type statFileInfo struct {
@@ -85,7 +86,7 @@ type statPool struct {
 }
 
 // errReopen is an internal sentinel that is never returned to callers.
-// It flows through batchCh between the producer and consumer in listFileInfos
+// It flows through batchCh between the producer and consumer in listCachedFileInfos
 // when the producer reopens the directory fd after a CephFS timeout.
 // The consumer must reset accumulated results because the new fd starts at
 // offset 0 and re-reads all entries.
@@ -94,6 +95,57 @@ var errReopen = errors.New("directory reopened after timeout")
 type readResult struct {
 	entries []os.DirEntry
 	err     error
+	statDir *os.File
+}
+
+// closeReadResultStatDir releases the dup'd directory fd held by a read batch.
+// The close is async to avoid deadlocking the consumer: when called from the
+// deferred cleanup path, the SyscallConn.Control callback that owns the fd ref
+// may still be on the stack, so a synchronous close could block. The Close
+// error is discarded because the fd is a read-only dup used only for fstatat;
+// it holds no write state and has no dirty data to flush.
+func closeReadResultStatDir(batch *readResult) {
+	if batch.statDir != nil {
+		//nolint:errcheck // async close is intentional for current-batch cleanup.
+		go batch.statDir.Close()
+		batch.statDir = nil
+	}
+}
+
+func (f *Fs) statReadBatch(ctx context.Context, batch *readResult, entriesBuf []cachedDirEntry, preFilter func(os.DirEntry) (cachedDirEntry, bool), statFunc func(entry cachedDirEntry) os.FileInfo, pool **statPool) ([]cachedDirEntry, []statFileInfo, error) {
+	defer closeReadResultStatDir(batch)
+
+	if len(batch.entries) == 0 {
+		return entriesBuf[:0], nil, nil
+	}
+
+	entries := entriesBuf[:0]
+	if cap(entries) < len(batch.entries) {
+		entries = make([]cachedDirEntry, 0, len(batch.entries))
+	}
+	if preFilter != nil {
+		for _, entry := range batch.entries {
+			filteredEntry, ok := preFilter(entry)
+			if !ok {
+				continue
+			}
+			filteredEntry.statDir = batch.statDir
+			entries = append(entries, filteredEntry)
+		}
+	} else {
+		for _, entry := range batch.entries {
+			entries = append(entries, cachedDirEntry{DirEntry: entry, statDir: batch.statDir})
+		}
+	}
+	if len(entries) == 0 {
+		return entries, nil, nil
+	}
+
+	fis, err := f.asyncStatCachedEntries(ctx, entries, statFunc, pool)
+	if err != nil {
+		return nil, nil, err
+	}
+	return entries, fis, nil
 }
 
 func newStatPool(ctx context.Context, workers int, statFunc func(os.DirEntry) os.FileInfo) *statPool {
@@ -635,7 +687,16 @@ func (f *Fs) listCachedFileInfos(ctx context.Context, fd *os.File, openDir func(
 	}
 
 	pipeCtx, pipeCancel := context.WithCancel(ctx)
-	defer pipeCancel()
+	var batchCh chan readResult
+	defer func() {
+		pipeCancel()
+		if batchCh == nil {
+			return
+		}
+		for remaining := range batchCh {
+			closeReadResultStatDir(&remaining)
+		}
+	}()
 
 	if useReadDir {
 		// Windows/Plan9: Readdir returns os.FileInfo directly, no separate stat needed.
@@ -697,7 +758,7 @@ func (f *Fs) listCachedFileInfos(ctx context.Context, fd *os.File, openDir func(
 	}
 
 	// Pipeline: producer goroutine reads batches, consumer stats them.
-	batchCh := make(chan readResult, 1)
+	batchCh = make(chan readResult, 1)
 
 	go func() {
 		defer close(batchCh)
@@ -744,9 +805,17 @@ func (f *Fs) listCachedFileInfos(ctx context.Context, fd *os.File, openDir func(
 					return
 				}
 			} else if !errors.Is(result.err, os.ErrDeadlineExceeded) {
+				if len(result.entries) > 0 {
+					var cloneErr error
+					result.statDir, cloneErr = cloneDirForListStat(readFd)
+					if cloneErr != nil {
+						fs.Debugf(f, "cloneDirForListStat: %v, falling back to entry.Info()", cloneErr)
+					}
+				}
 				select {
 				case batchCh <- result:
 				case <-pipeCtx.Done():
+					closeReadResultStatDir(&result)
 					return
 				}
 				if result.err != nil {
@@ -781,33 +850,17 @@ func (f *Fs) listCachedFileInfos(ctx context.Context, fd *os.File, openDir func(
 	var entries []cachedDirEntry
 	for batch := range batchCh {
 		if batch.err == errReopen {
+			closeReadResultStatDir(&batch)
 			allFis = allFis[:0]
 			continue
 		}
-		if len(batch.entries) > 0 {
-			entries = entries[:0]
-			if cap(entries) < len(batch.entries) {
-				entries = make([]cachedDirEntry, 0, len(batch.entries))
-			}
-			if preFilter != nil {
-				for _, entry := range batch.entries {
-					filteredEntry, ok := preFilter(entry)
-					if !ok {
-						continue
-					}
-					entries = append(entries, filteredEntry)
-				}
-			} else {
-				for _, entry := range batch.entries {
-					entries = append(entries, cachedDirEntry{DirEntry: entry})
-				}
-			}
-			fis, statErr := f.asyncStatCachedEntries(ctx, entries, statFunc, pool)
-			if statErr != nil {
-				return nil, statErr
-			}
-			allFis = append(allFis, fis...)
+		var fis []statFileInfo
+		var statErr error
+		entries, fis, statErr = f.statReadBatch(ctx, &batch, entries, preFilter, statFunc, pool)
+		if statErr != nil {
+			return nil, statErr
 		}
+		allFis = append(allFis, fis...)
 		if batch.err == io.EOF {
 			break
 		}
@@ -895,7 +948,7 @@ func (f *Fs) List(ctx context.Context, dir string) (entries fs.DirEntries, err e
 				return nil
 			}
 		}
-		fi, fierr := entry.Info()
+		fi, fierr := statDirEntry(entry)
 		if os.IsNotExist(fierr) {
 			return nil
 		}

backend/local/list_fstatat_linux.go

@@ -0,0 +1,152 @@
+//go:build linux && amd64
+
+// This file implements the linux/amd64 fast-stat path: cloneDirForListStat
+// dup's the directory fd via F_DUPFD_CLOEXEC, and statDirEntry calls
+// fstatat(dirfd, name, AT_SYMLINK_NOFOLLOW) to stat each entry without
+// constructing an absolute path. On other platforms the build tag excludes
+// this file and list_fstatat_other.go provides stubs that fall back to
+// entry.Info().
+
+package local
+
+import (
+	"os"
+	"syscall"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+type fstatatFileInfo struct {
+	name    string
+	mode    os.FileMode
+	size    int64
+	modTime time.Time
+	stat    syscall.Stat_t
+}
+
+func (fi *fstatatFileInfo) Name() string       { return fi.name }
+func (fi *fstatatFileInfo) Size() int64        { return fi.size }
+func (fi *fstatatFileInfo) Mode() os.FileMode  { return fi.mode }
+func (fi *fstatatFileInfo) ModTime() time.Time { return fi.modTime }
+func (fi *fstatatFileInfo) IsDir() bool        { return fi.mode.IsDir() }
+func (fi *fstatatFileInfo) Sys() any           { return &fi.stat }
+
+func fileModeFromStat(m uint32) os.FileMode {
+	mode := os.FileMode(m & 0o777)
+	switch m & syscall.S_IFMT {
+	case syscall.S_IFDIR:
+		mode |= os.ModeDir
+	case syscall.S_IFLNK:
+		mode |= os.ModeSymlink
+	case syscall.S_IFIFO:
+		mode |= os.ModeNamedPipe
+	case syscall.S_IFSOCK:
+		mode |= os.ModeSocket
+	case syscall.S_IFBLK:
+		mode |= os.ModeDevice
+	case syscall.S_IFCHR:
+		mode |= os.ModeDevice | os.ModeCharDevice
+	case syscall.S_IFREG:
+		// regular file, no extra bits
+	default:
+		mode |= os.ModeIrregular
+	}
+	if m&syscall.S_ISUID != 0 {
+		mode |= os.ModeSetuid
+	}
+	if m&syscall.S_ISGID != 0 {
+		mode |= os.ModeSetgid
+	}
+	if m&syscall.S_ISVTX != 0 {
+		mode |= os.ModeSticky
+	}
+	return mode
+}
+
+func syscallTimespecFromUnix(t unix.Timespec) syscall.Timespec {
+	return syscall.Timespec{
+		Sec:  t.Sec,
+		Nsec: t.Nsec,
+	}
+}
+
+func syscallStatFromUnix(st unix.Stat_t) syscall.Stat_t {
+	return syscall.Stat_t{
+		Dev:     st.Dev,
+		Ino:     st.Ino,
+		Nlink:   st.Nlink,
+		Mode:    st.Mode,
+		Uid:     st.Uid,
+		Gid:     st.Gid,
+		Rdev:    st.Rdev,
+		Size:    st.Size,
+		Blksize: st.Blksize,
+		Blocks:  st.Blocks,
+		Atim:    syscallTimespecFromUnix(st.Atim),
+		Mtim:    syscallTimespecFromUnix(st.Mtim),
+		Ctim:    syscallTimespecFromUnix(st.Ctim),
+	}
+}
+
+func fstatatNoFollow(dirfd int, name string) (os.FileInfo, error) {
+	var st unix.Stat_t
+	for {
+		err := unix.Fstatat(dirfd, name, &st, unix.AT_SYMLINK_NOFOLLOW)
+		if err == syscall.EINTR {
+			continue
+		}
+		if err != nil {
+			return nil, err
+		}
+		break
+	}
+	// int64 casts are no-ops on amd64 but required for other architectures if the build tag is widened.
+	//nolint:unconvert
+	modTime := time.Unix(int64(st.Mtim.Sec), int64(st.Mtim.Nsec))
+	return &fstatatFileInfo{
+		name:    name,
+		mode:    fileModeFromStat(st.Mode),
+		size:    st.Size,
+		modTime: modTime,
+		stat:    syscallStatFromUnix(st),
+	}, nil
+}
+
+func cloneDirForListStat(fd *os.File) (*os.File, error) {
+	sc, err := fd.SyscallConn()
+	if err != nil {
+		return nil, err
+	}
+	var dupFD int
+	var dupErr error
+	ctrlErr := sc.Control(func(rawfd uintptr) {
+		dupFD, dupErr = unix.FcntlInt(rawfd, unix.F_DUPFD_CLOEXEC, 0)
+	})
+	if ctrlErr != nil {
+		return nil, ctrlErr
+	}
+	if dupErr != nil {
+		return nil, dupErr
+	}
+	return os.NewFile(uintptr(dupFD), fd.Name()), nil
+}
+
+func statDirEntry(entry cachedDirEntry) (os.FileInfo, error) {
+	if entry.statDir == nil {
+		return entry.Info()
+	}
+	sc, err := entry.statDir.SyscallConn()
+	if err != nil {
+		return nil, err
+	}
+	var fi os.FileInfo
+	var fiErr error
+	ctrlErr := sc.Control(func(rawfd uintptr) {
+		fi, fiErr = fstatatNoFollow(int(rawfd), entry.Name())
+	})
+	if ctrlErr != nil {
+		return nil, ctrlErr
+	}
+	return fi, fiErr
+}