Structured GraphQL Error Handling

[janeli1]

Structured GraphQL Error Handling

Fields serve as the fundamental atomic units requested by the client. In GraphQL, each Field can either return null (if nullable) or an error. The client relies on the detailed, Field level error information to determine whether this data unit should be cached. Therefore, it's important to manage errors at the field level to ensure that callers comprehend why they were unable to retrieve a specific Field and behave appropriately.

gqlgen handles required fields errors as,

1. If a field is declared and the data for this field is null, a Field error is added to the error list in the response, and the data will show as null, up to the nearest non-null entity.
2. If a field is NOT declared, even if the data for this field is null, no error is returned.
3. For the same field that appears in multiple parts of a response, field errors will be added for all paths. For example, in the schema provided below, the createdAt field in PastTransportJob Type is a required field. When the data for this field comes back as null, we get 2 error messages because it appears in both edges and nodes in PastOrdersConnection with different paths.

//schema
type Query {
 myPastOrders(first: Int!, after: String): PastOrdersConnection
}

type PastOrdersEdge {
 cursor: String!
 node: PastOrder
}

type PastOrdersConnection {
 edges : [PastOrdersEdge]
 nodes : [PastOrder]
 pageInfo : PageInfo!
 totalCount : Int!
}

type PastOrder {
 uuid: ID!
 job: PastTransportJob!
}

type PastTransportJob {
 uuid: ID!
 createdAt: Time!
}


"errors": [
    {
      "message": "the requested element is null which the schema does not allow",
      "path": [
        "myPastOrders",
        "edges",
        0,
        "node",
        "job",
        "createdAt"
      ]
    },
    {
      "message": "the requested element is null which the schema does not allow",
      "path": [
        "myPastOrders",
        "nodes",
        0,
        "job",
        "createdAt"
      ]
    }
  ],

The API today in gqlgen is to call graphql.AddError:

graphql.AddError(ctx, &gqlerror.Error{
	Path:       graphql.GetPath(ctx),
	Message:    "A descriptive error message",
	Extensions: map[string]interface{}{
		"code": "400",
	},
})

This has a few issues:

• It requires that you accurately pass in the field name into the method call. It’s easy to introduce a typo here. Lists are particularly challenging where you need to keep track of the correct array index.
• There’s no way to enforce specific types of errors being thrown (for example ensuring it maps to an HTTP error code).
• You can return both an error and a value. It’s not clear what the client should do with the value in the case of an error.

We believe there’s a simpler, less error prone API that solves all of these issues. The approach is similar to the Omittable type used on input types today in gqlgen.

We propose introducing a Result wrapper struct for all scalar types:

// Result ...
type Result[TValue any, TError error] struct {
	value TValue
	set   bool
	err   TError
}

// Success ...
func Success[TValue any](val TValue) Result[TValue, error] {
	return Result[TValue, error]{
		value: val,
		set:   true,
	}
}

// Error ...
func Error[TValue any, TError error](err error) Result[TValue, error] {
	return Result[TValue, error]{
		set: true,
		err: err,
	}
}

// GetValue ...
func (o Result[TValue, TError]) GetValue() TValue {
	return o.value
}

// GetError ...
func (o Result[TValue, TError]) GetError() error {
	return o.err
}

// IsSet ...
func (o Result[TValue, TError]) IsSet() bool {
	return o.set
}

This is very similar to the Result monad in Kotlin.

When developers hydrate data for a field, they can either set a value or set an error based on whether the downstream production service is able to return a valid response or not.

This API enables us to model the 3 possible states of each field:

1. Field hydration is successful and has a value.
2. Field hydration is successful and the value is null as expected for an optional field.
3. Field hydration failed with a specific error and the value is null.

The modelgen code for this proposal works as follows:

