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


-- | Composable, type-safe library to build HTTP API servers
--   
--   WebGear is a library to for building composable, type-safe HTTP API
--   servers. WebGear focuses on good documentation and usability. See the
--   documentation of WebGear module to get started.
@package webgear-server
@version 0.1.0


-- | Traits are optional attributes that a value might posess. For example,
--   a list containing totally ordered values might have a <tt>Maximum</tt>
--   trait where the associated attribute is the maximum value. The trait
--   exists only if the list is non-empty.
--   
--   Traits help to access these attributes in a type-safe manner.
--   
--   Traits are somewhat similar to <a>refinement types</a>, but allow
--   arbitrary attributes to be associated with a value instead of only a
--   predicate.
module WebGear.Trait

-- | A <a>Trait</a> is an optional attribute <tt>t</tt> associated with a
--   value <tt>a</tt>.
--   
--   The <a>check</a> function validates the presence of the trait for a
--   given value. Checking the presence of the trait can optionally modify
--   the value as well.
class Monad m => Trait t a m where {
    
    -- | Type of the associated attribute
    type family Val t a;
    
    -- | Type of check failures
    type family Fail t a;
}

-- | Checks the presence of the associated attribute.
check :: Trait t a m => a -> m (CheckResult t a)

-- | Result of a <a>check</a> operation
data CheckResult t a
CheckSuccess :: a -> Val t a -> CheckResult t a
CheckFail :: Fail t a -> CheckResult t a

-- | A value linked with a type-level list of traits.
data Linked (ts :: [Type]) a

-- | Constraint for functions that use multiple traits
type family Traits ts a m :: Constraint

-- | Link a value with the trivial trait
linkzero :: a -> Linked '[] a

-- | Attempt to link an additional trait with an already linked value
linkplus :: Trait t a m => Linked ts a -> m (Either (Fail t a) (Linked (t : ts) a))

-- | Remove the leading trait from the linked value
linkminus :: Linked (t : ts) a -> Linked ts a

-- | Retrive the value from a linked value
unlink :: Linked ts a -> a

-- | Constraint that proves that the trait <tt>t</tt> is present somewhere
--   in the list of traits <tt>ts</tt>.
class Has t ts
traitValue :: Has t ts => Linked ts a -> Tagged t (Val t a)

-- | Constraint that proves that all the traits in the list <tt>ts</tt> are
--   present in the list <tt>qs</tt>.
type family Have ts qs :: Constraint
instance forall k a (t :: k). (GHC.Classes.Eq a, GHC.Classes.Eq (WebGear.Trait.Val t a), GHC.Classes.Eq (WebGear.Trait.Fail t a)) => GHC.Classes.Eq (WebGear.Trait.CheckResult t a)
instance forall k a (t :: k). (GHC.Show.Show a, GHC.Show.Show (WebGear.Trait.Val t a), GHC.Show.Show (WebGear.Trait.Fail t a)) => GHC.Show.Show (WebGear.Trait.CheckResult t a)
instance forall k a (t :: k). (GHC.Read.Read a, GHC.Read.Read (WebGear.Trait.Val t a), GHC.Read.Read (WebGear.Trait.Fail t a)) => GHC.Read.Read (WebGear.Trait.CheckResult t a)
instance WebGear.Trait.Has t (t : ts)
instance forall k (t :: k) (ts :: [*]) t'. WebGear.Trait.Has t ts => WebGear.Trait.Has t (t' : ts)
instance GHC.Base.Monad m => WebGear.Trait.Trait '[] a m
instance forall a1 (t :: a1) a2 (m :: * -> *) (ts :: [a1]). (WebGear.Trait.Trait t a2 m, WebGear.Trait.Trait ts a2 m) => WebGear.Trait.Trait (t : ts) a2 m


-- | Common types and functions used throughout WebGear.
module WebGear.Types

-- | Information on the request sent by the client. This abstracts away the
--   details of the underlying implementation.
data Request

-- | The client's host information.
remoteHost :: Request -> SockAddr

-- | HTTP version such as 1.1.
httpVersion :: Request -> HttpVersion

-- | Was this request made over an SSL connection?
--   
--   Note that this value will <i>not</i> tell you if the client originally
--   made this request over SSL, but rather whether the current connection
--   is SSL. The distinction lies with reverse proxies. In many cases, the
--   client will connect to a load balancer over SSL, but connect to the
--   WAI handler without SSL. In such a case, <a>isSecure</a> will be
--   <a>False</a>, but from a user perspective, there is a secure
--   connection.
isSecure :: Request -> Bool

-- | Request method such as GET.
requestMethod :: Request -> Method

