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

Constructors

Rsp

Fields

• rspShouldCommit :: ShouldCommitOrRollback
• rspPayload :: RspPayload

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

data RspPayload

Constructors

ToJSON x => RspPayload_Good x

ApiErr e => RspPayload_Bad e

RspPayload_Custom Status ByteString ByteString

First ByteString is MIME type; second is response body

RspPayload_Empty

data ShouldCommitOrRollback

Constructors

ShouldCommit

ShouldRollback

Instances

Eq ShouldCommitOrRollback

Defined in Gingersnap.Core

Methods

(==) :: ShouldCommitOrRollback -> ShouldCommitOrRollback -> Bool

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

Show ShouldCommitOrRollback

Defined in Gingersnap.Core

Methods

showsPrec :: Int -> ShouldCommitOrRollback -> ShowS

show :: ShouldCommitOrRollback -> String

showList :: [ShouldCommitOrRollback] -> ShowS

Reexports, for convenience

data Pool a

Instances

Show (Pool a)

Defined in Data.Pool

Methods

showsPrec :: Int -> Pool a -> ShowS

show :: Pool a -> String

showList :: [Pool a] -> ShowS

createPool

Arguments

:: IO a

Action that creates a new resource.

-> (a -> IO ())

Action that destroys an existing resource.

-> Int

The number of stripes (distinct sub-pools) to maintain. The smallest acceptable value is 1.

-> NominalDiffTime

Amount of time for which an unused resource is kept open. The smallest acceptable value is 0.5 seconds.

The elapsed time before destroying a resource may be a little longer than requested, as the reaper thread wakes at 1-second intervals.

-> Int

Maximum number of resources to keep open per stripe. The smallest acceptable value is 1.

Requests for resources will block if this limit is reached on a single stripe, even if other stripes have idle resources available.

-> IO (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 destroyAllResources when you're done with the pool so that the resources are freed up as soon as possible.

data Connection

Instances

Eq Connection

Defined in Database.PostgreSQL.Simple.Internal

Methods

(==) :: Connection -> Connection -> Bool

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