Rules	Schema	Codegen model
Scalar Types	type Human implements Character {   ...   id: ID! //required field   totalCredits: Int //optional field }	type Human struct {    ID           result.Result[string, error]    TotalCredits result.Result[*int, error] }
Enum		No change needed. Please refer to generated models examples below.
Lists	type Droid implements Character {  ...  primaryFunctions: [String] }	type Droid struct { ...    PrimaryFunctions []result.Result[*string, error] `json:"primaryFunctions,omitempty"` }
Interface	interface Character {  ...  name: String }	type Character interface {    ...    GetName() result.Result[*string, error] } func (this Droid) GetName() result.Result[*string, error] { return this.Name } func (this Human) GetName() result.Result[*string, error] { return this.Name }
Union		No change needed. Please refer to generated models examples below.

Runtime implementation

After we get the response from a resolver, the response carries Field data with Result types. Resolvers will return response data to the GraphQL response parser. The parser traverses the query and adds an error when it hits an marshall error with the corresponding path information. This is the same idea of the existing GraphQL parser for inputs using UnmarshalJSON. In gqlgen, when there is an unmarshall error for a query input model, the caller of UnmarshalJSON will add the error with path info with graphql.AddErrorOnPath. We propose implementing the graphql.Marshaler interface for Result types to either:

1. Return error when an error is set for the Result type OR
2. If a required field is not set, return the default error message as “the requested element is null which the schema does not allow”.
   Update gqlgen make the caller of MarshalJSON add this error with path info.

func (o Result[TValue any, TError error]) MarshalJSON() ([]byte, error) {
	if o.errorMsg != nil {
             return []byte("null"), o.error
       }
        if !o.set {
		if TValue is nillable {
			return []byte("null"), nil
                 } else {	
                        return []byte("null"), fmt.Printf("the requested element is null which the schema does not allow")
                 }		
	}
	return json.Marshal(o.value)
}

Example

Schema

type Draw @key(fields: "uuid") {
  uuid: ID!
  name: String!
  luckyNumber: Int
  won: Boolean
  message: String
}

type Starship {
  id: ID!
  name: String
  length: Float
}

interface Character {
  id: ID!
  name: String
  friends: [Character]
  appearsIn: [Episode!]!
}

type Human implements Character {
  id: ID!
  name: String
  friends: [Character]
  appearsIn: [Episode!]!
  starships: [Starship]
  totalCredits: Int
}

type Droid implements Character {
  id: ID!
  name: String
  friends: [Character]
  appearsIn: [Episode!]!
  primaryFunctions: [String]
  createdAt: Time!
}

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

union SearchResult = Human | Droid | Starship

type SearchResponse {
  nodes: [SearchResult]
}

Generated models

/* Example to support queries like:
hero(episode: Episode): Character
droid(id: ID!): Droid
search(text: String!): SearchResponse
*/

import (
	"fmt"
	"io"
	"strconv"
	"time"

	"graphql-dummy-service/graphql/result"
)

// Character ...
type Character interface {
	IsCharacter()
	GetID() result.Result[string, error]
	GetName() result.Result[*string, error]
	GetFriends() []result.Result[Character]
	GetAppearsIn() []result.Result[Episode]
}

// SearchResult ...
type SearchResult interface {
	IsSearchResult()
}

// Droid ...
type Droid struct {
	ID               result.Result[string, error]    `json:"id"`
	Name             result.Result[*string, error]   `json:"name,omitempty"`
	Friends          []result.Result[Character]      `json:"friends,omitempty"`
	AppearsIn        []result.Result[Episode]        `json:"appearsIn"`
	PrimaryFunctions []result.Result[*string, error] `json:"primaryFunctions,omitempty"`
	CreatedAt        result.Result[time.Time, error] `json:"createdAt,omitempty"`
}

// IsCharacter ...
func (Droid) IsCharacter() {}

// GetID ...
func (this Droid) GetID() result.Result[string, error] { return this.ID }

// GetName ...
func (this Droid) GetName() result.Result[*string, error] { return this.Name }

// GetFriends ...
func (this Droid) GetFriends() []Character {
	if this.Friends == nil {
		return nil
	}
	interfaceSlice := make([]Character, 0, len(this.Friends))
	for _, concrete := range this.Friends {
		interfaceSlice = append(interfaceSlice, concrete)
	}
	return interfaceSlice
}

// GetAppearsIn ...
func (this Droid) GetAppearsIn() []Episode {
	if this.AppearsIn == nil {
		return nil
	}
	interfaceSlice := make([]Episode, 0, len(this.AppearsIn))
	for _, concrete := range this.AppearsIn {
		interfaceSlice = append(interfaceSlice, concrete)
	}
	return interfaceSlice
}

// IsSearchResult ...
func (Droid) IsSearchResult() {}

// Human ...
type Human struct {
	ID           result.Result[string, error]  `json:"id"`
	Name         result.Result[*string, error] `json:"name,omitempty"`
	Friends      []result.Result[Character]    `json:"friends,omitempty"`
	AppearsIn    []result.Result[Episode]      `json:"appearsIn"`
	Starships    []result.Result[*Starship]		 `json:"starships,omitempty"`
	TotalCredits result.Result[*int, error]    `json:"totalCredits,omitempty"`
}

func (Human) IsCharacter()                                {}
func (this Human) GetID() result.Result[string, error]    { return this.ID }
func (this Human) GetName() result.Result[*string, error] { return this.Name }
func (this Human) GetFriends() []Character {
	if this.Friends == nil {
		return nil
	}
	interfaceSlice := make([]Character, 0, len(this.Friends))
	for _, concrete := range this.Friends {
		interfaceSlice = append(interfaceSlice, concrete)
	}
	return interfaceSlice
}
func (this Human) GetAppearsIn() []Episode {
	if this.AppearsIn == nil {
		return nil
	}
	interfaceSlice := make([]Episode, 0, len(this.AppearsIn))
	for _, concrete := range this.AppearsIn {
		interfaceSlice = append(interfaceSlice, concrete)
	}
	return interfaceSlice
}

func (Human) IsSearchResult() {}

type SearchResponse struct {
	Nodes []result.Result[SearchResult] `json:"nodes,omitempty"`
}

type Starship struct {
	ID     result.Result[string]          `json:"id"`
	Name   result.Result[string]          `json:"name"`
	Length result.Result[*float64, error] `json:"length,omitempty"`
}

func (Starship) IsSearchResult() {}

type Episode string

const (
	EpisodeNewhope Episode = "NEWHOPE"
	EpisodeEmpire  Episode = "EMPIRE"
	EpisodeJedi    Episode = "JEDI"
)

var AllEpisode = []Episode{
	EpisodeNewhope,
	EpisodeEmpire,
	EpisodeJedi,
}

func (e Episode) IsValid() bool {
	switch e {
	case EpisodeNewhope, EpisodeEmpire, EpisodeJedi:
		return true
	}
	return false
}

func (e Episode) String() string {
	return string(e)
}

func (e *Episode) UnmarshalGQL(v interface{}) error {
	str, ok := v.(string)
	if !ok {
		return fmt.Errorf("enums must be strings")
	}

	*e = Episode(str)
	if !e.IsValid() {
		return fmt.Errorf("%s is not a valid Episode", str)
	}
	return nil
}

func (e Episode) MarshalGQL(w io.Writer) {
	fmt.Fprint(w, strconv.Quote(e.String()))
}SearchResult `json:"nodes,omitempty"`
}

