Add GraphQL Extensions (Khan#184)

This enables accessing the Extensions field, as defined in the response
format: https://spec.graphql.org/October2021/#sec-Response-Format

Extensions can be enabled using configuration option use_extensions.
This will change the return parameters of the generated client
functions. Making it a breaking change if enabled.

Since extensions are untyped as defined in the spec, the Client will
return an interface of type map[string]interface{}.

docs/CHANGELOG.md

@@ -23,10 +23,12 @@ When releasing a new version:
 ### Breaking changes:
 
 - genqlient now requires Go 1.16 or higher.
+- The [`graphql.Client`](https://pkg.go.dev/github.com/Khan/genqlient/graphql#Client) interface now accepts two structs for the request and response, to allow future expansion, rather than several individual arguments.  Clients implementing the interface themselves will need to change the signature; clients who simply call `graphql.NewClient` are unaffected.
 
 ### New features:
 
 - genqlient can now run as a portable binary (i.e. without a local checkout of the repository or `go run`).
+- You can now enable `use_extensions` in the configuration file, to receive extensions returned by the GraphQL API server. Generated functions will return extensions as `map[string]interface{}`, if enabled.
 
 ### Bug fixes:
 

docs/genqlient.yaml

@@ -87,6 +87,16 @@ client_getter: "github.com/you/yourpkg.GetClient"
 # Defaults to false.
 use_struct_references: boolean
 
+# If set, generated code will have a third return parameter of type 
+# map[string]interface{}. This will contain the optional values
+# of the Extensions field send from Servers.
+# ref.: https://spec.graphql.org/October2021/#sec-Response-Format
+#
+# This can be useful for extending the GraphQL Protocol.
+#
+# Defaults to false.
+use_extensions: boolean
+
 
 # A map from GraphQL type name to Go fully-qualified type name to override
 # the Go type genqlient will use for this GraphQL type.

example/genqlient.yaml

@@ -2,7 +2,6 @@ schema: schema.graphql
 operations:
 - genqlient.graphql
 generated: generated.go
-
 # needed since it doesn't match the directory name:
 package: main
 

generate/config.go

@@ -27,6 +27,7 @@ type Config struct {
 	ClientGetter     string                  `yaml:"client_getter"`
 	Bindings         map[string]*TypeBinding `yaml:"bindings"`
 	StructReferences bool                    `yaml:"use_struct_references"`
+	Extensions       bool                    `yaml:"use_extensions"`
 
 	// Set to true to use features that aren't fully ready to use.
 	//

generate/generate_test.go

@@ -191,6 +191,10 @@ func TestGenerateWithConfig(t *testing.T) {
 			ClientGetter: "github.com/Khan/genqlient/internal/testutil.GetClientFromNowhere",
 			ContextType:  "-",
 		}},
+		{"Extensions", "", &Config{
+			Generated:  "generated.go",
+			Extensions: true,
+		}},
 	}
 
 	sourceFilename := "SimpleQuery.graphql"

generate/operation.go.tmpl

@@ -12,34 +12,35 @@ func {{.Name}}(
     {{.GraphQLName}} {{.GoType.Reference}},
     {{end -}}
     {{end -}}
-) (*{{.ResponseName}}, error) {
-    {{- if .Input -}}
-    {{/* We need to avoid conflicting with any of the function's argument names
-         which are derived from the GraphQL argument names; notably `input` is
-         a common one.  So we use a name that's not legal in GraphQL, namely
-         one starting with a double-underscore. */ -}}
-    __input := {{.Input.GoName}}{
+) (*{{.ResponseName}}, {{if .Config.Extensions -}}map[string]interface{},{{end}} error) {
+    req := &graphql.Request{
+        OpName: "{{.Name}}",
+        Query:  `{{.Body}}`,
+    {{if .Input -}}
+        Variables: &{{.Input.GoName}}{
         {{range .Input.Fields -}}
         {{.GoName}}: {{.GraphQLName}},
         {{end -}}
-    }
+        },
     {{end -}}
-
+    }
     var err error
     {{if .Config.ClientGetter -}}
-    client, err := {{ref .Config.ClientGetter}}({{if ne .Config.ContextType "-"}}ctx{{else}}{{end}})
+    var client graphql.Client
+
+    client, err = {{ref .Config.ClientGetter}}({{if ne .Config.ContextType "-"}}ctx{{else}}{{end}})
     if err != nil {
-        return nil, err
+        return nil, {{if .Config.Extensions -}}nil,{{end -}} err
     }
     {{end}}
+    var data {{.ResponseName}}
+    resp := &graphql.Response{Data: &data}
 
-	var retval {{.ResponseName}}
     err = client.MakeRequest(
         {{if ne .Config.ContextType "-"}}ctx{{else}}nil{{end}},
-        "{{.Name}}",
-        `{{.Body}}`,
-        &retval,
-        {{if .Input}}&__input{{else}}nil{{end}},
+        req,
+        resp,
     )
-    return &retval, err
+
+    return &data, {{if .Config.Extensions -}}resp.Extensions,{{end -}} err
 }