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


-- | Another Haskell web toolkit based on scotty
--   
@package Spock
@version 0.4.3.2

module Web.Spock

-- | Run a spock application using the warp server, a given db storageLayer
--   and an initial state. Spock works with database libraries that already
--   implement connection pooling and with those that don't come with it
--   out of the box. For more see the <a>PoolOrConn</a> type.
spock :: Int -> SessionCfg sess -> PoolOrConn conn -> st -> SpockM conn sess st () -> IO ()

-- | Spock is supercharged Scotty, that's why the <a>SpockM</a> is built on
--   the ScottyT monad. Insive the SpockM monad, you may define routes and
--   middleware.
type SpockM conn sess st a = ScottyT Text (WebStateM conn sess st) a

-- | The SpockAction is the monad of all route-actions. You have access to
--   the database, session and state of your application.
type SpockAction conn sess st a = ActionT Text (WebStateM conn sess st) a

-- | You can feed Spock with either a connection pool, or instructions on
--   how to build a connection pool. See <a>ConnBuilder</a>
data PoolOrConn a
PCPool :: (Pool a) -> PoolOrConn a
PCConduitPool :: (Pool a) -> PoolOrConn a
PCConn :: (ConnBuilder a) -> PoolOrConn a

-- | The ConnBuilder instructs Spock how to create or close a database
--   connection.
data ConnBuilder a
ConnBuilder :: IO a -> (a -> IO ()) -> PoolCfg -> ConnBuilder a
cb_createConn :: ConnBuilder a -> IO a
cb_destroyConn :: ConnBuilder a -> a -> IO ()
cb_poolConfiguration :: ConnBuilder a -> PoolCfg

-- | If Spock should take care of connection pooling, you need to configure
--   it depending on what you need.
data PoolCfg
PoolCfg :: Int -> Int -> NominalDiffTime -> PoolCfg
pc_stripes :: PoolCfg -> Int
pc_resPerStripe :: PoolCfg -> Int
pc_keepOpenTime :: PoolCfg -> NominalDiffTime
class HasSpock m
runQuery :: HasSpock m => (SpockConn m -> IO a) -> m a
getState :: HasSpock m => m (SpockState m)

-- | Configuration for the session manager
data SessionCfg a
SessionCfg :: Text -> NominalDiffTime -> Int -> a -> SessionCfg a
sc_cookieName :: SessionCfg a -> Text
sc_sessionTTL :: SessionCfg a -> NominalDiffTime
sc_sessionIdEntropy :: SessionCfg a -> Int
sc_emptySession :: SessionCfg a -> a

-- | Read the stored session
readSession :: SpockAction conn sess st sess

-- | Write to the current session. Note that all data is stored on the
--   server. The user only reciedes a sessionId to be identified.
writeSession :: sess -> SpockAction conn sess st ()

-- | Modify the stored session
modifySession :: (sess -> sess) -> SpockAction conn sess st ()

-- | Set a cookie living for a given number of seconds
setCookie :: (SpockError e, MonadIO m) => Text -> Text -> NominalDiffTime -> ActionT e m ()

-- | Set a cookie living until a specific <a>UTCTime</a>
setCookie' :: (SpockError e, MonadIO m) => Text -> Text -> UTCTime -> ActionT e m ()

-- | Read a cookie previously set in the users browser for your site
getCookie :: (SpockError e, MonadIO m) => Text -> ActionT e m (Maybe Text)

-- | SafeActions are actions that need to be protected from csrf attacks
class (Hashable a, Eq a, Typeable a) => SafeAction a
runSafeAction :: SafeAction a => a -> SpockAction conn sess st ()

