Rename and document ReadOptions for readdir

Author: harendra-kumar

core/src/Streamly/FileSystem/DirIO.hs

@@ -22,9 +22,9 @@ module Streamly.FileSystem.DirIO
 #else
       ReadOptions
     , followSymlinks
-    , ignoreNonExisting
-    , ignoreLoopErrors
-    , ignoreInAccessible
+    , ignoreMissing
+    , ignoreSymlinkLoops
+    , ignoreInaccessible
 #endif
     -- * Streams
     , read

core/src/Streamly/Internal/FileSystem/DirIO.hs

@@ -85,9 +85,9 @@ module Streamly.Internal.FileSystem.DirIO
     , defaultReadOptions
 #if !defined(mingw32_HOST_OS) && !defined(__MINGW32__)
     , followSymlinks
-    , ignoreNonExisting
-    , ignoreLoopErrors
-    , ignoreInAccessible
+    , ignoreMissing
+    , ignoreSymlinkLoops
+    , ignoreInaccessible
 #endif
 
     -- * Streams
@@ -161,7 +161,7 @@ import Streamly.Internal.FileSystem.Windows.ReadDir
 #else
 import Streamly.Internal.FileSystem.Posix.ReadDir
     ( readEitherChunks, eitherReader, reader, ReadOptions, defaultReadOptions
-    , followSymlinks, ignoreNonExisting, ignoreLoopErrors, ignoreInAccessible
+    , followSymlinks, ignoreMissing, ignoreSymlinkLoops, ignoreInaccessible
     )
 #endif
 import qualified Streamly.Internal.Data.Stream as S

core/src/Streamly/Internal/FileSystem/Posix/ReadDir.hsc

@@ -11,9 +11,9 @@ module Streamly.Internal.FileSystem.Posix.ReadDir
 #if !defined(mingw32_HOST_OS) && !defined(__MINGW32__)
       ReadOptions
     , followSymlinks
-    , ignoreNonExisting
-    , ignoreLoopErrors
-    , ignoreInAccessible
+    , ignoreMissing
+    , ignoreSymlinkLoops
+    , ignoreInaccessible
     , defaultReadOptions
 
     , readScanWith_
