-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Embed a raw 'Application' in a Servant API
--   
--   Please see <a>README.md</a>.
@package servant-rawm
@version 0.3.0.0


module Servant.RawM.Internal.API

-- | Specialization of <a>RawM'</a> to <a>FileServer</a>. This can be used
--   if you are using <a>serveDirectoryWebApp</a>,
--   <a>serveDirectoryFileServer</a>, etc.
type RawM = RawM' FileServer

-- | This is a type to use to define a Servant API. It signifies a route
--   that allows embedding of a WAI <a>Application</a>. It is similar to
--   <a>Raw</a>, but it has a <a>HasServer</a> instance that allows
--   embedding of monadic effects. This should be more convenient than
--   <a>Raw</a>.
--   
--   The phantom type <tt>serverType</tt> is used for defining the
--   <a>HasDocs</a> instance. There are instances for <a>HasClient</a> and
--   <a>HasServer</a> for <a>RawM'</a> with a polymorphic phantom type, but
--   there is only a <a>HasDocs</a> instance specified for <tt><a>RawM'</a>
--   <a>FileServer</a></tt>. This allows the end-user to easily create a
--   <a>HasDocs</a> instance for a custom <a>Application</a>.
data RawM' serverType

-- | Used by <a>RawM</a> as a phantom type.
data FileServer


