rpc: add support for batched requests/responses (#3534)

Continues from #3280 in building support for batched requests/responses in the JSON RPC (as per issue #3213).

* Add JSON RPC batching for client and server

As per #3213, this adds support for [JSON RPC batch requests and
responses](https://www.jsonrpc.org/specification#batch).

* Add additional checks to ensure client responses are the same as results

* Fix case where a notification is sent and no response is expected

* Add test to check that JSON RPC notifications in a batch are left out in responses

* Update CHANGELOG_PENDING.md

* Update PR number now that PR has been created

* Make errors start with lowercase letter

* Refactor batch functionality to be standalone

This refactors the batching functionality to rather act in a standalone
way. In light of supporting concurrent goroutines making use of the same
client, it would make sense to have batching functionality where one
could create a batch of requests per goroutine and send that batch
without interfering with a batch from another goroutine.

* Add examples for simple and batch HTTP client usage

* Check errors from writer and remove nolinter directives

* Make error strings start with lowercase letter

* Refactor examples to make them testable

* Use safer deferred shutdown for example Tendermint test node

* Recompose rpcClient interface from pre-existing interface components

* Rename WaitGroup for brevity

* Replace empty ID string with request ID

* Remove extraneous test case

* Convert first letter of errors.Wrap() messages to lowercase

* Remove extraneous function parameter

* Make variable declaration terse

* Reorder WaitGroup.Done call to help prevent race conditions in the face of failure

* Swap mutex to value representation and remove initialization

* Restore empty JSONRPC string ID in response to prevent nil

* Make JSONRPCBufferedRequest private

* Revert PR hard link in CHANGELOG_PENDING

* Add client ID for JSONRPCClient

This adds code to automatically generate a randomized client ID for the
JSONRPCClient, and adds a check of the IDs in the responses (if one was
set in the requests).

* Extract response ID validation into separate function

* Remove extraneous comments

* Reorder fields to indicate clearly which are protected by the mutex

* Refactor for loop to remove indexing

* Restructure and combine loop

* Flatten conditional block for better readability

* Make multi-variable declaration slightly more readable

* Change for loop style

* Compress error check statements

* Make function description more generic to show that we support different protocols

* Preallocate memory for request and result objects

rpc/lib/server/handlers_test.go

@@ -154,6 +154,72 @@ func TestRPCNotification(t *testing.T) {
 	require.Equal(t, len(blob), 0, "a notification SHOULD NOT be responded to by the server")
 }
 
+func TestRPCNotificationInBatch(t *testing.T) {
+	mux := testMux()
+	tests := []struct {
+		payload     string
+		expectCount int
+	}{
+		{
+			`[
+				{"jsonrpc": "2.0","id": ""},
+				{"jsonrpc": "2.0","method":"c","id":"abc","params":["a","10"]}
+			 ]`,
+			1,
+		},
+		{
+			`[
+				{"jsonrpc": "2.0","id": ""},
+				{"jsonrpc": "2.0","method":"c","id":"abc","params":["a","10"]},
+				{"jsonrpc": "2.0","id": ""},
+				{"jsonrpc": "2.0","method":"c","id":"abc","params":["a","10"]}
+			 ]`,
+			2,
+		},
+	}
+	for i, tt := range tests {
+		req, _ := http.NewRequest("POST", "http://localhost/", strings.NewReader(tt.payload))
+		rec := httptest.NewRecorder()
+		mux.ServeHTTP(rec, req)
+		res := rec.Result()
+		// Always expecting back a JSONRPCResponse
+		assert.True(t, statusOK(res.StatusCode), "#%d: should always return 2XX", i)
+		blob, err := ioutil.ReadAll(res.Body)
+		if err != nil {
+			t.Errorf("#%d: err reading body: %v", i, err)
+			continue
+		}
+
+		var responses []types.RPCResponse
+		// try to unmarshal an array first
+		err = json.Unmarshal(blob, &responses)
+		if err != nil {
+			// if we were actually expecting an array, but got an error
+			if tt.expectCount > 1 {
+				t.Errorf("#%d: expected an array, couldn't unmarshal it\nblob: %s", i, blob)
+				continue
+			} else {
+				// we were expecting an error here, so let's unmarshal a single response
+				var response types.RPCResponse
+				err = json.Unmarshal(blob, &response)
+				if err != nil {
+					t.Errorf("#%d: expected successful parsing of an RPCResponse\nblob: %s", i, blob)
+					continue
+				}
+				// have a single-element result
+				responses = []types.RPCResponse{response}
+			}
+		}
+		if tt.expectCount != len(responses) {
+			t.Errorf("#%d: expected %d response(s), but got %d\nblob: %s", i, tt.expectCount, len(responses), blob)
+			continue
+		}
+		for _, response := range responses {
+			assert.NotEqual(t, response, new(types.RPCResponse), "#%d: not expecting a blank RPCResponse", i)
+		}
+	}
+}
+
 func TestUnknownRPCPath(t *testing.T) {
 	mux := testMux()
 	req, _ := http.NewRequest("GET", "http://localhost/unknownrpcpath", nil)