fluencelabs/tendermint
1
0
Fork 0
mirror of https://github.com/fluencelabs/tendermint synced 2025-06-22 17:31:34 +00:00
Code Issues Projects Releases Wiki Activity

rpc/libs/doc: formatting for godoc, closes #2420

Browse Source
This commit is contained in:
zramsay
2018-09-25 18:11:18 -04:00
committed by Anton Kaliaev
parent cf8b42d813
commit df329e8f27
1 changed files with 86 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
rpc/lib/doc.go
View File

@ -1,103 +1,88 @@
/* // HTTP RPC server supporting calls via uri params, jsonrpc, and jsonrpc over websockets
HTTP RPC server supporting calls via uri params, jsonrpc, and jsonrpc over websockets //
// Client Requests
# Client Requests //
// Suppose we want to expose the rpc function `HelloWorld(name string, num int)`.
Suppose we want to expose the rpc function `HelloWorld(name string, num int)`. //
// GET (URI)
## GET (URI) //
// As a GET request, it would have URI encoded parameters, and look like:
As a GET request, it would have URI encoded parameters, and look like: //
// curl 'http://localhost:8008/hello_world?name="my_world"&num=5'
``` //
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:
//
Note the `'` around the url, which is just so bash doesn't ignore the quotes in `"my_world"`. // curl http://localhost:8008/hello_world?name=\"my_world\"&num=5
This should also work: //
// 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.
curl http://localhost:8008/hello_world?name=\"my_world\"&num=5 //
``` // POST (JSONRPC)
//
A GET request to `/` returns a list of available endpoints. // As a POST request, we use JSONRPC. For instance, the same request would have this as the body:
For those which take arguments, the arguments will be listed in order, with `_` where the actual value should be. //
// {
## POST (JSONRPC) // "jsonrpc": "2.0",
// "id": "anything",
As a POST request, we use JSONRPC. For instance, the same request would have this as the body: // "method": "hello_world",
// "params": {
``` // "name": "my_world",
{ // "num": 5
"jsonrpc": "2.0", // }
"id": "anything", // }
"method": "hello_world", //
"params": { // With the above saved in file `data.json`, we can make the request with
"name": "my_world", //
"num": 5 // curl --data @data.json http://localhost:8008
} //
} //
``` // WebSocket (JSONRPC)
//
With the above saved in file `data.json`, we can make the request with // 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.
curl --data @data.json http://localhost:8008 //
``` // Server Definition
//
## WebSocket (JSONRPC) // Define some types and routes:
//
All requests are exposed over websocket in the same form as the POST JSONRPC. // type ResultStatus struct {
Websocket connections are available at their own endpoint, typically `/websocket`, // Value string
though this is configurable when starting the server. // }
//
# Server Definition
Define some types and routes:
```
type ResultStatus struct {
Value string
}
// Define some routes // Define some routes
var Routes = map[string]*rpcserver.RPCFunc{ //
"status": rpcserver.NewRPCFunc(Status, "arg"), // var Routes = map[string]*rpcserver.RPCFunc{
} // "status": rpcserver.NewRPCFunc(Status, "arg"),
// }
// an rpc function //
func Status(v string) (*ResultStatus, error) { // An rpc function:
return &ResultStatus{v}, nil //
} // func Status(v string) (*ResultStatus, error) {
// return &ResultStatus{v}, nil
``` // }
//
Now start the server: // Now start the server:
//
``` // mux := http.NewServeMux()
mux := http.NewServeMux() // rpcserver.RegisterRPCFuncs(mux, Routes)
rpcserver.RegisterRPCFuncs(mux, Routes) // wm := rpcserver.NewWebsocketManager(Routes)
wm := rpcserver.NewWebsocketManager(Routes) // mux.HandleFunc("/websocket", wm.WebsocketHandler)
mux.HandleFunc("/websocket", wm.WebsocketHandler) // logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) // go func() {
go func() { // _, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux, logger)
_, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux, logger) // if err != nil {
if err != nil { // panic(err)
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.
Note that unix sockets are supported as well (eg. `/path/to/socket` instead of `0.0.0.0:8008`) //
// Examples
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. // - [Tendermint](https://github.com/tendermint/tendermint/blob/master/rpc/core/routes.go)
// - [tm-monitor](https://github.com/tendermint/tendermint/blob/master/tools/tm-monitor/rpc.go)
# Examples
* [Tendermint](https://github.com/tendermint/tendermint/blob/master/rpc/core/routes.go)
* [tm-monitor](https://github.com/tendermint/tendermint/blob/master/tools/tm-monitor/rpc.go)
*/
package rpc package rpc