-- | Path info in individual pieces - the URL without a hostname/port and
--   without a query string, split on forward slashes.
pathInfo :: Request -> [Text]

-- | Get request with an updated URL path info.
setPathInfo :: [Text] -> Request -> Request

-- | Parsed query string information.
queryString :: Request -> Query

-- | A list of headers (a pair of key and value) in an HTTP request.
requestHeaders :: Request -> RequestHeaders

-- | Get the value of a request header
requestHeader :: HeaderName -> Request -> Maybe ByteString

-- | The size of the request body. In the case of a chunked request body,
--   this may be unknown.
--   
--   Since 1.4.0
requestBodyLength :: Request -> RequestBodyLength

-- | Get the next chunk of the body. Returns <a>empty</a> when the body is
--   fully consumed.
getRequestBodyChunk :: Request -> IO ByteString

-- | A response sent from the server to the client.
--   
--   The response contains a status, optional headers and an optional body
--   of type <tt>a</tt>.
data Response a
Response :: Status -> HashMap HeaderName ByteString -> Maybe a -> Response a

-- | Response status code
[respStatus] :: Response a -> Status

-- | Response headers
[respHeaders] :: Response a -> HashMap HeaderName ByteString

-- | Optional response body
[respBody] :: Response a -> Maybe a

-- | Convert a WebGear response to a WAI Response.
waiResponse :: Response ByteString -> Response

-- | Create or update a response header.
addResponseHeader :: Header -> Response a -> Response a

-- | A handler is a function from a request to response in a monadic
--   context. Both the request and the response can have linked traits.
--   
--   The type level list <tt>req</tt> contains all the traits expected to
--   be present in the request. The handler will produce a response that
--   satisfies all the traits in the type level list <tt>res</tt>.
type Handler m req res a = Kleisli m (Linked req Request) (Linked res (Response a))

-- | A middleware takes a handler as input and produces another handler
--   that usually adds some functionality.
--   
--   A middleware can do a number of things with the request handling such
--   as:
--   
--   <ul>
--   <li>Change the request traits before invoking the handler.</li>
--   <li>Change the response traits before passing it back to its
--   caller.</li>
--   <li>Use the linked value of any of the request or response
--   traits.</li>
--   <li>Change the response body.</li>
--   </ul>
type Middleware m req req' res' res a' a = Handler m req' res' a' -> Handler m req res a

-- | A middleware that manipulates only the request traits and leaves the
--   response unchanged.
type RequestMiddleware m req req' res a = Middleware m req req' res res a a

-- | A middleware that manipulates only the response traits and leaves the
--   request unchanged.
type ResponseMiddleware m req res' res a = Middleware m req req res' res a a


-- | Trait capturing the HTTP method in a request.
module WebGear.Trait.Method

-- | A <a>Trait</a> for capturing the HTTP method of a request
data Method (t :: StdMethod)

-- | A typeclass implemented by all <a>StdMethod</a>s to convert them from
--   type level to term level.
class IsStdMethod t

-- | Convert <tt>t</tt> to term level.
toStdMethod :: IsStdMethod t => Proxy t -> StdMethod

-- | Failure to match method against an expected value
data MethodMismatch
MethodMismatch :: Method -> Method -> MethodMismatch
[expectedMethod] :: MethodMismatch -> Method
[actualMethod] :: MethodMismatch -> Method
instance (GHC.Base.Monad m, WebGear.Trait.Method.IsStdMethod t) => WebGear.Trait.Trait (WebGear.Trait.Method.Method t) Network.Wai.Internal.Request m
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.GET
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.POST
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.HEAD
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.PUT
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.DELETE
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.TRACE
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.CONNECT
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.OPTIONS
instance WebGear.Trait.Method.IsStdMethod 'Network.HTTP.Types.Method.PATCH


-- | Traits related to HTTP headers.
module WebGear.Trait.Header

-- | A <a>Trait</a> for capturing a header with name <tt>s</tt> in a
--   request or response and convert it to some type <tt>t</tt> via
--   <a>FromHttpApiData</a>.
data Header (s :: Symbol) (t :: Type)

-- | Failure in extracting a header value
data HeaderFail
HeaderNotFound :: HeaderFail
HeaderParseError :: Text -> HeaderFail

-- | A <a>Trait</a> for ensuring that a header named <tt>s</tt> has value
--   <tt>t</tt>.
data HeaderMatch (s :: Symbol) (t :: Symbol)