type Starship struct {
	ID     result.Result[string]          `json:"id"`
	Name   result.Result[string]          `json:"name"`
	Length result.Result[*float64, error] `json:"length,omitempty"`
}

func (Starship) IsSearchResult() {}

type Episode string

const (
	EpisodeNewhope Episode = "NEWHOPE"
	EpisodeEmpire  Episode = "EMPIRE"
	EpisodeJedi    Episode = "JEDI"
)

var AllEpisode = []Episode{
	EpisodeNewhope,
	EpisodeEmpire,
	EpisodeJedi,
}

func (e Episode) IsValid() bool {
	switch e {
	case EpisodeNewhope, EpisodeEmpire, EpisodeJedi:
		return true
	}
	return false
}

func (e Episode) String() string {
	return string(e)
}

func (e *Episode) UnmarshalGQL(v interface{}) error {
	str, ok := v.(string)
	if !ok {
		return fmt.Errorf("enums must be strings")
	}

	*e = Episode(str)
	if !e.IsValid() {
		return fmt.Errorf("%s is not a valid Episode", str)
	}
	return nil
}

func (e Episode) MarshalGQL(w io.Writer) {
	fmt.Fprint(w, strconv.Quote(e.String()))
}

[StevenACoffman]

Hey, I really appreciate you writing this proposal up! I want to give people time to respond before I make up my own mind.

My feelings on monads in Go is very accurately reflected by In search of better error handling for Go - I like monads in other languages, but I don’t see user-implemented monads generally as a perfect fit for Go until some other things are added to the language (please give me sum types).

However, in GraphQL, and in gqlgen, we already have to support things that are awkward in Go. (I'm looking at you Enums!) Maybe monadic Results are a better way to represent GraphQL partial success.

On the other hand, I really hate breaking backwards compatibility and forcing people to change what already works requires a really good justification.

So I'm currently conflicted and would like other people's opinion(s).

[janeli1]

Hi Steven, thank you for your comments!
I agree that that backwards compatibility is a valid concern. This plan in this proposal is to make the Result Wrapper as a configurable option. Similar to how the existing Omittable Input Type is supported as a configurable option,
We can build the Result Wrapper as a configurable option that the user can turn on using config in gqlgen.yml as below:

# Optional: wrap all scalar types with Result wrapper to support field level error handling.
result_wrapper: true

In this case, users has option to decide whether use Result Wrapper based on their needs. Please let me know if this approach seems reasonable.

[StevenACoffman]

Yeah, that sounds great actually. Then the experiment can proceed and we can let the community decide who wants to adopt it.

[clayne11]

I personally am supportive of this API. I agree that monads would be much better with sum types, exhaustive switch statements, and generic method support. That said, these are quite possibly (sadly) never coming to Go.

The current error handling API in gqlgen is extremely error prone / difficult to use correctly, and I can't think of a better approach to this problem than what's described here. I think we can find a way to make this backwards compatible with a switch.

I do also fundamentally think there's a few critical improvements like this that can be made to gqlgen and then we might want to consider a v1.0.0 that formalizes some of these improvements in a non-backwards compatible way so we can simplify the code base and integration patterns with a clean slate. That's a separate discussion though.