github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/tm2/pkg/bft/rpc/lib/doc.go (about)

     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  // WebSocket (JSONRPC)
    40  //
    41  // All requests are exposed over websocket in the same form as the POST JSONRPC.
    42  // Websocket connections are available at their own endpoint, typically `/websocket`,
    43  // though this is configurable when starting the server.
    44  //
    45  // # Server Definition
    46  //
    47  // Define some types and routes:
    48  //
    49  //	type ResultStatus struct {
    50  //		    Value string
    51  //	}
    52  //
    53  // Define some routes
    54  //
    55  //	  var Routes = map[string]*rpcserver.RPCFunc{
    56  //		    "status": rpcserver.NewRPCFunc(Status, "arg"),
    57  //	  }
    58  //
    59  // An rpc function:
    60  //
    61  //	  func Status(v string) (*ResultStatus, error) {
    62  //		    return &ResultStatus{v}, nil
    63  //	  }
    64  //
    65  // Now start the server:
    66  //
    67  //	mux := http.NewServeMux()
    68  //	rpcserver.RegisterRPCFuncs(mux, Routes)
    69  //	wm := rpcserver.NewWebsocketManager(Routes)
    70  //	mux.HandleFunc("/websocket", wm.WebsocketHandler)
    71  //	logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
    72  //	listener, err := rpc.Listen("0.0.0.0:8080", rpcserver.Config{})
    73  //	if err != nil { panic(err) }
    74  //	go rpcserver.StartHTTPServer(listener, mux, logger)
    75  //
    76  // Note that unix sockets are supported as well (eg. `/path/to/socket` instead of `0.0.0.0:8008`)
    77  // Now see all available endpoints by sending a GET request to `0.0.0.0:8008`.
    78  // Each route is available as a GET request, as a JSONRPCv2 POST request, and via JSONRPCv2 over websockets.
    79  //
    80  // # Examples
    81  //
    82  // - [Tendermint](https://github.com/gnolang/gno/tm2/pkg/bft/blob/master/rpc/core/routes.go)
    83  // - [tm-monitor](https://github.com/gnolang/gno/tm2/pkg/bft/blob/master/tools/tm-monitor/rpc.go)
    84  package rpc