From 3702cb7e7c01fb7eea2d2ccc089b4e65c92bbd78 Mon Sep 17 00:00:00 2001
From: Anton Kaliaev <anton.kalyaev@gmail.com>
Date: Thu, 5 Oct 2017 11:44:02 +0400
Subject: [PATCH] restore rpc/lib readme as doc.go (Refs #710) [ci skip]

I don't want to lose any documentation. Correct me if I am wrong, but we
don't have this docs anywhere else.
---
 rpc/lib/doc.go | 102 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 rpc/lib/doc.go

diff --git a/rpc/lib/doc.go b/rpc/lib/doc.go
new file mode 100644
index 000000000..9b13e2303
--- /dev/null
+++ b/rpc/lib/doc.go
@@ -0,0 +1,102 @@
+/*
+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, nil)
+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/tools/blob/master/tm-monitor/rpc.go)
+*/