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


-- | Consistent and safe JSON APIs with snap-core and (by default) postgresql-simple
--   
--   Straightforward JSON API tools and idioms for snap-core and datastore
--   access (by default PostgreSQL via postgresql-simple), that provide:
--   
--   <ul>
--   <li>Safe access to pools of DB connections (preventing connection
--   leaks)</li>
--   <li>Simple and consistent JSON responses for successes and failures
--   (including unexpected failures)</li>
--   <li>An optional read-only/maintenance mode for keeping services up
--   during e.g. database migrations</li>
--   </ul>
--   
--   See the README for a tutorial and example use.
@package gingersnap
@version 0.3.1.0

module Gingersnap.Core

-- | This means everything's succeeded. We should commit DB changes and
--   return a success object
rspGood :: ToJSON x => x -> Rsp

-- | We should send back an error object and roll back DB changes
rspBad :: ApiErr ae => ae -> Rsp

-- | Like <a>rspBad</a> but should still commit DB changes
rspBadCommit :: ApiErr ae => ae -> Rsp

-- | The same as <a>rspBad</a> but more explicit that we roll back
rspBadRollback :: ApiErr ae => ae -> Rsp
rspGoodCSV :: ByteString -> Rsp

-- | First Bytestring is the content type, e.g. "application/json" Here's a
--   helpful list:
--   <a>https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types</a>
rspGoodLBS :: ByteString -> ByteString -> Rsp

-- | Everything worked and we send a 200, but we don't have any data to
--   send
rspEmptyGood :: Rsp

-- | How we construct responses. You probably don't want to be constructing
--   or inspecting them by hand; instead you can use <a>rspGood</a>,
--   <a>rspBadRollback</a>, etc.
data Rsp
Rsp :: ShouldCommitOrRollback -> RspPayload -> Rsp
[rspShouldCommit] :: Rsp -> ShouldCommitOrRollback
[rspPayload] :: Rsp -> RspPayload

-- | Sometimes you don't need a DB connection at all!
pureRsp :: IsCtx ctx => ctx -> Rsp -> Snap ()

-- | _If you hit the DB, use this function!_
--   
--   NOTE this is for IO actions, not Snap actions. This is to ensure we
--   can't call e.g. <tt>finishEarly</tt> and never hit the 'end
--   transaction' code! (It also has the side benefit of keeping code
--   fairly framework-agnostic)
inTransaction :: IsCtx ctx => ctx -> (ConnType ctx -> IO Rsp) -> Snap ()

-- | The most general version of <a>inTransaction</a>.
--   
--   An endpoint that uses a read-only transaction mode will keep
--   responding even when the server is in read-only mode, while all others
--   will return the result of <a>apiErr_inReadOnlyMode</a> (by default a
--   503)
--   
--   <a>inTransactionMode</a> will eventually be replaced by this.
inTransactionWithMode :: IsCtx ctx => ctx -> TxModeType ctx -> (ConnType ctx -> IO Rsp) -> Snap ()

-- | Postgres-specific version of <a>inTransactionWithMode</a>
--   
--   Will likely be removed in a future version
inTransactionMode :: (IsCtx ctx, TxModeType ctx ~ TransactionMode) => ctx -> IsolationLevel -> ReadWriteMode -> (ConnType ctx -> IO Rsp) -> Snap ()

-- | Creates a read-only transaction and will keep responding even if the
--   server's in read-only mode.
--   
--   Note that you the programmer are asserting the DB queries are
--   read-only. There's nothing in this library or in postgresql-simple
--   which statically checks that to be true!
inTransaction_readOnly :: (IsCtx ctx, TxModeType ctx ~ TransactionMode) => ctx -> (ConnType ctx -> IO Rsp) -> Snap ()

-- | This is the default for IsCtx but this allows us to be explicit
inTransaction_readWrite :: (IsCtx ctx, TxModeType ctx ~ TransactionMode) => ctx -> (ConnType ctx -> IO Rsp) -> Snap ()

