Safe Haskell	None
Language	Haskell2010

Network.JSONRPC

Contents

Introduction

Synopsis

decodeConduit :: forall (m :: Type -> Type). MonadLogger m => Ver -> ConduitT ByteString (Either Response Value) m ()
encodeConduit :: forall j (m :: Type -> Type). (ToJSON j, MonadLogger m) => ConduitT j ByteString m ()
initSession :: Ver -> Bool -> STM Session
jsonrpcTCPClient :: (MonadLoggerIO m, MonadUnliftIO m) => Ver -> Bool -> ClientSettings -> JSONRPCT m a -> m a
jsonrpcTCPServer :: (MonadLoggerIO m, MonadUnliftIO m) => Ver -> Bool -> ServerSettings -> JSONRPCT m () -> m a
processIncoming :: forall (m :: Type -> Type). (Functor m, MonadLoggerIO m) => JSONRPCT m ()
receiveBatchRequest :: forall (m :: Type -> Type). MonadLoggerIO m => JSONRPCT m (Maybe BatchRequest)
receiveRequest :: forall (m :: Type -> Type). MonadLoggerIO m => JSONRPCT m (Maybe Request)
runJSONRPCT :: (MonadLoggerIO m, MonadUnliftIO m) => Ver -> Bool -> ConduitT ByteString Void m () -> ConduitT () ByteString m () -> JSONRPCT m a -> m a
sendBatchRequest :: forall (m :: Type -> Type) q r. (MonadLoggerIO m, ToJSON q, ToRequest q, FromResponse r) => [q] -> JSONRPCT m [Maybe (Either ErrorObj r)]
sendBatchResponse :: forall (m :: Type -> Type). MonadLoggerIO m => BatchResponse -> JSONRPCT m ()
sendMessage :: forall (m :: Type -> Type). MonadLoggerIO m => Message -> JSONRPCT m ()
sendRequest :: forall (m :: Type -> Type) q r. (MonadLoggerIO m, ToJSON q, ToRequest q, FromResponse r) => q -> JSONRPCT m (Maybe (Either ErrorObj r))
sendResponse :: forall (m :: Type -> Type). MonadLoggerIO m => Response -> JSONRPCT m ()
type JSONRPCT = ReaderT Session
type SentRequests = HashMap Id (TMVar (Maybe Response))
data Session = Session {
- inCh :: TBMChan (Either Response Value)
- outCh :: TBMChan Message
- reqCh :: Maybe (TBMChan BatchRequest)
- lastId :: TVar Id
- sentReqs :: TVar SentRequests
- rpcVer :: Ver
- dead :: TVar Bool
}
buildRequest :: (ToJSON q, ToRequest q) => Ver -> q -> Id -> Request
buildResponse :: (Monad m, FromRequest q, ToJSON r) => Respond q m r -> Request -> m (Maybe Response)
errorId :: Id -> ErrorObj
errorInvalid :: Value -> ErrorObj
errorMethod :: Method -> ErrorObj
errorParams :: Value -> String -> ErrorObj
errorParse :: ByteString -> ErrorObj
fromError :: ErrorObj -> String
fromId :: Id -> String
fromRequest :: FromRequest q => Request -> Either ErrorObj q
fromResponse :: FromResponse r => Method -> Response -> Maybe r
data BatchRequest
- = BatchRequest {
  - getBatchRequest :: ![Request]
  }
- | SingleRequest {
  - getSingleRequest :: !Request
  }
data BatchResponse
- = BatchResponse {
  - getBatchResponse :: ![Response]
  }
- | SingleResponse {
  - getSingleResponse :: !Response
  }
data ErrorObj
- = ErrorObj {
  - getErrMsg :: !String
  - getErrCode :: !Int
  - getErrData :: !Value
  }
- | ErrorVal {
  - getErrData :: !Value
  }
class FromRequest q where
- parseParams :: Method -> Maybe (Value -> Parser q)
class FromResponse r where
- parseResult :: Method -> Maybe (Value -> Parser r)
data Id
- = IdInt {
  - getIdInt :: !Int
  }
- | IdTxt {
  - getIdTxt :: !Text
  }
data Message
- = MsgRequest {
  - getMsgRequest :: !Request
  }
- | MsgResponse {
  - getMsgResponse :: !Response
  }
- | MsgBatch {
  - getBatch :: ![Message]
  }
type Method = Text
data Request
- = Request {
  - getReqVer :: !Ver
  - getReqMethod :: !Method
  - getReqParams :: !Value
  - getReqId :: !Id
  }
- | Notif {
  - getReqVer :: !Ver
  - getReqMethod :: !Method
  - getReqParams :: !Value
  }
