snap-core-0.5.2: Snap: A Haskell Web Framework (Core)

Snap.Util.FileServe

Contents

- Configuration for directory serving
- File servers
- Deprecated interface

Description

Contains web handlers to serve files from a directory.

Synopsis

- getSafePath :: MonadSnap m => m FilePath
- type MimeMap = Map FilePath ByteString
- type HandlerMap m = Map FilePath (FilePath -> m ())
- data DirectoryConfig m = DirectoryConfig {
  - indexFiles :: [FilePath]
  - indexGenerator :: FilePath -> m ()
  - dynamicHandlers :: HandlerMap m
  - mimeTypes :: MimeMap
  - preServeHook :: FilePath -> m ()
  }
- simpleDirectoryConfig :: MonadSnap m => DirectoryConfig m
- defaultDirectoryConfig :: MonadSnap m => DirectoryConfig m
- fancyDirectoryConfig :: MonadSnap m => DirectoryConfig m
- defaultIndexGenerator :: MonadSnap m => MimeMap -> ByteString -> FilePath -> m ()
- defaultMimeTypes :: MimeMap
- serveDirectory :: MonadSnap m => FilePath -> m ()
- serveDirectoryWith :: MonadSnap m => DirectoryConfig m -> FilePath -> m ()
- serveFile :: MonadSnap m => FilePath -> m ()
- serveFileAs :: MonadSnap m => ByteString -> FilePath -> m ()
- fileServe :: MonadSnap m => FilePath -> m ()
- fileServe' :: MonadSnap m => MimeMap -> FilePath -> m ()
- fileServeSingle :: MonadSnap m => FilePath -> m ()
- fileServeSingle' :: MonadSnap m => ByteString -> FilePath -> m ()

# Documentation

getSafePath :: MonadSnap m => m FilePath

Gets a path from the `Request` using `rqPathInfo` and makes sure it is safe to use for opening files. A path is safe if it is a relative path and has no .. elements to escape the intended directory structure.

# Configuration for directory serving

type MimeMap = Map FilePath ByteString

A type alias for MIME type

type HandlerMap m = Map FilePath (FilePath -> m ())

A type alias for dynamic handlers

data DirectoryConfig m

A collection of options for serving static files out of a directory.

Constructors

DirectoryConfig |

Fields

indexFiles :: [FilePath]

  Files to look for when a directory is requested (e.g., index.html)

indexGenerator :: FilePath -> m ()

  Handler to generate a directory listing if there is no index.

dynamicHandlers :: HandlerMap m

  Map of extensions to pass to dynamic file handlers. This could be used, for example, to implement CGI dispatch, pretty printing of source code, etc.

mimeTypes :: MimeMap

  MIME type map to look up content types.

preServeHook :: FilePath -> m ()

  Handler that is called before a file is served. It will only be called when a file is actually found, not for generated index pages.

simpleDirectoryConfig :: MonadSnap m => DirectoryConfig m

A very simple configuration for directory serving. This configuration uses built-in MIME types from `defaultMimeTypes`, and has no index files, index generator, dynamic file handlers, or `preServeHook`.

defaultDirectoryConfig :: MonadSnap m => DirectoryConfig m

A reasonable default configuration for directory serving. This configuration uses built-in MIME types from `defaultMimeTypes`, serves common index files `index.html` and `index.htm`, but does not autogenerate directory indexes, nor have any dynamic file handlers. The `preServeHook` will not do anything.

fancyDirectoryConfig :: MonadSnap m => DirectoryConfig m

A more elaborate configuration for file serving. This configuration uses built-in MIME types from `defaultMimeTypes`, serves common index files `index.html` and `index.htm`, and autogenerates directory indexes with a Snap-like feel. It still has no dynamic file handlers, nor `preServeHook`, which should be added as needed.

Files recognized as indexes include `index.html`, `index.htm`, `default.html`, `default.htm`, `home.html`

defaultIndexGenerator

Arguments

:: MonadSnap m |
=> MimeMap | MIME type mapping for reporting types
-> ByteString | Style info to insert in header
-> FilePath | Directory to generate index for
-> m () |

An automatic index generator, which is fairly small and does not rely on any external files (which may not be there depending on external request routing).

A `MimeMap` is passed in to display the types of files in the directory listing based on their extension. Preferably, this is the same as the map in the `DirectoryConfig`

The styles parameter allows you to apply styles to the directory listing. The listing itself consists of a table, containing a header row using th elements, and one row per file using td elements, so styles for those pieces may be attached to the appropriate tags.

defaultMimeTypes :: MimeMap

