Web.Spock

Spock's core

spock :: Int -> SessionCfg sess -> PoolOrConn conn -> st -> SpockM conn sess st () -> IO ()

Run a spock application using the warp server, a given db storageLayer and an initial state. Spock works with database libraries that already implement connection pooling and with those that don't come with it out of the box. For more see the PoolOrConn type.

type SpockM conn sess st = SpockT (WebStateM conn sess st)

Insive the SpockM monad, you may define routes and middleware.

type SpockAction conn sess st = ActionT (WebStateM conn sess st)

The SpockAction is the monad of all route-actions. You have access to the database, session and state of your application.

spockT :: MonadIO m => Port -> (forall a. m a -> IO a) -> SpockT m () -> IO ()

Run a raw spock server on a defined port. If you don't need a custom base monad you can just supply id as lift function.

data SpockT m a

Instances

MonadTrans SpockT

Monad m => Monad (SpockT m)

Functor m => Functor (SpockT m)

(Monad m, Functor m) => Applicative (SpockT m)

MonadIO m => MonadIO (SpockT m)

data ActionT m a

Instances

MonadTrans ActionT

Monad m => Monad (ActionT m)

Functor m => Functor (ActionT m)

(Monad m, Functor m) => Applicative (ActionT m)

MonadIO m => MonadIO (ActionT m)

Defining routes

get :: MonadIO m => Text -> ActionT m () -> SpockT m ()

Specify an action that will be run when the HTTP verb GET and the given route match

post :: MonadIO m => Text -> ActionT m () -> SpockT m ()

Specify an action that will be run when the HTTP verb POST and the given route match

head :: MonadIO m => Text -> ActionT m () -> SpockT m ()

Specify an action that will be run when the HTTP verb HEAD and the given route match

put :: MonadIO m => Text -> ActionT m () -> SpockT m ()

Specify an action that will be run when the HTTP verb PUT and the given route match

delete :: MonadIO m => Text -> ActionT m () -> SpockT m ()

Specify an action that will be run when the HTTP verb DELETE and the given route match

patch :: MonadIO m => Text -> ActionT m () -> SpockT m ()

Specify an action that will be run when the HTTP verb PATCH and the given route match

defRoute :: MonadIO m => StdMethod -> Text -> ActionT m () -> SpockT m ()

Define a route matching a provided StdMethod and route

subcomponent :: MonadIO m => Text -> SpockT m () -> SpockT m ()

Define a subcomponent

 subcomponent "/api" $
    do get "/user" $ text "USER"
       post "/new-user" $ text "OK!"

>>> curl http://localhost:8080/api/user
USER

data StdMethod

HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).

Constructors

GET

POST

HEAD

PUT

DELETE

TRACE

CONNECT

OPTIONS

PATCH

Instances

Bounded StdMethod

Enum StdMethod

Eq StdMethod

Ord StdMethod

Read StdMethod

Show StdMethod

Ix StdMethod

Hashable StdMethod

combineRoute :: Text -> Text -> Text

Combine two routes, ensuring that the slashes don't get messed up

Handeling requests

request :: MonadIO m => ActionT m Request

Get the original Wai Request object

header :: MonadIO m => Text -> ActionT m (Maybe Text)

Read a header

cookie :: MonadIO m => Text -> ActionT m (Maybe Text)

Read a cookie

body :: MonadIO m => ActionT m ByteString

Get the raw request body

jsonBody :: (MonadIO m, FromJSON a) => ActionT m (Maybe a)

Parse the request body as json

files :: MonadIO m => ActionT m (HashMap Text UploadedFile)

Get uploaded files

data UploadedFile

Constructors

UploadedFile

Fields

uf_name :: Text

uf_contentType :: Text

uf_tempLocation :: FilePath

params :: MonadIO m => ActionT m [(Text, Text)]

Get all request params

param :: (PathPiece p, MonadIO m) => Text -> ActionT m (Maybe p)

Read a request param. Spock looks in route captures first, then in POST variables and at last in GET variables

Sending responses

setStatus :: MonadIO m => Status -> ActionT m ()

Set a response status

setHeader :: MonadIO m => Text -> Text -> ActionT m ()

Set a response header. Overwrites already defined headers

redirect :: MonadIO m => Text -> ActionT m ()

Redirect to a given url

setCookie :: MonadIO m => Text -> Text -> NominalDiffTime -> ActionT m ()

Set a cookie living for a given number of seconds

setCookie' :: MonadIO m => Text -> Text -> UTCTime -> ActionT m ()

Set a cookie living until a specific UTCTime

bytes :: MonadIO m => ByteString -> ActionT m ()

Send a ByteString as response body. Provide your own Content-Type

lazyBytes :: MonadIO m => ByteString -> ActionT m ()

Send a lazy ByteString as response body. Provide your own Content-Type

