Safe Haskell	None
Language	Haskell2010

Network.JsonRpc.Client

Contents

Summary
Demo
Types
Signatures
Single Requests
Batch Requests
Errors
Type Classes

Description

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

Synopsis

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

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 Source

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

data p ::: ps infixr 9 Source

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) Source
(ClientFunction ps r f, ToJSON a) => ClientFunction ((:::) a ps) r (a -> f) Source
ConvertParams ps1 ps2 => ConvertParams ((:::) p ps1) ((:+:) p ps2) Source

Single Requests

toFunction Source

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

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 Source

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

Instances

Functor Batch Source
Applicative Batch Source
Alternative Batch Source
FromJSON r => ClientFunction () r (Batch r) Source
ComposeMultiParam (Batch a -> b) (Batch a) b Source

toBatchFunction Source

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

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

Converts all requests in a batch to notifications.

runBatch Source

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:

If the batch is empty, the server function is not called.
If the batch has exactly one request, it is sent as a request object.
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 Source

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

Type Classes

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

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) Source
(ClientFunction ps r f, ToJSON a) => ClientFunction ((:::) a ps) r (a -> f) Source

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

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) Source
ComposeMultiParam (Batch a -> b) (Batch a) b Source