jsonrpc

README

DEPRECATION WARNING This package is unmaintained and probably not what you're looking for.

jsonrpc

Package jsonrpc implements a standards compliant, asynchronous JSON-RPC client. The JSON-RPC 2.0 standard as specified in http://www.jsonrpc.org/specification is supported, while it is also possible to implement vendor specific dialects. The client is thread safe, i.e. request and notification functions can be called from any goroutine.

Documentation

http://godoc.org/github.com/calmh/jsonrpc

Example

// Connect to a remote JSON-RPC server

conn, err := net.Dial("tcp", "svr.example.com:3994")
if err != nil {
	panic(err)
}

// Set up a JSON-RPC channel on top of the socket, standard JSON-RPC 2.0
// dialect

rpc := jsonrpc.NewConnection(conn, jsonrpc.StandardDialect)

// Create two request functions, one for the method "hello" and one for the
// method "system.ping".

hello := rpc.Request("hello")
ping := rpc.Request("system.ping")

// Call the hello method with one string parameter.
// {"id": 0, "method": "hello", "params": ["world"], "jsonrpc": "2.0"}

helloRc, err := hello("world")
if err != nil {
	panic(err)
}

// Call the ping method with an empty parameter list. Note that we do not
// wait for the server to complete the hello request above before sending
// the ping request -- this is request pipelining.
// {"id": 1, "method": "ping", "params": [], "jsonrpc": "2.0"}

pingRc, err := ping()
if err != nil {
	panic(err)
}

// Await the response for the ping request and then the hello request. It
// does not matter in which order the server returned the responses.

var resp jsonrpc.Response
var ok bool
resp, ok = <-pingRc
if !ok {
	panic("read error reading response")
}
fmt.Printf("%v\n", resp)
resp, ok = <-helloRc
if !ok {
	panic("read error reading response")
}
fmt.Printf("%v\n", resp)

License

MIT

Documentation

Overview

**DEPRECATION WARNING**

This package is unmaintained and probably not what you're looking for.

Package jsonrpc implements a standards compliant, asynchronous JSON-RPC client. The JSON-RPC 2.0 standard as specified in http://www.jsonrpc.org/specification is supported, while it is also possible to implement vendor specific dialects. The client is thread safe, i.e. request and notification functions can be called from any goroutine.

The RPC client is instantiated on top of an io.ReadWriter, for example a net.Conn. You then create Request and Notification functions from the RPC client. These are bound to the RPC client and return a chan Response (Request only) and possibly an error when called. When the result is needed a read from the channel will yield the Response object.

There are two stages where error handling is necessary:

- When calling the generated Request or Notification functions; these return an error if the underlying ReadWriter is known bad (due to a previous read or write error).

- When reading from the Response channel; the channel will be closed instead of producing a value if there is an error in sending the request or receiving the response.

Getting a nil error from a request function does not imply the request was successfully sent. There are several more layers where errors may occur before the request reaches the remote server, several of which are outside of the control of this package. Only on receipt of a Response object can you be sure that a request was processed by the server.

See the Connection example for details.

Index

• Variables
• type Connection
  • func NewConnection(rw io.ReadWriter, dialect Dialect) *Connection
  • func (c *Connection) Notification(method string) Notification
  • func (c *Connection) Request(method string) Request
• type Dialect
• type Notification
• type Request
• type Response
• type ResponseError

Examples

• Connection

Variables

var ProceraDialect = Dialect{proceraRequest, proceraNotification}

ProceraDialect implements the Procera modified JSON-RPC 2.0 dialect. It differs from the standard JSON-RPC 2.0 by omitting the "jsonrpc":"2.0" field and adding an optional "tags" field. For all requests and notifications, it is required that the first parameter is a []string containing the tags. It may be nil.

var StandardDialect = Dialect{standardRequest, standardNotification}

StandardDialect implements the JSON-RPC 2.0 standard dialect as described in http://www.jsonrpc.org/specification.

Types

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

