Spock Haskell Web Framework

Securing Spock browser applications

Sun, 06 Sep 2026 00:00:00 +0000

The new browser security guide follows a complete login, form, JSON update, and logout flow. Its runnable example uses Argon2id password hashing, browser session settings, CSRF checks, session ID rotation, and Lucid escaping. Tests cover rejected requests, stolen tokens, old session IDs, and logout revocation.

The guide also explains the explicit CSRF hook needed when using Spock-api-server with cookie authentication, along with database and reverse proxy responsibilities. Start with the example and its tests, or use the FAQ for a shorter explanation of sessions and expiry.

Shareable APIs and more

Thu, 25 Aug 2016 13:00:00 +0000

This is a historical release announcement. For current GHC JavaScript builds, typed clients and a deployable shared/server/browser example, use the browser tutorial.

I’m happy to announce the next Spock release! This release comes with several cool new features:

“Shareable” API definitions
wildcard route pattern
Custom error handlers
Custom HTTP verbs
New CSRF protection
New session storage system
Removal of untyped routing
Split of packages
Multiple bug fixes

A big thank you goes to all awesome contributors (in chronological order): lloucas-imvu, timjb, dancingrobot84 and cdepillabout!

“Shareable” API definitions

When we started using GHCJS for a project’s frontend where the backend was powered with Spock, a real pain point was that calling JSON-APIs defined in the frontend didn’t really feel good: One had to render the route defined in Spock, send the correct JSON body (sending the correct JSON body was not enforced anywhere) and receive and parse the response JSON body. If you are already using the same language, I think calling an endpoint from the frontend should rather feel just like a type-safe function call. And that’s what “shareable” API definitions try to solve. Basically, the idea is to split your project into three packages:

project-api
project-frontend
project-backend

(where ‘project’ is your project’s name)

Now in project-api we will use only Spock-api to describe our API. For example for a login endpoint:

module MyProject.Api.User where

import Data.Int
import Web.Spock.Api
import qualified Data.Text as T

data LoginReq
   = LoginReq
   { lr_username :: !T.Text
   , lr_password :: !T.Text
   } deriving (Show, Eq, Generic, NFData, Typeable, ToJSON, FromJSON)

data LoginResp
   = LoginOkay !User
   | LoginFailed
   deriving (Show, Eq, Generic, NFData, Typeable, ToJSON, FromJSON)

data User
   = User
   { u_id :: !Int64
   , u_name :: !T.Text
   , u_email :: !T.Text
   , u_isSuperuser :: !Bool
   } deriving (Show, Eq, Generic, NFData, Typeable, ToJSON, FromJSON)

loginUser :: Endpoint '[] ('Just LoginReq) LoginResp
loginUser = MethodPost Proxy ("api" <//> "user" <//> "auth")

We can now go ahead and implement that endpoint in project-backend using the Spock-api-server package (together with Spock-core or Spock):

module MyProject.Api.Server.User
    ( api )
where

import qualified MyProject.Api.User as A

import Web.Spock
import Web.Spock.Api.Server

api :: Application ()
api =
    defEndpoint A.loginUser loginHandler

loginHandler :: A.LoginReq -> Action A.LoginResp
loginHandler r =
    do auth <- runQuery $ \conn -> authUser conn (A.lr_username r) (A.lr_password r)
       case auth of
         Just user ->
             do modifySession $ \sess -> sess { s_user = Just (A.u_id user) }
                pure (A.LoginOkay user)
         Nothing ->
             pure A.LoginFailed

Note that defEndpoint is just another Spock combinator, like the ones you already know and love (get, post, …). Now we can use our API in our frontend in project-frontend using the Spock-api-ghcjs package:

module Main where

import MyProject.Api.User

import Web.Spock.Api.Client

type SessionId = T.Text

main :: IO ()
main =
    do Just res <- callEndpoint loginUser (LoginReq "alex" "alexcool")
       putStrLn ("Login result was: " ++ show res)

The final step is to compile project-backend with GHC and project-frontend with GHCJS. The easiest way to go would be to write two stack files, one stack.yaml and one stack-frontend.yaml and use the correct one. Example:

# stack.yaml
resolver: lts-6.13
packages:
  - pkgs/project-api
  - pkgs/project-backend
  - location:
      git: https://github.com/agrafix/Spock
      commit: 77333a2de5dea0dc8eba9432ab16864e93e5d70e
    extra-dep: true
    subdirs:
      - Spock
      - Spock-core
      - Spock-api
      - Spock-api-server
      - reroute

# stack-frontend.yaml
resolver: lts-6.13
packages:
  - pkgs/project-api
  - pkgs/project-frontend
  - location:
      git: https://github.com/agrafix/Spock
      commit: 77333a2de5dea0dc8eba9432ab16864e93e5d70e
    extra-dep: true
    subdirs:
      - Spock-api
      - Spock-api-ghcjs
      - reroute
compiler: ghcjs-0.2.0.20160414_ghc-7.10.3
compiler-check: match-exact
setup-info:
  ghcjs:
    source:
      ghcjs-0.2.0.20160414_ghc-7.10.3:
        url: https://s3.amazonaws.com/ghcjs/ghcjs-0.2.0.20160414_ghc-7.10.3.tar.gz
        sha1: 6d6f307503be9e94e0c96ef1308c7cf224d06be3

`wildcard` route pattern

The wildcard route pattern lets you capture the leftover of a route without explicitly defining what it looks like. For example a route "foo" </> "bar" will only match on requests to foo/bar, but a route "foo" </> wildcard will match on foo/baz, foo/baz/bim and so on. The captured leftover will be passed as Text as you are used to from matched paramters. Note that a new type parameter in Path will enforce that wildcard can only be used at the end of a route pattern.

Custom error handlers

You can now define your own error handler in the Spock configuration. An error handler is a function errorHandler :: Status -> ActionCtxT () IO (), so you could, for example, write out the error to some event log and show a nice error page to the user. If an uncaught exception occurs in another request handler your error handler will be called with status500. The default error handler will state the HTTP status code and message along with a Powered by Spock :-)