-- | _You should only use this once!_
--   
--   This lets you do a write transaction during read-only mode (not a
--   read-only transaction! A time where <a>ctxGetReadOnlyMode</a> would
--   return True)
--   
--   You may need this so that an admin user can take the app out of
--   read-only mode
inTransaction_override :: (IsCtx ctx, TxModeType ctx ~ TransactionMode) => ctx -> (ConnType ctx -> IO Rsp) -> Snap ()

-- | DON'T USE THIS FUNCTION! This should only be called by
--   <a>inTransaction_override</a> and <a>inTransactionWithMode</a> and
--   <a>inTransactionMode</a>
--   
--   Only exported to enable writing <tt>_override</tt> for non-postgres
--   datastores
inTransaction_internal :: IsCtx ctx => ctx -> TxModeType ctx -> (ConnType ctx -> IO Rsp) -> Snap ()
rspIsGood :: Rsp -> Bool

-- | Don't be daunted! The only thing you need to provide (i.e. that
--   doesn't have a default value) is <a>ctxConnectionPool</a>
class ApiErr (CtxErrType ctx) => IsCtx ctx where {
    type family CtxErrType ctx;
    type family ConnType ctx :: *;
    type family TxModeType ctx :: *;
    type CtxErrType ctx = DefaultApiErr;
    type ConnType ctx = Connection;
    type TxModeType ctx = TransactionMode;
}
ctxConnectionPool :: IsCtx ctx => ctx -> Pool (ConnType ctx)
ctxGetReadOnlyMode :: IsCtx ctx => ctx -> IO Bool
ctx_wrapSuccess :: (IsCtx ctx, ToJSON x) => ctx -> x -> Value
ctx_rollback :: IsCtx ctx => ctx -> ConnType ctx -> IO ()
ctx_rollback :: (IsCtx ctx, ConnType ctx ~ Connection) => ctx -> ConnType ctx -> IO ()
ctx_commit :: IsCtx ctx => ctx -> ConnType ctx -> IO ()
ctx_commit :: (IsCtx ctx, ConnType ctx ~ Connection) => ctx -> ConnType ctx -> IO ()
ctx_defaultTransactionMode :: IsCtx ctx => ctx -> TxModeType ctx
ctx_defaultTransactionMode :: (IsCtx ctx, TxModeType ctx ~ TransactionMode) => ctx -> TxModeType ctx
ctx_txIsReadOnly :: IsCtx ctx => ctx -> TxModeType ctx -> Bool
ctx_txIsReadOnly :: (IsCtx ctx, TxModeType ctx ~ TransactionMode) => ctx -> TxModeType ctx -> Bool
ctx_beginTransaction :: IsCtx ctx => ctx -> TxModeType ctx -> ConnType ctx -> IO ()
ctx_beginTransaction :: (IsCtx ctx, TxModeType ctx ~ TransactionMode, ConnType ctx ~ Connection) => ctx -> TxModeType ctx -> ConnType ctx -> IO ()
reqObject :: IsCtx ctx => ctx -> Snap (ReqObject ctx)
reqObject' :: IsCtx ctx => ctx -> Word64 -> Snap (ReqObject ctx)

-- | Like (.!?) but returns a 422 error (with <tt>errorEarly</tt>) if the
--   key isn't present
(.!) :: (IsCtx ctx, FromJSON x) => ReqObject ctx -> Text -> Snap x

-- | Get a JSON value from the request object, and give a HTTP 422 response
--   (<tt>errorEarly</tt>) if the value is malformed (not able to be
--   decoded). If it's not present, don't fail: just give us a Nothing
(.!?) :: (IsCtx ctx, FromJSON x) => ReqObject ctx -> Text -> Snap (Maybe x)
data ReqObject ctx
ReqObject :: ctx -> HashMap Text Value -> ReqObject ctx

-- | This returns any 'Snap x' so you can use it like a throw anywhere in
--   your snap code
--   
--   NOTE: if you ever use 's <tt>withTransaction</tt> (which we don't
--   recommend!) this function has the same caveats as <tt>finishWith</tt>
errorEarlyCode :: ApiErr ae => ae -> Snap x
class ApiErr apiErr
errResult :: ApiErr apiErr => apiErr -> ErrResult

