websockets-rpc
===============

A simple message-based streaming RPC mechanism built using WebSockets

## Usage

The idea is pretty simple:

- A client initiates the RPC call to a server with a `Subscription`
- the client may send additional data at any time with `Supply`, who can also cancel the RPC call
- the server may respond incrementally with `Reply`
- the server finishes the RPC call with a `Complete`

```
client                                                         server
    ------------------------subscribe--------------------------->
    - - - - - - - - - - - - -supply - - - - - - - - - - - - - - >
    < - - - - - - - - - - - -reply- - - - - - - - - - - - - - - -
    <-----------------------complete-----------------------------
```

if the `supply` and `reply` parts were ommitted, it would be identical to a traditional RPC mechanism.


### Example

```haskell
import Network.WebSockets.RPC
import Data.Aeson

-- subscriptions from client to server
data MySubDSL = Foo
  deriving (FromJSON, ToJSON) -- you should figure this part out :)

-- supplies from client to server
data MySupDSL = Bar
  deriving (FromJSON, ToJSON)

-- replies from server to client
data MyRepDSL = Baz
  deriving (FromJSON, ToJSON)

-- onCompletes from server to client
data MyComDSL = Qux
  deriving (FromJSON, ToJSON)
```


Server:

```haskell
{-# LANGUAGE NamedFieldPuns, ScopedTypeVariables #-}


myServer :: (MonadIO m, MonadThrow m) => ServerAppT (WebSocketServerRPCT MySubDSL MySupDSL m)
myServer = rpcServer $ \RPCServerParams{reply,complete} eSubSup -> case eSubSup of
  Left Foo -> do
    forM_ [1..5] $ \_ -> do
      liftIO $ threadDelay 1000000
      reply Baz
    complete Qux
  Right Bar -> reply Baz
```

Client:

```haskell
{-# LANGUAGE NamedFieldPuns #-}


myClient :: (MonadIO m, MonadThrow m) => ClientAppT (WebSocketClientRPCT MyRepDSL MyComDSL m) ()
myClient = rpcClient $ \dispatch ->
  -- only going to make one RPC call for this example
  dispatch RPCClient
    { subscription = Foo
    , onReply = \RPCClientParams{supply,cancel} Baz -> do
        liftIO $ threadDelay 1000000
        supply Bar
        (q :: Bool) <- liftIO getRandom
        if q then cancel else pure ()
    , onComplete = \Qux -> liftIO $ putStrLn "finished"
    }
```

> the `threadDelay` calls are just to exemplify the asynchronisity of the system, nothing to do with avoiding race conditions >.>


To turn the `ServerAppT` and `ClientAppT` into natural [WebSockets](https://hackage.haskell.org/package/websockets)
types, use the morphisms from [Wai-Transformers](https://hackage.haskell.org/package/wai-trasformers).


## Contributing

this is my swamp