You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Ethan Buchman 9860c8fee1 rpc: cleanup some comments [ci skip] 8 years ago
..
client json.RawMessage in RPCRequest to defer parsing 8 years ago
server rpc: cleanup some comments [ci skip] 8 years ago
test rpc -> rpc/lib and rpc/tendermint -> rpc 8 years ago
types json.RawMessage in RPCRequest to defer parsing 8 years ago
Dockerfile rpc -> rpc/lib and rpc/tendermint -> rpc 8 years ago
Makefile rpc -> rpc/lib and rpc/tendermint -> rpc 8 years ago
README.md some cleanup from review 8 years ago
circle.yml rpc -> rpc/lib and rpc/tendermint -> rpc 8 years ago
rpc_test.go json.RawMessage in RPCRequest to defer parsing 8 years ago
version.go rpc -> rpc/lib and rpc/tendermint -> rpc 8 years ago

README.md

tendermint/rpc/lib

CircleCI

HTTP RPC server supporting calls via uri params, jsonrpc, and jsonrpc over websockets

Client Requests

Suppose we want to expose the rpc function HelloWorld(name string, num int).

GET (URI)

As a GET request, it would have URI encoded parameters, and look like:

curl 'http://localhost:8008/hello_world?name="my_world"&num=5'

Note the ' around the url, which is just so bash doesn't ignore the quotes in "my_world". This should also work:

curl http://localhost:8008/hello_world?name=\"my_world\"&num=5

A GET request to / returns a list of available endpoints. For those which take arguments, the arguments will be listed in order, with _ where the actual value should be.

POST (JSONRPC)

As a POST request, we use JSONRPC. For instance, the same request would have this as the body:

{
  "jsonrpc": "2.0",
  "id": "anything",
  "method": "hello_world",
  "params": {
    "name": "my_world",
    "num": 5
  }
}

With the above saved in file data.json, we can make the request with

curl --data @data.json http://localhost:8008

WebSocket (JSONRPC)

All requests are exposed over websocket in the same form as the POST JSONRPC. Websocket connections are available at their own endpoint, typically /websocket, though this is configurable when starting the server.

Server Definition

Define some types and routes:

type ResultStatus struct {
	Value string
}

// Define some routes
var Routes = map[string]*rpcserver.RPCFunc{
	"status": rpcserver.NewRPCFunc(Status, "arg"),
}

// an rpc function
func Status(v string) (*ResultStatus, error) {
	return &ResultStatus{v}, nil
}

Now start the server:

mux := http.NewServeMux()
rpcserver.RegisterRPCFuncs(mux, Routes)
wm := rpcserver.NewWebsocketManager(Routes, nil)
mux.HandleFunc("/websocket", wm.WebsocketHandler)
go func() {
	_, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux)
	if err != nil {
		panic(err)
	}
}()

Note that unix sockets are supported as well (eg. /path/to/socket instead of 0.0.0.0:8008)

Now see all available endpoints by sending a GET request to 0.0.0.0:8008. Each route is available as a GET request, as a JSONRPCv2 POST request, and via JSONRPCv2 over websockets.

Examples

CHANGELOG

0.7.0

BREAKING CHANGES:

  • removed Client empty interface
  • ClientJSONRPC#Call params argument became a map
  • rename ClientURI -> URIClient, ClientJSONRPC -> JSONRPCClient

IMPROVEMENTS:

  • added HTTPClient interface, which can be used for both ClientURI and ClientJSONRPC
  • all params are now optional (Golang's default will be used if some param is missing)
  • added Call method to WSClient (see method's doc for details)