-- | Failure in extracting a header value
data HeaderMismatch
HeaderMismatch :: ByteString -> Maybe ByteString -> HeaderMismatch
[expectedHeader] :: HeaderMismatch -> ByteString
[actualHeader] :: HeaderMismatch -> Maybe ByteString
instance GHC.Show.Show WebGear.Trait.Header.HeaderMismatch
instance GHC.Read.Read WebGear.Trait.Header.HeaderMismatch
instance GHC.Classes.Eq WebGear.Trait.Header.HeaderMismatch
instance GHC.Classes.Eq WebGear.Trait.Header.HeaderFail
instance GHC.Show.Show WebGear.Trait.Header.HeaderFail
instance GHC.Read.Read WebGear.Trait.Header.HeaderFail
instance (GHC.TypeLits.KnownSymbol s, GHC.TypeLits.KnownSymbol t, GHC.Base.Monad m) => WebGear.Trait.Trait (WebGear.Trait.Header.HeaderMatch s t) Network.Wai.Internal.Request m
instance (GHC.TypeLits.KnownSymbol s, Web.Internal.HttpApiData.FromHttpApiData t, GHC.Base.Monad m) => WebGear.Trait.Trait (WebGear.Trait.Header.Header s t) Network.Wai.Internal.Request m


-- | Types and functions to route HTTP requests.
module WebGear.Route

-- | The monad transformer stack for routing.
--   
--   <ul>
--   <li>The <a>ExceptT</a> provides short-circuiting behaviour for
--   <a>rejectRoute</a> and <a>failHandler</a>.</li>
--   <li>In case of <a>rejectRoute</a>, a <a>Nothing</a> value is returned
--   and in case of <a>failHandler</a>, a <tt>Response ByteString</tt> is
--   returned.</li>
--   <li>The <a>First</a> wrapper is provided to get instances of
--   <a>Alternative</a> and <a>MonadPlus</a> for <a>RouterT</a>.</li>
--   </ul>
type RouterT m = ExceptT (Maybe (First (Response ByteString))) m

-- | HTTP request routing with short circuiting behavior.
class (Alternative m, MonadPlus m) => MonadRouter m

-- | Mark the current route as rejected, alternatives can be tried
rejectRoute :: MonadRouter m => m a

-- | Short-circuit the current handler and return a response
failHandler :: MonadRouter m => Response ByteString -> m a

-- | Convert a routable handler into a plain function.
--   
--   This function is typically used to convert WebGear routes to a
--   <a>Application</a>.
runRoute :: Monad m => Handler (RouterT m) '[] res ByteString -> Request -> m Response
instance GHC.Base.Monad m => WebGear.Route.MonadRouter (WebGear.Route.RouterT m)


-- | Middlewares related to HTTP methods.
module WebGear.Middlewares.Method

-- | A middleware to check whether the request has a specified HTTP method.
--   
--   Typically this would be used with a type application such as:
--   
--   <pre>
--   method @GET handler
--   </pre>
--   
--   It is also idiomatic to use the template haskell quasiquoter
--   <a>match</a> in cases where both HTTP method and path needs to be
--   matched.
method :: forall t m req res a. (IsStdMethod t, MonadRouter m) => RequestMiddleware m req (Method t : req) res a


-- | Middlewares related to HTTP headers.
module WebGear.Middlewares.Header

-- | A middleware to check that the Content-Type header in the request has
--   a specific value. It will fail the handler if the header did not
--   match.
--   
--   Typical usage:
--   
--   <pre>
--   requestContentType @"application/json" handler
--   </pre>
requestContentType :: forall c m req res a. (KnownSymbol c, MonadRouter m) => RequestMiddleware m req (HeaderMatch "Content-Type" c : req) res a


-- | Traits related to the route path of a request.
module WebGear.Trait.Path

-- | A path component which is literally matched against the request but
--   discarded after that.
data Path (s :: Symbol)

-- | A path variable that is extracted and converted to a value of type
--   <tt>val</tt>. The <tt>tag</tt> is usually a type-level symbol (string)
--   to uniquely identify this variable.
data PathVar tag (val :: Type)

-- | Failure to extract a <a>PathVar</a>
data PathVarFail
PathVarNotFound :: PathVarFail
PathVarParseError :: Text -> PathVarFail
instance GHC.Read.Read WebGear.Trait.Path.PathVarFail
instance GHC.Show.Show WebGear.Trait.Path.PathVarFail
instance GHC.Classes.Eq WebGear.Trait.Path.PathVarFail
instance forall k val (m :: * -> *) (tag :: k). (Web.Internal.HttpApiData.FromHttpApiData val, GHC.Base.Monad m) => WebGear.Trait.Trait (WebGear.Trait.Path.PathVar tag val) Network.Wai.Internal.Request m
instance (GHC.TypeLits.KnownSymbol s, GHC.Base.Monad m) => WebGear.Trait.Trait (WebGear.Trait.Path.Path s) Network.Wai.Internal.Request m


