| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Network.JSONRPC
Synopsis
- type JSONRPCT = ReaderT Session
- runJSONRPCT :: (MonadLoggerIO m, MonadUnliftIO m) => Ver -> Bool -> ConduitT ByteString Void m () -> ConduitT () ByteString m () -> JSONRPCT m a -> m a
- decodeConduit :: MonadLogger m => Ver -> ConduitT ByteString (Either Response Value) m ()
- encodeConduit :: (ToJSON j, MonadLogger m) => ConduitT j ByteString m ()
- receiveRequest :: MonadLoggerIO m => JSONRPCT m (Maybe Request)
- receiveBatchRequest :: MonadLoggerIO m => JSONRPCT m (Maybe BatchRequest)
- sendResponse :: MonadLoggerIO m => Response -> JSONRPCT m ()
- sendBatchResponse :: MonadLoggerIO m => BatchResponse -> JSONRPCT m ()
- sendRequest :: (MonadLoggerIO m, ToJSON q, ToRequest q, FromResponse r) => q -> JSONRPCT m (Maybe (Either ErrorObj r))
- sendBatchRequest :: (MonadLoggerIO m, ToJSON q, ToRequest q, FromResponse r) => [q] -> JSONRPCT m [Maybe (Either ErrorObj r)]
- 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
- type SentRequests = HashMap Id (TMVar (Maybe Response))
- data Session = Session {}
- initSession :: Ver -> Bool -> STM Session
- processIncoming :: (Functor m, MonadLoggerIO m) => JSONRPCT m ()
- sendMessage :: MonadLoggerIO m => Message -> JSONRPCT m ()
- data Request
- = Request {
- getReqVer :: !Ver
- getReqMethod :: !Method
- getReqParams :: !Value
- getReqId :: !Id
- | Notif {
- getReqVer :: !Ver
- getReqMethod :: !Method
- getReqParams :: !Value
- = Request {
- data BatchRequest
- = BatchRequest {
- getBatchRequest :: ![Request]
- | SingleRequest { }
- = BatchRequest {
- class FromRequest q where
- parseParams :: Method -> Maybe (Value -> Parser q)
- fromRequest :: FromRequest q => Request -> Either ErrorObj q
- class ToRequest q where
- requestMethod :: q -> Method
- requestIsNotif :: q -> Bool
- buildRequest :: (ToJSON q, ToRequest q) => Ver -> q -> Id -> Request
- data Response
- data BatchResponse
- = BatchResponse {
- getBatchResponse :: ![Response]
- | SingleResponse { }
- = BatchResponse {
- class FromResponse r where
- parseResult :: Method -> Maybe (Value -> Parser r)
- fromResponse :: FromResponse r => Method -> Response -> Maybe r
- 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)
- data ErrorObj
- = ErrorObj {
- getErrMsg :: !String
- getErrCode :: !Int
- getErrData :: !Value
- | ErrorVal {
- getErrData :: !Value
- = ErrorObj {
- fromError :: ErrorObj -> String
- errorParse :: ByteString -> ErrorObj
- errorInvalid :: Value -> ErrorObj
- errorParams :: Value -> String -> ErrorObj
- errorMethod :: Method -> ErrorObj
- errorId :: Id -> ErrorObj
- data Message
- = MsgRequest {
- getMsgRequest :: !Request
- | MsgResponse { }
- | MsgBatch { }
- = MsgRequest {
- type Method = Text
- data Id
- fromId :: Id -> String
- data Ver
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
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.
Conduits for encoding/decoding
decodeConduit :: 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 :: (ToJSON j, MonadLogger m) => ConduitT j ByteString m () 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
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.
Server
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.
Internal data and functions
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
Constructors
| Request | |
Fields
| |
| Notif | |
Fields
| |
Instances
data BatchRequest Source #
Constructors
| BatchRequest | |
Fields
| |
| SingleRequest | |
Fields | |
Instances
Parsing
class FromRequest q where Source #
Methods
parseParams :: Method -> Maybe (Value -> Parser q) Source #
Parser for params Value in JSON-RPC request.
Instances
| FromRequest Value Source # | |
Defined in Network.JSONRPC.Data | |
| FromRequest () Source # | |
Defined in Network.JSONRPC.Data | |
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 Value Source # | |
Defined in Network.JSONRPC.Data | |
| ToRequest () Source # | |
Defined in Network.JSONRPC.Data | |
Responses
Constructors
| Response | |
| ResponseError | |
| OrphanError | |
Instances
data BatchResponse Source #
Constructors
| BatchResponse | |
Fields
| |
| SingleResponse | |
Fields | |
Instances
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 Value Source # | |
Defined in Network.JSONRPC.Data | |
| FromResponse () Source # | |
Defined in Network.JSONRPC.Data | |
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
Error object from JSON-RPC 2.0. ErrorVal for backwards compatibility.
Constructors
| ErrorObj | |
Fields
| |
| ErrorVal | |
Fields
| |
Instances
| Arbitrary ErrorObj Source # | |
| FromJSON ErrorObj Source # | |
| ToJSON ErrorObj Source # | |
Defined in Network.JSONRPC.Data | |
| Generic ErrorObj Source # | |
| Show ErrorObj Source # | |
| NFData ErrorObj Source # | |
Defined in Network.JSONRPC.Data | |
| Eq ErrorObj Source # | |
| type Rep ErrorObj Source # | |
Defined in Network.JSONRPC.Data type Rep ErrorObj = D1 ('MetaData "ErrorObj" "Network.JSONRPC.Data" "json-rpc-1.1.1-EK4G3oPKFrrAIxXwVc4vmj" 'False) (C1 ('MetaCons "ErrorObj" 'PrefixI 'True) (S1 ('MetaSel ('Just "getErrMsg") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 String) :*: (S1 ('MetaSel ('Just "getErrCode") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "getErrData") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Value))) :+: C1 ('MetaCons "ErrorVal" 'PrefixI 'True) (S1 ('MetaSel ('Just "getErrData") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Value))) | |
Error messages
errorParse :: ByteString -> ErrorObj Source #
Parse error.
errorInvalid :: Value -> ErrorObj Source #
Invalid request.
errorMethod :: Method -> ErrorObj Source #
Method not found.
Others
Constructors
| MsgRequest | |
Fields
| |
| MsgResponse | |
Fields | |
| MsgBatch | |
Instances
| Arbitrary Message Source # | |
| FromJSON Message Source # | |
| ToJSON Message Source # | |
Defined in Network.JSONRPC.Data | |
| Generic Message Source # | |
| Show Message Source # | |
| NFData Message Source # | |
Defined in Network.JSONRPC.Data | |
| Eq Message Source # | |
| type Rep Message Source # | |
Defined in Network.JSONRPC.Data type Rep Message = D1 ('MetaData "Message" "Network.JSONRPC.Data" "json-rpc-1.1.1-EK4G3oPKFrrAIxXwVc4vmj" 'False) (C1 ('MetaCons "MsgRequest" 'PrefixI 'True) (S1 ('MetaSel ('Just "getMsgRequest") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Request)) :+: (C1 ('MetaCons "MsgResponse" 'PrefixI 'True) (S1 ('MetaSel ('Just "getMsgResponse") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Response)) :+: C1 ('MetaCons "MsgBatch" 'PrefixI 'True) (S1 ('MetaSel ('Just "getBatch") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 [Message])))) | |
Instances
| Arbitrary Id Source # | |
| FromJSON Id Source # | |
| ToJSON Id Source # | |
Defined in Network.JSONRPC.Data | |
| Enum Id Source # | |
| Generic Id Source # | |
| Read Id Source # | |
| Show Id Source # | |
| NFData Id Source # | |
Defined in Network.JSONRPC.Data | |
| Eq Id Source # | |
| Hashable Id Source # | |
Defined in Network.JSONRPC.Data | |
| type Rep Id Source # | |
Defined in Network.JSONRPC.Data type Rep Id = D1 ('MetaData "Id" "Network.JSONRPC.Data" "json-rpc-1.1.1-EK4G3oPKFrrAIxXwVc4vmj" 'False) (C1 ('MetaCons "IdInt" 'PrefixI 'True) (S1 ('MetaSel ('Just "getIdInt") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)) :+: C1 ('MetaCons "IdTxt" 'PrefixI 'True) (S1 ('MetaSel ('Just "getIdTxt") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text))) | |