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.

103 lines
2.4 KiB

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