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.

Establish JSON-RPC context

type JsonRpcT = ReaderT Session

runJsonRpcT

Arguments

:: (MonadLoggerIO m, MonadBaseControl IO m)

=> Ver

JSON-RPC version

-> Bool

Ignore incoming requests or notifications

-> Sink Message m ()

Sink to send messages

-> Source m (Either Response Message)

Incoming messages or error responses to be returned to sender

-> JsonRpcT m a

JSON-RPC action

-> m a

Output of action

Create JSON-RPC session around conduits from transport layer. When context exits session disappears.

Conduits for encoding/decoding

decodeConduit :: MonadLogger m => Ver -> Conduit ByteString m (Either Response Message)

encodeConduit :: MonadLogger m => Conduit Message m ByteString

Communicate with remote party

receiveRequest :: MonadLoggerIO m => JsonRpcT m (Maybe Request)

Receive requests from remote endpoint. Returns Nothing if incoming channel is closed or has never been opened.

sendResponse :: MonadLoggerIO m => Response -> JsonRpcT m ()

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

Returns Nothing if did not receive response, could not parse it, or request was a notification. Just Left contains the error object returned by server if any. Just Right means response was received just right.

Transports

Client

jsonRpcTcpClient

Arguments

:: (MonadLoggerIO m, MonadBaseControl IO m)

=> Ver

JSON-RPC version

-> Bool

Ignore incoming requests or notifications

-> ClientSettings

Connection settings

-> JsonRpcT m a

JSON-RPC action

-> m a

Output of action

TCP client transport for JSON-RPC.

Server

jsonRpcTcpServer

Arguments

:: (MonadLoggerIO m, MonadBaseControl IO m)

=> Ver

JSON-RPC version

-> Bool

Ignore incoming requests or notifications

-> ServerSettings

Connection settings

-> JsonRpcT m ()

Action to perform on connecting client thread

-> m a

TCP server transport for JSON-RPC.

Internal data and functions

type SentRequests = HashMap Id (TMVar (Maybe Response))

data Session

Constructors

Session

Fields

inCh :: TBMChan (Either Response Message)

outCh :: TBMChan Message

reqCh :: Maybe (TBMChan Request)

lastId :: TVar Id

sentReqs :: TVar SentRequests

rpcVer :: Ver

initSession :: Ver -> Bool -> STM Session

processIncoming :: (Functor m, MonadLoggerIO m) => JsonRpcT m ()

Requests

data Request

Constructors

Request

Fields

getReqVer :: !Ver

getReqMethod :: !Method

getReqParams :: !Value

getReqId :: !Id

Notif

Fields

getReqVer :: !Ver

getReqMethod :: !Method

getReqParams :: !Value

Instances

Eq Request

Show Request

Arbitrary 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 -> Either ErrorObj q

Encoding

class ToRequest q where

Methods

requestMethod :: q -> Method

Method associated with request data to build a request object.

requestIsNotif :: q -> Bool

Is this request to be sent as a notification (no id, no response)?

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

ResponseError

Fields

getResVer :: !Ver

getError :: !ErrorObj

getResId :: !Id

OrphanError

Fields

getResVer :: !Ver

getError :: !ErrorObj

Instances

Eq Response

Show Response

Arbitrary 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 (Maybe Response)

Errors

data ErrorObj

Constructors

ErrorObj

Fields

getErrMsg :: !String

getErrCode :: !Int

getErrData :: !Value

ErrorVal

Fields

getErrData :: !Value

Instances

Eq ErrorObj

Show ErrorObj

Arbitrary ErrorObj

ToJSON ErrorObj

FromJSON ErrorObj

NFData ErrorObj

fromError :: ErrorObj -> String

Error messages

errorParse :: ByteString -> 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

Instances

Eq Message

Show Message

Arbitrary Message

ToJSON Message

FromJSON Message

NFData Message

type Method = Text

data Id

Constructors

IdInt

Fields

getIdInt :: !Int

IdTxt

Fields

getIdTxt :: !Text

Instances

Enum Id

Eq Id

Read Id

Show Id

Generic Id

Arbitrary Id

ToJSON Id

FromJSON Id

NFData Id

Hashable Id

type Rep Id

fromId :: Id -> String

data Ver

Constructors

V1

JSON-RPC 1.0

V2

JSON-RPC 2.0

Instances

Eq Ver

Read Ver

Show Ver

Generic Ver

Arbitrary Ver

NFData Ver

type Rep Ver