make client an interface

graphql/client.go

@@ -10,17 +10,57 @@ import (
 	"github.com/vektah/gqlparser/gqlerror"
 )
 
-type Client struct {
+// Client is the interface that the generate code calls into to actually make
+// requests.
+type Client interface {
+	// MakeRequest must make a request to the client's GraphQL API.
+	//
+	// ctx is the context that should be used to make this request.  If context
+	// is disabled in the genql settings, this will be set to
+	// context.Background().
+	//
+	// query is the literal string representing the GraphQL query, e.g.
+	// `query myQuery { myField }`.  variables contains the GraphQL variables
+	// to be sent along with the query, or may be nil if there are none.
+	// Typically, GraphQL APIs will accept a JSON payload of the form
+	//	{"query": "query myQuery { ... }", "variables": {...}}`
+	// but MakeRequest may use some other transport, handle extensions, or set
+	// other parameters, if it wishes.
+	//
+	// retval is a pointer to the struct representing the query result, e.g.
+	// new(myQueryResponse).  Typically, GraphQL APIs will return a JSON
+	// payload of the form
+	//	{"data": {...}, "errors": {...}}
+	// and retval is designed so that `data` will json-unmarshal into `retval`.
+	// (Errors are returned.) But again, MakeRequest may customize this.
+	MakeRequest(
+		ctx context.Context,
+		query string,
+		retval interface{},
+		variables map[string]interface{},
+	) error
+}
+
+type client struct {
 	endpoint   string
 	method     string
 	httpClient *http.Client
 }
 
-func NewClient(endpoint string, httpClient *http.Client) *Client {
+// NewClient returns a Client which makes requests to the given endpoint,
+// suitable for most users.
+//
+// The client makes requests to the given GraphQL endpoint using standard
+// GraphQL HTTP-over-JSON transport.  It will use the given http client, or
+// http.DefaultClient if a nil client is passed.
+//
+// The typical method of adding authentication headers is to wrap the client's
+// Transport to add those headers.  See example/caller.go for an example.
+func NewClient(endpoint string, httpClient *http.Client) Client {
 	if httpClient == nil {
 		httpClient = http.DefaultClient
 	}
-	return &Client{endpoint, http.MethodPost, httpClient}
+	return &client{endpoint, http.MethodPost, httpClient}
 }
 
 type payload struct {
@@ -33,7 +73,7 @@ type response struct {
 	Errors gqlerror.List   `json:"errors"`
 }
 
-func (client *Client) MakeRequest(ctx context.Context, query string, retval interface{}, variables map[string]interface{}) error {
+func (client *client) MakeRequest(ctx context.Context, query string, retval interface{}, variables map[string]interface{}) error {
 	body, err := json.Marshal(payload{
 		Query:     query,
 		Variables: variables,