-- | The request object is missing a required key. E.g. the request is
--   <tt>{"first": <a>Tom</a>}</tt> but we need both a <tt>"first"</tt> and
--   a <tt>"last"</tt>
apiErr_missingRequestKey :: ApiErr apiErr => Text -> apiErr

-- | We can't process the request because the request is malformed JSON or
--   not JSON at all
apiErr_requestNotJSON :: ApiErr apiErr => apiErr

-- | The request *is* JSON, but not an object (e.g. maybe it's an array or
--   a number, but we need an object)
apiErr_requestNotJSONObject :: ApiErr apiErr => apiErr

-- | It's a JSON object but it's malformed somehow (e.g. maybe it's got the
--   wrong keys). In other words, we can't <a>fromJSON</a> it successfully.
--   
--   (The <a>Text</a> is the key of the malformed value)
apiErr_malformedRequestValue :: ApiErr apiErr => Text -> Value -> apiErr

-- | A 500 internal server error
--   
--   The Text value is the error message. You may want different behavior
--   in development vs. production, e.g. not showing internal errors in
--   prod
apiErr_unexpectedError :: ApiErr apiErr => Text -> apiErr
apiErr_inReadOnlyMode :: ApiErr apiErr => apiErr
data ErrResult
ErrResult :: Status -> Value -> ErrResult
data DefaultApiErr
DefaultApiErr_ReadOnlyMode :: DefaultApiErr
DefaultApiErr_MissingRequestKey :: Text -> DefaultApiErr
DefaultApiErr_RequestNotJSON :: DefaultApiErr
DefaultApiErr_RequestNotJSONObject :: DefaultApiErr
DefaultApiErr_MalformedRequestValue :: Text -> Value -> DefaultApiErr
DefaultApiErr_UnexpectedError :: Text -> DefaultApiErr
DefaultApiErr_Custom :: Status -> String -> [(Text, Value)] -> DefaultApiErr
ctxErr :: IsCtx ctx => ctx -> CtxErrType ctx -> CtxErrType ctx
data RspPayload
RspPayload_Good :: x -> RspPayload
RspPayload_Bad :: e -> RspPayload

-- | First ByteString is MIME type; second is response body
RspPayload_Custom :: Status -> ByteString -> ByteString -> RspPayload
RspPayload_Empty :: RspPayload
data ShouldCommitOrRollback
ShouldCommit :: ShouldCommitOrRollback
ShouldRollback :: ShouldCommitOrRollback
data Pool a

-- | Create a striped resource pool.
--   
--   Although the garbage collector will destroy all idle resources when
--   the pool is garbage collected it's recommended to manually
--   <a>destroyAllResources</a> when you're done with the pool so that the
--   resources are freed up as soon as possible.
createPool :: () => IO a -> (a -> IO ()) -> Int -> NominalDiffTime -> Int -> IO (Pool a)
data Connection
instance GHC.Generics.Generic Gingersnap.Core.Rsp
instance GHC.Generics.Generic Gingersnap.Core.ShouldCommitOrRollback
instance GHC.Classes.Eq Gingersnap.Core.ShouldCommitOrRollback
instance GHC.Show.Show Gingersnap.Core.ShouldCommitOrRollback
instance GHC.Classes.Eq Gingersnap.Core.DefaultApiErr
instance GHC.Show.Show Gingersnap.Core.DefaultApiErr
instance GHC.Classes.Eq Gingersnap.Core.ErrResult
instance GHC.Show.Show Gingersnap.Core.ErrResult
instance Control.DeepSeq.NFData Gingersnap.Core.Rsp
instance GHC.Show.Show Gingersnap.Core.Rsp
instance Control.DeepSeq.NFData Gingersnap.Core.ShouldCommitOrRollback
instance Control.DeepSeq.NFData Gingersnap.Core.RspPayload
instance Gingersnap.Core.ApiErr Gingersnap.Core.DefaultApiErr
instance Control.DeepSeq.NFData Gingersnap.Core.ErrResult
