Allow genqlient types to be marshaled safely (#120)

## Summary:
When genqlient generates output types, it generates whatever code is
necessary to unmarshal them.  Conversely, when it generates input types,
it generates whatever code is necessary to marshal.  This is all that's
needed for genqlient itself: it never needs to marshal output types or
unmarshal input types.

But maybe you do!  (For example, to put the responses in a cache, which
is the use case that @csilvers hit at Khan, although there are others
one can imagine.)  While we can't support every serialization format you
might want (at least not without adding plugins or some such), it's not
unreasonable to expect that since genqlient can read JSON, it can write
it too.  Sadly, in the past this was not true for types requiring custom
unmarshaling logic, for several reasons.

In this commit I implement logic to always write both marshalers and
unmarshalers whenever they're needed to be able to correctly round-trip
the types, even though genqlient doesn't do so.  I wasn't starting from
scratch, since of course we already write both marshalers and
unmarshalers in some cases.  But this ended up requiring surprisingly
large changes on the marshaling side, mostly to correctly support
embedding (which we use for named fragments).

Specifically, as the comments in `types.go` discuss, the most difficult
issue is spreads with duplicate fields, which translate to Go embedded
fields which end up hidden from the json-marshaler.  Ultimately, I had
to do things quite differently from unmarshaling, and essentially
flatten the type when we write marshaler.  But in the end it's not so
ugly -- indeed arguably it's cleaner!  Mainly it's just different.

One thing to note is that we do marshal `__typename` based on
what we know about the types; users need not fill it in (and if they
do we'll ignore it).  This seemed to me to be a better UX, and
didn't add much complexity.

In general, I begin to wonder whether using `encoding/json` at all is
really right for genqlient: we're doing a lot of work to appease it,
despite knowing what our types look like.  I think it would still be a
significant increase in lines of code to roll our own, but that code
would perhaps be simpler, and would surely be faster (although if we
just want the speed gains we could use another JSON-generator library,
see also #47).  Anyway, something to think about in the future.

## Test plan:
make tesc


Author: benjaminjkraft

Reviewers: csilvers, StevenACoffman, benjaminjkraft, dnerdy, aberkan, jvoll, mahtabsabet, MiguelCastillo

Required Reviewers: 

Approved By: StevenACoffman, dnerdy

Checks: ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint, ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint

Pull Request URL: #120

docs/CHANGELOG.md

@@ -24,6 +24,8 @@ When releasing a new version:
 
 ### New features:
 
+- genqlient's types are now safe to JSON-marshal, which can be useful for putting them in a cache, for example.  See the [docs](FAQ.md#-let-me-json-marshal-my-response-objects) for details.
+
 ### Bug fixes:
 
 ## v0.2.0

docs/FAQ.md

@@ -96,6 +96,19 @@ bindings:
 
 Or, you can bind it to any other type, perhaps one with size-checked constructors; see the [`genqlient.yaml` documentation](`genqlient.yaml`) for more details.
 
+### … let me json-marshal my response objects
+
+This is supported by default!  All genqlient-generated types support both JSON-marshaling and unmarshaling, which can be useful for putting them in a cache, inspecting them by hand, using them in mocks (although this is [not recommended](#-test-my-graphql-apis)), or anything else you can do with JSON.  It's not guaranteed that marshaling a genqlient type will produce the exact GraphQL input -- we try to get as close as we can but there are some limitations around Go zero values -- but unmarshaling again should produce the value genqlient returned.  That is:
+
+```go
+resp, err := MyQuery(...)
+// not guaranteed to match what the server sent (but close):
+b, err := json.Marshal(resp)
+// guaranteed to match resp:
+var respAgain MyQueryResponse
+err := json.Unmarshal(b, &resp)
+```
+
 ## How do I make a query with …
 
 ### … a specific name for a field?

generate/marshal.go.tmpl

@@ -1,28 +1,60 @@
-{{/* See unmarshal.go.tmpl for more on how this works; this is mostly just
-     parallel (and simplified -- we don't need to handle embedding). */}}
+{{/* We generate MarshalJSON for much the same reasons as UnmarshalJSON -- see
+     unmarshal.go.tmpl for details.  (Note we generate both even if genqlient
+     itself needs only UnmarshalJSON, for the benefit of callers who want to,
+     for example, put genqlient responses in a cache.)  But our implementation
+     for marshaling is quite different.
+
+     Specifically, the treatment of field-visibility with embedded fields must
+     differ from both ordinary encoding/json and unmarshaling: we need to
+     choose exactly one conflicting field in all cases (whereas Go chooses at
+     most one and when unmarshaling we choose them all).  See
+     goStructType.FlattenedFields in types.go for more discussion of embedding
+     and visibility.
+
+     To accomplish that, we essentially flatten out all the embedded fields
+     when marshaling, following those precedence rules.  Then we basically
+     follow what we do in unmarshaling, but in reverse order: first we marshal
+     the special fields, then we glue everything together with the ordinary
+     fields.
+
+     We do one other thing differently, for the benefit of the marshal-helper
+     in marshal_helper.go.tmpl.  While when unmarshaling it's easy to unmarshal
+     out the __typename field, then unmarshal out everything else, with
+     marshaling we can't do the same (at least not without some careful
+     JSON-stitching; the considerations are basically the same as those
+     discussed in FlattenedFields).  So we write out a helper method
+     __premarshalJSON() which basically does all but the final JSON-marshal.
+     (Then the real MarshalJSON() just calls that, and then marshals.)
+     Thus a marshal-helper for this type, if any, can call __premarshalJSON()
+     directly, and embed its result. */}}
+
+type __premarshal{{.GoName}} struct{
+    {{range .FlattenedFields -}}
+    {{if .NeedsMarshaling -}}
+    {{.GoName}} {{repeat .GoType.SliceDepth "[]"}}{{ref "encoding/json.RawMessage"}} `json:"{{.JSONName}}"`
+    {{else}}
+    {{.GoName}} {{.GoType.Reference}} `json:"{{.JSONName}}"`
+    {{end}}
+    {{end}}
+}
 
 func (v *{{.GoName}}) MarshalJSON() ([]byte, error) {
-    {{/* We do the two passes in the opposite order of unmarshal: first, we
-         marshal the special fields, then we assign those to the wrapper struct
-         and finish marshaling the whole object.  But first we set up the
-         object for the second part, so we can assign to it as we go. */}}
-    var fullObject struct{
-        *{{.GoName}}
-        {{range .Fields -}}
-        {{if .NeedsMarshaler -}}
-        {{.GoName}} {{repeat .GoType.SliceDepth "[]"}}{{ref "encoding/json.RawMessage"}} `json:"{{.JSONName}}"`
-        {{end -}}
-        {{end -}}
-        {{ref "github.com/Khan/genqlient/graphql.NoMarshalJSON"}}
+    premarshaled, err := v.__premarshalJSON()
+    if err != nil {
+        return nil, err
     }
-    fullObject.{{.GoName}} = v
+    return json.Marshal(premarshaled)
+}
 
-    {{range $field := .Fields -}}
-    {{if $field.NeedsMarshaler -}}
+func (v *{{.GoName}}) __premarshalJSON() (*__premarshal{{.GoName}}, error) {
+    var retval __premarshal{{.GoName}}
+
+    {{range $field := .FlattenedFields -}}
+    {{if $field.NeedsMarshaling -}}
     {
-        {{/* Here dst is the json.RawMessage, and src is the Go type */}}
-        dst := &fullObject.{{$field.GoName}}
-        src := v.{{$field.GoName}}
+        {{/* Here dst is the json.RawMessage, and src is the Go type. */}}
+        dst := &retval.{{$field.GoName}}
+        src := v.{{$field.Selector}}
         {{range $i := intRange $field.GoType.SliceDepth -}}
         *dst = make(
             {{repeat (sub $field.GoType.SliceDepth $i) "[]"}}{{ref "encoding/json.RawMessage"}},
@@ -45,7 +77,7 @@ func (v *{{.GoName}}) MarshalJSON() ([]byte, error) {
             {{if not $field.GoType.IsPointer}}&{{end}}src)
         if err != nil {
             return nil, fmt.Errorf(
-                "Unable to marshal {{$.GoName}}.{{$field.GoName}}: %w", err)
+                "Unable to marshal {{$.GoName}}.{{$field.Selector}}: %w", err)
         }
         {{if $field.GoType.IsPointer -}}
         }{{/* end if src != nil */}}
@@ -54,8 +86,10 @@ func (v *{{.GoName}}) MarshalJSON() ([]byte, error) {
         }
         {{end -}}
     }
+    {{else -}}
+    retval.{{$field.GoName}} = v.{{$field.Selector}}
+    {{end -}}
     {{end -}}
-    {{end}}
 
-    return {{ref "encoding/json.Marshal"}}(&fullObject)
+    return &retval, nil
 }

generate/marshal_helper.go.tmpl

@@ -0,0 +1,44 @@
+{{/* This is somewhat parallel to unmarshal_helper.go.tmpl, but, as usual, in
+     reverse.  Note the helper accepts a pointer-to-interface, for
+     consistency with unmarshaling and with the API we expect of custom
+     marshalers. */}}
+
+func __marshal{{.GoName}}(v *{{.GoName}}) ([]byte, error) {
+    {{/* Determine the GraphQL typename, which the unmarshaler will need should
+         it be called on our output. */}}
+    var typename string
+    switch v := (*v).(type) {
+    {{range .Implementations -}}
+    case *{{.GoName}}:
+        typename = "{{.GraphQLName}}"
+
+        {{/* Now actually do the marshal, with the concrete type. (Go only
+             marshals embeds the way we want if they're structs.)  Except that
+             won't work right if the implementation-type has its own
+             MarshalJSON method (maybe it in turn has an interface-typed
+             field), so we call the helper __premarshalJSON directly (see
+             marshal.go.tmpl). */}}
+        {{if .NeedsMarshaling -}}
+        premarshaled, err := v.__premarshalJSON()
+        if err != nil {
+            return nil, err
+        }
+        result := struct {
+            TypeName string `json:"__typename"`
+            *__premarshal{{.GoName}}
+        }{typename, premarshaled}
+        {{else -}}
+        result := struct {
+            TypeName string `json:"__typename"`
+            *{{.GoName}}
+        }{typename, v}
+        {{end -}}
+        return json.Marshal(result)
+    {{end -}}
+    case nil:
+        return []byte("null"), nil
+    default:
+        return nil, {{ref "fmt.Errorf"}}(
+            `Unexpected concrete type for {{.GoName}}: "%T"`, v)
+    }
+}