TsWeb - A very opinionated web API
TsWeb is a binding between the Spock web framework and the Beam database
API. It provides convenience functions for running database queries from
within Spock actions, a Spock session manager replacement using the Beam API,
and type-safe routing including type-checked reverse lookups (URLs are
associated with first-class labels which are used for reverse lookup).
Sample Program
Most of the functionality of TsWeb (ideally, all of it) is demonstrated in the
example program, which lives under the Example directory of the source tree.
Have a look there for a working example of TsWeb.
Restricted Views
TsWeb views run with minimal rights; by default they do not have access to the
database nor do they have any user information initialized. A view's type
signature enumerates its requirements, and those requirements are granted by
the view's routing. For example, a view that needs read-write database access,
an admin user, and a route to the index URL might have this type signature:
myview ::
( ListContains n0 Admin xs
, ListContains n1 ReadWritePool xs
, Has "index" lts (Path '[] 'Open) )
=> TsActionCtxT lts xs sessdata a
myview = do
db :: ReadOnlyPool <- getExtra
Admin me <- getExtra
indexPath <- showPath #index
...
And then the view would be routed as:
runroute readonlypool readwritepool $
path #index root (getpost indexView) .
path #myview "mine" (dbwrite $ getpost $ auth adminP myview)
See the docs for "TsWeb.Routing" and "TsWeb.Routing.Auth" for more details.
Action Queries
Have a look at "TsWeb.Db" for documentation on running Beam queries from a
Spock context. This is just sugar, but it's pretty nice. A small example:
myview :: ListContains n ReadWritePool xs => TsActionCtxT lts xs sessdata a
myview = do
queryList (select $ all_ (_dbUser db)) >>= \case
QSimply users -> text $ T.pack $ show users
QError err -> text $ "Error: " <> Text.pack (show err)
See "TsWeb.Db" for more details.
Session Manager
This is pretty much invisible, but use TsWeb.Session.patchConfig on your Spock
config to replace the default session manager with the TsWeb one. Lifted
directly from the "TsWeb.Session" documentation:
spockCfg <-
patchConfig (_dbSession db) ropool rwpool <$>
defaultSpockCfg sess PCNoDatabase ()
runSpock port (spock spockCfg routes)
where
sess = ...
routes = ...
Type-safe URLs with reversing.
TsWeb builds on Spock's reroute library to also add type-checked reverse
lookups. There's a pretty complete document on that under "TsWeb.Routing",
which I'm simply pasting in here:
index :: Has "users" lts (Path '[] 'Open) => TsActionCtxT lts xs sess a
index = showPath #users >>= text
users :: Has "root" lts (Path '[] 'Open) => TsActionCtxT lts xs sess a
users = do
root <- showPath #root
text $ "GET users, root is, " <> root
usersPost :: TsActionCtxT lts xs sess a
usersPost = text "POST to users!"
Then, routing to those views looks like this:
runroute ropool rwpool $
path #root root (getpost index) .
path #users "users" (do get users
post usersPost)
