The future of Fetcher - subscriptions, @stream, @defer, @live and multipart HTTP

[acao]

the fetcher prop is one of the most important GraphiQL props. it's required and open-ended for a reason. at it's core, its a function that returns a promise that is used both to retrieve the introspection schema, and for executing operations.

it's a bit of a misnomer because the browser fetch API is not a requirement by any means, though it's a sensible default example. but we purposefully have always kept the fetcher interface open ended so that people could implement their own means of executing graphql operations against a schema or introspecting a schema in any fashion, using any transport. (one of the remaining issues here is response formatting (protobufs, yaml, etc) but that's another matter).

GraphQL Language nor GraphiQL assume HTTP

GraphiQL is the spec implementaton for the language, so it's important that we adhere to the generic language spec, and follow other emerging graphql specifications from various graphql working groups. Ideally, within a few minor versions in 1.x, we can ship these utilities (such as the fetcher abstraction described below) that allow people to easily implement most of the popular transport/op type spec combinations and even hopefully more experimental language features as well.

the recent headers tab feature was the first time the actual GraphiQL component assumed anything regarding HTTP. our implementation examples usually have assumed HTTP, but the actual application hasn't until then. even then, it's disabled by default, mostly for this reason and to avoid breaking custom themes.

the reasons for the choice to not assume graphql implementations use HTTP are well known, however if you are unfamiliar with the reasons for this, see: the language working group spec body vs the graphql http working group spec body (I think a graphql websockets working group has just started as well?) . (they are open to anyone who adds themselves to the agenda in the graphql spec repos btw!)

schemaFetcher

One thing that could make this easier, without breaking the API, is an optional schemaFetcher prop that returns a schema primitive, and overrides the use of the fetcher prop for schema introspection. one can just detect if operationType.toLowercase() === 'introspectionquery', however then it still expects a JSON introspection result.

On the other hand, a schemaFetcher prop would allow you to return a schema primitive however you like, for example - by loading and parsing an SDL file and using schemaFromAST (scales much better than http introspection imo). @lostplan was just mentioning how chrome(Ium)'s implementation of the browser FS API now supports reading from the actual disk, so that unlocks SO MANY options. streaming GraphQL schemas to disk for frontend devs and analysts, for example.

This way, if someone is handling mostly multipart HTTP and wss, for example, they can fetch the schema however and fetcher is only worried about schema execution.

Because schemaFetcher is optional, and fetcher behaves the same unless it's used, it is a completely nonbreaking change for 1.0 that would unlock a lot of options. people could have servers that don't even return singular JSON results at all, not even just for introspection!

the need for fetcher abstractions

in order to implement other spec configurations, we have to start getting very opinionated about what's supported in the provided fetcher, so some abstractions for generating a fetcher prop (using provided libraries) may be in order for the 90% case.

thinking the function could be called createStandardGraphiQLFetcher() and have options like:

const fetcher = createStandardGraphiQLFetcher({
  schemaUrl: ``,
  defaultHeaders: { "authorization": "Bearer 123" },
  useGetForQueries: true,
  parseMultipart: true,
  wsSubscriptions: true,
  wsEndpoint: ``, // if different from schema
 
})

<GraphiQL fetcher={fetcher} />

what other options does it need to be as unopinionated as possible whilst obscuring the abstractions mentioned below?

we will need to be very careful about how this ships (probably as a seperate package) to avoid any dependency bloat, as well. tree shaking might allow us to export it from graphiql package, but that would still introduce more complexity in terms of more dependencies, peer dependencies, etc

Subscriptions over WSS

The way we've implemented subscriptions using this pattern is using GraphiQL Subscriptions Fetcher which expects a ws client interface like subscriptions-transport-ws.

createStandardGraphiQLFetcher could take care of all of this with wsSubscriptions: true

@stream, @defer @live and other multipart responses

now that stream and defer are spec, the http multipart spec is likely soon to follow, so we will need to implement fetch-multipart-graphql when users opt-in to that spec implementation

thinking the fetcher response will just be evaluated for whether it's multipart, and parsed differently as such?

createStandardGraphiQLFetcher could take care of all of this with parseMultipart: true

Subscriptions over HTTP? Or wss queries and mutations?

This is a thing that I had no idea was happening until recently, where people are using HTTP GET/POST with subscriptions somehow? or is it queries and mutations over WSS? help i forgot which 🤣

It should be explored further and potentially implemented as part of this abstraction, if the HTTP spec working group and general community agrees. We have had several issues related to this already

TODO

• cross-reference issues/bugs
• explore other popular transport/op type combinations

[FluorescentHallucinogen]

From UI perspective, it would be really nice to see both, patches and the final response. Something like this: https://twitter.com/apollographql/status/1303781711759568897.

[acao]

yes, subscriptions already work that way currently, so we were hoping to do the same for HTTP multipart

[acao]

ah hmm... ours might work a little different at first. just thinking of concatenating them all as JSON results, but then it would be nice to use comments in the JSON like apollo does do delimit/markup responses with metadata... or to even have a special results display that has metadata for each patch and response

[acao]

https://github.com/n1ru4l/graphql-bleeding-edge-playground @n1ru4l has an excellent starting point on this concept here, with a fetcher handling multipart parsing

[acao]

it’s a great feeling when the solution feels this ubiquitous, haha

[n1ru4l]

It would also help if we could somehow standardize the sink types across all involved packages I feel I need to as any casts more often than I would like to 😢

Also what about replacing the term query with operation for the graphql document string?

[acao]

yes, i think a good place for that standardization would be the graphql http working group spec, since this is for the http/s multipart spec

[acao]

in the version 2 RFC i renamed query to operation in soo many places it felt great! thats still ready to to with hooks, i18n, monaco if someone wants to implement a replacement for context which was too underperformant. more writeups about that effort coming soon

[acao]

https://github.com/graphql/graphiql/tree/main/packages/graphiql-2-rfc-context

I will update it's readme sometime soon with details on what all of this introduces, the drawbacks, and instructions on how create your own RFC based on this if you want, or build a new one from scratch!

[n1ru4l]

in terms of displaying the results in GraphiQL it would be nice if one could be able to switch between showing all partial results ot showing the complete merged result.

[FluorescentHallucinogen]

See #1700 (comment). 😉

[n1ru4l]

nevermind then I will try to take a look at this 😂

[acao]

this is next up after some other language spec is adopted first! it will be the first effort towards graphiql being able to exemplify and support the full transport spec reference, as express-graphql has already done