Document packWith and unpackWith

Author: Bodigrim

Codec/Archive/Tar/Check/Internal.hs

@@ -67,11 +67,7 @@ import qualified System.FilePath.Posix   as FilePath.Posix
 -- link target. A failure in any entry terminates the sequence of entries with
 -- an error.
 --
-checkSecurity :: MonadThrow m
-              => Maybe LinkTarget  -- ^ OtherEntryType 'K' discovered before the actual entry
-              -> Maybe FilePath    -- ^ OtherEntryType 'L' discovered before the actual entry
-              -> Entry
-              -> m ()
+checkSecurity :: CheckSecurityCallback
 checkSecurity mLink mPath e = do
   let path = fromMaybe (entryPath e) mPath
   check path
@@ -120,6 +116,7 @@ data FileNameError
   = InvalidFileName FilePath
   | AbsoluteFileName FilePath
   | UnsafeLinkTarget FilePath
+  -- ^ @since 0.6.0.0
   deriving (Typeable)
 
 instance Show FileNameError where
@@ -150,12 +147,7 @@ showFileNameError mb_plat err = case err of
 -- Note: This check must be used in conjunction with 'checkSecurity'
 -- (or 'checkPortability').
 --
-checkTarbomb :: MonadThrow m
-             => FilePath
-             -> Maybe LinkTarget  -- ^ OtherEntryType 'K' discovered before the actual entry
-             -> Maybe FilePath    -- ^ OtherEntryType 'L' discovered before the actual entry
-             -> Entry
-             -> m ()
+checkTarbomb :: FilePath -> CheckSecurityCallback
 checkTarbomb expectedTopDir _mLink _mPath entry = do
   case entryContent entry of
     OtherEntryType 'g' _ _ -> pure () --PAX global header
@@ -205,11 +197,7 @@ instance Show TarBombError where
 --   includes characters that are valid in both systems and the \'/\' vs \'\\\'
 --   directory separator conventions.
 --
-checkPortability :: MonadThrow m
-                 => Maybe LinkTarget  -- ^ OtherEntryType 'K' discovered before the actual entry
-                 -> Maybe FilePath    -- ^ OtherEntryType 'L' discovered before the actual entry
-                 -> Entry
-                 -> m ()
+checkPortability :: CheckSecurityCallback
 checkPortability _mLink _mPath entry
   | entryFormat entry `elem` [V7Format, GnuFormat]
   = throwM $ NonPortableFormat (entryFormat entry)

Codec/Archive/Tar/Pack.hs

@@ -68,6 +68,10 @@ pack :: FilePath   -- ^ Base directory
      -> IO [Entry]
 pack = packWith checkSecurity
 
+-- | Like 'pack', but does not perform any sanity/security checks on the input.
+-- You can do so yourself, e.g.: @packWith@ 'checkSecurity' @dir@ @files@.
+--
+-- @since 0.6.0.0
 packWith :: CheckSecurityCallback
          -> FilePath   -- ^ Base directory
          -> [FilePath] -- ^ Files and directories to pack, relative to the base dir

Codec/Archive/Tar/Types.hs

@@ -635,4 +635,13 @@ instance NFData e => NFData (Entries e) where
   rnf  Done       = ()
   rnf (Fail e)    = rnf e
 
-type CheckSecurityCallback = forall m. MonadThrow m => Maybe LinkTarget -> Maybe FilePath -> Entry -> m ()
+-- | @since 0.6.0.0
+type CheckSecurityCallback =
+  forall m.
+     MonadThrow m
+  => Maybe LinkTarget
+  -- ^ OtherEntryType 'K' discovered before the actual entry
+  -> Maybe FilePath
+  -- ^ OtherEntryType 'L' discovered before the actual entry
+  -> Entry
+  -> m ()

Codec/Archive/Tar/Unpack.hs

@@ -76,21 +76,15 @@ import Control.Exception as Exception
 -- part-way.
 --
 -- On its own, this function only checks for security (using 'checkSecurity').
--- You can do other checks by applying checking functions to the 'Entries' that
--- you pass to this function. For example:
---
--- > unpack dir (checkTarbomb expectedDir entries)
---
--- If you care about the priority of the reported errors then you may want to
--- use 'checkSecurity' before 'checkTarbomb' or other checks.
+-- Use 'unpackWith' if you need more checks.
 --
 unpack :: Exception e => FilePath -> Entries e -> IO ()
 unpack = unpackWith checkSecurity
 
 -- | Like 'unpack', but does not perform any sanity/security checks on the tar entries.
--- You can do so yourself, e.g.:
+-- You can do so yourself, e.g.: @unpackRaw@ 'checkSecurity' @dir@ @entries@.
 --
--- > unpackRaw dir (checkPortability . checkSecurity $ entries)
+-- @since 0.6.0.0
 unpackWith :: Exception e => CheckSecurityCallback -> FilePath -> Entries e -> IO ()
 unpackWith secCB baseDir entries = do
   uEntries <- unpackEntries Nothing Nothing [] entries

changelog.md

@@ -17,6 +17,8 @@ See also http://pvp.haskell.org/faq
   * Ignore FAT32 errors when setting modification time
   * Switch to trailer parsing mode only after a full block of `NUL`
   * Drop deprecated `emptyIndex` and `finaliseIndex`
+  * Extend `FileNameError` with `UnsafeLinkTarget` constructor
+  * Add `CheckSecurityCallback`, `packWith`, `unpackWith`
 
 0.5.1.1 Herbert Valerio Riedel <[email protected]> August 2019