Gingersnap.Core

Documentation

class IsCtx ctx where

Minimal complete definition

ctxConnectionPool

Methods

ctxConnectionPool :: ctx -> Pool Connection

ctxGetReadOnlyMode :: ctx -> IO Bool

ctx_wrapSuccess :: ToJSON x => ctx -> x -> Value

ctx_err_inReadOnlyMode :: ctx -> ErrResult

class ApiErr apiErr where

Minimal complete definition

errResult

Methods

errResult :: apiErr -> ErrResult

Instances

ApiErr ErrResult

Defined in Gingersnap.Core

Methods

errResult :: ErrResult -> ErrResult

data ErrResult

Constructors

ErrResult Status Value

Instances

Eq ErrResult

Defined in Gingersnap.Core

Methods

(==) :: ErrResult -> ErrResult -> Bool

(/=) :: ErrResult -> ErrResult -> Bool

Show ErrResult

Defined in Gingersnap.Core

Methods

showsPrec :: Int -> ErrResult -> ShowS

show :: ErrResult -> String

showList :: [ErrResult] -> ShowS

ApiErr ErrResult

Defined in Gingersnap.Core

Methods

errResult :: ErrResult -> ErrResult

data Rsp

Instances

Show Rsp

Defined in Gingersnap.Core

Methods

showsPrec :: Int -> Rsp -> ShowS

show :: Rsp -> String

showList :: [Rsp] -> ShowS

rspGood :: ToJSON x => x -> Rsp

This means everything's succeeded. We should commit DB changes and return a success object

rspBad :: ApiErr ae => ae -> Rsp

We should send back an error object and roll back DB changes

rspBadCommit :: ApiErr ae => ae -> Rsp

Like rspBad but should still commit DB changes

rspBadRollback :: ApiErr ae => ae -> Rsp

The same as rspBad but more explicit that we roll back

rspGoodCSV :: ByteString -> Rsp

rspGoodLBS :: ByteString -> ByteString -> Rsp

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

rspEmptyGood :: Rsp

Everything worked and we send a 200, but we don't have any data to send

pureRsp :: IsCtx ctx => ctx -> Rsp -> Snap ()

Sometimes you don't need a DB connection at all!

inTransaction :: IsCtx ctx => ctx -> (Connection -> IO Rsp) -> Snap ()

• If you hit the DB, use this function!*

This is a lot like withTransaction, but it allows us to rollback if we want, without throwing an error. (Don't use withTransaction!)

NOTE this is for IO actions, not Snap actions. This is to ensure we can't call e.g. finishEarly and never hit the 'end transaction' code! (It also has the side benefit of keeping code fairly framework-agnostic)

inTransaction_readOnly :: IsCtx ctx => ctx -> (Connection -> IO Rsp) -> Snap ()

An endpoint that uses inTransaction_readOnly will keep responding even when the server is 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_override :: IsCtx ctx => ctx -> (Connection -> 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 ctxGetReadOnlyMode would return True)

You may need this so that an admin user can take the app out of read-only mode

inTransactionMode :: IsCtx ctx => ctx -> IsolationLevel -> ReadWriteMode -> (Connection -> IO Rsp) -> Snap ()

rspIsGood :: Rsp -> Bool

errorEarlyCode :: ApiErr ae => ae -> Snap x

NOTE: be very careful to not use this with any setup/teardown block like withTransaction - causes resource leaks - BUT! This should never happen to you because all your DB code should use inTransaction!

NOTE: use 403 forbidden instead of unauthorized - unauth means not logged in at all

Also note this returns any 'Snap x' so you can use it like a throw anywhere in your snap code