-- | Traits related to HTTP body.
module WebGear.Trait.Body

-- | A <a>Trait</a> for converting a JSON request body into a value.
data JSONRequestBody (t :: Type)
instance (Data.Aeson.Types.FromJSON.FromJSON t, Control.Monad.IO.Class.MonadIO m) => WebGear.Trait.Trait (WebGear.Trait.Body.JSONRequestBody t) Network.Wai.Internal.Request m


-- | Middlewares related to HTTP body.
module WebGear.Middlewares.Body

-- | A middleware to parse the request body as JSON and convert it to a
--   value via a <a>FromJSON</a> instance.
--   
--   Usage for a type <tt>t</tt> which has a <a>FromJSON</a> instance:
--   
--   <pre>
--   jsonRequestBody @t handler
--   </pre>
jsonRequestBody :: forall t m req res a. (FromJSON t, MonadRouter m, MonadIO m) => RequestMiddleware m req (JSONRequestBody t : req) res a

-- | A middleware that converts the response that has a <a>ToJSON</a>
--   instance to a <a>ByteString</a> response.
--   
--   This will also set the "Content-Type" header of the response to
--   "application/json".
--   
--   Usage for a type <tt>t</tt> which has a <a>ToJSON</a> instance:
--   
--   <pre>
--   jsonResponseBody @t handler
--   </pre>
jsonResponseBody :: (ToJSON t, Monad m) => Middleware m req req res '[] t ByteString


-- | Middlewares related to route paths.
module WebGear.Middlewares.Path

-- | A middleware that literally matches path <tt>s</tt>.
--   
--   The symbol <tt>s</tt> could contain one or more parts separated by a
--   forward slash character. The route will be rejected if there is no
--   match.
--   
--   For example, the following code could be used to match the URL path
--   "a/b/c" and then invoke <tt>handler</tt>:
--   
--   <pre>
--   path @"a/b/c" handler
--   </pre>
path :: forall s ts res m a. (KnownSymbol s, MonadRouter m) => RequestMiddleware m ts (Path s : ts) res a

-- | A middleware that captures a path variable from a single path
--   component.
--   
--   The value captured is converted to a value of type <tt>val</tt> via
--   <a>FromHttpApiData</a>. The route will be rejected if the value is not
--   found or cannot be converted.
--   
--   For example, the following code could be used to read a path component
--   as <a>Int</a> tagged with the symbol "objId", and then invoke
--   <tt>handler</tt>:
--   
--   <pre>
--   pathVar @"objId" @Int handler
--   </pre>
pathVar :: forall tag val ts res m a. (FromHttpApiData val, MonadRouter m) => RequestMiddleware m ts (PathVar tag val : ts) res a

-- | Produces middleware(s) to match an optional HTTP method and path.
--   
--   This quasiquoter can be used in several ways:
--   
--   <ul>
--   <li><tt>[match|a/b/c]</tt> is equivalent to <tt><a>path</a>
--   @"a/b/c"</tt></li>
--   <li><tt>[match|a/b/objId:Int/d]</tt> is equivalent to <tt><a>path</a>
--   @"a/b" . <a>pathVar</a> @"objId" @Int . <a>path</a> </tt>"d"@</li>
--   <li><tt>[match|GET a/b/c]</tt> is equivalent to <tt><a>method</a> @GET
--   $ <a>path</a> @"a/b/c"</tt></li>
--   <li><tt>[match|GET a/b/objId:Int/d]</tt> is equivalent to
--   <tt><a>method</a> @GET . <a>path</a> @"a/b" . <a>pathVar</a> @"objId"
--   @Int . <a>path</a> @"d"</tt></li>
--   </ul>
match :: QuasiQuoter


-- | Middlewares provided by WebGear.
module WebGear.Middlewares

-- | Respond with a 200 OK
ok :: Monad m => a -> m (Linked '[] (Response a))

-- | Respond with a 204 NoContent
noContent :: (Monad m, IsString s) => m (Linked '[] (Response s))

-- | Respond with a 400 Bad Request
badRequest :: Monad m => m (Linked '[] (Response a))

-- | Respond with a 404 NotFound
notFound :: Monad m => m (Linked '[] (Response a))


-- | WebGear helps to build composable, type-safe HTTP API servers.
--   
--   The documentation below gives an overview of WebGear. Example programs
--   built using WebGear are available at
--   <a>https://github.com/rkaippully/webgear/tree/master/webgear-examples</a>.
module WebGear