-- | Wire up a safe action: Safe actions are actions that are protected
--   from csrf attacks. Here's a usage example:
--   
--   <pre>
--   newtype DeleteUser = DeleteUser Int deriving (Hashable, Typeable, Eq)
--   
--   instance SafeAction DeleteUser where
--      runSafeAction (DeleteUser i) =
--         do runQuery $ deleteUserFromDb i
--            redirect "/user-list"
--   
--   get "/user-details/:userId" $
--     do userId &lt;- param "userId"
--        deleteUrl &lt;- safeActionPath (DeleteUser userId)
--        html $ TL.concat [ "Click &lt;a href='", TL.fromStrict deleteUrl, "'&gt;here&lt;/a&gt; to delete user!" ]
--   </pre>
--   
--   Note that safeActions currently only support GET and POST requests.
safeActionPath :: SafeAction a => a -> SpockAction conn sess st Text

-- | get = <a>addroute</a> <a>GET</a>
get :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | post = <a>addroute</a> <a>POST</a>
post :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | put = <a>addroute</a> <a>PUT</a>
put :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | delete = <a>addroute</a> <a>DELETE</a>
delete :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | patch = <a>addroute</a> <a>PATCH</a>
patch :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | Define a route with a <a>StdMethod</a>, <a>Text</a> value representing
--   the path spec, and a body (<tt>Action</tt>) which modifies the
--   response.
--   
--   <pre>
--   addroute GET "/" $ text "beam me up!"
--   </pre>
--   
--   The path spec can include values starting with a colon, which are
--   interpreted as <i>captures</i>. These are named wildcards that can be
--   looked up with <a>param</a>.
--   
--   <pre>
--   addroute GET "/foo/:bar" $ do
--       v &lt;- param "bar"
--       text v
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; curl http://localhost:3000/foo/something
--   something
--   </pre>
addroute :: (ScottyError e, MonadIO m) => StdMethod -> RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | HTTP standard method (as defined by RFC 2616, and PATCH which is
--   defined by RFC 5789).
data StdMethod :: *
GET :: StdMethod
POST :: StdMethod
HEAD :: StdMethod
PUT :: StdMethod
DELETE :: StdMethod
TRACE :: StdMethod
CONNECT :: StdMethod
OPTIONS :: StdMethod
PATCH :: StdMethod

-- | Use given middleware. Middleware is nested such that the first
--   declared is the outermost middleware (it has first dibs on the request
--   and last action on the response). Every middleware is run on each
--   request.
middleware :: Monad m => Middleware -> ScottyT e m ()

-- | Add a route that matches regardless of the HTTP verb.
matchAny :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m ()

-- | Specify an action to take if nothing else is found. Note: this
--   _always_ matches, so should generally be the last route specified.
notFound :: (ScottyError e, MonadIO m) => ActionT e m () -> ScottyT e m ()

-- | Get the <a>Request</a> object.
request :: (ScottyError e, Monad m) => ActionT e m Request

-- | Get a request header. Header name is case-insensitive. (Deprecated in
--   favor of <a>header</a>.)
reqHeader :: (ScottyError e, Monad m) => Text -> ActionT e m (Maybe Text)

-- | Get the request body.
body :: (ScottyError e, Monad m) => ActionT e m ByteString

-- | Get a parameter. First looks in captures, then form data, then query
--   parameters.
--   
--   <ul>
--   <li>Raises an exception which can be caught by <a>rescue</a> if
--   parameter is not found.</li>
--   <li>If parameter is found, but <a>read</a> fails to parse to the
--   correct type, <a>next</a> is called. This means captures are somewhat
--   typed, in that a route won't match if a correctly typed capture cannot
--   be parsed.</li>
--   </ul>
param :: (Parsable a, ScottyError e, Monad m) => Text -> ActionT e m a

-- | Get all parameters from capture, form and query (in that order).
params :: (ScottyError e, Monad m) => ActionT e m [Param]

-- | Parse the request body as a JSON object and return it. Raises an
--   exception if parse is unsuccessful.
jsonData :: (FromJSON a, ScottyError e, Monad m) => ActionT e m a

-- | Get list of uploaded files.
files :: (ScottyError e, Monad m) => ActionT e m [File]

