[RPC] Static swagger (#3880)

* manually swagging

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* three definitions with polymorphism

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* added blockchain and block

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* low quality generation, commit, block_response and validators

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* genesis and consensus states endpoints

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* fix indentation

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* consensus parameters

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* fix indentation

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* add height to consensus parameters endpoint

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* unconfirmed_txs and num_unconfirmed_txs

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* add missing query parameter

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* add ABCI queries

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* added index document for swagger documentation

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* add missing routes

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* contract tests added on CCI

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* contract tests job should be in the test suite

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* simplify requirements to test

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* typo

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* build is a prerequisite to start localnet

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* reduce nodejs size, move goodman to get_tools, add docs, fix comments

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* Update scripts/get_tools.sh

That's cleaner, thanks!

Co-Authored-By: Anton Kaliaev <anton.kalyaev@gmail.com>

* xz not supported by cci image, let's keep it simple

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* REMOVE-indirect debug of CCI paths

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* dirty experiment, volume is empty but binary has been produced

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* dirty experiment, volume is empty but binary has been produced

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* dirty experiment going on

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* locally works, CCI have difficulties with second layaer containers volumes

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* restore experiment, use machine instead of docker for contract tests

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* simplify a bit

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* rollback on machine golang

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* Document the changes

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* Changelog

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

* comments

Signed-off-by: Karoly Albert Szabo <szabo.karoly.a@gmail.com>

.circleci/config.yml

@@ -359,6 +359,35 @@ jobs:
       - store_artifacts:
           path: /go/src/github.com/tendermint/tendermint/tendermint-*.tar.gz
 
+  # Test RPC implementation against the swagger documented specs
+  contract_tests:
+    working_directory: /home/circleci/.go_workspace/src/github.com/tendermint/tendermint
+    machine:
+      image: circleci/classic:latest
+    environment:
+      GOBIN: /home/circleci/.go_workspace/bin
+      GOPATH: /home/circleci/.go_workspace/
+      GOOS: linux
+      GOARCH: amd64
+    parallelism: 1
+    steps:
+      - checkout
+      - run:
+          name: Test RPC endpoints agsainst swagger documentation
+          command: |
+            set -x
+            export PATH=~/.local/bin:$PATH
+
+            # install node 11.15 and dredd
+            ./scripts/get_nodejs.sh
+
+            # build the binaries with a proper version of Go
+            docker run --rm -v "$PWD":/go/src/github.com/tendermint/tendermint -w /go/src/github.com/tendermint/tendermint golang make build-linux build-contract-tests-hooks
+
+            # This docker image works with go 1.7, we can install here the hook handler that contract-tests is going to use
+            go get github.com/snikch/goodman/cmd/goodman
+            make contract-tests
+
 workflows:
   version: 2
   test-suite:
@@ -397,6 +426,10 @@ workflows:
               only:
                 - master
                 - /v[0-9]+\.[0-9]+/
+      - contract_tests:
+          requires:
+            - setup_dependencies
+
   release:
     jobs:
       - prepare_build

CHANGELOG_PENDING.md

@@ -22,6 +22,7 @@ program](https://hackerone.com/tendermint).
 - [privval] \#3370 Refactors and simplifies validator/kms connection handling. Please refer to thttps://github.com/tendermint/tendermint/pull/3370#issue-257360971
 - [consensus] \#3839 Reduce "Error attempting to add vote" message severity (Error -> Info)
 - [mempool] \#3877 Make `max_tx_bytes` configurable instead of `max_msg_bytes`
+- [rpc] \#3880 Document endpoints with `swagger`, introduce contract tests of implementation against documentation
 
 ### BUG FIXES:
 

CONTRIBUTING.md

@@ -183,3 +183,16 @@ If they have `.go` files in the root directory, they will be automatically
 tested by circle using `go test -v -race ./...`. If not, they will need a
 `circle.yml`. Ideally, every repo has a `Makefile` that defines `make test` and
 includes its continuous integration status using a badge in the `README.md`.
+
+### RPC Testing
+
+If you contribute to the RPC endpoints it's important to document your changes in the [Swagger file](./docs/spec/rpc/swagger.yaml)
+To test your changes you should install `nodejs` version `v11.15.*` and run:
+
+```bash
+npm i -g dredd
+make build-linux build-contract-tests-hooks
+make contract-tests
+``` 
+
+This command will popup a network and check every endpoint against what has been documented

Makefile

@@ -308,7 +308,23 @@ sentry-stop:
 build-slate:
 	bash scripts/slate.sh
 
+# Build hooks for dredd, to skip or add information on some steps
+build-contract-tests-hooks:
+ifeq ($(OS),Windows_NT)
+	go build -mod=readonly $(BUILD_FLAGS) -o build/contract_tests.exe ./cmd/contract_tests
+else
+	go build -mod=readonly $(BUILD_FLAGS) -o build/contract_tests ./cmd/contract_tests
+endif
+
+# Run a nodejs tool to test endpoints against a localnet
+# The command takes care of starting and stopping the network
+# prerequisits: build-contract-tests-hooks build-linux
+# the two build commands were not added to let this command run from generic containers or machines.
+# The binaries should be built beforehand
+contract-tests:
+	dredd
+
 # To avoid unintended conflicts with file names, always add to .PHONY
 # unless there is a reason not to.
 # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
-.PHONY: check build build_race build_abci dist install install_abci check_tools get_tools update_tools draw_deps get_protoc protoc_abci protoc_libs gen_certs clean_certs grpc_dbserver test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt rpc-docs build-linux localnet-start localnet-stop build-docker build-docker-localnode sentry-start sentry-config sentry-stop build-slate protoc_grpc protoc_all build_c install_c test_with_deadlock cleanup_after_test_with_deadlock lint
+.PHONY: check build build_race build_abci dist install install_abci check_tools get_tools update_tools draw_deps get_protoc protoc_abci protoc_libs gen_certs clean_certs grpc_dbserver test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt rpc-docs build-linux localnet-start localnet-stop build-docker build-docker-localnode sentry-start sentry-config sentry-stop build-slate protoc_grpc protoc_all build_c install_c test_with_deadlock cleanup_after_test_with_deadlock lint build-contract-tests-hooks contract-tests

cmd/contract_tests/main.go

@@ -0,0 +1,34 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/snikch/goodman/hooks"
+	"github.com/snikch/goodman/transaction"
+)
+
+func main() {
+	// This must be compiled beforehand and given to dredd as parameter, in the meantime the server should be running
+	h := hooks.NewHooks()
+	server := hooks.NewServer(hooks.NewHooksRunner(h))
+	h.BeforeAll(func(t []*transaction.Transaction) {
+		fmt.Println(t[0].Name)
+	})
+	h.BeforeEach(func(t *transaction.Transaction) {
+		if strings.HasPrefix(t.Name, "Tx") ||
+			// We need a proper example of evidence to broadcast
+			strings.HasPrefix(t.Name, "Info > /broadcast_evidence") ||
+			// We need a proper example of path and data
+			strings.HasPrefix(t.Name, "ABCI > /abci_query") ||
+			// We need to find a way to make a transaction before starting the tests,
+			// that hash should replace the dummy one in hte swagger file
+			strings.HasPrefix(t.Name, "Info > /tx") {
+			t.Skip = true
+			fmt.Printf("%s Has been skipped\n", t.Name)
+		}
+	})
+	server.Serve()
+	defer server.Listener.Close()
+	fmt.Print("FINE")
+}