type Respond q (m :: Type -> Type) r = q -> m (Either ErrorObj r)
data Response
- = Response {
  - getResVer :: !Ver
  - getResult :: !Value
  - getResId :: !Id
  }
- | ResponseError {
  - getResVer :: !Ver
  - getError :: !ErrorObj
  - getResId :: !Id
  }
- | OrphanError {
  - getResVer :: !Ver
  - getError :: !ErrorObj
  }
class ToRequest q where
- requestMethod :: q -> Method
- requestIsNotif :: q -> Bool
data Ver
- = V1
- | V2

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.

decodeConduit :: forall (m :: Type -> Type). MonadLogger m => Ver -> ConduitT ByteString (Either Response Value) m () Source #

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

encodeConduit :: forall j (m :: Type -> Type). (ToJSON j, MonadLogger m) => ConduitT j ByteString m () Source #

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

jsonrpcTCPClient Source #

Arguments

:: (MonadLoggerIO m, MonadUnliftIO 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.

jsonrpcTCPServer Source #

Arguments

:: (MonadLoggerIO m, MonadUnliftIO 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.

processIncoming :: forall (m :: Type -> Type). (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.

receiveBatchRequest :: forall (m :: Type -> Type). MonadLoggerIO m => JSONRPCT m (Maybe BatchRequest) Source #

Receive batch of requests. Will also accept single requests.

receiveRequest :: forall (m :: Type -> Type). 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.

runJSONRPCT Source #

Arguments

:: (MonadLoggerIO m, MonadUnliftIO m)
=> Ver	JSON-RPC version
-> Bool	Ignore incoming requests/notifs
-> ConduitT ByteString Void m ()	Sink to send messages
-> ConduitT () ByteString m ()	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.

sendBatchRequest :: forall (m :: Type -> Type) q r. (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.

sendBatchResponse :: forall (m :: Type -> Type). MonadLoggerIO m => BatchResponse -> JSONRPCT m () Source #

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

sendMessage :: forall (m :: Type -> Type). 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.

sendRequest :: forall (m :: Type -> Type) q r. (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.

sendResponse :: forall (m :: Type -> Type). MonadLoggerIO m => Response -> JSONRPCT m () Source #

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

type JSONRPCT = ReaderT Session Source #

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

buildRequest Source #

Arguments

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

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.

errorId :: Id -> ErrorObj Source #

Id not recognized.

errorInvalid :: Value -> ErrorObj Source #

Invalid request.

errorMethod :: Method -> ErrorObj Source #

Method not found.

errorParams :: Value -> String -> ErrorObj Source #

Invalid params.

errorParse :: ByteString -> ErrorObj Source #

Parse error.

fromError :: ErrorObj -> String Source #

Get a user-friendly string with the error information.

fromId :: Id -> String Source #

Pretty display a message id. Meant for logs.

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

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

Parse a response knowing the method of the corresponding request.

data BatchRequest Source #

Constructors

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

Instances

Instances details

Arbitrary BatchRequest Source #

Instance details

Defined in Network.JSONRPC.Arbitrary

Methods

arbitrary :: Gen BatchRequest #

shrink :: BatchRequest -> [BatchRequest] #

FromJSON BatchRequest Source #

Instance details

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

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

FromRequest Value Source #
Instance details Defined in Network.JSONRPC.Data Methods parseParams :: Method -> Maybe (Value -> Parser Value) Source #
FromRequest () Source #
Instance details Defined in Network.JSONRPC.Data Methods parseParams :: Method -> Maybe (Value -> Parser ()) Source #

FromResponse Value Source #
Instance details Defined in Network.JSONRPC.Data Methods parseResult :: Method -> Maybe (Value -> Parser Value) Source #
FromResponse () Source #
Instance details Defined in Network.JSONRPC.Data Methods parseResult :: Method -> Maybe (Value -> Parser ()) Source #

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

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

Response
Fields getResVer :: !Ver getResult :: !Value getResId :: !Id
ResponseError
Fields getResVer :: !Ver getError :: !ErrorObj getResId :: !Id
OrphanError
Fields getResVer :: !Ver getError :: !ErrorObj

ToRequest Value Source #
Instance details Defined in Network.JSONRPC.Data Methods requestMethod :: Value -> Method Source # requestIsNotif :: Value -> Bool Source #
ToRequest () Source #
Instance details Defined in Network.JSONRPC.Data Methods requestMethod :: () -> Method Source # requestIsNotif :: () -> Bool Source #

IdInt
Fields getIdInt :: !Int
IdTxt
Fields getIdTxt :: !Text