forked from tendermint/tendermint
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
rpc/libs/doc: formatting for godoc, closes tendermint#2420
- Loading branch information
Showing
1 changed file
with
86 additions
and
101 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,103 +1,88 @@ | ||
| /* | ||
| 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 | ||
| } | ||
| // 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) | ||
| mux.HandleFunc("/websocket", wm.WebsocketHandler) | ||
| logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) | ||
| go func() { | ||
| _, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux, logger) | ||
| 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 | ||
| * [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) | ||
| */ | ||
| // | ||
| // 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) | ||
| // mux.HandleFunc("/websocket", wm.WebsocketHandler) | ||
| // logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) | ||
| // go func() { | ||
| // _, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux, logger) | ||
| // 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 | ||
| // | ||
| // - [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 |