The default set of mime type mappings we use when serving files. Its value:

     Map.fromList [
       ( ".asc"     , "text/plain"                        ),
       ( ".asf"     , "video/x-ms-asf"                    ),
       ( ".asx"     , "video/x-ms-asf"                    ),
       ( ".avi"     , "video/x-msvideo"                   ),
       ( ".bz2"     , "application/x-bzip"                ),
       ( ".c"       , "text/plain"                        ),
       ( ".class"   , "application/octet-stream"          ),
       ( ".conf"    , "text/plain"                        ),
       ( ".cpp"     , "text/plain"                        ),
       ( ".css"     , "text/css"                          ),
       ( ".cxx"     , "text/plain"                        ),
       ( ".dtd"     , "text/xml"                          ),
       ( ".dvi"     , "application/x-dvi"                 ),
       ( ".gif"     , "image/gif"                         ),
       ( ".gz"      , "application/x-gzip"                ),
       ( ".hs"      , "text/plain"                        ),
       ( ".htm"     , "text/html"                         ),
       ( ".html"    , "text/html"                         ),
       ( ".jar"     , "application/x-java-archive"        ),
       ( ".jpeg"    , "image/jpeg"                        ),
       ( ".jpg"     , "image/jpeg"                        ),
       ( ".js"      , "text/javascript"                   ),
       ( ".log"     , "text/plain"                        ),
       ( ".m3u"     , "audio/x-mpegurl"                   ),
       ( ".mov"     , "video/quicktime"                   ),
       ( ".mp3"     , "audio/mpeg"                        ),
       ( ".mpeg"    , "video/mpeg"                        ),
       ( ".mpg"     , "video/mpeg"                        ),
       ( ".ogg"     , "application/ogg"                   ),
       ( ".pac"     , "application/x-ns-proxy-autoconfig" ),
       ( ".pdf"     , "application/pdf"                   ),
       ( ".png"     , "image/png"                         ),
       ( ".ps"      , "application/postscript"            ),
       ( ".qt"      , "video/quicktime"                   ),
       ( ".sig"     , "application/pgp-signature"         ),
       ( ".spl"     , "application/futuresplash"          ),
       ( ".svg"     , "image/svg+xml"                     ),
       ( ".swf"     , "application/x-shockwave-flash"     ),
       ( ".tar"     , "application/x-tar"                 ),
       ( ".tar.bz2" , "application/x-bzip-compressed-tar" ),
       ( ".tar.gz"  , "application/x-tgz"                 ),
       ( ".tbz"     , "application/x-bzip-compressed-tar" ),
       ( ".text"    , "text/plain"                        ),
       ( ".tgz"     , "application/x-tgz"                 ),
       ( ".torrent" , "application/x-bittorrent"          ),
       ( ".txt"     , "text/plain"                        ),
       ( ".wav"     , "audio/x-wav"                       ),
       ( ".wax"     , "audio/x-ms-wax"                    ),
       ( ".wma"     , "audio/x-ms-wma"                    ),
       ( ".wmv"     , "video/x-ms-wmv"                    ),
       ( ".xbm"     , "image/x-xbitmap"                   ),
       ( ".xml"     , "text/xml"                          ),
       ( ".xpm"     , "image/x-xpixmap"                   ),
       ( ".xwd"     , "image/x-xwindowdump"               ),
       ( ".zip"     , "application/zip"                   ) ]

# File servers

serveDirectory

Arguments

:: MonadSnap m |
=> FilePath | Directory to serve from
-> m () |

Serves static files from a directory using the default configuration as given in `defaultDirectoryConfig`.

serveDirectoryWith

Arguments

:: MonadSnap m |
=> DirectoryConfig m | Configuration options
-> FilePath | Directory to serve from
-> m () |

Serves static files from a directory. Configuration options are passed in a `DirectoryConfig` that captures various choices about desired behavior. The relative path given in `rqPathInfo` is searched for a requested file, and the file is served with the appropriate mime type if it is found. Absolute paths and "`..`" are prohibited to prevent files from being served from outside the sandbox.

serveFile

Arguments

:: MonadSnap m |
=> FilePath | path to file
-> m () |

Serves a single file specified by a full or relative path. If the file does not exist, throws an exception (not that it does not pass to the next handler). The path restrictions on `serveDirectory` don't apply to this function since the path is not being supplied by the user.

serveFileAs

Arguments

:: MonadSnap m |
=> ByteString | MIME type
-> FilePath | path to file
-> m () |

Same as `serveFile`, with control over the MIME mapping used.

# Deprecated interface

fileServe

Arguments

:: MonadSnap m |
=> FilePath | root directory
-> m () |

Serves files out of the given directory, using no index files and default MIME types.

The function name is obsolete. You should use `serveDirectory` or `serveDirectoryWith` instead, which do similar things but with more options and clearer, more consistent names.

fileServe'

Arguments

:: MonadSnap m |
=> MimeMap | MIME type mapping
-> FilePath | root directory
-> m () |

Serves files out of the given directory, with a given MIME type mapping.

The function name is obsolete. You should use `serveDirectoryWith` instead, which offers more options and a clearer, more consistent name.

fileServeSingle

Arguments

:: MonadSnap m |
=> FilePath | path to file
-> m () |

Serves a single file specified by a full or relative path. The path restrictions on fileServe don't apply to this function since the path is not being supplied by the user.

The function name is obsolete. You should use `serveFile` instead, which does the same thing but with a clearer, more consistent name.

fileServeSingle'

Arguments

:: MonadSnap m |
=> ByteString | MIME type mapping
-> FilePath | path to file
-> m () |

Same as `fileServeSingle`, with control over the MIME mapping used.

The function name is obsolete. You should use `serveFileAs` instead, which does the same thing but with a clearer, more consistent name.