docs/spec/rpc/index.html

@@ -0,0 +1,25 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <title>Tendermint RPC</title>
+        <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" >
+        <link rel="icon" type="image/png" href="//unpkg.com/swagger-ui-dist@3/favicon-16x16.png"/>
+        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+    </head>
+
+    <body>
+        <div id="swagger-ui"></div>
+        <script>
+            window.onload = function() {
+                window.ui = SwaggerUIBundle({
+                    url: "./swagger.yaml",
+                    dom_id: '#swagger-ui',
+                    deepLinking: true,
+                    layout: "BaseLayout"
+                });
+            }
+        </script>
+    </body>
+</html>

dredd.yml

@@ -0,0 +1,33 @@
+color: true
+dry-run: null
+hookfiles: build/contract_tests
+language: go
+require: null
+server: make localnet-start
+server-wait: 30
+init: false
+custom: {}
+names: false
+only: []
+reporter: []
+output: []
+header: []
+sorted: false
+user: null
+inline-errors: false
+details: false
+method: [GET]
+loglevel: warning
+path: []
+hooks-worker-timeout: 5000
+hooks-worker-connect-timeout: 1500
+hooks-worker-connect-retry: 500
+hooks-worker-after-connect-wait: 100
+hooks-worker-term-timeout: 5000
+hooks-worker-term-retry: 500
+hooks-worker-handler-host: 127.0.0.1
+hooks-worker-handler-port: 61321
+config: ./dredd.yml
+# This path accepts no variables
+blueprint: ./docs/spec/rpc/swagger.yaml
+endpoint: 'http://127.0.0.1:26657/'