-- | This module only exports a <a>HasClient</a> instance for
--   <tt>RawM</tt>.
module Servant.RawM.Internal.Client
instance Servant.Client.Core.Internal.RunClient.RunClient m => Servant.Client.Core.Internal.HasClient.HasClient m (Servant.RawM.Internal.API.RawM' serverType)


-- | This module exports a <a>HasDocs</a> instance for <tt>RawM</tt>.
module Servant.RawM.Internal.Docs
instance Servant.Docs.Internal.HasDocs serverType => Servant.Docs.Internal.HasDocs (Servant.RawM.Internal.API.RawM' serverType)
instance Servant.Docs.Internal.HasDocs Servant.RawM.Internal.API.FileServer


-- | This module exports <a>HasServer</a> instances for <a>RawM'</a>, as
--   well as some helper functions for serving directories of files.
module Servant.RawM.Internal.Server

-- | Serve anything under the specified directory as a <a>RawM'</a>
--   endpoint.
--   
--   <pre>
--   type MyApi = "static" :&gt; RawM'
--   
--   server :: ServerT MyApi m
--   server = serveDirectoryWebApp "/var/www"
--   </pre>
--   
--   would capture any request to <tt>/static/&lt;something&gt;</tt> and
--   look for <tt>&lt;something&gt;</tt> under <tt>/var/www</tt>.
--   
--   It will do its best to guess the MIME type for that file, based on the
--   extension, and send an appropriate <i>Content-Type</i> header if
--   possible.
--   
--   If your goal is to serve HTML, CSS and Javascript files that use the
--   rest of the API as a webapp backend, you will most likely not want the
--   static files to be hidden behind a <i>/static/</i> prefix. In that
--   case, remember to put the <a>serveDirectoryWebApp</a> handler in the
--   last position, because <i>servant</i> will try to match the handlers
--   in order.
--   
--   Corresponds to the <a>defaultWebAppSettings</a> <a>StaticSettings</a>
--   value.
serveDirectoryWebApp :: Applicative m => FilePath -> ServerT (RawM' serverType) m

-- | Same as <a>serveDirectoryWebApp</a>, but uses
--   <a>defaultFileServerSettings</a>.
serveDirectoryFileServer :: Applicative m => FilePath -> ServerT (RawM' serverType) m

-- | Same as <a>serveDirectoryWebApp</a>, but uses
--   <a>webAppSettingsWithLookup</a>.
serveDirectoryWebAppLookup :: Applicative m => ETagLookup -> FilePath -> ServerT (RawM' serverType) m

-- | Uses <a>embeddedSettings</a>.
serveDirectoryEmbedded :: Applicative m => [(FilePath, ByteString)] -> ServerT (RawM' serverType) m

-- | Alias for <a>staticApp</a>. Lets you serve a directory with arbitrary
--   <a>StaticSettings</a>. Useful when you want particular settings not
--   covered by the four other variants. This is the most flexible method.
serveDirectoryWith :: Applicative m => StaticSettings -> ServerT (RawM' serverType) m
instance Servant.Server.Internal.HasServer (Servant.RawM.Internal.API.RawM' serverType) context


-- | Export all of the instances for the Client, Docs, and Server.
module Servant.RawM.Internal


-- | This module exposes a <a>RawM</a> type that allows you to embed a WAI
--   <a>Application</a> in your Servant API.
--   
--   It is similar to <a>Raw</a> provided by Servant, but there is one big
--   difference. <a>RawM</a> allows you to use monadic effects to create
--   the <a>Application</a>.
--   
--   What does this look like in practice? The following is an example of
--   using <a>RawM</a>:
--   
--   <pre>
--   type Api = "serve-directory-example" :&gt; <a>RawM</a>
--   
--   serverRoot :: <a>ServerT</a> Api (<a>ReaderT</a> <a>FilePath</a> <a>IO</a>)
--   serverRoot = rawEndpoint
--   
--   rawEndpoint :: <a>ReaderT</a> <a>FilePath</a> <a>IO</a> <a>Application</a>
--   rawEndpoint = do
--     filePath &lt;- <a>ask</a>
--     <a>serveDirectoryWebApp</a> filePath
--   
--   apiProxy :: <a>Proxy</a> Api
--   apiProxy = <a>Proxy</a>
--   
--   app :: FilePath -&gt; <a>Application</a>
--   app filePath =
--     <a>serve</a> apiProxy apiServer
--     where
--       apiServer :: <a>Server</a> Api
--       apiServer = <a>hoistServer</a> apiProxy transformation serverRoot
--   
--       transformation :: <a>ReaderT</a> <a>FilePath</a> <a>IO</a> a -&gt; <a>Handler</a> a
--       transformation readerT = <a>liftIO</a> $ <a>runReaderT</a> readerT filePath
--   </pre>
--   
--   Notice how the above <tt>rawEndpoint</tt> handler is able to get the
--   <tt>filePath</tt> from the <a>ReaderT</a>. Using Servant's default
--   <a>Raw</a> type, <tt>rawEndpoint</tt> would have to be written like
--   the following:
--   
--   <pre>
--   type Api' = "serve-directory-example" :&gt; <tt>Raw</tt>
--   
--   serverRoot' :: <a>ServerT</a> Api' (<a>ReaderT</a> <a>FilePath</a> <a>IO</a>)
--   serverRoot' = rawEndpoint'
--   
--   rawEndpoint' :: <a>Tagged</a> (<a>ReaderT</a> <a>FilePath</a> <a>IO</a>) <a>Application</a>
--   rawEndpoint' = ...
--   </pre>
--   
--   <tt>rawEndpoint'</tt> does not have access to the <a>ReaderT</a>
--   monad, so there is no way to get the directory path.
--   
--   <a>RawM</a> solves this problem by allowing the <a>Application</a> to
--   be produced monadically.
--   
--   There is an <a>example</a> in the source code repository that shows a
--   more in-depth server, client, and documentation.
module Servant.RawM

-- | Specialization of <a>RawM'</a> to <a>FileServer</a>. This can be used
--   if you are using <a>serveDirectoryWebApp</a>,
--   <a>serveDirectoryFileServer</a>, etc.
type RawM = RawM' FileServer

-- | This is a type to use to define a Servant API. It signifies a route
--   that allows embedding of a WAI <a>Application</a>. It is similar to
--   <a>Raw</a>, but it has a <a>HasServer</a> instance that allows
--   embedding of monadic effects. This should be more convenient than
--   <a>Raw</a>.
--   
--   The phantom type <tt>serverType</tt> is used for defining the
--   <a>HasDocs</a> instance. There are instances for <a>HasClient</a> and
--   <a>HasServer</a> for <a>RawM'</a> with a polymorphic phantom type, but
--   there is only a <a>HasDocs</a> instance specified for <tt><a>RawM'</a>
--   <a>FileServer</a></tt>. This allows the end-user to easily create a
--   <a>HasDocs</a> instance for a custom <a>Application</a>.
data RawM' serverType

-- | Used by <a>RawM</a> as a phantom type.
data FileServer

-- | Serve anything under the specified directory as a <a>RawM'</a>
--   endpoint.
--   
--   <pre>
--   type MyApi = "static" :&gt; RawM'
--   
--   server :: ServerT MyApi m
--   server = serveDirectoryWebApp "/var/www"
--   </pre>
--   
--   would capture any request to <tt>/static/&lt;something&gt;</tt> and
--   look for <tt>&lt;something&gt;</tt> under <tt>/var/www</tt>.
--   
--   It will do its best to guess the MIME type for that file, based on the
--   extension, and send an appropriate <i>Content-Type</i> header if
--   possible.
--   
--   If your goal is to serve HTML, CSS and Javascript files that use the
--   rest of the API as a webapp backend, you will most likely not want the
--   static files to be hidden behind a <i>/static/</i> prefix. In that
--   case, remember to put the <a>serveDirectoryWebApp</a> handler in the
--   last position, because <i>servant</i> will try to match the handlers
--   in order.
--   
--   Corresponds to the <a>defaultWebAppSettings</a> <a>StaticSettings</a>
--   value.
serveDirectoryWebApp :: Applicative m => FilePath -> ServerT (RawM' serverType) m

-- | Same as <a>serveDirectoryWebApp</a>, but uses
--   <a>defaultFileServerSettings</a>.
serveDirectoryFileServer :: Applicative m => FilePath -> ServerT (RawM' serverType) m

-- | Same as <a>serveDirectoryWebApp</a>, but uses
--   <a>webAppSettingsWithLookup</a>.
serveDirectoryWebAppLookup :: Applicative m => ETagLookup -> FilePath -> ServerT (RawM' serverType) m

-- | Uses <a>embeddedSettings</a>.
serveDirectoryEmbedded :: Applicative m => [(FilePath, ByteString)] -> ServerT (RawM' serverType) m

-- | Alias for <a>staticApp</a>. Lets you serve a directory with arbitrary
--   <a>StaticSettings</a>. Useful when you want particular settings not
--   covered by the four other variants. This is the most flexible method.
serveDirectoryWith :: Applicative m => StaticSettings -> ServerT (RawM' serverType) m