A Connection is a JSON-RPC channel over an existing ReadWriter, such as a socket.

Example

package main

import (
	"fmt"
	"github.com/calmh/jsonrpc"
	"net"
)

func main() {
	// Connect to a remote JSON-RPC server

	conn, err := net.Dial("tcp", "svr.example.com:3994")
	if err != nil {
		panic(err)
	}

	// Set up a JSON-RPC channel on top of the socket, standard JSON-RPC 2.0
	// dialect

	rpc := jsonrpc.NewConnection(conn, jsonrpc.StandardDialect)

	// Create two request functions, one for the method "hello" and one for the
	// method "system.ping".

	hello := rpc.Request("hello")
	ping := rpc.Request("system.ping")

	// Call the hello method with one string parameter.
	// {"id": 0, "method": "hello", "params": ["world"], "jsonrpc": "2.0"}

	helloRc, err := hello("world")
	if err != nil {
		panic(err)
	}

	// Call the ping method with an empty parameter list. Note that we do not
	// wait for the server to complete the hello request above before sending
	// the ping request -- this is request pipelining.
	// {"id": 1, "method": "ping", "params": [], "jsonrpc": "2.0"}

	pingRc, err := ping()
	if err != nil {
		panic(err)
	}

	// Await the response for the ping request and then the hello request. It
	// does not matter in which order the server returned the responses.

	var resp jsonrpc.Response
	var ok bool
	resp, ok = <-pingRc
	if !ok {
		panic("read error reading response")
	}
	fmt.Printf("%v\n", resp)
	resp, ok = <-helloRc
	if !ok {
		panic("read error reading response")
	}
	fmt.Printf("%v\n", resp)
}

func NewConnection

func NewConnection(rw io.ReadWriter, dialect Dialect) *Connection

NewConnection creates a new JSON-RPC channel over the specified ReadWriter, using a specific Dialect to encode the transmitted data.

func (*Connection) Notification

func (c *Connection) Notification(method string) Notification

Notification returns a new notification function for use over the channel.

func (*Connection) Request

func (c *Connection) Request(method string) Request

Request returns a new request function for use over the channel.

type Dialect

type Dialect struct {
	// The RequestMap maps parameters sent a request function (ID, Method,
	// Params) to a map that is JSON marshalled over the wire.
	RequestMap func(int, string, []interface{}) map[string]interface{}
	// The NotificationMap maps parameters sent a request function (Method,
	// Params) to a map that is JSON marshalled over the wire.
	NotificationMap func(string, []interface{}) map[string]interface{}
}

A Dialect is a specific wire encoding of requests and notifications.

type Notification

type Notification func(...interface{}) error

A Notification function performs a notification on the JSON-RPC server when called. An error is returned if the request could not be sent due to communication problems. The meaning of the arguments to the request function is defined by the Dialect, but in the standard dialect these are simply sent verbatim as the method arguments.

type Request

type Request func(...interface{}) (<-chan Response, error)

A Request function performs a request on the JSON-RPC server when called and returns a channel where the response may be read. A nil channel and an error is returned if the request could not be sent due to communication problems.

The response object that is sent on the channel may contain an error from the server. The result channel is closed in the case of a read error after sending the request but before recieving the response.

The meaning of the arguments to the request function is defined by the Dialect, but in the standard dialect these are simply sent verbatim as the method arguments.

type Response

type Response struct {
	ID      int            // Sequence number autogenerated by the request function
	Result  interface{}    // Result of a successfull request; may be nil.
	Error   *ResponseError // Error of an unsuccessfull (but successfully sent) request; may be nil.
	JSONRPC string         // JSON-RPC version string as returned by the server (most likely "2.0" or blank).
}

A Response is a JSON-RPC 2.0 response as received by the server in response to a request.

type ResponseError

type ResponseError struct {
	Code    int
	Message string
	Data    interface{}
}

A ResponseError is an error object returned by the JSON-RPC server in response to unsuccessfull or erroneous requests.