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.

88 lines
2.7 KiB

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