Network.JsonRpc

Introduction

This JSON-RPC library is fully-compatible with JSON-RPC 2.0 and 1.0. It provides an interface that combines a JSON-RPC client and server. It can set and keep track of request ids to parse responses. There is support for sending and receiving notifications. You may use any underlying transport. Basic TCP client and server provided.

A JSON-RPC application using this interface is considered to be peer-to-peer, as it can send and receive all types of JSON-RPC message independent of whether it originated the connection.

Server Example

This JSON-RPC server returns the current time.

{-# LANGUAGE OverloadedStrings #-}
import Control.Applicative
import Data.Aeson.Types hiding (Error)
import Data.Conduit.Network
import Data.Time.Clock
import Data.Time.Format
import Network.JsonRpc
import System.Locale

data TimeReq = TimeReq
data TimeRes = TimeRes { timeRes :: UTCTime }

instance FromRequest TimeReq where
    parseParams "time" = Just $ const $ return TimeReq 
    parseParams _ = Nothing

instance ToJSON TimeRes where
    toJSON (TimeRes t) = toJSON $ formatTime defaultTimeLocale "%c" t

respond :: Respond TimeReq IO TimeRes
respond TimeReq = Right . TimeRes <$> getCurrentTime

main :: IO ()
main = jsonRpcTcpServer V2 (serverSettings 31337 "::1") respond dummySrv

Client Example

Corresponding TCP client to get time from server.

{-# LANGUAGE OverloadedStrings #-}
import Control.Concurrent
import Control.Concurrent.STM
import Control.Monad
import Control.Monad.Trans
import Data.Aeson
import Data.Aeson.Types hiding (Error)
import Data.Conduit.Network
import qualified Data.Text as T
import Data.Time.Clock
import Data.Time.Format
import Network.JsonRpc
import System.Locale

data TimeReq = TimeReq
data TimeRes = TimeRes { timeRes :: UTCTime }

instance ToRequest TimeReq where
    requestMethod TimeReq = "time"

instance ToJSON TimeReq where
    toJSON TimeReq = emptyArray

instance FromResponse TimeRes where
    parseResult "time" = Just $ withText "time" $ \t -> case f t of
        Just t' -> return $ TimeRes t'
        Nothing -> mzero
      where
        f t = parseTime defaultTimeLocale "%c" (T.unpack t)
    parseResult _ = Nothing

req :: JsonRpcT IO UTCTime
req = sendRequest TimeReq >>= liftIO . atomically >>= \ts -> case ts of
    Left e -> error $ fromError e
    Right (Just (TimeRes r)) -> return r
    _ -> error "Could not parse response"

main :: IO ()
main = jsonRpcTcpClient V2 (clientSettings 31337 "::1") dummyRespond .
    replicateM_ 4 $ req >>= liftIO . print >> liftIO (threadDelay 1000000)

Establish JSON-RPC context

type JsonRpcT = ReaderT Session

runJsonRpcT

Arguments

:: (FromRequest q, ToJSON r)

=> Ver

JSON-RPC version

-> Respond q IO r

Respond to incoming requests

-> Sink ByteString IO ()

Sink to send messages

-> Source IO ByteString

Source of incoming messages

-> JsonRpcT IO a

JSON-RPC action

-> IO a

Output of action

Create JSON-RPC session around ByteString conduits from transport layer. When context exits, session stops existing.

Communicate with remote party

sendRequest :: (ToJSON q, ToRequest q, FromResponse r, MonadIO m) => q -> JsonRpcT m (STM (Either ErrorObj (Maybe r)))

Returns Right Nothing if could not parse response. Run output in STM monad. STM will block until response arrives.

sendNotif :: (ToJSON no, ToNotif no, Monad m) => no -> JsonRpcT m (STM ())

Send notification. Run output in STM monad. Will not block.

receiveNotif :: (Monad m, FromNotif n) => JsonRpcT m (STM (Maybe (Either ErrorObj (Maybe n))))

Receive notifications from peer. Returns Nothing if incoming channel is closed and empty. Result is Right Nothing if it failed to parse notification. Run output in STM monad. Will not block.

Transports

Client

jsonRpcTcpClient

Arguments

:: (FromRequest q, ToJSON r)

=> Ver

JSON-RPC version

-> ClientSettings

Connection settings

-> Respond q IO r

Respond to incoming requests

-> JsonRpcT IO a

JSON-RPC action

-> IO a

Output of action

TCP client transport for JSON-RPC.

dummyRespond :: Monad m => Respond () m ()

Respond function for systems that do not reply to requests, as usual in clients.

Server

jsonRpcTcpServer

Arguments

:: (FromRequest q, ToJSON r)

=> Ver

JSON-RPC version

-> ServerSettings

Connection settings

-> Respond q IO r

Respond to incoming requests

-> JsonRpcT IO ()

Action to perform on connecting client thread

-> IO ()

TCP server transport for JSON-RPC.

dummySrv :: MonadIO m => JsonRpcT m ()

Dummy server for servers not expecting client to send notifications, that is most cases.

Requests

data Request

Constructors

Request

Fields

getReqVer :: !Ver

getReqMethod :: !Method

getReqParams :: !Value

getReqId :: !Id

Instances

Eq Request

Show Request

ToJSON Request

FromJSON Request

NFData Request

Parsing

class FromRequest q where

Methods

parseParams :: Method -> Maybe (Value -> Parser q)

Parser for params Value in JSON-RPC request.

Instances

FromRequest ()

FromRequest Value

fromRequest :: FromRequest q => Request -> Maybe q

Encoding

class ToRequest q where

Methods

requestMethod :: q -> Method

Method associated with request data to build a request object.

Instances

ToRequest ()

ToRequest Value

buildRequest

Arguments

:: (ToJSON q, ToRequest q)

=> Ver

JSON-RPC version

-> q

Request data

-> Id

-> Request

Responses

data Response

Constructors

Response

Fields

getResVer :: !Ver

getResult :: !Value

getResId :: !Id

Instances

Eq Response

Show Response

ToJSON Response

FromJSON Response

NFData Response

Parsing

class FromResponse r where

Methods

parseResult :: Method -> Maybe (Value -> Parser r)

Parser for result Value in JSON-RPC response. Method corresponds to request to which this response answers.

Instances

FromResponse ()

FromResponse Value

fromResponse :: FromResponse r => Method -> Response -> Maybe r

Encoding

type Respond q m r = q -> m (Either ErrorObj r)

buildResponse :: (Monad m, FromRequest q, ToJSON r) => Respond q m r -> Request -> m (Either RpcError Response)

Notifications

data Notif

Constructors

Notif

Fields

getNotifVer :: !Ver

getNotifMethod :: !Method

getNotifParams :: !Value

Instances

Eq Notif

Show Notif

ToJSON Notif

FromJSON Notif

NFData Notif

Parsing

class FromNotif n where

Methods

parseNotif :: Method -> Maybe (Value -> Parser n)

Parser for notification params Value.

Instances

FromNotif ()

FromNotif Value

fromNotif :: FromNotif n => Notif -> Maybe n

Encoding

class ToNotif n where

Methods

notifMethod :: n -> Method

Instances

ToNotif ()

ToNotif Value

buildNotif :: (ToJSON n, ToNotif n) => Ver -> n -> Notif

Errors

data RpcError

Constructors

RpcError

Fields

getErrVer :: !Ver

getErrObj :: !ErrorObj

getErrId :: !Id

Instances

Eq RpcError

Show RpcError

ToJSON RpcError

FromJSON RpcError

NFData RpcError

data ErrorObj

Constructors

ErrorObj

Fields

getErrMsg :: !String

getErrCode :: !Int

getErrData :: !Value

ErrorVal

Fields

getErrData :: !Value

Instances

Eq ErrorObj

Show ErrorObj

ToJSON ErrorObj

FromJSON ErrorObj

NFData ErrorObj

fromError :: ErrorObj -> String

Error Messages

errorParse :: Value -> ErrorObj

Parse error.

errorInvalid :: Value -> ErrorObj

Invalid request.

errorParams :: Value -> ErrorObj

Invalid params.

errorMethod :: Method -> ErrorObj

Method not found.

errorId :: Id -> ErrorObj

Id not recognized.

Others

data Message

Constructors

MsgRequest

Fields

getMsgRequest :: !Request

MsgResponse

Fields

getMsgResponse :: !Response

MsgNotif

Fields

getMsgNotif :: !Notif

MsgError

Fields

getMsgError :: !RpcError

Instances

Eq Message

Show Message

ToJSON Message

FromJSON Message

NFData Message

type Method = Text

data Id

Constructors

IdInt

Fields

getIdInt :: !Int

IdTxt

Fields

getIdTxt :: !Text

IdNull

Instances

Enum Id

Eq Id

Read Id

Show Id

Generic Id

ToJSON Id

FromJSON Id

NFData Id

Hashable Id

type Rep Id

data Ver

Constructors

V1

JSON-RPC 1.0

V2

JSON-RPC 2.0

Instances

Eq Ver

Read Ver

Show Ver

NFData Ver