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 = ErrorT 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)

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

Single Requests

toFunction Source

Arguments

:: (Monad m, Functor 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, Functor 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

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

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, Functor 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

data RpcError :: *

JSON-RPC error.

Constructors

RpcError
Fields errCode :: Int errMsg :: Text errData :: Maybe Value

Instances

Eq RpcError
Show RpcError
ToJSON RpcError
FromJSON RpcError
Error RpcError
(Monad m, Functor 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.

Minimal complete definition

toBatch

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 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.

Minimal complete definition

compose

Instances

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