First of all, you should check out the user guide if you are not familiar with WebGear. This is a short blog post and I won’t be covering everything in detail.

Haskell for HTTP APIs

Most APIs accept some input from the HTTP request, perform a bunch of validations and operations, and then respond with some data retrieved from a backend such as a database or other services. Haskell has some unique strengths that makes this whole process robust.

I strongly believe in making illegal states unrepresentable in the types and techniques like “parse, don’t validate”. Haskell is well-suited for this style of programming and WebGear implements some of these ideas in building HTTP APIs.

Type Safety

Haskell’s type system makes it possible to encode concepts at type level and WebGear makes good use of this. For example, here is a handler:

-- Use this handler for a route such as: PUT /api/widget/<widgetId>
putWidgetHandler :: Have [ Method PUT
                         , PathVar "widgetId" Int
                         , JSONRequestBody Widget
                         , BasicAuth
                         ] req
                 => Handler req Widget
putWidgetHandler = ...

This handler can only be used with requests with a PUT method and a URL path variable named widgetId with an Int value. It is a compile time error otherwise, here is an example:

• The request doesn't have the trait ‘Method 'PUT’.

  Did you use a wrong trait type?
  For e.g., ‘PathVar "foo" Int’ instead of ‘PathVar "foo" String’?

  Or did you forget to apply an appropriate middleware?
  For e.g. The trait ‘JSONRequestBody Foo’ can be used with ‘jsonRequestBody @Foo’ middleware.

Middlewares “parse” the request and express traits such as HTTP method as a type level list. The trait attributes can be extracted from the request in a type safe manner:

type WidgetId = PathVar "widgetId" Int

putWidgetHandler :: Has WidgetId req => Handler req Widget
putWidgetHandler = Kleisli $ \request -> do
  -- wid has type Int
  let wid = get (Proxy @WidgetId) request
  ...

You cannot access the widget ID unless you have a Has WidgetId constraint in the type signature. And to satisfy this constraint, you must use the pathVar middleware which verifies the presence of such a path variable in the request.

You don’t need to know a lot of advanced haskell features to use WebGear. Using Has or Have constraints and the get function with a Proxy is enough to get you going.

Composable Handlers

Composition is a key tool to manage complexity. The ability to split code into reusable pieces and combine them at will is the foundation on which we build all our software. WebGear shines really well in this. Handlers are regular functions and you can just use function composition.

For example, if you have a number of routes that use the same basic authentication, you can extract that as a common authentication middleware.

allRoutes :: Handler req Widget
allRoutes = basicAuth "realm" checkCredentials
            $ getWidget <|> putWidget

getWidget :: Has BasicAuth req => Handler req Widget
getWidget = ...

putWidget :: Has BasicAuth req => Handler req Widget
putWidget = ...

This also shows a prominent difference between WebGear and Servant. Servant uses type level combinators to implement such functionality. This helps to derive a server, client, documentation etc from the same type definition. But composition at type level is not as easy to deal with as value level composition. Error messages are often cryptic and this is a big barrier to entry for newcomers. You also have to resort to techniques like servant-flatten to workaround problems caused by nested types.

WebGear on the other hand uses functions which can be composed trivially. The trade-off is that you cannot generate client and documentation from WebGear middlewares and handlers, they only build a server.

Building Middlewares

Often you would want to build your own traits and middlewares. This is straightforward in WebGear.

Let us take an example. Many microservices use Correlation IDs to trace a transaction across many services. This is done by sending a special HTTP header - Correlation-ID - in every request and response. All services include this correlation ID in their logs. The first request in the transaction obviously will not receive the header and should generate a random ID instead.

How do we implement this in WebGear? We start by defining a data type for correlation IDs and implement the Trait type class for it.

data CorrelationId = CorrelationId ByteString

instance MonadIO m => Trait CorrelationId Request m where
  type Attribute CorrelationId Request = CorrelationId
  type Absence CorrelationId Request = Void

  toAttribute :: Request -> m (Result CorrelationId Request)
  toAttribute req = do
    let h = requestHeader "Correlation-ID" req
    Found . CorrelationId <$> maybe randomUUID pure h

