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


-- | A super-simple web server framework
--   
--   A super-simple, easy to use web server framework inspired by Scotty.
--   The goals of the project are: (1) Be easy to use (2) Allow graceful
--   exception handling (3) Parse request parameters easily and in a typed
--   manner.
@package webby
@version 1.1.0


module Webby

-- | The main monad transformer stack used in the web-framework.
--   
--   The type of a handler for a request is <tt>WebbyM appEnv ()</tt>. The
--   <tt>appEnv</tt> parameter is used by the web application to store an
--   (read-only) environment. For e.g. it can be used to store a database
--   connection pool.
data WebbyM appEnv a

-- | A route pattern represents logic to match a request to a handler.
data RoutePattern

-- | A route is a pair of a route pattern and a handler.
type Route env = (RoutePattern, WebbyM env ())

-- | Create a route for a user-provided HTTP request method, pattern and
--   handler function.
mkRoute :: Method -> Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a <tt>POST</tt> request method, given the path
--   pattern and handler.
post :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a <tt>GET</tt> request method, given the path
--   pattern and handler.
get :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a <tt>PUT</tt> request method, given the path
--   pattern and handler.
put :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Create a route for a <tt>DELETE</tt> request method, given path
--   pattern and handler.
delete :: Text -> WebbyM appEnv () -> (RoutePattern, WebbyM appEnv ())

-- | Captures are simply extracted path elements in a HashMap
type Captures = HashMap Text Text

-- | Retrieve all path captures
captures :: WebbyM appEnv Captures

-- | Retrieve a particular capture
getCapture :: FromHttpApiData a => Text -> WebbyM appEnv a

-- | Checks if the request contains the given query param
flag :: Text -> WebbyM appEnv Bool

-- | Get the given header value
header :: HeaderName -> WebbyM appEnv (Maybe Text)

-- | Get all the request headers
headers :: WebbyM appEnv [Header]

-- | Parse the request body as a JSON object and return it. Raises
--   <a>WebbyJSONParseError</a> exception if parsing is unsuccessful.
jsonData :: FromJSON a => WebbyM appEnv a

-- | Gets the given query param's value
param :: FromHttpApiData a => Text -> WebbyM appEnv (Maybe a)

-- | Similar to <a>param</a> except that it returns the handler with a '400
--   BadRequest' if the query param is missing.
param_ :: FromHttpApiData a => Text -> WebbyM appEnv a

-- | Get all request query params as a list of key-value pairs
params :: WebbyM appEnv [(Text, Text)]

-- | Get the <a>Request</a> of the handler
request :: WebbyM appEnv Request

-- | Return the raw request body as a lazy bytestring
requestBodyLBS :: WebbyM appEnv LByteString

-- | Returns request body size in bytes
requestBodyLength :: WebbyM appEnv (Maybe Int64)

-- | Returns an action that returns successive chunks of the rquest body.
--   It returns an empty bytestring after the request body is consumed.
getRequestBodyChunkAction :: WebbyM appEnv (WebbyM appEnv ByteString)

-- | Set response status
setStatus :: Status -> WebbyM appEnv ()

-- | Append given header to the response headers
addHeader :: Header -> WebbyM appEnv ()

-- | Similar to <a>addHeader</a> but replaces a header
setHeader :: Header -> WebbyM appEnv ()

-- | Send a binary stream in the response body. Also sets
--   <tt>Content-Type</tt> header to <tt>application/octet-stream</tt>
blob :: ByteString -> WebbyM appEnv ()

-- | Set the body of the response to the JSON encoding of the given value.
--   Also sets <tt>Content-Type</tt> header to <tt>application/json;
--   charset=utf-8</tt>
json :: ToJSON b => b -> WebbyM appEnv ()

-- | Send plain-text in the response body. Also sets <tt>Content-Type</tt>
--   header to <tt>text/plain; charset=utf-8</tt>
text :: Text -> WebbyM appEnv ()

-- | Set the body of the response to a StreamingBody. Doesn't set the
--   <tt>Content-Type</tt> header, so you probably want to do that on your
--   own with <a>setHeader</a>.
stream :: StreamingBody -> WebbyM appEnv ()

-- | Send an image in the response body. Also sets <tt>Content-Type</tt>
--   header to @mimeType e.g. image/svg+xml
image :: ByteString -> MimeType -> WebbyM appEnv ()

-- | Send a binary stream in the response body. Doesn't set
--   <tt>Content-Type</tt> header
raw :: ByteString -> WebbyM appEnv ()

-- | Use this function to create a WAI application. It takes a
--   user/application defined <tt>appEnv</tt> data type and a list of
--   routes. Routes are matched in the given order. If none of the requests
--   match a request, a default 404 response is returned.
mkWebbyApp :: env -> WebbyServerConfig env -> IO Application

-- | The WAI application.
--   
--   Note that, since WAI 3.0, this type is structured in continuation
--   passing style to allow for proper safe resource handling. This was
--   handled in the past via other means (e.g., <tt>ResourceT</tt>). As a
--   demonstration:
--   
--   <pre>
--   app :: Application
--   app req respond = bracket_
--       (putStrLn "Allocating scarce resource")
--       (putStrLn "Cleaning up")
--       (respond $ responseLBS status200 [] "Hello World")
--   </pre>
type Application = Request -> Response -> IO ResponseReceived -> IO ResponseReceived

-- | Holds web server configuration like API routes, handlers and an
--   optional exception handler
data WebbyServerConfig env

-- | Default <tt>WebbyServerConfig</tt> typically used in conjunction with
--   <a>setRoutes</a> and <a>setExceptionHandler</a>
defaultWebbyServerConfig :: WebbyServerConfig env

-- | Sets API routes and their handlers of a <a>WebbyServerConfig</a>
setRoutes :: [Route env] -> WebbyServerConfig env -> WebbyServerConfig env

-- | Sets the exception handler of a <a>WebbyServerConfig</a>
setExceptionHandler :: Exception e => (e -> WebbyM env ()) -> WebbyServerConfig env -> WebbyServerConfig env

-- | Used to return early from an API handler
finish :: WebbyM appEnv a

-- | Various kinds of errors thrown by this library - these can be caught
--   by handler code.
data WebbyError
WebbyJSONParseError :: Text -> WebbyError
WebbyParamParseError :: Text -> Text -> WebbyError
[wppeParamName] :: WebbyError -> Text
[wppeErrMsg] :: WebbyError -> Text
WebbyMissingCapture :: Text -> WebbyError