This module defines the RawM type that allows you to embed a WAI Application in your Servant API.

It is similar to Raw provided by Servant, but there is one big difference. RawM allows you to use monadic effects to create the Application.

What does this look like in practice? The following is an example of using RawM:

  import Servant.RawM.Server

  type Api = "serve-directory-example" :> RawM

  serverRoot :: ServerT Api (ReaderT FilePath IO)
  serverRoot = rawEndpoint

  rawEndpoint :: ReaderT FilePath IO Application
  rawEndpoint = do
    filePath <- ask
    serveDirectoryWebApp filePath

  apiProxy :: Proxy Api
  apiProxy = Proxy

  app :: FilePath -> Application
  app filePath =
    serve apiProxy apiServer
    where
      apiServer :: Server Api
      apiServer = hoistServer apiProxy transformation serverRoot

      transformation :: ReaderT FilePath IO a -> Handler a
      transformation readerT = liftIO $ runReaderT readerT filePath

Notice how the above rawEndpoint handler is able to get the filePath from the ReaderT. Using Servant's default Raw type, rawEndpoint would have to be written like the following:

  type Api' = "serve-directory-example" :> Raw

  serverRoot' :: ServerT Api' (ReaderT FilePath IO)
  serverRoot' = rawEndpoint'

  rawEndpoint' :: Tagged (ReaderT FilePath IO) Application
  rawEndpoint' = ...

rawEndpoint' does not have access to the ReaderT monad, so there is no way to get the directory path.

RawM solves this problem by allowing the Application to be produced monadically.

There is an example in the source code repository that shows a more in-depth server, client, and documentation.

After servant-rawm 1.0.0.0, the implementations for RawM server, client, and documentation generator are divided into three packages: servant-rawm-server, servant-rawm-client, and servant-rawm-docs to avoid pulling in unnecessary dependencies. This module is re-exported in Servant.RawM.Server, Servant.RawM.Client, and Servant.RawM.Docs, so you don't need to import this module explicitly. Import the corresponding implementation instead.