The Trait type class has two associated types - Attribute and Absence. Attribute is the type of the trait attribute and Absence is an error type for the case when correlation ID is missing. In this case, we always have a correlation ID, either from the request or a randomly generated one. So we use CorrelationId as the Attribute and Void as Absence.

The toAttribute function returns a CorrelationId either from the Correlation-ID header or generating a random UUID.

Next, let us build a middleware that uses CorrelationId:

withCorrelationId :: MonadIO m
                  => RequestMiddleware' m req (CorrelationId : req) a
withCorrelationId handler = Kleisli $ \request -> do
  result <- probe @CorrelationId request
  either absurd runHandler result
  where
    runHandler request = do
      let CorrelationId cid = get (Proxy @CorrelationId) request
      response <- runKleisli handler request
      pure $ setResponseHeader "Correlation-ID" cid response

The probe function checks the presence of CorrelationId and the result is an Either value with the Left indicating Absence and the Right indicating an Attribute.

We know that CorrelationId is always present and will not have a Left case indicating absence of the trait. But most other traits are “optional” and have to deal with a case where they are absent from the request. So probe returns an Either value to indicate this.

The absurd function from Data.Void module is used to handle the Left case that will never occur.

For the positive case where we have a correlation ID, runHandler invokes the handler and then adds the correlation ID to the response.

We can use this middleware with any of the handlers:

allRoutes :: Handler req ByteString
allRoutes = withCorrelationId
            $ putWidget <|> deleteWidget

putWidget :: Has CorrelationId req => Handler req ByteString
putWidget = method @PUT $ Kleisli $ \request -> do
  let cid = get (Proxy @CorrelationId) request
  ...

Summary

Hopefully this post has convinced you that WebGear can build type safe APIs without requiring a PhD in type theory. The user-facing parts of the library is built with care to not require many advanced Haskell concepts. You can find code, examples, and much more about WebGear in the Github repo.

Patterns

Patterns are ubiquitous in Haskell code; it is one of the first things you learn as you get familiar with the language. Almost every piece of Haskell code will have a pattern match construct in a function definition or case expression. However, they have some limitations as well.

As an example, let us look at how to represent identifiers:

import qualified Data.Text as Text
import Data.Text (Text)

newtype Identifier = Identifier { unIdentifier :: Text }
  deriving Eq

We can construct values of type Identifier with the Identifier data constructor (e.g. Identifier "foo"). You can deconstruct an identifier in two ways:

identifierLength1 :: Identifier -> Int
identifierLength1 = Text.length . unIdentifier

identifierLength2 :: Identifier -> Int
identifierLength2 (Identifier s) = Text.length s

Having both a record field accessor and a pattern matching syntax is very useful. We can pick the best one depending on the usage.

A curious case

How would you implement case-insensitive identifiers? In such a case, Identifier "foo" and Identifier "Foo" are considered equal. We must retain the original case in the data type though. Many other use cases - such as displaying the identifier with the original input case - require that.

Well, it turns out not too complicated. We can do this:

import Data.Function(on)

newtype Identifier = Identifier { unIdentifier :: Text }

instance Eq Identifier where
  (==) = (==) `on` (Text.toCaseFold . unIdentifier)

This is as expressive as the previous implementation. We still have the same data constructor and pattern matching at the usage sites. It has one serious drawback though - performance. Text.toCaseFold is evaluated for each equality check which makes this a slow operation.

A performance fix

Here is one way to solve the performance problem:

data Identifier = Identifier
  { unIdentifier :: Text
  , folded       :: Text
  }

makeIdentifier :: Text -> Identifier
makeIdentifier s = Identifier
  { unIdentifier = s
  , folded       = Text.toCaseFold s
  }

instance Eq Identifier where
 (==) = (==) `on` folded

This moves the expensive Text.toCaseFold to record construction so that we don’t pay a penalty on each == evaluation. This covers the common use case where the identifier is constructed once and then the equality check is performed many times on it. In fact, this is the implementation used by the case-insensitive package.

