Disabling null bubbling should be a "request" option

[benjie]

Methods to disable null propagation

There are a number of ways we might consider disabling null propagation

1. Operation directive (@disableErrorPropagation, @behavior(onError: NULL), @onError(action: NULL), @noBubblesPlz, etc)
2. Document directive (as above, but document level so it obviously applies to fragments too)
3. Request parameter
4. Schema toggle (breaking change / GraphQL 2.0)
5. Only using semantic non-null types on output (never using strictly non-null types)

Thinking about the future

I've been thinking about what GraphQL should look like in 10 years time, and I'm pretty sure that disabling null bubbling is going to be desired for most clients. Any client that:

• throws away the entire request if an error occurs
• uses a normalized cache
• uses a "throw on error" mechanism

should be moving away from the traditional null bubbling mechanics so that they can leverage the semantically non-null types in the schema.

Why a request parameter?

Adding the directive to every GraphQL operation you write feels wrong, and it would be very easy to accidentally miss it on a single operation. Your client could do it for you (like Apollo Client traditionally adds __typename to every selection set) but I don't think we should do much document manipulation like this and it undermines the ease of implementing trusted documents (the document you write is further from the document you actually execute).

I think we should use a request parameter (e.g. errorBehavior) to indicate that the client wishes to disable null bubbling.

Users shouldn't have to add a directive to every GraphQL document they write.

A "request" parameter can be implemented on client or server - e.g. normally the server provides the schema part of a GraphQL "request". So if your server chooses, it could choose to disable null propagation on every request. We may dictate in the GraphQL-over-HTTP spec whether this is allowed or not, but it's an option!

Most importantly for me: error propagation doesn't really relate to individual GraphQL operations, it relates to the client or framework you're using.

Worked example

Consider a simple client that uses fetch() + graphql-toe to return the result of a (traditional) GraphQL request:

import { toe } from "graphql-toe";

export async function graphqlFetch<T>(request: {
  query: string,
  operationName?: string,
  variables?: object,
}) {
  const response = await fetch("/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/graphql-response+json, application/json;q=0.9",
    },
    body: JSON.stringify(request),
  });

  const contentType = response.headers.get("Content-Type");
  const isDefinitelyGraphQLResponse = contentType?.startsWith("application/graphql-response+json");

  if (!isDefinitelyGraphQLResponse && !response.ok) {
    throw new Error(`Unexpected response: ${response.status} ${response.statusText}`);
  }

  const result = response.json();

  return toe(result) as T;
}

This client throws when an errored field is accessed (thanks to graphql-toe), so it's impossible for code to ever read an "error null", and thus it may as well disable error propagation on every request:

-    body: JSON.stringify(request),
+    body: JSON.stringify({ ...request, errorBehavior: "NULL" }),

This is a very small change for the client function and involves no effort on the caller's part. From the caller's perspective no types have broken and it hasn't invalidated any of the existing code; what has changed is that the impact of errors are now more local to the places where they were accessed, rather than destroying seemingly independent fragment selection sets.

That is, of course, assuming that the GraphQL server supports it (we should add a key to the response to indicate that this new parameter has been honoured). But here's the great thing - if the server doesn't support this parameter it will simply ignore it and return the traditional result - no change. This means that all clients who would like to disable null bubbling can turn on that option today(ish), and when support is added to their server it will magically start working.

Implementation

I wrote up an implementation of this back in September: graphql/graphql-js#4192

This worked by adding an additional errorPropagation: boolean = true option to the GraphQL args, and then not re-throwing the error during execute:

https://github.com/graphql/graphql-js/blob/eb9b6c8a77193fc5ed3685d1e95d32b99c9df9d9/src/execution/execute.ts#L609

I think this option should be changed to be errorBehavior: 'PROPAGATE' | 'NULL' | 'ABORT' (because I think clients that throw away the entire request if an error occurs should just use errorBehavior: 'ABORT' from the outset), and I don't think I added a parameter to the output, but otherwise the concept is broadly the same.