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.

127 lines
3.1 KiB

8 years ago
8 years ago
  1. # go-rpc
  2. [![CircleCI](https://circleci.com/gh/tendermint/go-rpc.svg?style=svg)](https://circleci.com/gh/tendermint/go-rpc)
  3. HTTP RPC server supporting calls via uri params, jsonrpc, and jsonrpc over websockets
  4. # Client Requests
  5. Suppose we want to expose the rpc function `HelloWorld(name string, num int)`.
  6. ## GET (URI)
  7. As a GET request, it would have URI encoded parameters, and look like:
  8. ```
  9. curl 'http://localhost:8008/hello_world?name="my_world"&num=5'
  10. ```
  11. Note the `'` around the url, which is just so bash doesn't ignore the quotes in `"my_world"`.
  12. This should also work:
  13. ```
  14. curl http://localhost:8008/hello_world?name=\"my_world\"&num=5
  15. ```
  16. A GET request to `/` returns a list of available endpoints.
  17. For those which take arguments, the arguments will be listed in order, with `_` where the actual value should be.
  18. ## POST (JSONRPC)
  19. As a POST request, we use JSONRPC. For instance, the same request would have this as the body:
  20. ```
  21. {
  22. "jsonrpc": "2.0",
  23. "id": "anything",
  24. "method": "hello_world",
  25. "params": {
  26. "name": "my_world",
  27. "num": 5
  28. }
  29. }
  30. ```
  31. With the above saved in file `data.json`, we can make the request with
  32. ```
  33. curl --data @data.json http://localhost:8008
  34. ```
  35. ## WebSocket (JSONRPC)
  36. All requests are exposed over websocket in the same form as the POST JSONRPC.
  37. Websocket connections are available at their own endpoint, typically `/websocket`,
  38. though this is configurable when starting the server.
  39. # Server Definition
  40. Define some types and routes:
  41. ```
  42. // Define a type for results and register concrete versions with go-wire
  43. type Result interface{}
  44. type ResultStatus struct {
  45. Value string
  46. }
  47. var _ = wire.RegisterInterface(
  48. struct{ Result }{},
  49. wire.ConcreteType{&ResultStatus{}, 0x1},
  50. )
  51. // Define some routes
  52. var Routes = map[string]*rpcserver.RPCFunc{
  53. "status": rpcserver.NewRPCFunc(StatusResult, "arg"),
  54. }
  55. // an rpc function
  56. func StatusResult(v string) (Result, error) {
  57. return &ResultStatus{v}, nil
  58. }
  59. ```
  60. Now start the server:
  61. ```
  62. mux := http.NewServeMux()
  63. rpcserver.RegisterRPCFuncs(mux, Routes)
  64. wm := rpcserver.NewWebsocketManager(Routes, nil)
  65. mux.HandleFunc("/websocket", wm.WebsocketHandler)
  66. go func() {
  67. _, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux)
  68. if err != nil {
  69. panic(err)
  70. }
  71. }()
  72. ```
  73. Note that unix sockets are supported as well (eg. `/path/to/socket` instead of `0.0.0.0:8008`)
  74. Now see all available endpoints by sending a GET request to `0.0.0.0:8008`.
  75. Each route is available as a GET request, as a JSONRPCv2 POST request, and via JSONRPCv2 over websockets.
  76. # Examples
  77. * [Tendermint](https://github.com/tendermint/tendermint/blob/master/rpc/core/routes.go)
  78. * [tm-monitor](https://github.com/tendermint/tools/blob/master/tm-monitor/rpc.go)
  79. ## CHANGELOG
  80. ### 0.7.0
  81. BREAKING CHANGES:
  82. - removed `Client` empty interface
  83. - `ClientJSONRPC#Call` `params` argument became a map
  84. - rename `ClientURI` -> `URIClient`, `ClientJSONRPC` -> `JSONRPCClient`
  85. IMPROVEMENTS:
  86. - added `HTTPClient` interface, which can be used for both `ClientURI`
  87. and `ClientJSONRPC`
  88. - all params are now optional (Golang's default will be used if some param is missing)