Implement GraphQL API

[albrow]

This is a WIP PR that implements the GraphQL API as described in #854.

Major tasks:

• Remove JSON-RPC API
• Server Implementation
  • order query
  • orders query
  • stats query
  • addOrders mutation
  • orderEvents subscription
• Go client
  • AddOrders
  • GetOrders
  • GetOrder
  • GetStats
  • RawQuery for arbitrary GraphQL queries.
• TypeScript client
  • addOrdersAsync
  • getOrdersAsync
  • getOrderAsync
  • getStatsAsync
  • onOrderEvents
    • Unsubscribe? Moving this to Support unsubscribing from GraphQL subscriptions #902.
    • Better WebSocket error handling
  • rawQueryAsync for arbitrary GraphQL queries.
• Testing
  • Marshaling/Unmarshaling JSON and GraphQL
  • Integration tests with Go client
  • Integration tests with TypeScript client
• Configuration (environment variables)
• Update or remove code that depended on JSON-RPC API
  • examples/add_order Decided to remove this as @jalextowle and I feel it doesn't really add a lot of value and can create confusion because it doesn't set up the required balances/allowances.
  • examples/subscribe_to_orders The Go client doesn't currently support subscriptions. We can add support for this later on based on demand.
  • cmd/mesh-bridge Decided not to update the bridge in this PR. We can update it in the future if needed.
  • Browser integration tests
• Update Dockerfiles
• Documentation
• Type de-duplication? (Maybe address in follow-up PR) Moving this to Reduce type de-duplication and finalize all APIs #900.
• Improve subscription support in GraphiQL page? (Maybe address in follow-up PR) Moving this to Improve support for subscriptions in GraphQL playground #903

[albrow]

Overview

It might be helpful to read up on some background information on GraphQL.

This PR implements a GraphQL server and two clients: Go and TypeScript. Both clients are designed to be usable by someone with no prior GraphQL experience, and therefore makes some assumptions about the kinds of queries you want to run (especially the shape of the data that will be returned). Users who are more familiar with GraphQL and want maximum flexibility may choose to create or generate their own clients.

The server uses https://github.com/99designs/gqlgen, which automatically generates some code for us based on the GraphQL schema. If we make any changes to the schema, we will need to run go generate ./... and then update the server code as needed. The relevant make tasks (e.g. build, test-all) will automatically run go generate ./.... See https://blog.golang.org/generate for more information about the go generate command.

The Go client uses https://github.com/machinebox/graphql, which is a low-level client library that doesn't generate anything for us. However, we are able to re-use some of the generated types from https://github.com/99designs/gqlgen. Notably, the Go client does not support subscriptions because the library we're using doesn't support them. We can add support for subscriptions based on demand.

The TypeScript client uses https://www.apollographql.com/docs/react/api/core/ApolloClient/. Apollo Client has a lot of interesting and powerful features when used in conjunction with React, but for the TypeScript client we are just handling the basics. The TypeScript client does support subscriptions.

Configuration

There are three new environment variables for configuring the server:

	// EnableGraphQLServer determines whether or not to enable the GraphQL server.
	// If enabled, GraphQL queries can be sent to GraphQLServerAddr at the /graphql
	// URL. By default, the GraphQL server is disabled.
	EnableGraphQLServer bool `envvar:"ENABLE_GRAPHQL_SERVER" default:"false"`
	// GraphQLServerAddr is the interface and port to use for the GraphQL API.
	// By default, 0x Mesh will listen on 0.0.0.0 (all available addresses) and
	// port 60557.
	GraphQLServerAddr string `envvar:"GRAPHQL_SERVER_ADDR" default:"0.0.0.0:60557"`
	// EnableGraphQLPlayground determines whether or not to enable GraphiQL, an interactive
	// GraphQL playground which can be accessed by visiting GraphQLServerAddr in a browser.
	// See https://github.com/graphql/graphiql for more information. By default, GraphiQL
	// is disabled.
	EnableGraphQLPlayground bool `envvar:"ENABLE_GRAPHQL_PLAYGROUND" default:"false"`

If you are running Mesh locally and ENABLE_GRAPHIQL is true, you can access the GraphiQL playground at http://localhost:60557. The playground is a good way to play around with the new API.

Files and directories

• graphql/ Contains the GraphQL schema, server, and Go code.
  • client/_ The Go client.
  • generated/ Code generated by https://github.com/99designs/gqlgen. Should not be edited directly.
  • gqltypes/ Go types which map 1-to-1 with types defined in the GraphQL schema. Mix of generated and manually-written code.
  • schema.graphql The canonical GraphQL schema.
  • schema.resolvers.go The resolver implementations used by the server (i.e. functions that define how each query is handled).
• gqlgen.yaml This configuration file tells https://github.com/99designs/gqlgen where to put generated code and how it should be generated.
• packages/
  • mesh-graphql-client/ The TypeScript client, including integration tests.

[jalextowle]

Overall, this is looking really solid. Most of comments are either nits, questions, or minor comments.

[jalextowle]

We're locked into the British spelling now 😂

[albrow]

🇬🇧 Yeah we have to pick one. In the past we were using two Ls and I don't think it make sense to change it in the public API.