JsonRPC (JsonRPC v0.1.0) View Source
A module to create JSON-RPC clients and handle JSON-RPC requests.
For more information to JSON-RPC 2.0 see the specification.
JsonRPC
comes without any code to sending the generated JSON-RPCs. For the
transport the behaviour JsonRPC.Transport
has to be used.
JsonRPC
uses jason
per default. To customize the JSON library, including the
following in your config:
config :json_rpc, parser: :poison
Client
A client can be written by using JsonRPC
.
defmodule Example.Client do
use JsonRPC, transport: Example.Transport
rpc add(a, b)
rpc msg(text), notification: true
rpc message(text), notification: true, delegate: "msg"
rpc params(map), params: :by_name
end
The module Example.Client
contains now the functions add/2
, msg/1
,
message/1
and params/1
. When one of this function will be called a
JSON-RPC will be generated and Example.Transport.send_rpc/2
will be called.
The first argument of Transport.send_rpc/2
is the encoded JSON-RPC and the
second argument are the options given to JsonRPC
.
See Transport.send_rpc
for more information.
See rpc/2
for more information about the options.
Server
A server has to use the function handle_request/2
.
Link to this section Summary
Functions
Handles the given HandleRequestError
.
Handles the given json
request and executes the corresponding function on
the given module
.
Handles the given json
response.
Defines a RPC with the given name and arguments.
Link to this section Types
Specs
Link to this section Functions
Specs
handle_error( %JsonRPC.HandleRequestError{ __exception__: term(), from: term(), reason: term(), request: term() }, keyword() ) :: json()
Handles the given HandleRequestError
.
This function generates a JSON-RPC error response for the given error
.
The optional opts
can overwrite the values for :code
and :message
.
Examples
iex> defmodule Mod do
...> def carp, do: raise RuntimeError, "no!"
...> end
iex> request = %{id: 3, jsonrpc: "2.0", method: "carp", params: []}
iex> try do
...> JsonRPC.handle_request(request, Mod)
...> rescue
...> error in JsonRPC.HandleRequestError ->
...> JsonRPC.handle_error(error)
...> end
%{
id: 3,
error: %{code: -32000, message: "** (RuntimeError) no!"},
jsonrpc: "2.0"
}
Specs
Handles the given json
request and executes the corresponding function on
the given module
.
The function returns the result of the called function as an JSON-RPC response.
If the given request encoded JSON, the result is also encoded JSON, and for a decoded request, a decode response is returned.
For a notification (a request without id) the function returns :notification
.
handle_request/2
catches exceptions raised by the called function and raises
a JsonRPC.HandleRequestError
. This error could be handled with
handle_error/2
.
Examples
iex> defmodule Math do
...> def add(a, b), do: a + b
...> end
iex> request = %{id: "id-1", jsonrpc: "2.0", method: "add", params: [1, 2]}
iex> JsonRPC.handle_request(request, Math)
%{id: "id-1", jsonrpc: "2.0", result: 3}
iex> JsonRPC.handle_request(Jason.encode!(request), Math)
~s|{"id":"id-1","jsonrpc":"2.0","result":3}|
iex> request = %{id: "id-2", jsonrpc: "2.0", method: "unknown", params: [1, 2]}
iex> JsonRPC.handle_request(request, Math)
%{
id: "id-2",
error: %{
code: -32601,
data: %{method: "unknown"},
message: "Method not found"
},
jsonrpc: "2.0"
}
Specs
Handles the given json
response.
The response must contain an id
from a previously sent request. This
function is usually used in an asynchronous JsonRPC.Transport
implementation.
Defines a RPC with the given name and arguments.
Options:
:notification
- a boolean to mark a RPC as a notification, defaults tofalse
:params
- treat arguments either as:by_position
or:by_name
, defaults to:by_position
. The RPC expected a keyword list or a map whenparams: :by_name
is set:delegate
- a string that overrides the RPC name