@@ -79,35 +79,101 @@ data {-# CTYPE "struct stat" #-} CStat
 
 newtype DirStream = DirStream (Ptr CDir)
 
+-- NOTE: If we are following symlinks, then we want to determine the type of
+-- the link destination not the link itself, so we need to use stat instead of
+-- lstat for resolving the symlink.
+--
+-- For recursive traversal, instead of classifying the dirents using stat, we
+-- can leave them unclassified, and deal with ENOTDIR when doing an opendir. We
+-- can just ignore that error if it is not a dir. This way we do not need to do
+-- stat at all. Or we can basically say don't try to determine the type of
+-- symlinks and always try to read symlinks as dirs. We can have an option for
+-- classifying symlinks or DT_UNKNOWN as potential dirs.
+
+-- When resolving a symlink we may encounter errors only if the directory entry
+-- is a symlink. If the directory entry is not a symlink then stat on it will
+-- have permissions, it will not give ELOOP or ENOENT unless the file was
+-- deleted or recreated after we read the dirent.
+
+-- | Options controlling the behavior of directory read.
 data ReadOptions =
     ReadOptions
     { _followSymlinks :: Bool
-    , _ignoreSymlinkLoopErrors :: Bool
-    , _ignoreNonExistingFiles :: Bool
-    , _ignoreInAccessibleFiles :: Bool
+    , _ignoreELOOP :: Bool
+    , _ignoreENOENT :: Bool
+    , _ignoreEACCESS :: Bool
     }
 
+-- | Control how symbolic links are handled when determining the type
+-- of a directory entry.
+--
+-- * If set to 'True', symbolic links are resolved before classification.
+--   This means a symlink pointing to a directory will be treated as a
+--   directory, and a symlink pointing to a file will be treated as a
+--   non-directory.
+--
+-- * If set to 'False', all symbolic links are classified as non-directories,
+--   without attempting to resolve their targets.
+--
+-- Enabling resolution may cause additional errors to occur due to
+-- insufficient permissions, broken links, or symlink loops. Such errors
+-- can be ignored or handled using the appropriate options.
+--
+-- The default is 'False'.
+--
+-- On Windows this option does nothing as of now, symlinks are not followed to
+-- determine the type.
 followSymlinks :: Bool -> ReadOptions -> ReadOptions
 followSymlinks x opts = opts {_followSymlinks = x}
 
-ignoreLoopErrors :: Bool -> ReadOptions -> ReadOptions
-ignoreLoopErrors x opts = opts {_ignoreSymlinkLoopErrors = x}
-
-ignoreNonExisting :: Bool -> ReadOptions -> ReadOptions
-ignoreNonExisting x opts = opts {_ignoreNonExistingFiles = x}
-
-ignoreInAccessible :: Bool -> ReadOptions -> ReadOptions
-ignoreInAccessible x opts = opts {_ignoreInAccessibleFiles = x}
+-- | When the 'followSymlinks' option is enabled and a directory entry is a
+-- symbolic link, we resolve it to determine the type of the symlink target.
+-- This option controls the behavior when encountering symlink loop errors
+-- during resolution.
+--
+-- When set to 'True', symlink loop errors are ignored, and the type is
+-- reported as not a directory. When set to 'False', the directory read
+-- operation fails with an error.
+--
+-- The default is 'False'.
+ignoreSymlinkLoops :: Bool -> ReadOptions -> ReadOptions
+ignoreSymlinkLoops x opts = opts {_ignoreELOOP = x}
+
+-- | When the 'followSymlinks' option is enabled and a directory entry is a
+-- symbolic link, we resolve it to determine the type of the symlink target.
+-- This option controls the behavior when encountering broken symlink errors
+-- during resolution.
+--
+-- When set to 'True', broken symlink errors are ignored, and the type is
+-- reported as not a directory. When set to 'False', the directory read
+-- operation fails with an error.
+--
+-- The default is 'False'.
+ignoreMissing :: Bool -> ReadOptions -> ReadOptions
+ignoreMissing x opts = opts {_ignoreENOENT = x}
+
+-- | When the 'followSymlinks' option is enabled and a directory entry is a
+-- symbolic link, we resolve it to determine the type of the symlink target.
+-- This option controls the behavior when encountering permission errors
+-- during resolution.
+--
+-- When set to 'True', any permission errors are ignored, and the type is
+-- reported as not a directory. When set to 'False', the directory read
+-- operation fails with an error.
+--
+-- The default is 'False'.
+ignoreInaccessible :: Bool -> ReadOptions -> ReadOptions
+ignoreInaccessible x opts = opts {_ignoreEACCESS = x}
 
 -- NOTE: The defaultReadOptions emulate the behaviour of "find".
 --
 defaultReadOptions :: ReadOptions
 defaultReadOptions =
     ReadOptions
     { _followSymlinks = False
-    , _ignoreSymlinkLoopErrors = False
-    , _ignoreNonExistingFiles = False
-    , _ignoreInAccessibleFiles = False
+    , _ignoreELOOP = False
+    , _ignoreENOENT = False
+    , _ignoreEACCESS = False
     }
 
 -- | Minimal read without any metadata.
@@ -305,13 +371,13 @@ statEntryType conf parent dname = do
                 else EntryIsNotDir
             Left errno -> do
                 if errno == eNOENT
-                then unless (_ignoreNonExistingFiles conf) $
+                then unless (_ignoreENOENT conf) $
                          throwErrno (errMsg path)
                 else if errno == eACCES
-                then unless (_ignoreInAccessibleFiles conf) $
+                then unless (_ignoreEACCESS conf) $
                          throwErrno (errMsg path)
                 else if errno == eLOOP
-                then unless (_ignoreSymlinkLoopErrors conf) $
+                then unless (_ignoreELOOP conf) $
                          throwErrno (errMsg path)
                 else throwErrno (errMsg path)
                 pure $ EntryIgnored

core/src/Streamly/Internal/FileSystem/Windows/ReadDir.hsc

@@ -206,6 +206,13 @@ readDirStreamEither _ (DirStream (h, ref, fdata)) =
 
     where
 
+    -- XXX: for a symlink the attribute may have a FILE_ATTRIBUTE_DIRECTORY if
+    -- the symlink was created as a directory symlink, but it might have
+    -- changed later. To find the real type of the symlink when we have
+    -- followSymlinks option on we need to check if it is a
+    -- FILE_ATTRIBUTE_REPARSE_POINT, we need to open the reparse point and find
+    -- the type.
+
     processEntry ptr = do
         let dname = #{ptr WIN32_FIND_DATAW, cFileName} ptr
         dattrs :: #{type DWORD} <-

test/Streamly/Test/FileSystem/DirIO.hs

@@ -118,13 +118,13 @@ testSymLinkFollow = do
             testCorrectness
                 sortedAnswerFollowSym
                 (listDirUnfoldDfs
-                     (Dir.followSymlinks True . Dir.ignoreNonExisting True)
+                     (Dir.followSymlinks True . Dir.ignoreMissing True)
                      fp)
         it "followSymlinks False" $
             testCorrectness
                 sortedAnswerNoFollowSym
                 (listDirUnfoldDfs
-                     (Dir.followSymlinks False . Dir.ignoreNonExisting True)
+                     (Dir.followSymlinks False . Dir.ignoreMissing True)
                      fp)
 
 -- | List the current directory recursively