Network.JsonRpc.Client

Functions for implementing the client side of JSON-RPC 2.0. See http://www.jsonrpc.org/specification.

Summary

• Create one Signature for each server-side method to be called. Signatures can be shared between client and server, using toServerMethod.
• Create a function of type Monad m => Connection m for communicating with the server.
• Create client-side functions by calling toFunction, toFunction_, toBatchFunction, or toBatchFunction_ on the Signatures.
• Client-side functions created with toBatchFunction or toBatchFunction_ return values of type Batch a. Combine them using Batch 's Applicative and Alternative instances, before calling runBatch on the result.

Demo

The demo folder contains a client and server that communicate using a shared set of Signatures. The client runs the server as a subprocess, sending requests to stdin and receiving responses from stdout. Compile both programs with the demo flag. Then run the client by passing it a command to run the server (e.g., demo-client demo-server).

Types

type Connection m = ByteString -> m (Maybe ByteString)

Function used to send requests to the server. Nothing represents no response, as when a JSON-RPC server receives only notifications.

type RpcResult m r = ExceptT RpcError m r

Return type of a method. A method call can either fail with an RpcError or succeed with a result of type r.

Signatures

data Signature ps r

Signature specifying the name, parameter names and types (ps), and return type (r) of a method.

Constructors

Signature Text ps

Instances

Show ps => Show (Signature ps r)

data p ::: ps infixr 9

A node in a linked list specifying parameter names and types. It is right associative.

Constructors

Text ::: ps infixr 9

Instances

Show ps => Show ((:::) p ps)

(ClientFunction ps r f, ToJSON a) => ClientFunction ((:::) a ps) r (a -> f)

ConvertParams ps1 ps2 => ConvertParams ((:::) p ps1) ((:+:) p ps2)

Single Requests

toFunction

Arguments

:: (Monad m, ClientFunction ps r f, ComposeMultiParam (Batch r -> RpcResult m r) f g)

=> Connection m

Function for sending requests to the server.

-> Signature ps r

Method signature.

-> g

Client-side function with a return type of RpcResult m r.

Creates a function for calling a JSON-RPC method on the server.

toFunction_

Arguments

:: (Monad m, ClientFunction ps r f, ComposeMultiParam (Batch r -> RpcResult m ()) f g)

=> Connection m

Function for sending requests to the server.

-> Signature ps r

Method signature.

-> g

Client-side function with a return type of RpcResult m ().

Creates a function for calling a JSON-RPC method on the server as a notification.

Batch Requests

data Batch r

A batch call. Batch multiple requests by combining values of this type using its Applicative and Alternative instances before running them with runBatch.

Instances

Alternative Batch

Functor Batch

Applicative Batch

FromJSON r => ClientFunction () r (Batch r)

ComposeMultiParam (Batch a -> b) (Batch a) b

toBatchFunction

Arguments

:: ClientFunction ps r f

=> Signature ps r

Method signature.

-> f

Client-side function with a return type of Batch r.

Creates a function for calling a JSON-RPC method as part of a batch request.

toBatchFunction_

Arguments

:: (ClientFunction ps r f, ComposeMultiParam (Batch r -> Batch ()) f g)

=> Signature ps r

Method signature.

-> g

Client-side function with a return type of Batch ().

Creates a function for calling a JSON-RPC method as a notification and as part of a batch request.

voidBatch :: Batch r -> Batch ()

Converts all requests in a batch to notifications.

runBatch

Arguments

:: Monad m

=> Connection m

Function for sending requests to the server.

-> Batch r

Batch to be evaluated.

-> RpcResult m r

Result.

Evaluates a batch. The process depends on its size:

1. If the batch is empty, the server function is not called.
2. If the batch has exactly one request, it is sent as a request object.
3. If the batch has multiple requests, they are sent as an array of request objects.

Errors

RpcError is used for all server-side errors, as described in the specification. Additionally, the error code -31999 is used for any errors that occur while parsing the server's response.

data RpcError :: *

JSON-RPC error.

Constructors

RpcError

Fields

errCode :: Int

errMsg :: Text

errData :: Maybe Value

Instances

Eq RpcError

Show RpcError

ToJSON RpcError

FromJSON RpcError

NFData RpcError

(Monad m, ToJSON r) => MethodParams (RpcResult m r) () m r

clientCode :: Int

Code used for all client-side errors. It is -31999.

Type Classes

class ClientFunction ps r f | ps r -> f, f -> ps r

Relationship between the parameters (ps), return type (r), and client-side batch function (f) of a JSON-RPC method.

Instances

FromJSON r => ClientFunction () r (Batch r)

(ClientFunction ps r f, ToJSON a) => ClientFunction ((:::) a ps) r (a -> f)

class ComposeMultiParam f g h | f g -> h, g h -> f

Relationship between a function (g) taking any number of arguments and yielding a Batch a, a function (f) taking a Batch a, and the function (h) that applies g to all of its arguments and then applies f to the result.

Instances

ComposeMultiParam f g h => ComposeMultiParam f (a -> g) (a -> h)

ComposeMultiParam (Batch a -> b) (Batch a) b