Safe Haskell	None
Language	Haskell2010

Network.JsonRpc

Contents

Introduction
Establish JSON-RPC context
Conduits for encoding/decoding
Communicate with remote party
Transports
- Client
- Server
Internal data and functions
Requests
- Parsing
- Encoding
Responses
Others

Synopsis

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 Source

runJsonRpcT Source

Arguments

:: (MonadLoggerIO m, MonadBaseControl IO m)
=> Ver	JSON-RPC version
-> Bool	Ignore incoming requests/notifs
-> Sink ByteString m ()	Sink to send messages
-> Source m ByteString	Source to receive messages from
-> 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 Value) Source

Conduit to decode incoming messages. Left Response indicates a response to send back to sender if parsing JSON fails.

encodeConduit :: (ToJSON j, MonadLogger m) => Conduit j m ByteString Source

Communicate with remote party

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

Receive requests from remote endpoint. Returns Nothing if incoming channel is closed or has never been opened. Will reject incoming request if sent in a batch.

receiveBatchRequest :: MonadLoggerIO m => JsonRpcT m (Maybe BatchRequest) Source

Receive batch of requests. Will also accept single requests.

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

Send response message. Do not use to respond to a batch of requests.

sendBatchResponse :: MonadLoggerIO m => BatchResponse -> JsonRpcT m () Source

Send batch of responses. Use to respond to a batch of requests.

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

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

sendBatchRequest :: (MonadLoggerIO m, ToJSON q, ToRequest q, FromResponse r) => [q] -> JsonRpcT m [Maybe (Either ErrorObj r)] Source

Send multiple requests in a batch. If only a single request, do not put it in a batch.

Transports

Client

jsonRpcTcpClient Source

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 Source

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)) Source

data Session Source

Constructors

Session
Fields inCh :: TBMChan (Either Response Value) outCh :: TBMChan Message reqCh :: Maybe (TBMChan BatchRequest) lastId :: TVar Id sentReqs :: TVar SentRequests rpcVer :: Ver dead :: TVar Bool

initSession :: Ver -> Bool -> STM Session Source

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

Process incoming messages. Do not use this directly unless you know what you are doing. This is an internal function.

sendMessage :: MonadLoggerIO m => Message -> JsonRpcT m () Source

Send any message. Do not use this. Use the other high-level functions instead. Will not track request ids. Incoming responses to requests sent using this method will be ignored.

Requests

data Request Source

Constructors

Request
Fields getReqVer :: !Ver getReqMethod :: !Method getReqParams :: !Value getReqId :: !Id
Notif
Fields getReqVer :: !Ver getReqMethod :: !Method getReqParams :: !Value

Instances

Eq Request
Show Request
Generic Request
Arbitrary Request
ToJSON Request
FromJSON Request
NFData Request
type Rep Request

data BatchRequest Source

Constructors

BatchRequest
Fields getBatchRequest :: ![Request]
SingleRequest
Fields getSingleRequest :: !Request

Instances

Eq BatchRequest
Show BatchRequest
Generic BatchRequest
Arbitrary BatchRequest
ToJSON BatchRequest
FromJSON BatchRequest
NFData BatchRequest
type Rep BatchRequest

Parsing

class FromRequest q where Source

Methods

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

Parser for params Value in JSON-RPC request.

Instances

FromRequest ()
FromRequest Value

fromRequest :: FromRequest q => Request -> Either ErrorObj q Source

Encoding

class ToRequest q where Source

Methods

requestMethod :: q -> Method Source

Method associated with request data to build a request object.

requestIsNotif :: q -> Bool Source

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

Instances

ToRequest ()
ToRequest Value

buildRequest Source

Arguments

:: (ToJSON q, ToRequest q)
=> Ver	JSON-RPC version
-> q	Request data
-> Id
-> Request

Responses

data Response Source

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
Generic Response
Arbitrary Response
ToJSON Response
FromJSON Response
NFData Response
type Rep Response

data BatchResponse Source

Constructors

BatchResponse
Fields getBatchResponse :: ![Response]
SingleResponse
Fields getSingleResponse :: !Response

Instances

Eq BatchResponse
Show BatchResponse
Generic BatchResponse
Arbitrary BatchResponse
ToJSON BatchResponse
FromJSON BatchResponse
NFData BatchResponse
type Rep BatchResponse

Parsing

class FromResponse r where Source

Methods

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

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 Source

Parse a response knowing the method of the corresponding request.

Encoding

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

Type of function to make it easy to create a response from a request. Meant to be used in servers.

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

Create a response from a request. Use in servers.

Errors

data ErrorObj Source

Error object from JSON-RPC 2.0. ErrorVal for backwards compatibility.

Constructors

ErrorObj
Fields getErrMsg :: !String getErrCode :: !Int getErrData :: !Value
ErrorVal
Fields getErrData :: !Value

Instances

Eq ErrorObj
Show ErrorObj
Generic ErrorObj
Arbitrary ErrorObj
ToJSON ErrorObj
FromJSON ErrorObj
NFData ErrorObj
type Rep ErrorObj

fromError :: ErrorObj -> String Source

Get a user-friendly string with the error information.

Error messages

errorParse :: ByteString -> ErrorObj Source

Parse error.

errorInvalid :: Value -> ErrorObj Source

Invalid request.

errorParams :: Value -> ErrorObj Source

Invalid params.

errorMethod :: Method -> ErrorObj Source

Method not found.

errorId :: Id -> ErrorObj Source

Id not recognized.

Others

data Message Source

Constructors

MsgRequest
Fields getMsgRequest :: !Request
MsgResponse
Fields getMsgResponse :: !Response
MsgBatch
Fields getBatch :: ![Message]

Instances

Eq Message
Show Message
Generic Message
Arbitrary Message
ToJSON Message
FromJSON Message
NFData Message
type Rep Message

type Method = Text Source

data Id Source

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 Source

Pretty display a message id. Meant for logs.

data Ver Source

JSON-RPC version.

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