text :: MonadIO m => Text -> ActionT m ()

Send text as a response body. Content-Type will be text/plain

html :: MonadIO m => Text -> ActionT m ()

Send a text as response body. Content-Type will be text/plain

file :: MonadIO m => Text -> FilePath -> ActionT m ()

Send a file as response

json :: (ToJSON a, MonadIO m) => a -> ActionT m ()

Send json as response. Content-Type will be application/json

blaze :: MonadIO m => Html -> ActionT m ()

Send blaze html as response. Content-Type will be text/html

Adding middleware

middleware :: MonadIO m => Middleware -> SpockT m ()

Hook up a Middleware

Database

data PoolOrConn a

You can feed Spock with either a connection pool, or instructions on how to build a connection pool. See ConnBuilder

Constructors

PCPool (Pool a)

PCConduitPool (Pool a)

PCConn (ConnBuilder a)

data ConnBuilder a

The ConnBuilder instructs Spock how to create or close a database connection.

Constructors

ConnBuilder

Fields

cb_createConn :: IO a

cb_destroyConn :: a -> IO ()

cb_poolConfiguration :: PoolCfg

data PoolCfg

If Spock should take care of connection pooling, you need to configure it depending on what you need.

Constructors

PoolCfg

Fields

pc_stripes :: Int

pc_resPerStripe :: Int

pc_keepOpenTime :: NominalDiffTime

Accessing Database and State

class HasSpock m where

Methods

runQuery :: (SpockConn m -> IO a) -> m a

Give you access to a database connectin from the connection pool. The connection is released back to the pool once the function terminates.

getState :: m (SpockState m)

Read the application's state. If you wish to have mutable state, you could use a TVar from the STM packge.

Instances

MonadTrans t => HasSpock (t (WebStateM conn sess st))

HasSpock (WebStateM conn sess st)

Sessions

data SessionCfg a

Configuration for the session manager

Constructors

SessionCfg

Fields

sc_cookieName :: Text

sc_sessionTTL :: NominalDiffTime

sc_sessionIdEntropy :: Int

sc_emptySession :: a

readSession :: SpockAction conn sess st sess

Read the stored session

writeSession :: sess -> SpockAction conn sess st ()

Write to the current session. Note that all data is stored on the server. The user only reciedes a sessionId to be identified.

modifySession :: (sess -> sess) -> SpockAction conn sess st ()

Modify the stored session

Safe actions

class (Hashable a, Eq a, Typeable a) => SafeAction conn sess st a where

SafeActions are actions that need to be protected from csrf attacks

Methods

runSafeAction :: a -> SpockAction conn sess st ()

The body of the safe action. Either GET or POST

safeActionPath :: forall conn sess st a. (SafeAction conn sess st a, HasSpock (SpockAction conn sess st), SpockConn (SpockAction conn sess st) ~ conn, SpockSession (SpockAction conn sess st) ~ sess, SpockState (SpockAction conn sess st) ~ st) => a -> SpockAction conn sess st Text

Wire up a safe action: Safe actions are actions that are protected from csrf attacks. Here's a usage example:

 newtype DeleteUser = DeleteUser Int deriving (Hashable, Typeable, Eq)

 instance SafeAction Connection () () DeleteUser where
    runSafeAction (DeleteUser i) =
       do runQuery $ deleteUserFromDb i
          redirect "/user-list"

 get "/user-details/:userId" $
   do userId <- param "userId"
      deleteUrl <- safeActionPath (DeleteUser userId)
      html $ TL.concat [ "Click <a href='", TL.fromStrict deleteUrl, "'>here</a> to delete user!" ]

Note that safeActions currently only support GET and POST requests.

Digestive Functors

runForm

Arguments

:: (Functor m, MonadIO m)

=> Text

form name

-> Form v (ActionT m) a

-> ActionT m (View v, Maybe a)

Run a digestive functors form

Internals for extending Spock

getSpockHeart :: MonadTrans t => t (WebStateM conn sess st) (WebState conn sess st)

Read the heart of Spock. This is useful if you want to construct your own monads that work with runQuery and getState using runSpockIO

runSpockIO :: WebState conn sess st -> WebStateM conn sess st a -> IO a

Run an action inside of Spocks core monad. This allows you to use runQuery and getState

data WebStateM conn sess st a

Instances

MonadBase IO (WebStateM conn sess st)

MonadBaseControl IO (WebStateM conn sess st)

MonadTrans t => HasSpock (t (WebStateM conn sess st))

Monad (WebStateM conn sess st)

Functor (WebStateM conn sess st)

Applicative (WebStateM conn sess st)

MonadIO (WebStateM conn sess st)

HasSpock (WebStateM conn sess st)

MonadReader (WebState conn sess st) (WebStateM conn sess st)

data WebState conn sess st

Instances

MonadReader (WebState conn sess st) (WebStateM conn sess st)