Generic + Nested records

[mitchellwrosen]

Hello! I'd like some advice on how to write a nested record suitable for a servant servant and client. Is it possible? Here's what I've discovered so far.

Preamble.

{-# LANGUAGE DataKinds, DeriveGeneric, TypeOperators #-}

import Servant
import Servant.API.Generic
import Servant.Client
import Servant.Client.Generic
import Servant.Server.Generic

Outer API type: has a route, plus a nested API type (Inner).

data Outer route = Outer
  { outer :: route :- Get '[JSON] ()
  , inner :: route :- ToServant Inner AsApi
  } deriving Generic

Inner API type with a couple routes.

data Inner route = Inner
  { foo :: route :- Get '[JSON] ()
  , bar :: route :- Get '[JSON] ()
  } deriving Generic

Generating a server works, but note we have to call genericServer on the inner record as well. It would be great to only have to call this once.

outerServer :: ToServant Outer AsServer
outerServer =
  genericServer Outer
    { outer = pure ()
    , inner = genericServer Inner
        { foo = pure ()
        , bar = pure ()
        }
    }

Generating a client does not work so well. I have to match the inner client with :<|>, which means reverse-engineering the nesting that genericClient makes.

callOuter :: ClientM ()
callInnerFoo :: ClientM ()
callInnerBar :: ClientM ()
Outer
  { outer = callOuter
  , inner = callInnerFoo :<|> callInnerBar
  } = genericClient

Unfortunately this nested record type (my first attempt) does not work.

data Outer route = Outer
  { outer :: route :- Get '[JSON] ()
  , inner :: Inner route
  } deriving Generic

With this we can generate a nice server (note: only call to genericServer).

outerServer :: ToServant Outer AsServer
outerServer =
  genericServer Outer
    { outer = pure ()
    , inner = Inner
        { foo = pure ()
        , bar = pure ()
        }
    }

However, I'm unable to call genericClient at this type due to the equality constraints.

callOuter :: ClientM ()
Outer callOuter _ = genericClient

    • Couldn't match type ‘Client ClientM (Inner AsApi)’
                     with ‘Inner (AsClientT ClientM)’
        arising from a use of ‘genericClient’
    • In the expression: genericClient
      In a pattern binding: Outer callOuter _ = genericClient
   |
64 | Outer callOuter _ = genericClient
   |                     ^^^^^^^^^^^^^

[alpmestan]

IIRC @domenkozar and I figured this out a few months back. Domen, any chance you still have some code/gist/etc around?

[domenkozar]

https://github.com/cachix/cachix/blob/master/cachix/src/Cachix/Client/Commands.hs#L60-L64

[alpmestan]

Thanks! :)

@mitchellwrosen For reference, the records that specify the endpoints that the clients linked to above target are here.

[mitchellwrosen]

Fantastic! Thanks. For anyone who stumbles upon this ticket, here is how to write my Outer client above (pattern matching every API call to the top-level).

callOuter :: ClientM ()
callInnerFoo :: ClientM ()
callInnerBar :: ClientM ()
Outer
  { outer = callOuter
  , inner = 
      fromServant @_ @(AsClientT ClientM) ->
        Inner
          { foo = callInnerFoo
          , bar = callInnerBar
          }
  } = genericClient

There's still that unfortunate bit of boilerplate when using genericServer (it doesn't just fwoop it all in one go), but oh well!

[alpmestan]

Should we leave this open, as a reminder that there's still a bit of boilerplate needed? Might be nice to document it on readthedocs (in the cookbook recipe I suppose) too.

[seanhess]

Does anyone have an example of how to do this for servant-server? The linked example only shows a client.

[mitchellwrosen]

@seanhess Yeah, see my original comment (though there might be a better way).

outerServer :: ToServant Outer AsServer
outerServer =
  genericServer Outer
    { outer = pure ()
    , inner = genericServer Inner
        { foo = pure ()
        , bar = pure ()
        }
    }

[alpmestan]

@mitchellwrosen @domenkozar Would either of you perhaps be interested in augmenting the cookbook recipe about the records+generic based approach, to document how nesting should be handled?

This would allow people (like @seanhess -- hello Sean!) to figure it out without having to find "servant issue 1015" =)

[seanhess]

Thanks @mitchellwrosen, hi @alpmestan!

I’ve managed to follow your example to get a value of ToServant Outer (AsServerT AppM) — where AppM is my monad stack, but I’m still struggling to get serve / hoistServer to work.

It looks like the Proxy should be Proxy (Outer routes) right?

What should these lines look like? It used to be working for a non generic API.

serve (Proxy :: ?) $ hoistServer (Proxy :: ?) nt outer

Where outer is ToServant Outer (AsServerT AppM) and nt is my natural transformation function.

Sorry for the formatting I’m on my phone. And thanks! A working example with generics and ServerT would be amazing

[alpmestan]

Does the following work?

type API = ToServant Outer AsApi
...
serve (Proxy :: Proxy API) $ hoistServer (Proxy :: Proxy API) nt outer

?

The idea is that we have different ways to traverse the records and collect the information we want on each endpoint. One per way to interpret APIs. AsApi instructs that ToServant type level computation to look at the Outer record and compile all the "endpoint types" into a single equivalent API type, expressed using :<|> to join the different endpoints together.

[seanhess]

That works, and makes sense, thank you @alpmestan!

Here's a working example for anyone arriving here later (missing imports and function bodies, but it should be enough).

data BaseApi route = BaseApi
    { _info ::     route :- Get '[JSON] Text
    , _accounts :: route :- "accounts" :> ToServantApi AccountsApi
    } deriving (Generic)

data AccountsApi route = AccountsApi
    { _all :: route :- Get '[JSON] [Account]
    , _post :: route :- ReqBody '[JSON] AccountInfo :> Post '[JSON] Account
    , _get :: route :- Capture "id" Text :> Get '[JSON] Account
    , _put :: route :- Capture "id" Text :> ReqBody '[JSON] AccountInfo :> Put '[JSON] Account
    } deriving (Generic)


accountsApi :: ToServant AccountsApi (AsServerT AppM)
accountsApi = genericServerT AccountsApi
    { _all  = undefined
    , _post = undefined
    , _get  = undefined
    , _put  = undefined
    }


baseApi :: ToServant BaseApi (AsServerT AppM)
baseApi = genericServerT BaseApi
    { _info = pure "hello"
    , _accounts = accountsApi
    }


type AppM = ReaderT AppState Handler
data AppState = AppState

nt :: AppState -> AppM a -> Handler a
nt s x = runReaderT x s




apiProxy :: Proxy (ToServant BaseApi AsApi)
apiProxy = Proxy


application :: AppState -> Application
application st = do
    serve apiProxy $ hoistServer apiProxy (nt st) baseApi