However, we lost the nice symmetric data constructor and pattern match we had in the previous solution. We want to hide the internal details of Identifier record from the usage sites. So we are forced to provide a smart constructor makeIdentifier instead and hide the Identifier data constructor. This also means we cannot pattern match on the Identifier data constructor anymore. The only way to deconstruct an identifier is via the unIdentifier function which is less expressive than the previous solution.

PatternSynonyms to the rescue

This is where pattern synonyms come in. We can use a pattern synonym to define this “missing” pattern. Here is the syntax:

{-# LANGUAGE PatternSynonyms #-}

data Identifier = MkIdentifier
  { unIdentifier :: Text
  , folded       :: Text
  }

instance Eq Identifier where
 (==) = (==) `on` folded

pattern Identifier :: Text -> Identifier
pattern Identifier s <- MkIdentifier s _ where
  Identifier s = MkIdentifier s (Text.toCaseFold s)

There are two components to this pattern synonym. First, we define how to use Identifier in pattern matches. The part:

pattern Identifier s <- MkIdentifier s _

tells GHC to replace a pattern match on Identifier s with MkIdentifier s _. For e.g., a case expression like this:

case ident of
  Identifier s -> ...

gets translated to:

case ident of
  MkIdentifier s _ -> ...

The second part:

Identifier s = MkIdentifier s (Text.toCaseFold s)

tells GHC to replace all occurrences of Identifier s in expressions with the corresponding MkIdentifier s (Text.toCaseFold s) expression. For e.g., a let expression like this:

let ident = Identifier s
in ...

gets translated to:

let ident = MkIdentifier s (Text.toCaseFold s)
in ...

Here is how the complete solution:

module Identifiers
  ( Identifier
  , pattern Identifier
  ) where

import           Data.Text (Text)
import qualified Data.Text as Text
import           Data.Function (on)

data Identifier = MkIdentifier
  { unIdentifier :: Text
  , folded       :: Text
  }

instance Eq Identifier where
 (==) = (==) `on` folded

pattern Identifier :: Text -> Identifier
pattern Identifier s <- MkIdentifier s _ where
  Identifier s = MkIdentifier s (Text.toCaseFold s)

The MkIdentifier data constructor and all its internal implementation details are hidden away but the usage sites still can use the nice Identifier s patterns for data construction and pattern matching. Clearly, this is a good improvement from the previous solution and retains all the performance benefits of it.

Note that there are other ways to declare pattern synonyms. See GHC documentation for more details. You might also be interested in the Data.Sequence module that makes good use of pattern synonyms along with the ViewPatterns extension.

If you have not already gone through the previous post, please do so for context. All the code discussed in this post is available at https://gitlab.com/rkaippully/polysemy-password-manager/tree/part2.

Running Effects

So far we have seen how to define an effect as a data type and how to embed such effect values in the Sem monad. But those effects were not “doing” anything. It’s all nice to have a good looking program, but what is the point if it does not do something? How do we run the code so that we have a real password manager?

It is not hard to run effects. Remember me saying that the r in Sem r a is a list of effects? We pick the first effect from that list and find a function that can handle that effect and eliminate it from the list. For example, if we have a program of type Sem [e1, e2] a, we must find a function that will interpret the e1 effect. Applying that function will consume the e1 effect and give us a value of type Sem [e2] a. Repeat this with an interpreter for e2 and you get a Sem [] a. This is a value with no effects. You can use the run function to get the value out of it.

Let us see how this works in practice.

Interpreting CryptoHash

The first step is to define an interpreter for the CryptoHash effect that we defined. We’ll use the BCrypt algorithm to manipulate password hashes as defined in the cryptonite library. The hashPassword and validatePassword functions in cryptonite seem to correspond to the MakeHash and ValidateHash data constructors of CryptoHash.

There is a function named interpret in polysemy that lets you handle an effect such as CryptoHash.

In the first round, we’ll implement ValidateHash.

runCryptoHashAsState :: Sem (CryptoHash : r) a -> Sem r a
runCryptoHashAsState = interpret $ \case
  ValidateHash password hash -> return (validatePassword password hash)

As you can see, interpret takes a function as its only parameter. This function has to transform a CryptoHash m x value into a Sem r x value.

Also, pay close attention to the type signature Sem (CryptoHash : r) a -> Sem r a. You might recall that the first type parameter to Sem is a type-level list of effects. Here (CryptoHash : r) is a list of effects with CryptoHash at its head and r as the tail - the remaining effects. After running the interpret function we eliminate the CryptoHash effect from the type (because it has been interpreted) and return a Sem r a.

Interpreting ValidateHash is straightforward. We just delegate the call to validatePassword and lift the result into Sem r monad.

Effect Dependencies

Interpreting MakeHash via hashPassword is trickier. The type signature of hashPassword is MonadRandom m => Int -> Password -> m PasswordHash. We need to run the hashing in a monad that allows random number generation. One choice is to run it in IO monad. But that will cause our Sem r to be polluted with IO. This will allow some other piece of code in this monad to run arbitrary IO actions. Let us avoid it if we can.

Another choice is to use a pseudo-random number generator with a deterministic random number generator (DRG) initialized by a seed value. If we have access to such a DRG, we can use withDRG function to run hashPassword in a MonadRandom context. But every time we use a DRG, its internal state gets updated and we get a new DRG value. So we need a mechanism to store this updated DRG and pass it to the next MakeHash usage.

This is where State effect comes in. We can use it to retrieve the current value of DRG. Then we invoke withDRG to generate a password hash. This invocation will also return an updated DRG which we’ll save back into the State effect.

The code looks like this:

MakeHash password -> do
  drg <- get
  let (h, drg') = withDRG drg (hashPassword 10 password)
  put drg'
  return h

We managed to interpret the CryptoHash effect but that requires a State effect. We express this in the type signature of runCryptoHashAsState function:

runCryptoHashAsState :: (DRG gen, Member (State gen) r)
                     => Sem (CryptoHash : r) a
                     -> Sem r a
runCryptoHashAsState = interpret $ \case
  ValidateHash password hash -> return (validatePassword password hash)
  MakeHash password          -> do
    drg <- get
    let (hash, drg') = withDRG drg (hashPassword 10 password)
    put drg'
    return hash

The constraint Member (State gen) r indicates that the State gen effect must be present in the list of effects r. We need to find an interpreter for State gen, but let us leave that for later.

Let us go to the next effect we have - KVStore.

Interpreting KVStore

Let us use an SQLite database to store the password hashes. We will assume we have a table named passwords with two columns username and hash to store the data. Interpreting a KVStore with this table is easy:

runKVStoreAsSQLite :: Member (Embed IO) r
                   => Sem (KVStore Username PasswordHash : r) a
                   -> Sem (Input Connection : r) a
runKVStoreAsSQLite = reinterpret $ \case
  LookupKV username -> do
    conn <- input
    hashes <- embed (queryNamed conn
                      "SELECT hash FROM passwords WHERE username = :username"
                      [":username" := username])
    return (fromOnly <$> listToMaybe hashes)
  UpdateKV username maybeHash -> do
    let (query, params) =
      case maybeHash of
        Just hash -> ( "INSERT INTO passwords (username, hash) " <>
                       "VALUES (:username, :hash) " <>
                       "ON CONFLICT (username) DO UPDATE SET hash = excluded.hash"
                     , [":username" := username, ":hash" := hash] )
        Nothing   -> ( "DELETE FROM passwords WHERE username = :username"
                     , [":username" := username] )
    conn <- input
    embed (executeNamed conn query params)

The structure of this handler is similar to the previous one for CryptoHash. But there are some important differences.

First, we make use of the sqlite-simple package for the DB operations. Actions provided by this library run in the IO monad. We have to somehow incorporate that into our interpretation. Polysemy allows embedding arbitrary monadic actions into the Sem monad via the Embed constraint. The Member (Embed IO) r constraint indicates that we have embedded IO monadic actions in the Sem monad. In the code, we can use the embed function to “lift” an IO operation into the Sem monad. This is analogous to liftIO in monad transformers.

Second, we need a database connection to execute our operations. In the case of CryptoHash, a State effect was used because of the need to get and update the DRG. In this case, the DB connection is just an input. Hence, we make use of Input effect instead. We use the input function to get a connection and use it for DB operations.

Third, we are using the function reinterpret here instead of interpret. There is a subtle but important difference - interpret handles and eliminates an effect, while reinterpret merely translates one effect to another. The runCryptoHashAsState handler converted a Sem (CryptoHash : r) a value into a Sem r a value; the CryptoHash effect was eliminated. But runKVStoreAsSQLite handler converts a Sem (KVStore Username PasswordHash : r) value into a Sem (Input Connection : r) a value. The KVStore effect just got reencoded as an Input effect.

But runCryptoHashAsState had a dependency on State effect and that was expressed as a type constraint. How is that different from reinterpret reencoding the KVStore effect?

There are two differences. The Member (State gen) r constraint merely says State gen is one of the effects in r. It can be located anywhere in the list r which means that this effect can be handled in an arbitrary order. The handlers for CryptoHash and State gen are only loosely related to each other. But when reinterpret reencodes an effect into another one, the new effect is added at the head of the effect list and has to be handled next. Typically, the handlers for KVStore Username PasswordHash and Input Connection will get invoked in that order. This shows that they are logically related; both these effects together represent the storage system for the data.

It is also crucial to note that there is a one-to-one correspondence between the two effects in reinterpret. Every time a KVStore effect is handled by runKVStoreAsSQLite handler, a new Input Connection effect is added to the list of effects. If our program had two separate key-value stores, it will need two separate connection inputs as well. This makes sense because we don’t want the data in those two stores mixed up. But there is no such one-to-one correspondence in the Member constraint introduced by runCryptoHashAsState. If we had two CryptoHash handlers, one using bcrypt and another using scrypt, the same DRG can be shared for both. So only one handler for State gen is necessary for any number of CryptoHash handlers.

Final Steps

With all this, we are ready for a complete implementation of our operations. Here is how to implement addUser:

runAddUser :: Username -> Password -> IO ()
runAddUser username password = do
  drg <- getSystemDRG
  withConnection dbFile $ \conn ->
    {-
       Handle effects one by one. The comments on each line indicates
       the list of effects yet to be handled at that point.
    -}
    addUser username password  -- [CryptoHash, KVStore Username Password]
      & runCryptoHashAsState   -- [KVStore Username Password, State gen]
      & runKVStoreAsSQLite     -- [Input Connection, State gen, Embed IO]
      & runInputConst conn     -- [State gen, Embed IO]
      & evalState drg          -- [Embed IO]
      & runM

We get a DRG and a DB connection through the IO monad. Then we start handling the effects in addUser username password. Notice how some effect handlers (such as runCryptoHashAsState) adds new effects to the “pending” list. Eventually, we are left with a Sem [Embed IO] a value. The runM function can convert that to an IO a value.

Some of the handlers are defined in polysemy library itself - you can find the definitions of runInputConst and evalState here and here respectively.

The validatePassword implementation is along similar lines and is left as an exercise for you.

Testing Effects

Polysemy also helps us in writing tests for our effects. We can provide alternate effect handlers in the test code and test our effects for correctness and coverage.

below is such an implementation. Note that this code is pure and does not require the IO monad.

runAddUser :: DRG gen
           => gen
           -> Map Username PasswordHash
           -> Username
           -> Password
           -> Map Username PasswordHash
runAddUser drg m username password =
  addUser username password  -- [CryptoHash, KVStore Username Password]
    & runCryptoHashAsState   -- [KVStore Username Password, State gen]
    & runKVStorePurely m     -- [State gen]
    & evalState drg          -- []
    & run
    & fst

This function takes a map of user names and hashes, performs the add operation, and returns the resultant map. A test can validate that the output map contains expected entries.

For a more interesting example, see https://gitlab.com/rkaippully/polysemy-password-manager/blob/part2/test/Spec.hs

Summary

That was a whirlwind tour of implementing effect handlers. Obviously, there is a lot more functionality in polysemy. The library documentation is quite detailed and informative. Go check it out!

Context

There have been a lot of discussions about free/freer monads and extensible effects in the Haskell community for quite a while now. There is plenty of information about these subjects out there but I could not find a good getting started guide for a practical application. I had a good grasp of how to use monad transformers and mtl; I was naturally curious about a practical application of effects.

I found this example code after some searching around. This guided me in the right direction and gave me the confidence to rewrite one of my tools using polysemy. After a few days of struggle with compiler errors, I managed to rewrite the app completely and also added enough tests. The entire experience was very rewarding and I learned a lot from it. At the same time, I could have done this a lot quicker if there was some sort of a beginners tutorial. What better way to fill that gap than by writing one myself now that I have some idea about the topic?

So here we are building a real-world application, at least as real-world as it can get in a blog post. Enjoy the ride!

My goal is not to show you how free/freer monads work under the hood or how they compare against alternatives. There are other articles available discussing those topics. I’ll focus on the usage of polysemy instead.

All the code discussed in this post is available at https://gitlab.com/rkaippully/polysemy-password-manager/tree/part1.

The password manager

Your boss asks you to build a password manager for securely storing usernames and passwords. You discuss the requirements in detail with your boss. He wants to add a username and password to the password store and also check if a given username and password combination is valid. Pretty standard stuff, so you get cracking.

You quickly write a spec in pseudo-code and show it to your boss for confirmation. He says that seems right-ish. And you are ready to go!

addUser username password = do
    hashedPassword <- makeHash password
    insertInStore username hashedPassword

validatePassword username password = do
    hashInStore <- lookupInStore username
    case hashInStore of
      Just h  -> validateHash password h
      Nothing -> return False   -- user not found

The spec is straightforward. To add a user, you hash the password and insert the username and the hash to some kind of storage. To validate a password, you first retrieve the hash for the user and then validate that the given password matches the hash.

Of course, this is not real Haskell code and won’t even compile if you try to. We haven’t specified how to generate a hash from a password or how to store and retrieve the data. But the intention is to specify the high-level idea and leave the lower level details for later implementation.

But what if I told you that you can use this spec (with very minor tweaks) as your real application code? That’d be very handy! After all, the spec is very concise and makes it so easy to convey ideas with others. Adding implementation details will clutter it up.

Polysemy lets you use such clutter-free code as your real implementation. We will see how that is done very soon. But first, let us set up a project.

Setting up a project

Polysemy is not present in a stackage LTS snapshot at the time of writing this. So I use:

$ stack new polysemy-password-manager --resolver nightly-2019-07-27

Polysemy recommends various language extensions and settings, Let us enable all that. You can see my configuration here.

The project settings are ready, let us get back to work!

What are effects?

For our purposes, an effect is anything that is outside the contours of a pure function. Typically, they are modeled as monads. For example, you might have optional values (Maybe), short-circuiting on errors (Either), read-only environment (Reader), logging (Writer), etc. While all these monads are useful, you almost always want to use more than one of them in your programs. For example, I want to read a configuration file and pass it as a read-only environment to my application code (aka Reader) and I want the application to do logging (aka Writer).

Unfortunately, monads do not compose in general. There is no general way to pick any two arbitrary monads and combine them to produce a composed monad. There are many solutions to this problem. Monad transformers are probably the most popular one in Haskell community. A composable effects library such as polysemy is another one.

If you examine the spec above, you’ll notice that it uses two effects. I’ll call them CryptoHash and KeyValueStore respectively. The CryptoHash effect handles the makeHash and validateHash operations while the KeyValueStore effect handles insertInStore and lookupInStore.

The CryptoHash effect

Generating a hash from an input is usually a pure function. But a good hashing scheme will also add a randomly generated salt to avoid rainbow table attacks. This makes it an effectful computation.

Let us see how to model this effect in polysemy.

-- A few type definitions to get started
newtype Username = Username ByteString
newtype Password = Password ByteString
newtype PasswordHash = PasswordHash ByteString

data CryptoHash m a where
  -- | Generates a hash from a password
  MakeHash :: Password -> CryptoHash m PasswordHash
  -- | Check if a password matches a hash
  ValidateHash :: Password -> PasswordHash -> CryptoHash m Bool

makeHash :: Member CryptoHash r => Password -> Sem r PasswordHash
makeHash x = send (MakeHash x :: CryptoHash (Sem r) PasswordHash)

validateHash :: Member CryptoHash r => Password -> PasswordHash -> Sem r Bool
validateHash password hash = send (ValidateHash password hash :: CryptoHash (Sem r) Bool)

There is quite a bit of stuff going on here. Let’s analyze it line by line.

First, we define a new data type named CryptoHash for our effect as a GADT. It takes two type parameters - m and a. The first one m represents a monad and a represents the return value of the operations. We also have two data constructors MakeHash and ValidateHash that correspond to the operations we had in the spec.

Note that CryptoHash is not a monad. It is just a regular data type. So we cannot use MakeHash and ValidateHash directly as monadic values in our code.

This is where the functions makeHash and validateHash come in. They convert a value of type CryptoHash (Sem r) a to a value of type Sem r a using the send function from polysemy[1]. Sem r is a monad. So we can use that value in a monadic style.

You are probably confused now. What exactly is this Sem monad? What does the Member CryptoHash r constraint in the type signatures mean?

The Sem monad

With polysemy, you write all your code in one monad - the Sem monad - regardless of the effects you deal with. The type parameter r in Sem r a is a type-level list of effects. For example, in our application we could use Sem [CryptoHash, KeyValueStore k v] a or Sem [KeyValueStore k v, CryptoHash] a. We are only interested to check whether the CryptoHash effect is present in the list r so that we can make use of it. We don’t care about its exact position on the list or whether there are other effects on the list. So instead of specifying a hardcoded list of effects such as Sem [CryptoHash, KeyValueStore k v] a, we use Member CryptoHash r => Sem r a to indicate that we have some unknown list of effects r and we require CryptoHash to be present in that list.

In case you are working with multiple effects you can use the Members constraint to avoid repetition. For example, Members [CryptoHash, KeyValueStore k v] r => Sem r a is same as (Member CryptoHash r, Member (KeyValueStore k v) r) => Sem r a. It says r is some list of effects and both CryptoHash and KeyValueStore k v effects are present in that list.

Sem monad is defined here as data Sem r a and Sem r is a monad. We can use it with the do notation just like any other monad. More importantly, we can work on multiple effects with just this one monad. Let us see how.

The KeyValueStore effect

The second effect we wanted was KeyValueStore. Unlike CryptoHash we do not have to define it. Polysemy comes with a standard set of effects in the polysemy package and some additional ones in the polysemy-zoo package. KVStore is one of them. We can use writeKV in place of insertInStore and lookupKV in place of lookupInStore.

Writing operations with Polysemy

So here is how we can rewrite the spec into valid Haskell code with polysemy.

addUser :: Members [CryptoHash, KVStore Username PasswordHash] r
        => Username
        -> Password
        -> Sem r ()
addUser username password = do
    hashedPassword <- makeHash password
    writeKV username hashedPassword

validatePassword :: Members [CryptoHash, KVStore Username PasswordHash] r
                 => Username
                 -> Password
                 -> Sem r Bool
validatePassword username password = do
    hashInStore <- lookupKV username
    case hashInStore of
      Just h  -> validateHash password h
      Nothing -> return False

This is the “business logic” of our application. Notice how close it is to the original spec. This is very useful for analyzing, refactoring, and reasoning about the core of your application in general.

Sem monad lets you compose multiple monadic effects in a type-safe manner. Members constraint in the type signature specifies the effects being used in the code and you can rest assured that the code is not making use of an effect not mentioned in the constraints.

The implementation details are intentionally kept out of this code. We have not specified where and how we’ll store the data because the KVStore effect does not define it. Similarly, we have not chosen the password hashing algorithm because CryptoHash does not specify one. All such implementation decisions (interpretations in polysemy-speak) can be done at a later stage. This also allows you to choose different implementations in different contexts. For example, we may choose to use a database to store the data in a real application. But an in-memory dictionary might be sufficient for testing the application.

Conclusion

Hopefully, this was a useful introduction of how to use polysemy to build the core parts of an application. I will explain how to write implementations of effects in the next part of this series.