Custom HTTP verbs

Apart from the standard HTTP verbs GET, POST, … one can now write servers accepting custom HTTP verbs, as common in some IoT device settings. You can use the hookRouteCustom combinator for this.

New CSRF protection

While I liked the SafeAction based CSRF protection a lot which generated custom (unguessable) endpoints for sensitive requests on demand, it came with problems because the sessions were no longer serializable and became quite large in some cases. Thus we now implement the common csrf protection mechanism by providing a csrf token per session and (optionally) automatically checking for it in all HTTP requests that are not GET, HEAD, OPTIONS or custom. Spock will look for the token in a configurable post parameter or in a configurable HTTP header.

New session storage system

We now allow interchangeable session storage systems, which allows you to replace the stm based implementation with for instance a redis based one. This is very useful if you have a cluster of webservers running that should share session state of users across workers. Essentially you will need to provide an implementation by filling the record SessionStore and passing it to the Spock configuration.

data SessionStore sess tx
   = SessionStore
   { ss_runTx :: forall a. tx a -> IO a
   , ss_loadSession :: SessionId -> tx (Maybe sess)
   , ss_deleteSession :: SessionId -> tx ()
   , ss_storeSession :: sess -> tx ()
   , ss_toList :: tx [sess]
   , ss_filterSessions :: (sess -> Bool) -> tx ()
   , ss_mapSessions :: (sess -> tx sess) -> tx ()
   }

Other changes

Removal of untyped routing

The untyped routing has fully been removed from Spock. There’s really no downside on using the type-safe api.

Split of packages

We’ve split the Spock package into Spock and Spock-core. If you are using features like sessions and/or database pooling then Spock is the right package for you. Spock-core is only a small package providing the basic wiring and combinators. We are planning on splitting out more features to make them reusable in other projects.

Multiple bug fixes

There are several bugs fixed and we’ve moved to some standard packages like cookie instead of our homegrown solution which should improve the stability of Spock.

Closing thoughts

Getting ready for a new release was a lot of work, but now it’s ready and I am curious to know what you think! Please send me an email or comment on Reddit or Hacker News. We’ve also already migrated TramCloud (sorry, German) to this version heavily relying on Spock-api and GHCJS.

Taking Authentication to the next Level

Sun, 23 Aug 2015 21:20:00 +0000

I’ve just released a new version of Spock: 0.9.0.0. Along with some small improvements a big feature has dropped: Contexts. Let’s take a look at them and how they can help out in an authentication scenario.

What are ‘Contexts’?

A context is a value that lives during a request. When a request arrives at your application, the context will be initialized with (). Hence the type of the basic route wiring monad SpockT m a which is an alias for SpockCtxT () m a. Inside your wired routes (ActionCtxT () m a) monad you can now access the context using the getContext :: MonadIO m => ActionCtxT ctx m ctx function. Let’s take a look at this:

import Web.Spock.Safe

main :: IO ()
main =
   runSpock 5000 $ spockT $
   get "some-action" $
   do () <- getContext
      text "Context was (). Boring!"

Now this isn’t really much news and it does not seem very useful. That’s why you can now register prehooks, that is actions that run before contained wired routes:

import Web.Spock.Safe
import Data.Monoid
import qualified Data.Text as T

main :: IO ()
main =
   runSpock 5000 $ spockT $
   do get "some-action" $
        do () <- getContext
           text "Context was (). Boring!"
      prehook (return 42) $
        get "other-action" $
        do magicNumber <- getContext
           text "And the magic number is: " <> (T.pack $ show magicNumber)

We’ve now hooked an action return 42 before our get "other-action" route. The type of prehook :: forall m ctx ctx'. MonadIO m => ActionCtxT ctx m ctx' -> SpockCtxT ctx' m () -> SpockCtxT ctx m () might seem a little bit complicated at first sight, but it really is not: You supply the action that runs in the current context ctx and return a new context ctx'. Then you supply new routes that will work on that context ctx'. The type “inside” the prehook in our example above would be SpockCtxT Int m a and getContext will thus return an Int.

Authentication

Prior contexts

Up to recently, authentication in Spock was tiring and not very safe from a programmers point of view. You had to define functions like

requireUser :: (User -> ActionT m a) -> ActionT m a
requireUser action =
   do sess <- readSession
      mUser <- getUserFromSession sess
      case mUser of
         Nothing -> text "Sorry, no access!"
         Just user -> action user

requireAdmin :: (Admin -> ActionT m a) -> ActionT m a
-- ...

and remember to use them in all your routes that you wanted protected. It would even make your code a little bumpy when combined with route parameters:

main :: IO ()
main =
   runSpock 5000 $ spockT $
   do get "public" $ text "Everyone can and should see me!"
      get "some-action" $ requireUser $ \_ ->
        text "Great, you are authed."
      get ("action" <//> var) $ \postId -> requireUser $ \user ->
        text ("User " <> userName user <> " requested " <> postId)
      get "admin-panel" $ requireAdmin $ \_ ->
        text "Hi admin!"
      get "all-customers" $
        do allCustomersWithSecretData <- getCustomers
           json allCustomersWithSecretData
      -- ...

Oops, we even forgot to write requireUser for the /all-customers route, so now even not logged in users can access all our customers and their secret data. Not good!

This approach has several problems:

Not very DRY: we have to write requireUser around every route we want protected
One can not easily see (types!) if a route should only run if the user is logged in (e.g. getCustomers has the type ActionCtxT ctx m [Customers] and can thus be run in any action)
Error prone

The new world

Contexts make authentication very elegant. Let’s dive right into code - you’ll need the hvect package in at least version 0.3.0.0.

Defining hooks

Instead of defining an requireUser like function, we will define a hook for use in the prehook function.

import Data.HVect
import Web.Spock.Safe

authHook :: ActionCtxT (HVect xs) m (HVect (User ': xs))
authHook =
    do oldCtx <- getContext
       sess <- readSession
       mUser <- getUserFromSession sess
       case mUser of
           Nothing -> text "Sorry, no access!"
           Just user -> return (user :&: oldCtx)

HVect is a heterogenous strict list, learn more about heterogenous collections here

This hook will extend any HVect xs context and insert the current User into it. If the current user is not logged in the request will be aborted with text "Sorry, no access!" like above. If we like to ensure that a user is administrator too, we can extend the hook by using another hook:

data IsAdmin = IsAdmin

adminHook :: ListContains n User xs => ActionCtxT (HVect xs) m (HVect (IsAdmin ': xs))
adminHook =
    do oldCtx <- getContext
       let user = findFirst oldCtx
       if userIsAdmin user
       then return (IsAdmin :&: oldCtx)
       else text "Sorry, you are not administrator!"

We indicate at type level that this route needs a User in the context and will add IsAdmin to the context. Using findFirst we extract the first (and only) occurence of the User in our context and check if he is an administrator.

To bootstrap everything, we need to lift the default context () to HVect '[]:

initHook :: ActionCtxT () m (HVect '[])
initHook = return HNil

Wiring it together

Now that we’ve written hooks it is time to wire them with our routes:

main :: IO ()
main =
   runSpock 5000 $ spockT $
   prehook initHook $
   do get "public" $ text "Everyone can and should see me!"
      prehook authHook $
        do get "some-action" $
             text "Great, you are authed."
           get ("action" <//> var) $ \postId ->
             do user <- liftM findFirst getContext
                text ("User " <> userName user <> " requested " <> postId)
           get "all-customers" $
             do allCustomersWithSecretData <- getCustomers
                json allCustomersWithSecretData
           prehook adminHook $
             get "admin-panel" $ text "Hi admin!"
      -- ...

Great! No more requireUser all over the place. Now let’s make sure that the getCustomers function can only be called when a user is logged in:

getCustomers :: ListContains n User xs => ActionCtxT (HVect xs) m [Customers]

ListContains n t xs is a TypeFamily that indicates that the type t is contained at position n in the type level list xs.

Now if we try to use getCustomers in an action/route outside of the prehook authHook (e.g. "public"), we will get a type error! And even better: We can use getCustomers inside the prehook adminHook too, because our ListContains predicates will simply compose. (Side note: you can also indicate that a type t should not be contained in the list using NotInList t xs ~ 'True)

Closing Notes

That’s it for now - if you are looking for a larger example check out funblog’s Web.Blog module which I’ve recently updated to demonstrate usage. If you find the documentation of Spock lacking in any way or you run into a bug, please feel free to create an issue on Github.

Comments

Looking forward to your Feedback on Reddit and HackerNews.

Type-safe routing in Spock

Sun, 19 Apr 2015 17:10:00 +0000

Since version 0.7 Spock features a new routing system that enables more type-safe code while still being relatively simple and lightweight.

For backwards compatibility, Spock still supports old-style routing. Users can choose to use it by importing Web.Spock.Simple or to use the new one by going with Web.Spock.Safe.

In this post, I will show how to declare routes using the new routing system and discuss its advantages. For comparison, here’s an example site implemented with old-style routing:

{-# LANGUAGE OverloadedStrings #-}

module Main where

import Web.Spock.Simple
import Data.Monoid ((<>))
import Data.Text (pack)

main :: IO ()
main = 
  runSpock 8080 $ spockT id $ do
    get "/" $
      html "<a href='/calculator/313/+/3'>Calculate 313 + 3</a>"
    get ("hello" <//> ":name") $ do
      name <- param' "name"
      text $ "Hello " <> name <> "!"
    get ("calculator" <//> ":a" <//> "+" <//> ":b") $ do
      a <- param' "a"
      b <- param' "b"
      text $ pack $ show (a + b :: Int)

This example contains three pages:

/hello/simon – greets Simon
/calculator/313/+/3 – 316
/ – links to the calculator page above

The first problem with this code is that handling of parameters in URLs is too repetitive. Declaring a parameter requires one to choose an identifier, which you must later repeat to get the value of the argument with param'. Mistyping the identifier of a parameter results is a mistake which is not caught by the type checker.

The new routing system solves this issue:

{-# LANGUAGE OverloadedStrings #-}

module Main where

import Web.Spock.Safe
import Data.Monoid ((<>))
import Data.Text (pack)

main :: IO ()
main = 
  runSpock 8080 $ spockT id $ do
    get root $
      html "<a href='/calculator/313/+/3'>Calculate 313 + 3</a>"
    get ("hello" <//> var) $ \name ->
      text $ "Hello " <> name <> "!"
    get ("calculator" <//> var <//> "+" <//> var) $ \a b ->
      text $ pack $ show (a + b :: Int)

In this example, the position of parameters in paths are declared with var. When a route is matched, the parsed parameter values are passed as Haskell arguments to the handler function in the order in which they occur in the route.

But there’s still something wrong with this code. Let’s say, I’ve decided that I like prefix notation better and renamed /calculator/313/+/3 to calculator/plus/313/3. But, of course, I forgot to update the target of the link! So now the visitors of my site are getting 404s and writing me lots of emails. Not good.

The solution to this problem are bidirectional routes, which can be used both for matching requests and for generating URLs. We can then declare routes only once, which ensures that links never get out of sync with the routing code. In Spock, the function renderRoute is used to instantiate a route with some parameters:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DataKinds #-}

module Main where

import Web.Spock.Safe
import Data.Monoid
import Data.Text (pack, Text)

helloR :: Path '[Text]
helloR = "hello" <//> var

addR :: Path '[Int, Int]
addR = "calculator" <//> var <//> "+" <//> var

main :: IO ()
main =
  runSpock 8080 $ spockT id $ do
    get root $
      html $ "<a href='" <> renderRoute addR 313 3 <> "'>Calculate 313 + 3</a>"
    get helloR $ \name ->
      text $ "Hello " <> name <> "!"
    get addR $ \a b ->
      text $ pack $ show (a + b)

How it works

The datatype of routes in Spock is indexed over the list of parameter types: Path :: [*] -> *. Here’s how values of this type are constructed:

The empty path is root :: Path '[].
For creating static path segments there is static :: String -> Path '[]. With OverloadedStrings string literals can be used: "blog" instead of static "blog".
Parameter path segments are created with var :: (Typeable a, PathPiece a) => Path '[a]. The parameter type a must instantiate PathPiece for serialization and deserialization. For implementation reasons, Typeable a is also required (which is automatically generated for all data types in GHC >= 7.10).
Paths can be concatenated with <//> :: Path as -> Path bs -> Path (Append as bs) (Append is ++ for type-level lists).

Route handlers for GET requests can be installed with

get :: MonadIO m => Path as -> HVectElim as (ActionT m ()) -> SpockT m ()

There are also post, delete, put, head, patch functions corresponding to other HTTP methods. HVectElim as x is the type of a function that takes as arguments values of the types as :: [*] and produces an x :: *:

HVectElim '[a,b,c,d] x ≡ a -> (b -> (c -> (d -> x)))

Finally, routes can be serialized with

renderRoute :: Path as -> HVectElim as Text

Internally, all route handlers are stored in a tree-like structure which can be efficiently queried for matches.

A note on type-checking

One small disadvantage of the new routing system is that code won’t compile before all parameters are used in a handler. For example

    get ("calculator" <//> var <//> "+" <//> var) $ \a b ->
      text "Haven't finished writing this handler!"

doesn’t type check because the compiler can’t infer a concrete type for the parameters a and b. One way to solve this is to use ScopedTypeVariables:

    get ("calculator" <//> var <//> "+" <//> var) $ \(a :: Int) (b :: Int) ->
      text "Haven't finished writing this handler!"

Another possibility is to provide an explicit type annotation for the route (requires DataKinds):

    get ("calculator" <//> var <//> "+" <//> var :: Path '[Int, Int]) $ \a b ->
      text "Haven't finished writing this handler!"

Finally, one can use the type synonym Var a for Route '[a] to annotate parameter segments:

    get ("calculator" <//> (var :: Var Int) <//> "+" <//> (var :: Var Int)) $ \a b ->
      text "Haven't finished writing this handler!"

Discussion

Many routing libraries are concerned with parsing and serializing URLs to an application-specific datatype of routes. For example, with web-routes-boomerang one would define the following data type for the example site:

data Example = Root
             | Hello Text
             | Add Int Int
             deriving (Eq, Show)

In Yesod, this data type and all corresponding functions are generated with Template Haskell:

mkYesod "Example" [parseRoutes|
  / RootR GET
  /hello/#Text HelloR GET
  /calculator/#Int/+/#Int AddR GET
|]

In the case of web-routes-boomerang, the user has to define a reversible parsing function using the boomerang DSL. This approach is more flexible than Yesod’s or Spock’s. For example, suppose one has defined

data Sitemap = ... | Article Int String

It is totally possible to map this constructor to the route /article/int-string with web-routes-boomerang. In Yesod or Spock, each parameter position is delimited by a slash and one would have to define

data ArticleIdentifier = ArtId Int String

and provide an instance of PathPiece ArticleIdentifier to get the same result. This in turn would require a change of the routes data type.

Another advantage of data type based routing systems is that the totality checker can ensure that every declared route is handled by the application.

Conclusion

In large applications, data type based routing has some benefits. In comparison to the old system, Spock’s new routing system leads to more concise and type safe code. It doesn’t require enabling tons of Haskell extensions, learning a new syntax or a DSL for writing bidirectional parsers. Because of its small API, it fits Spock’s goal to be a framework that users can get started with very quickly.

Type-safe routing is implemented in the reroute package and can be used independently of Spock.

Welcome to the Spock Homepage

Thu, 02 Apr 2015 17:25:00 +0000

Today I am launching the website for the Haskell web framework Spock. Currently, there is a short homepage to market the framework, a beginners tutorial and some helpful links. Over time I plan to add more tutorials and will write about releases and new features. Guest posts are welcome, too. If you have anything you’d like to share about Spock (that can be technical or just an experience report), feel free to contact me at mail@athiemann.net.

For now, enjoy the site and the framework - hope to see you back soon!