A go implementation of an rpc client using json as data format over http. The implementation is based on the JSON-RPC 2.0 specification: http://www.jsonrpc.org/specification
Supports:
- requests with arbitrary parameters
- requests with named parameters
- notifications
- batch requests
- convenient response retrieval
- basic authentication
- custom headers
- custom http client
go get -u github.com/ybbus/jsonrpc
Let's say we want to retrieve a person with a specific id using rpc-json over http. Then we want to save this person with new properties. We have to provide basic authentication credentials. (Error handling is omitted here)
type Person struct {
Id int `json:"id"`
Name string `json:"name"`
Age int `json:"age"`
}
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
rpcClient.SetBasicAuth("alex", "secret")
response, _ := rpcClient.Call("getPersonById", 123)
person := Person{}
response.GetObject(&person)
person.Age = 33
rpcClient.Call("updatePerson", person)
}
Let's start by executing a simple json-rpc http call: In production code: Always make sure to check err != nil first!
This calls generate and send a valid rpc-json object. (see: http://www.jsonrpc.org/specification#request_object)
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("getDate")
// generates body: {"jsonrpc":"2.0","method":"getDate","id":0}
}
Call a function with parameter:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("addNumbers", 1, 2)
// generates body: {"jsonrpc":"2.0","method":"addNumbers","params":[1,2],"id":0}
}
Call a function with arbitrary parameters:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("createPerson", "Alex", 33, "Germany")
// generates body: {"jsonrpc":"2.0","method":"createPerson","params":["Alex",33,"Germany"],"id":0}
}
Call a function with named parameters:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
rpcClient.CallNamed("createPerson", map[string]interface{}{
"name": "Bartholomew Allen",
"nicknames": []string{"Barry", "Flash",},
"male": true,
"age": 28,
"address": map[string]interface{}{"street": "Main Street", "city": "Central City"},
})
// generates body: {"jsonrpc":"2.0","method":"createPerson","params":
// {"name": "Bartholomew Allen", "nicknames": ["Barry", "Flash"], "male": true, "age": 28,
// "address": {"street": "Main Street", "city": "Central City"}}
// ,"id":0}
}
Call a function providing custom data structures as parameters:
type Person struct {
Name string `json:"name"`
Age int `json:"age"`
Country string `json:"country"`
}
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("createPerson", Person{"Alex", 33, "Germany"})
// generates body: {"jsonrpc":"2.0","method":"createPerson","params":[{"name":"Alex","age":33,"country":"Germany"}],"id":0}
}
Complex example:
type Person struct {
Name string `json:"name"`
Age int `json:"age"`
Country string `json:"country"`
}
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("createPersonsWithRole", []Person{{"Alex", 33, "Germany"}, {"Barney", 38, "Germany"}}, []string{"Admin", "User"})
// generates body: {"jsonrpc":"2.0","method":"createPersonsWithRole","params":[[{"name":"Alex","age":33,"country":"Germany"},{"name":"Barney","age":38,"country":"Germany"}],["Admin","User"]],"id":0}
}
A jsonrpc notification is a rpc call to the server without expecting a response. Only an error object is returned in case of networkt / http error. No id field is set in the request json object. (see: http://www.jsonrpc.org/specification#notification)
Execute an simple notification:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
err := rpcClient.Notification("disconnectClient", 123)
if err != nil {
//error handling goes here
}
}
A jsonrpc batch call encapsulates multiple json-rpc requests in a single rpc-service call. It returns an array of results (for all non-notification requests). (see: http://www.jsonrpc.org/specification#batch)
Execute two jsonrpc calls and a single notification as batch:
func main() {
rpcClient := jsonrpc.NewRPCClient(httpServer.URL)
req1 := rpcClient.NewRPCRequestObject("addNumbers", 1, 2)
req2 := rpcClient.NewRPCRequestObject("getPersonByName", "alex")
notify1 := rpcClient.NewRPCNotificationObject("disconnect", true)
responses, _ := rpcClient.Batch(req1, req2, notify1)
person := Person{}
response2, _ := responses.GetResponseOf(req2)
response2.GetObject(&person)
}
To update the ID of an existing rpcRequest object:
func main() {
rpcClient := jsonrpc.NewRPCClient(httpServer.URL)
req1 := rpcClient.NewRPCRequestObject("addNumbers", 1, 2)
req2 := rpcClient.NewRPCRequestObject("getPersonByName", "alex")
notify1 := rpcClient.NewRPCNotifyObject("disconnect", true)
responses, _ := rpcClient.Batch(req1, req2, notify1)
rpcClient.UpdateRequestID(req1) // updates id to the next valid id if autoincrement is enabled
}
Before working with the response object, make sure to check err != nil first. This error indicates problems on the network / http level of an error when parsing the json response.
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, err := rpcClient.Call("addNumbers", 1, 2)
if err != nil {
//error handling goes here
}
}
The next thing you have to check is if an rpc-json protocol error occoured. This is done by checking if the Error field in the rpc-response != nil: (see: http://www.jsonrpc.org/specification#error_object)
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, err := rpcClient.Call("addNumbers", 1, 2)
if err != nil {
//error handling goes here
}
if response.Error != nil {
// check response.Error.Code, response.Error.Message, response.Error.Data here
}
}
After making sure that no errors occoured you can now examine the RPCResponse object. When executing a json-rpc request, most of the time you will be interested in the "result"-property of the returned json-rpc response object. (see: http://www.jsonrpc.org/specification#response_object) The library provides some helper functions to retrieve the result in the data format you are interested in. Again: check for err != nil here to be sure the expected type was provided in the response and could be parsed.
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("addNumbers", 1, 2)
result, err := response.GetInt()
if err != nil {
// result seems not to be an integer value
}
// helpers provided for all primitive types:
response.GetInt() // int32 or int64 depends on architecture / implementation
response.GetInt64()
response.GetFloat64()
response.GetString()
response.GetBool()
}
Retrieving arrays and objects is also very simple:
// json annotations are only required to transform the structure back to json
type Person struct {
Id int `json:"id"`
Name string `json:"name"`
Age int `json:"age"`
}
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("getPersonById", 123)
person := Person{}
err := response.GetObject(&Person) // expects a rpc-object result value like: {"id": 123, "name": "alex", "age": 33}
fmt.Println(person.Name)
}
Retrieving arrays e.g. of ints:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("getRandomNumbers", 10)
rndNumbers := []int{}
err := response.getObject(&rndNumbers) // expects a rpc-object result value like: [10, 188, 14, 3]
fmt.Println(rndNumbers[0])
}
If the rpc-service is running behind a basic authentication you can easily set the credentials:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
rpcClient.SetBasicAuth("alex", "secret")
response, _ := rpcClient.Call("addNumbers", 1, 2) // send with Authorization-Header
}
Setting some custom headers (e.g. when using another authentication) is simple:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
rpcClient.SetCustomHeader("Authorization", "Bearer abcd1234")
response, _ := rpcClient.Call("addNumbers", 1, 2) // send with a custom Auth-Header
}
Per default the ID of the json-rpc request increments automatically for each request. You can change this behaviour:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
response, _ := rpcClient.Call("addNumbers", 1, 2) // send with ID == 0
response, _ = rpcClient.Call("addNumbers", 1, 2) // send with ID == 1
rpcClient.SetNextID(10)
response, _ = rpcClient.Call("addNumbers", 1, 2) // send with ID == 10
rpcClient.SetAutoIncrementID(false)
response, _ = rpcClient.Call("addNumbers", 1, 2) // send with ID == 11
response, _ = rpcClient.Call("addNumbers", 1, 2) // send with ID == 11
}
If you have some special needs on the http.Client of the standard go library, just provide your own one. For example to use a proxy when executing json-rpc calls:
func main() {
rpcClient := jsonrpc.NewRPCClient("http://my-rpc-service:8080/rpc")
proxyURL, _ := url.Parse("http://proxy:8080")
transport := &http.Transport{Proxy: http.ProxyURL(proxyURL)}
httpClient := &http.Client{
Transport: transport,
}
rpcClient.SetHTTPClient(httpClient)
}