websockets-rpc: Simple streaming RPC mechanism using WebSockets

[ bsd3, library, web ] [ Propose Tags ]

Please see the README on Github at https://github.com/athanclark/sparrow-server#readme


[Skip to Readme]
Versions 0.0.0, 0.0.1, 0.0.2, 0.1.0, 0.1.1, 0.2.0, 0.3.0, 0.3.1, 0.4.0, 0.4.1, 0.5.0, 0.5.1, 0.6.0, 0.7.0
Dependencies aeson, async, base (>=4.10 && <5.0), bytestring, containers, exceptions, hashable, monad-control, mtl, QuickCheck, stm, text, transformers, unordered-containers, uuid, wai-transformers, websockets (>=0.12), websockets-simple (>=0.1.0) [details]
License BSD-3-Clause
Copyright BSD-3
Author Athan Clark
Maintainer athan.clark@gmail.com
Category Web
Home page https://github.com/athanclark/websockets-rpc#readme
Bug tracker https://github.com/athanclark/websockets-rpc/issues
Source repo head: git clone https://github.com/athanclark/websockets-rpc
Uploaded by athanclark at Fri Mar 16 01:52:16 UTC 2018
Distributions NixOS:0.7.0
Downloads 2346 total (165 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2018-03-16 [all 3 reports]
Hackage Matrix CI

Modules

  • Network
    • WebSockets
      • Network.WebSockets.RPC
        • Network.WebSockets.RPC.ACKable
        • Trans
          • Network.WebSockets.RPC.Trans.Client
          • Network.WebSockets.RPC.Trans.Server
        • Network.WebSockets.RPC.Types

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for websockets-rpc-0.7.0

[back to package description]

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

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:

{-# 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:

{-# 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 types, use the morphisms from Wai-Transformers.

Contributing

this is my swamp