-- | Set the HTTP response status. Default is 200.
status :: (ScottyError e, Monad m) => Status -> ActionT e m ()

-- | Add to the response headers. Header names are case-insensitive.
addHeader :: (ScottyError e, Monad m) => Text -> Text -> ActionT e m ()

-- | Set one of the response headers. Will override any previously set
--   value for that header. Header names are case-insensitive.
setHeader :: (ScottyError e, Monad m) => Text -> Text -> ActionT e m ()

-- | Redirect to given URL. Like throwing an uncatchable exception. Any
--   code after the call to redirect will not be run.
--   
--   <pre>
--   redirect "http://www.google.com"
--   </pre>
--   
--   OR
--   
--   <pre>
--   redirect "/foo/bar"
--   </pre>
redirect :: (ScottyError e, Monad m) => Text -> ActionT e m a

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/plain".
text :: (ScottyError e, Monad m) => Text -> ActionT e m ()

-- | Set the body of the response to the given <a>Text</a> value. Also sets
--   "Content-Type" header to "text/html".
html :: (ScottyError e, Monad m) => Text -> ActionT e m ()

-- | Send a file as the response. Doesn't set the "Content-Type" header, so
--   you probably want to do that on your own with <a>setHeader</a>.
file :: (ScottyError e, Monad m) => FilePath -> ActionT e m ()

-- | Set the body of the response to the JSON encoding of the given value.
--   Also sets "Content-Type" header to "application/json".
json :: (ToJSON a, ScottyError e, Monad m) => a -> ActionT e m ()

-- | Set the body of the response to a Source. Doesn't set the
--   "Content-Type" header, so you probably want to do that on your own
--   with <a>setHeader</a>.
source :: (ScottyError e, Monad m) => Source IO (Flush Builder) -> ActionT e m ()

-- | Set the body of the response to the given <a>ByteString</a> value.
--   Doesn't set the "Content-Type" header, so you probably want to do that
--   on your own with <a>setHeader</a>.
raw :: (ScottyError e, Monad m) => ByteString -> ActionT e m ()

-- | Throw an exception, which can be caught with <a>rescue</a>. Uncaught
--   exceptions turn into HTTP 500 responses.
raise :: (ScottyError e, Monad m) => e -> ActionT e m a

-- | Catch an exception thrown by <a>raise</a>.
--   
--   <pre>
--   raise "just kidding" `rescue` (\msg -&gt; text msg)
--   </pre>
rescue :: (ScottyError e, Monad m) => ActionT e m a -> (e -> ActionT e m a) -> ActionT e m a

-- | Abort execution of this action and continue pattern matching routes.
--   Like an exception, any code after <a>next</a> is not executed.
--   
--   As an example, these two routes overlap. The only way the second one
--   will ever run is if the first one calls <a>next</a>.
--   
--   <pre>
--   get "/foo/:bar" $ do
--     w :: Text &lt;- param "bar"
--     unless (w == "special") next
--     text "You made a request to /foo/special"
--   
--   get "/foo/:baz" $ do
--     w &lt;- param "baz"
--     text $ "You made a request to: " &lt;&gt; w
--   </pre>
next :: (ScottyError e, Monad m) => ActionT e m a
data RoutePattern :: *

-- | Same as "param", but the target type needs to implement
--   <a>PathPiece</a>
paramPathPiece :: PathPiece s => Text -> SpockAction conn sess st s

-- | Read the heart of Spock. This is useful if you want to construct your
--   own monads that work with runQuery and getState using "runSpockIO"
getSpockHeart :: MonadTrans t => t (WebStateM conn sess st) (WebState conn sess st)

-- | Run an action inside of Spocks core monad. This allows you to use
--   runQuery and getState
runSpockIO :: WebState conn sess st -> WebStateM conn sess st a -> IO a
data WebStateM conn sess st a
data WebState conn sess st