Documentation

[Lucu.git] / Network / HTTP / Lucu / StaticFile.hs

diff --git a/Network/HTTP/Lucu/StaticFile.hs b/Network/HTTP/Lucu/StaticFile.hs
index 7937af9b6fee02996136d7335664f921af0c6932..e710fc90ec62beb0e9cf22164a5c65c92d134b9a 100644 (file)
--- a/Network/HTTP/Lucu/StaticFile.hs
+++ b/Network/HTTP/Lucu/StaticFile.hs
@@ -1,9 +1,11 @@
 module Network.HTTP.Lucu.StaticFile
-    ( staticFile       -- FilePath -> ResourceDef
-    , handleStaticFile -- FilePath -> Resource ()
+    ( staticFile
+    , handleStaticFile
 
-    , staticDir       -- FilePath -> ResourceDef
-    , handleStaticDir -- FilePath -> Resource ()
+    , staticDir
+    , handleStaticDir
+
+    , generateETagFromFile
     )
     where
 
@@ -68,7 +70,18 @@ handleStaticFile path
                     foundNoEntity Nothing
 
 
--- inode-size-lastmod
+-- |Computation @'generateETagFromFile' fpath@ generates a strong
+-- entity tag from a file. The file doesn't necessarily have to be a
+-- regular file; it may be a FIFO or a device file. The tag is made of
+-- inode ID, size and modification time.
+--
+-- Note that the tag is not strictly strong because the file could be
+-- modified twice at a second without changing inode ID or size, but
+-- it's not really possible to generate a strict strong ETag from a
+-- file since we don't want to simply grab the entire file and use it
+-- as an ETag. It is indeed possible to hash it with SHA-1 or MD5 to
+-- increase strictness, but it's too inefficient if the file is really
+-- large (say, 1 TiB).
 generateETagFromFile :: FilePath -> IO ETag
 generateETagFromFile path
     = do stat <- getFileStatus path