Type-Safe Microservices in Haskell with Servant

10.05.2016 NOTE! The post was updated with the latest servant-0.7
code, but some bugs might be still left. PRs are welcome!

Microservices were becoming a hot thing few years ago and it seems
they are still on the rise.

It always surprised me how brave developers are: at one moment they
just decide to introduce hundreds contracts of network-separated APIs
without having any static proof that it “works well together”. I have
no idea how others are solving this problem, but was interested in
trying it out in Haskell.

This repository is a tutorial (with working code) of super-small
service called OwlCloud. It is implemented mostly via
Servant framework.

I will try to explain how things look like for those who don’t do
Haskell every day (I believe most Haskellers could easily do the same
anyway).

WARNING! While being small, the service is still almost real-world,
contains a lot of features, so it has quite a lot of boilerplate. The
purpose is to show that it’s not THAT much boilerplate as for a
service having all these features.

Architecture overview

                                      +--------------------------------------+   +----------------+
                                 +--->+ Users microservice (/api/users/*)    +---> Users storage  |
                                 |    +-------------+------------------------+   +----------------+
                                 |                  ^
+-----------+      +-------------+                  |
|  Request  +----->+ Front End  ||                  |
+-----------+      +-------------+                  |
                                 |                  |
                                 |    +-------------+------------------------+   +----------------+
                                 +--->+ Albums microservice (/api/albooms/*) +---> Albums storage |
                                      +--------------------------------------+   +----------------+

Request hits a Front-End. Front-end will act as a proxy which only
knows prefix of each microservice’s public part of API (starts with
/api/), and proxies request to it. It won’t try to do any other job.

Each microservice is a REST app, which has public (/api/*) and
private (/private-api/*) parts. Private parts don’t do any
security-checks regarding their requestor, as they’re assumed to be
inside secured network. Additional security could be done in future if
needed.

Users microservice will have these end-points:

• /api/users/owl-in/ — accept POST-request with a json-document
  like {"whoo": "user", "passwoord": "who?"}, and return signin
  token (a string)
• /api/users/owl-out — accepts HTTP header Authorization with
  token to check a user, and signs them out (forgets this token)
• /private-api/users/token-validity/:token — returns a validity
  response if token is still good or not. This is an example of inner
  API, used by other microservices to not work with database directly,
  but rather ask this microservice if user’s token is valid

Albums microservice will look quite simple:

• /api/albooms/ — will check user for a correct Authorization
  header via Users microservice, and in case of success will render
  list of albums with photos inside (should I create a microservice
  for photos to make things more interesting?)

  Should accept sortby query parameter, which is either whoolest
  (owl for “coolest”), or date.

Installation and Running

If you’re curious to play a bit with this repo’s code, here are the
instructions.

1. Install haskell stack tool.
2. Run stack build inside project root (right next to this README)

To run, open 3 terminals and run these commands in them:

stack exec owlcloud-front
stack exec owlcloud-users
stack exec owlcloud-albums

Alternatively, if you have my par tool
installed, you can just run:

par "stack exec owlcloud-front" "stack exec owlcloud-users" "stack exec owlcloud-albums"

If stack doesn’t work for you, you can try cabal-only-instructions.

Code overview: projects layout

There are 4 cabal projects in root of this project: owlcloud-front,
owlcloud-lib, owlcloud-users and owlcloud-albums.

-front will correspond to front-end proxy, -lib contains shared
code like routes, types, and common utilities.

-users and -albums are purely microservices.

Routes

In Servant, type-safety of your REST API is taken to the extreme. This
means that type expresses not only path of your route, but also types
of its dynamic pieces, query-parameters, type of data passed through
request-body, expected headers, format and type of
return-value. Sounds impressive, isn’t it?

But how does it look like, exactly? Well, it’s far from looking as an
intuitive DSL, but it’s good-enough to not want to write one, imho.

The code for routes resides in
owlcloud-lib/src/OwlCloud/Types.hs.

Servant API expects you to first describe routes “in types”, and then
connect them with your routes where you want to. So, you can
“implement” your routes several times, just as you can write multiple
functions of some type. This lets us describe API for each
microservice, and then combine them in bigger API.

type OwlCloudAPI = UsersAPI :<|> AlbumsAPI

This is a central type, which describes all our APIs. We have two
type-synonyms for each microservice, and then smash them together with
a type-level combinator :<|>. Using type-synonyms means that our
type-errors might (and will!) become nasty, and rather suitable for
experienced haskeller’s brain, but nothing very special to Servant is
needed, just a general Haskell type-error-resolving experience.

We don’t actually use this type, since our front-end proxy just blindly
proxies requests by their prefixes, but having OwlCloudAPI might be
useful for documentation and type-checking purposes. You might also
combine your microservices in one big service for purposes of testing
locally, but it’s not in scope of this tutorial.

So, types for Users microservice will look like this:

type UsersAPI =
  "api" :> "users" :> "owl-in" :> ReqBody '[JSON] LoginReq :> Post '[JSON] SigninToken :<|>
  "api" :> "users" :> Authorized ("owl-out" :> Post '[JSON] ()) :<|>
  "private-api" :> "users" :> "token-validity" :> Capture "token" SigninToken :> Get '[JSON] TokenValidity
newtype SigninToken = SigninToken Text
    deriving (ToJSON, FromJSON, FromHttpApiData, ToHttpApiData, Ord, Eq)
data LoginReq = LoginReq
    { whoo      :: Text
    , passwoord :: Text }
    deriving (Generic)
data TokenValidity = TokenValidity
    { isValid :: Bool }
    deriving (Generic, Show)
instance FromJSON LoginReq
instance ToJSON LoginReq
instance FromJSON TokenValidity
instance ToJSON TokenValidity

That’s a big piece of code. Let’s look closer.

Again, we have individual routes combined together with :<|> at the
end of each line.

First route looks like this:

  "api" :> "users" :> "owl-in" :> ReqBody '[JSON] LoginReq :> Post '[JSON] SigninToken

It corresponds (as you might have guessed) to route
/api/users/owl-in. ReqBody '[JSON] LoginReq tells that Servant
will take a request body, requiring a Content-Type: application/json
header in your request, decode it as a JSON decoder (it can support
multiple, if you put more in list) into LoginReq type, and pass it
as a parameter to your handler, which we’ll see later.

Post '[JSON] SigninToken tells us that we’ll respond to
POST-reuqest, we’ll respond in JSON with a SigninToken datatype.

Wow, whole bunch of information about our route, and all that encoded
in mostly-readable type-level representation. Neat!

Second route:

  "api" :> "users" :> Authorized ("owl-out" :> Post '[JSON] ())

Everything should be clear except that Authorized function-like
thing. What’s that? It’s a type-synonym I defined at the bottom of the
same file:

type Authorized t = Header "Authorization" SigninToken :> t

So, if you replace a type-synonym, your route will look like:

  "api" :> "users" :> Header "Authorization" SigninToken :> "owl-out" :> Post '[JSON] ()

Every resource, which wants to access data of some user, will have to
send a SigninToken, which is just a newtype around Text, and put
it under Authorization header.

Last route is:

  "private-api" :> "users" :> "token-validity" :> Capture "token" SigninToken :> Get '[JSON] TokenValidity

New part is Capture here. It just tells that we have a dynamic part
of a route /private-api/users/token-validity/<dynamic-part-here>,
which will be captured and passed as a param into our handler.

Albums microservice types should look quite familiar now:

type AlbumsAPI =
  "api" :> "albooms" :> Authorized (QueryParam "sortby" SortBy :> Get '[JSON] [Album])
data Album = Album [Photo]
    deriving (Generic)
data Photo = Photo
    { description :: Text
    , image       :: URL }
    deriving (Generic)
data SortBy
    = SortByWhoolest
    | SortByDate
instance FromJSON Photo
instance ToJSON Photo
instance FromJSON Album
instance ToJSON Album
instance FromHttpApiData SortBy where
    parseQueryParam "whoolest" = Right SortByWhoolest
    parseQueryParam "date" = Right SortByDate
    parseQueryParam x = Left ("Unknown sortby value:" <> x)
instance ToHttpApiData SortBy where
    toQueryParam SortByWhoolest = "whoolest"
    toQueryParam SortByDate = "date"

We capture a sortby param, which you will pass as ?sortby=date at
the end of your url.

Here you can also see manual implementation of FromHttpApiData
type-class: it’s used to encode/decode url piece value into your
datatype.

Handlers

We’ve covered routes, now we can show how our handlers look
like. Let’s begin with a Users microservice.

Code resides at
./owlcloud-users/src/Main.hs file.

Let’s begin with some machinery to combine individual handlers into
UsersAPI type, and then generation of a
wai Application type. WAI
is a set of contracts, which describe a “reusable haskell web
application interface”. It’s similar to Python’s WSGI, if you’re
familiar with that. After you have a WAI Application, you can run it
with a haskell web-server of your choice. We’ll use
warp, which is as fast as
nginx (and sometimes faster!).

server :: Server UsersAPI
server = owlIn :<|> owlOut :<|> tokenValidity
usersAPI :: Proxy UsersAPI
usersAPI = Proxy
app :: Application
app = serve usersAPI server

First thing to notice is that we use a new operator :<|> from
Servant, which is a value-level operator (never confuse with :<|>,
haha). It combines individual handlers together, and type-system then
checks that type of overall expression matches UsersAPI. Errors are
somewhat big, as type-synonyms are expanded with not too much help to
us, but if you’ll look careful enough — you’ll be able to figure
thing out.

Now, to individual handlers:

owlIn :: LoginReq -> ExceptT ServantErr IO SigninToken
owlIn LoginReq{..} =
    case (whoo, passwoord) of
      ("great horned owl", "tiger") -> do
          uuid <- liftIO UUID.nextRandom
          let token = SigninToken (UUID.toText uuid)
          liftIO $ atomically $
              modifyTVar db $ \s ->
                s { validTokens = Set.insert token (validTokens s) }
          return token
      _ -> throwE (ServantErr 400 "Username/password pair did not match" "" [])

They start with our /api/users/owl-in handler. We begin with
something which amazes me about Servant already: you get your
route-parameters as…function parameters!

So, no more silly manual extraction of data from some big Request
type: you get what you asked for, and you get it via function
parameters. Servant handles the rest for you.

Now, since we don’t use a real database for purpose of this tutorial,
we’ll just allow single login/password pair: (“great horned owl”,
“tiger”). If it matches, we are generating a SigninToken and put it
into a global STM-variable db. It resides inside
Common.hs, if you’re interested
looking at actual implementation, but in real-world app it’ll probably
just be a database. For curious, type of our database is this:

data State = State
    { validTokens :: Set SigninToken
    , albumsList  :: [Album] }
db :: TVar State
db = unsafePerformIO (unsafeInterleaveIO (newTVarIO (State Set.empty initialAlbums)))

Yes, we use a global variable in Haskell, and sometimes it makes
sense, and it’s dangerous (as indicated by the scary names).

If you enter wrong credentials, we will respond with a 400-code
error, and a help-message describing the reason. You can add some
response body, and additional headers if you want to, but I don’t.

Error is returned in this interesting way:

throwE (ServantErr 400 "Username/password pair did not match" "" [])

This
throwE
combinator from transformers package, is something which converts
some error-type e into a ExceptT e m a type. The reason we’re
using it is because Servant uses type ExceptT ServantErr IO a for
our handlers. It’s a small
Monad Transformer
stack on top of IO, which allows explicit short-circuiting via
ServantErr type, denoting failure.

Our owl-out handler just removes your token from our imaginary database:

owlOut :: Maybe SigninToken -> ExceptT ServantErr IO ()
owlOut mt = do
    checkAuth mt
    maybe (return ()) out mt
  where
    out token = liftIO $ atomically $ modifyTVar db $ \s ->
                  s { validTokens = Set.delete token (validTokens s) }
checkAuth :: Maybe SigninToken -> ExceptT ServantErr IO ()
checkAuth = maybe unauthorized runCheck
  where
    runCheck (SigninToken token) = do
        state <- liftIO $ atomically $ readTVar db
        let isMember = Set.member (SigninToken token) (validTokens state)
        unless isMember unauthorized
    unauthorized =
        throwE (ServantErr 401 "You are not authenticated. Please sign-in" "" [])

Last handler is an inner API to check token validity:

tokenValidity :: SigninToken -> ExceptT ServantErr IO TokenValidity
tokenValidity token = do
    state <- liftIO $ atomically $ readTVar db
    return (TokenValidity (Set.member token (validTokens state)))

Finally, we run our app on port 8082. Of course, this should be
stored in some environment variable or config in real-world:

main :: IO ()
main = run 8082 app

We use run from Warp web-server mentioned before.

The Albums microservice shouldn’t be much harder to understand. Just
one end-point, no need for glueing with :<|> operator:

server :: Manager -> Server AlbumsAPI
server = albums

Also notice that we’ll need to pass a Manager value in order to have
connection-pooling and caching when we speak to other
microservices. It’s created in main and just passed in parameters.

Handler:

albums :: Manager -> Maybe SigninToken -> Maybe SortBy -> ExceptT ServantErr IO [Album]
albums mgr mt sortBy = do
    checkValidity mgr mt
    state <- liftIO $ atomically $ readTVar db
    return (albumsList state)

We don’t do any actual sorting here, GHC will tell us about this via
Warning of unused sortBy variable (how many frameworks tell you your
GET-parameters from your API description are not used?).

Now, the interesting part is the checkValidity function. We put it
in Common.hs, since it’d be reused by other microservices in the
future. It will do a request to the Users microservice, check the validity of
a token, and show an error if needed.

checkValidity :: Manager
              -> Maybe SigninToken
              -> ExceptT ServantErr IO ()
checkValidity mgr =
    maybe (throwE (ServantErr 400 "Please, provide an authorization token" "" []))
          (\t -> fly (apiUsersTokenValidity t mgr usersBaseUrl) >>= handleValidity)
  where
    handleValidity (TokenValidity True) = return ()
    handleValidity (TokenValidity False) =
        throwE (ServantErr 400 "Your authorization token is invalid" "" [])

You already understand all the left ... parts which just return
errors. But what’s fly (apiUsersTokenValidity t), exactly?

Let’s make a new sub-header in this tutorial so it’s easier to find.

Requesting other microservices

Servant gives you a mechanism to request other services in a type-safe
manner. What you need to do, is to “unpack” your type-level API
definition into individual request-routes (also in Common.hs):

apiUsersOwlIn :<|> apiUsersOwlOut :<|> apiUsersTokenValidity =
    client (Proxy::Proxy UsersAPI)
apiAlbumsList =
    client (Proxy::Proxy AlbumsAPI)

The scary Proxy::Proxy UsersAPI part is just to move things from
type-level to value-level world. This is usually done when you’re
already able to extract all needed information from just a type, but
you need to do some actions with it at the value-level world.

So, we deconstructed some special-built structure (via client
function) into individual routines, which are able to request other
microservices.

Their types take usual route arguments, and are returning something of
type ExceptT ServantError m a. So, these values are not some
descriptions, but rather actions themselves, and they do the hard job
of requesting microservices for you. Cool!

Notice the
ServantError
type. It’s not the
ServantErr
type we’ve seen before, used to short-circuit from handler. Rather,
it’s a REST-client-response error, which might happen if, say, your
microservice is down or responded with an error.

So we implement a special fly function, which will convert the response
from one possible error (microservice-request error) into another: the one
which we will send to our users, plus some logging.

fly :: (Show b, MonadIO m)
    => ExceptT ServantError m b
    -> ExceptT ServantErr m b
fly apiReq = do
  res <- lift (runExceptT apiReq)
  either logAndFail return res
  where
    logAndFail e = do
        liftIO (putStrLn ("Got internal-api error: " ++ show e))
        throwE internalError
    internalError = ServantErr 500 "CyberInternal MicroServer MicroError" "" []

There you go, now you know how that type-safe microservice-requesting
machinery works. Wasn’t that hard, wasn’t it!

Last bit: front-end

Now, the last bit is to write a front-end. Code is located at
owlcloud-front/src/Main.hs file.

I admit, I didn’t implement a bullet-proof fully-functional proxy
which handles everything in a streaming fashion (sombody, please do
so, would be a useful tutorial, and shouldn’t take too much code),
it’s just not what I intend to do in this tutorial, but this one
shouldn’t be bad in terms of performance.

We define our app as:

app :: Manager -> Application
app mgr req respond =
    case pathInfo req of
        ("api":"users":_) -> microservice "http://localhost:8082/"
        ("api":"albooms":_) -> microservice "http://localhost:8083/"
        _ -> respond (responseLBS status404 [] ",,,(o,o),,,\n ';:`-':;' \n   -\"-\"-   \n")
  where
    microservice = microserviceProxy mgr req respond

We look at request-path, if it begins with /api/users, we
micro-forward it to “http://localhost:8082/“ (hardcode!). Same for
/api/albooms end-point.

We use a wreq package to do
actual requests:

microserviceProxy :: Manager -> Request -> (Network.Wai.Response -> IO b) -> Text
                  -> IO b
microserviceProxy mgr req respond basePath = do
    let opts = W.defaults & W.manager .~ Right mgr
                          & W.headers .~ requestHeaders req
                          & W.params .~ getReqParams req
        url = basePath <> T.intercalate "/" (pathInfo req)
    tryProxying opts url `catch` onErr
  where
    tryProxying opts url = do
      r <- case requestMethod req of
             "GET" -> W.getWith opts (toString url)
             "POST" -> requestBody req >>= W.postWith opts (toString url)
      respond (responseLBS (r ^. W.responseStatus) (r ^. W.responseHeaders)
                 (r ^. W.responseBody))
    onErr (StatusCodeException s hdrs _) = respond (responseLBS s hdrs "")
    onErr e = do
      putStrLn ("Internal error: " ++ show e)
      respond (responseLBS status500 [] "Internal server error")

We just re-build a request from the request we received ourselves, and
then respond with the response we receive. We implement GET and
POST methods only, but you’ve got the idea for others.

Last bit — running our front-end:

main :: IO ()
main = do
    mgr <- newManager defaultManagerSettings
    run 8081 (app mgr)

We create a wreq manager, which handles keep-alived connections (to
not re-connect to microservice on each request) for us, and just run
the web-server.

That’s it. That was easy, wasn’t it?

Testing

Let us look how it works.

➜  ~  curl -i -XGET -H "Content-Type: application/json" -H "Authorization: badtoken" localhost:8083/api/albooms/
HTTP/1.1 400 Your authorization token is invalid
Transfer-Encoding: chunked
Date: Sat, 12 Sep 2015 09:07:19 GMT
Server: Warp/3.1.3
➜  ~  curl -i -XPOST -H "Content-Type: application/json" --data '{"whoo": "great horned owl", "passwoord": "tiger"}' localhost:8081/api/users/owl-in
HTTP/1.1 201 Created
Transfer-Encoding: chunked
Transfer-Encoding: chunked
Date: Sat, 12 Sep 2015 09:07:36 GMT
Server: Warp/3.1.3
Content-Type: application/json
"88255ebf-2dca-4638-b037-639fb762f6e0"
➜  ~  curl -i -XGET -H "Content-Type: application/json" -H "Authorization: 88255ebf-2dca-4638-b037-639fb762f6e0" localhost:8083/api/albooms/
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Date: Sat, 12 Sep 2015 09:07:48 GMT
Server: Warp/3.1.3
Content-Type: application/json
[[{"image":"http://i.imgur.com/PuhhmQi.jpg","description":"Scating"},{"image":"http://i.imgur.com/v5kqUIM.jpg","description":"Taking shower"}],[{"image":"http://i.imgur.com/3hRAGWJ.png","description":"About to fly"},{"image":"http://i.imgur.com/ArZrhR6.jpg","description":"Selfie"}]]

Conclusion

We just saw how easy it is to write some boilerplate to use The
Microservice Architecture, keeping our type-safety for us and our
future team mates happy.

I hope you enjoyed it.

Please, send your PRs improving both code and tutorial if you feel
like doing that.