json-rpc

A small, transport-agnostic JSON-RPC 2.0 client for Crystal.

The client builds and decodes the JSON-RPC envelope; a pluggable transport carries bytes to the peer. An HTTP transport ships in the box, and the abstract JSON::RPC::Transport lets you speak JSON-RPC over anything else (a Unix socket, an in-process stub for tests, a transport that handles CSRF tokens, …).

Installation

Add the dependency to your shard.yml:

dependencies:
  json-rpc:
    github: plambert/json-rpc.cr

Then run shards install.

Usage

require "json-rpc"

client = JSON::RPC::Client.new("http://localhost:8080/rpc")

# Call a method and read the result (returned as JSON::Any).
sum = client.call("add", {a: 2, b: 3}).as_i

# Fire a notification (no id, no response expected).
client.notify("log", {level: "info", text: "started"})

Errors

• A JSON-RPC error member raises JSON::RPC::Error, exposing #code, #message, and #data.
• A transport-level failure (e.g. a non-2xx HTTP status) raises JSON::RPC::TransportError, exposing #status when the transport has a notion of one.

Both inherit from JSON::RPC::Exception.

Custom transports

Implement JSON::RPC::Transport#call(body : String) : String to control how requests are delivered:

class MyTransport < JSON::RPC::Transport
  def call(body : String) : String
    # send `body`, return the raw response body
  end
end

client = JSON::RPC::Client.new(MyTransport.new)

JSON::RPC::HTTPTransport is the default. Subclass it and override #post or #call to layer in behavior such as token negotiation — this is exactly how transmission-rpc handles Transmission's X-Transmission-Session-Id CSRF dance.

Development

shards install
crystal spec -v --error-trace
crystal tool format
ameba

License

MIT