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

:: (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 (Either ErrorObj (Maybe r))

Returns Right Nothing if could not parse response.

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

Send notification. Will not block.

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

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

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 true in 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

Generic Ver

NFData Ver

type Rep Ver