Persisted queries (on steroids)

[gampleman]

Introduce a more powerful version of Persisted Queries.

Background

There is a neat feature of some GraphQL implementations called persisted queries. The exact details are not AFAICT yet fully standardised and different implementation therefore vary between the details. But the basic story is something like this:

1. At build time a (privileged) client extracts its GraphQL operations and uploads them to the server.
2. The server stores these queries under a content hash returned to the client. The server is free to parse and optimise these queries at its leisure.
3. At runtime the client only sends the hash and potentially any GraphQL variables the query contained.

The benefits are:

1. Smaller queries transmitted over the wire¹.
2. The server can skip parsing and validating the query (and theoretically nothing stops the backend engineers from manually handling that route and providing an uber-optimized implementation).
3. The client can have a smaller bundle, since it needs less code to handle the requests.
4. Simple HTTP caching becomes possible, as these can now just be GET requests.

However, I think one could go much further in this direction if persisted queries allowed also to store (pure) computation (i.e. SelectionSets :)). There is often an inefficiency in APIs. For instance, on our homepage we want to fetch a collection, where each item has a collection of its own, each item in there has some attributes. But our homepage only wants to show the range of possible attributes (i.e. the min and the max). In order to do that, we need to fetch the entire collection, just to show those 2 numbers. However, if the selection set was executed server side, we could just transmit the 2 numbers we need.

Proposal

The server could accept a small language that would allow data manipulation as well as emitting GraphQL queries - in a pure manner without runtime exceptions. This is quite like what SelectionSet already provides. The end result of this computation would be a serialisable datastructure that the client can easily (and automatically) decode.

There is some hand-waving around the details, as this is clearly not really a proposal for the here and now, as this requires both client, server and build tooling support. My aim here is more to start the conversation and see if this has potential.

Risks and drawbacks

Allowing arbitrary computation on the backend could have serious security implications (I think using Elm should nullify these, but still). There is also some potential for DoS vectors here, so I think having strict timeouts would be necessary. Further (and I think a lot stored queries implementations do this already) this capability doesn't necessarily need to be available to random 3rd party clients, but could be restricted to privileged clients (i.e. first party or third party that have strong contractual relationships, etc).

Additional ideas

A further cool capability would be to be able to chain GraphQL requests inside the stored query. This might struggle with timeouts, but we often have issues where multiple mutations and queries have to be run sequentially to perform an operation, which results in a lot of unnecessary traffic between the server and client.

Additionally, if timeouts were an insufficient tool, then perhaps a program counter limit could be imposed (like in the Erlang VM, or Gas in ETH).

Footnotes

1. This can be pretty significant. A recent query I was debugging at work had over 16000 characters in it. ↩

[dillonkearns]

@hariroshan commented asking about this, so I thought I'd follow up in this thread instead to keep things organized.

From the Proposal section above:

The server could accept a small language that would allow data manipulation as well as emitting GraphQL queries - in a pure manner without runtime exceptions. This is quite like what SelectionSet already provides. The end result of this computation would be a serialisable datastructure that the client can easily (and automatically) decode.

There is some hand-waving around the details, as this is clearly not really a proposal for the here and now, as this requires both client, server and build tooling support. My aim here is more to start the conversation and see if this has potential.

My gut feeling is that there isn't a clear goal to this specific idea of having a language that the server can execute. For example, which server framework would be able to make use of this? What would the contract be? What problem would this solve where there is already a GraphQL implementation that does some data transformation? I don't see a specific problem that is solved here. I think tools like Lamdera and elm-pages are more likely to be useful approaches to doing pure data transformations - coupling that set of transformations directly to GraphQL queries seems like a mismatch to me.

That said, the more general idea of persisted queries is certainly interesting. The fact that it's not standardized does make it challenging to support. I'm not sure if there's some sort of common ground between different persistent query implementations that elm-graphql could hook into in a meaningful way to interface with different GraphQL server tools to give them what they expect a persistent queries client to provide. I think a good starting point would be to research what the contract is for a few different popular backend tools (for example, here are some docs for Apollo's persistent queries) and compare how they work:

• What does the HTTP request look like that sends the query with the hash?
• How does it do a fallback with the actual query if the hash isn't recognized? What kind of error response is sent for the client to know it failed?
• At the build step, how do you teach the backend what persistent queries should be available? I'm guessing it might rely on GraphQL variables, which could be a dead end for the current elm-graphql architecture because of some of the challenges outlined in Support Absinthe logger masking by allowing variables to be used instead of directly inserting input values #27

I think that lack of GraphQL variables in elm-graphql would probably be the first thing to consider as that would make exploring this more deeply moot without some solution to that design challenge.

Besides that, I think a tool to support persisted queries for elm-graphql would probably need to use some code generation (and static code analysis using something like elmi-to-json to get a list of top-level definitions of a certain type, or something along those lines) to take a module with some top-level definitions of SelectionSets, get their String representation (probably through a CLI that runs some temporary generated Elm code), and then pass that set of gql queries over to the backend framework to get the corresponding hash.

Anyway, hope those notes are helpful! Thanks for the discussion.

[hariroshan]

Hi. I remember previous versions of react relay used to find all the GraphQl queries used in the folder, computes hashes for it and the outputs a JSON file with the a single object mapping hashes to queries

{
[hash1] : "query { helloworld }",
[hash2] : "query { hello }",
...
}

And any server can take this json file and build a lookup mapping if the request contains the hash (operation id). Incase if the operation is not found the client gets GraphQl error and and sends serialised query as fallback.

Maybe we can take the same approach ?
We can send operation id (hash) like the operation name.

Another approach I can think of is, if we let the developers define a module and write all the SelectionSets and expose them then we can somehow evaluate all the exposed queries to its serialised form and produce the json output

[dillonkearns]

Nice, that makes sense for the contract for the backend tool. It seems like it would be a lot of work but a solvable problem to have something to generate that based on some Elm code, and it could be customizable how to output the hash-to-query mapping in a way that's consumable for different tools.

I think the big question still would be GraphQL variables. Without a way to use GraphQL variables, I don't think you would be able to use persisted queries in a meaningful way, so I think it's probably best to discuss that more before considering something building something like this.