-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
35 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,57 +1,53 @@ | ||
# jsonrpc2 - v2.0.1 | ||
# jsonrpc2/v4 | ||
[![GoDoc](https://godoc.org/github.com/AdamSLevy/jsonrpc2?status.svg)](https://godoc.org/github.com/AdamSLevy/jsonrpc2) | ||
[![Go Report Card](https://goreportcard.com/badge/github.com/AdamSLevy/jsonrpc2)](https://goreportcard.com/report/github.com/AdamSLevy/jsonrpc2) | ||
[![Coverage Status](https://coveralls.io/repos/github/AdamSLevy/jsonrpc2/badge.svg?branch=master)](https://coveralls.io/github/AdamSLevy/jsonrpc2?branch=master) | ||
[![Build Status](https://travis-ci.org/AdamSLevy/jsonrpc2.svg?branch=master)](https://travis-ci.org/AdamSLevy/jsonrpc2) | ||
|
||
Package jsonrpc2 is an easy-to-use, thin, minimalist implementation of the | ||
JSON-RPC 2.0 protocol with a handler for HTTP servers. It avoids implementing | ||
any HTTP helper functions and instead simply provides conforming Request and | ||
Response Types, and an http.HandlerFunc that handles single and batch Requests, | ||
protocol errors, and recovers panics from the application's RPC method calls. | ||
Package jsonrpc2 is a minimalist implementation of the JSON-RPC 2.0 protocol | ||
that provides types for Requests and Responses, and an http.Handler that calls | ||
MethodFuncs registered with RegisterMethod(). The HTTPRequestHandler will | ||
recover from any MethodFunc panics and will always respond with a valid JSON | ||
RPC Response, unless of course the request was a notification. | ||
|
||
It strives to conform to the official specification: | ||
[https://www.jsonrpc.org](https://www.jsonrpc.org). | ||
[https://www.jsonrpc.org](https://www.jsonrpc.org) | ||
|
||
|
||
## Getting started | ||
Please read the official godoc documentation for the most up to date | ||
information. | ||
|
||
## Quick Overview | ||
### Client | ||
|
||
Clients can use the Request, Response, and Error types with the json and http | ||
packages to make HTTP JSON-RPC 2.0 calls and parse their responses. | ||
```go | ||
reqBytes, _ := json.Marshal(jsonrpc2.NewRequest("subtract", 0, []int{5, 1})) | ||
httpResp, _ := http.Post("www.example.com", "application/json", | ||
bytes.NewReader(reqBytes)) | ||
respBytes, _ := ioutil.ReadAll(httpResp.Body) | ||
response := &jsonrpc2.Response{} | ||
json.Unmarshal(respBytes, response) | ||
``` | ||
|
||
### Server | ||
Servers must implement their RPC method functions to match the MethodFunc type | ||
and then register their function with a name using RegisterMethod(name, | ||
function). Read the documentation for RegisterMethod and MethodFunc for more | ||
information. RemarshalJSON is a convenience function for converting the | ||
abstract params argument into a custom concrete type. | ||
```golang | ||
jsonrpc2.RegisterMethod("subtract", func(params interface{}) jsonrpc2.Response { | ||
var p []interface{} | ||
var ok bool | ||
if p, ok = params.([]interface{}); !ok { | ||
return jsonrpc2.NewInvalidParamsErrorResponse( | ||
"params must be an array of two numbers") | ||
} | ||
if len(p) != 2 { | ||
return jsonrpc2.NewInvalidParamsErrorResponse( | ||
"params must be an array of two numbers") | ||
} | ||
var x [2]float64 | ||
for i := range x { | ||
if x[i], ok = p[i].(float64); !ok { | ||
return jsonrpc2.NewInvalidParamsErrorResponse( | ||
"params must be an array of two numbers") | ||
} | ||
} | ||
result := x[0] - x[1] | ||
return jsonrpc2.NewResponse(result) | ||
}) | ||
|
||
Servers must implement their RPC method functions to match the MethodFunc type. | ||
Methods must be registered with a name using RegisterMethod(). | ||
```go | ||
var func versionMethod(p json.RawMessage) *jsonrpc2.Response { | ||
if p != nil { | ||
return jsonrpc2.NewInvalidParamsErrorResponse(nil) | ||
} | ||
return jrpc.NewResponse("0.0.0") | ||
} | ||
jsonrpc2.RegisterMethod("version", jsonrpc2.MethodFunc(versionMethod)) | ||
``` | ||
After all methods are registered, set up an HTTP Server with HTTPRequestHandler | ||
as the handler. | ||
```golang | ||
http.ListenAndServe(":8080", jsonrpc2.HTTPRequestHandler) | ||
Read the documentation for RegisterMethod and MethodFunc for more information. | ||
|
||
After all methods are registered, set up an HTTP Server with | ||
```go | ||
HTTPRequestHandler as the handler. | ||
http.ListenAndServe(":8080", jsonrpc2.HTTPRequestHandler) | ||
``` |