go.mod

@@ -14,10 +14,8 @@ require (
 	github.com/gogo/protobuf v1.2.1
 	github.com/golang/protobuf v1.3.2
 	github.com/google/gofuzz v1.0.0 // indirect
-	github.com/google/pprof v0.0.0-20190723021845-34ac40c74b70 // indirect
 	github.com/gorilla/websocket v1.2.0
 	github.com/hashicorp/hcl v1.0.0 // indirect
-	github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6 // indirect
 	github.com/inconshreveable/mousetrap v1.0.0 // indirect
 	github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515 // indirect
 	github.com/libp2p/go-buffer-pool v0.0.1
@@ -32,6 +30,7 @@ require (
 	github.com/prometheus/procfs v0.0.0-20181005140218-185b4288413d // indirect
 	github.com/rcrowley/go-metrics v0.0.0-20180503174638-e2704e165165
 	github.com/rs/cors v1.6.0
+	github.com/snikch/goodman v0.0.0-20171125024755-10e37e294daa
 	github.com/spf13/afero v1.1.2 // indirect
 	github.com/spf13/cast v1.3.0 // indirect
 	github.com/spf13/cobra v0.0.1
@@ -41,7 +40,6 @@ require (
 	github.com/stretchr/testify v1.3.0
 	github.com/tendermint/go-amino v0.14.1
 	github.com/tendermint/tm-db v0.1.1
-	golang.org/x/arch v0.0.0-20190312162104-788fe5ffcd8c // indirect
 	golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2
 	golang.org/x/net v0.0.0-20190628185345-da137c7871d7
 	google.golang.org/grpc v1.22.0

go.sum

@@ -46,16 +46,12 @@ github.com/golang/snappy v0.0.1/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEW
 github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
 github.com/google/gofuzz v1.0.0 h1:A8PeW59pxE9IoFRqBp37U+mSNaQoZ46F1f0f863XSXw=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
-github.com/google/pprof v0.0.0-20190723021845-34ac40c74b70 h1:XTnP8fJpa4Kvpw2qARB4KS9izqxPS0Sd92cDlY3uk+w=
-github.com/google/pprof v0.0.0-20190723021845-34ac40c74b70/go.mod h1:zfwlbNMJ+OItoe0UupaVj+oy1omPYYDuagoSzA8v9mc=
 github.com/gorilla/websocket v1.2.0 h1:VJtLvh6VQym50czpZzx07z/kw9EgAxI3x1ZB8taTMQQ=
 github.com/gorilla/websocket v1.2.0/go.mod h1:E7qHFY5m1UJ88s3WnNqhKjPHQ0heANvMoAMk2YaljkQ=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
 github.com/hpcloud/tail v1.0.0 h1:nfCOvKYfkgYP8hkirhJocXT2+zOD8yUNjXaWfTlyFKI=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
-github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6 h1:UDMh68UUwekSh5iP2OMhRRZJiiBccgV7axzUG8vi56c=
-github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM=
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
 github.com/jessevdk/go-flags v0.0.0-20141203071132-1679536dcc89/go.mod h1:4FA24M0QyGHXBuZZK/XkWh8h0e1EYbRYJSGM75WSRxI=
@@ -98,6 +94,8 @@ github.com/rcrowley/go-metrics v0.0.0-20180503174638-e2704e165165 h1:nkcn14uNmFE
 github.com/rcrowley/go-metrics v0.0.0-20180503174638-e2704e165165/go.mod h1:bCqnVzQkZxMG4s8nGwiZ5l3QUCyqpo9Y+/ZMZ9VjZe4=
 github.com/rs/cors v1.6.0 h1:G9tHG9lebljV9mfp9SNPDL36nCDxmo3zTlAf1YgvzmI=
 github.com/rs/cors v1.6.0/go.mod h1:gFx+x8UowdsKA9AchylcLynDq+nNFfI8FkUZdN/jGCU=
+github.com/snikch/goodman v0.0.0-20171125024755-10e37e294daa h1:YJfZp12Z3AFhSBeXOlv4BO55RMwPn2NoQeDsrdWnBtY=
+github.com/snikch/goodman v0.0.0-20171125024755-10e37e294daa/go.mod h1:oJyF+mSPHbB5mVY2iO9KV3pTt/QbIkGaO8gQ2WrDbP4=
 github.com/spf13/afero v1.1.2 h1:m8/z1t7/fwjysjQRYbP0RD+bUIF/8tJwPdEZsI83ACI=
 github.com/spf13/afero v1.1.2/go.mod h1:j4pytiNVoe2o6bmDsKpLACNPDBIoEAkihy7loJ1B0CQ=
 github.com/spf13/cast v1.3.0 h1:oget//CVOEoFewqQxwr0Ej5yjygnqGkvggSE/gB35Q8=
@@ -119,14 +117,10 @@ github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965 h1:1oFLiOyVl+W7
 github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965/go.mod h1:9OrXJhf154huy1nPWmuSrkgjPUtUNhA+Zmy+6AESzuA=
 github.com/tendermint/go-amino v0.14.1 h1:o2WudxNfdLNBwMyl2dqOJxiro5rfrEaU0Ugs6offJMk=
 github.com/tendermint/go-amino v0.14.1/go.mod h1:i/UKE5Uocn+argJJBb12qTZsCDBcAYMbR92AaJVmKso=
-github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d h1:yCHL2COLGLNfb4sA9AlzIHpapb8UATvAQyJulS6Eg6Q=
-github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d/go.mod h1:0cPKWu2Mou3IlxecH+MEUSYc1Ch537alLe6CpFrKzgw=
 github.com/tendermint/tm-db v0.1.1 h1:G3Xezy3sOk9+ekhjZ/kjArYIs1SmwV+1OUgNkj7RgV0=
 github.com/tendermint/tm-db v0.1.1/go.mod h1:0cPKWu2Mou3IlxecH+MEUSYc1Ch537alLe6CpFrKzgw=
 go.etcd.io/bbolt v1.3.3 h1:MUGmc65QhB3pIlaQ5bB4LwqSj6GIonVJXpZiaKNyaKk=
 go.etcd.io/bbolt v1.3.3/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU=
-golang.org/x/arch v0.0.0-20190312162104-788fe5ffcd8c h1:Rx/HTKi09myZ25t1SOlDHmHOy/mKxNAcu0hP1oPX9qM=
-golang.org/x/arch v0.0.0-20190312162104-788fe5ffcd8c/go.mod h1:flIaEI6LNU6xOCD5PaJvn9wGP0agmIOqjrtsKGRguv4=
 golang.org/x/crypto v0.0.0-20170930174604-9419663f5a44/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 h1:VklqNMn3ovrHsnt90PveolxSbWFaJdECFbxSq0Mqo2M=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -163,4 +157,3 @@ gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWD
 gopkg.in/yaml.v2 v2.2.1 h1:mUhvW9EsL+naU5Q3cakzfE91YhliOondGd6ZrsDBHQE=
 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
-rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=

scripts/get_nodejs.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+VERSION=v11.15.0
+NODE_FULL=node-${VERSION}-linux-x64
+
+mkdir -p ~/.local/bin
+mkdir -p ~/.local/node
+wget http://nodejs.org/dist/${VERSION}/${NODE_FULL}.tar.gz -O ~/.local/node/${NODE_FULL}.tar.gz
+tar -xzf ~/.local/node/${NODE_FULL}.tar.gz -C ~/.local/node/
+ln -s ~/.local/node/${NODE_FULL}/bin/node ~/.local/bin/node
+ln -s ~/.local/node/${NODE_FULL}/bin/npm ~/.local/bin/npm
+export PATH=~/.local/bin:$PATH
+npm i -g dredd@11.0.1
+ln -s ~/.local/node/${NODE_FULL}/bin/dredd ~/.local/bin/dredd

scripts/get_tools.sh

@@ -64,3 +64,4 @@ installFromGithub golangci/golangci-lint 7b2421d55194c9dc385eff7720a037aa9244ca3
 installFromGithub petermattis/goid b0b1615b78e5ee59739545bb38426383b2cda4c9
 installFromGithub sasha-s/go-deadlock d68e2bc52ae3291765881b9056f2c1527f245f1e
 go get golang.org/x/tools/cmd/goimports
+installFromGithub snikch/goodman 10e37e294daa3c9a90abded60ff9924bafab3888 cmd/goodman