Using changesets with stored operations

[mroach]

We recently started using changesets in our schema for handling breaking changes. One such example is changing a field's return type from a simple array of objects to a paginated list. It works well.

Now, we're trying to get the operation store setup and syncing queries from a client app. Only one query fails to sync, and that's the query that depends on a changeset being activated.

Response Body:  {
  "added":[],
  "not_modified":[],
  "failed":["7cbaf30a53e267038fd110ed9a61a758"],
  "errors": {
    "7cbaf30a53e267038fd110ed9a61a758": ["Field 'edges' doesn't exist on type 'User' (9:13)"]
  },
  "committed":false
}

I can certainly understand why this would be the case since the operation store doesn't know what changeset version the client is using and can't make any assumptions. The query expects the field to be a connection type, but the engine thinks it's still the old array type.

I'm guessing the problem comes from GraphQL::Pro::OperationStore::Validate not setting changeset_version in the context when validating the query.
Setting the changeset version there would probably fix the validation problem and might even allow the query to be stored. The next question is: what about execution? I guess that might work if the client continues to send the changeset version with each request (e.g. send query hash + changeset version), but I don't think that would make the most sense since the stored queries are only compatible with the changeset version they were designed for and the server would know the changeset version at sync time if the client included that value.

If my assumptions are correct so far, I imagine one solution might be:

• Add a parameter to graphql-ruby-client for the schema version, allowing the client to tell the server what version the queries were designed with.
• Add a column to graphql_operations for the changeset version. Store the changeset version that the client passed with the sync operation.
• When executing stored operations, apply the changeset version that was stored with that operation.

Sidenote: the changeset version might need to groomed/validated before storage. For example if the latest changeset is 2023-01-09 but the client is using a value of 2023-01-22, the actual changeset version that's being applied is 2023-01-09 and the value they sent doesn't exist.

[rmosolgo]

Hey, thanks for the detailed question and sorry about the trouble.

For syncing, I think the --header option should work (doc), for example:

graphql-ruby-client sync ... --header=API-Version:2023-01-09

(Swap API-Version for your header name if needed.)

Then, I the client will need to include a version header along with the operationId, so that that context[:changeset_version] can be populated in the controller, before running the GraphQL query. (As you noted, operations don't store a changeset version, and I don't think they should, since a single query string could be run on different changeset versions.)

Want to give those a try? Let me know what you think!

[mroach]

First I ran into an issue with the CLI app:

root@42cb9824cb80:/opt/app# graphql-ruby-client sync --url=http://10.88.0.192:5000/graphql/frontend/sync \
  --secret=XX --header=x-schema-version:2023-01-23 --client=test --outfile=out.js --path="/opt/app/src/js/graphql/**/*.graphql"                                     
/usr/local/lib/node_modules/graphql-ruby-client/cli.js:21
            argv.header.forEach(function (h) {
                        ^

TypeError: argv.header.forEach is not a function
    at Object.<anonymous> (/usr/local/lib/node_modules/graphql-ruby-client/cli.js:21:25)
    at Module._compile (node:internal/modules/cjs/loader:1218:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1272:10)
    at Module.load (node:internal/modules/cjs/loader:1081:32)
    at Module._load (node:internal/modules/cjs/loader:922:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:23:47

Node.js v18.13.0

Turns out if I add another --header option with any value, then it works. I guess argv.header isn't an enumerable type unless you specify it multiple times?

Anyway, adding the header didn't work. I don't understand how it would. The operation sync endpoint doesn't know what header we use to specify the changeset version. The only place we currently have any reference to it is in our main GraphQL controller where we're doing something like context = { changeset_version: request.headers["x-schema-version"], ... }

Isn't the issue with sync with GraphQL::Pro::OperationStore::AddOperationBatch#prepare_operation and then GraphQL::Pro::OperationStore::Validate.validate which builds a context that does not include changeset_version?

[rmosolgo]

Well, derp! Sorry about all the hiccups on that. Now I see what you mean about the OperationStore endpoint needing an update to receive that header. Let me work up some fixes in the JS library and in GraphQL-Pro, then I'll post an update back here.

[rmosolgo]

(In the works at #4305)

[rmosolgo]

I just released graphql-ruby-client v1.11.5 and graphql-pro v1.23.8, and with those versions, adding sync ... --changeset-version=... will add a Changeset-Version header to the sync request, then that value is used for validating and saving stored operations on the server. Want to give those a try?

(At runtime, queries still need a context[:changeset_version] value since the same persisted document might have different behavior on different API versions.)

[mroach]

I've upgraded and it works; nice! Thanks for the quick response and implementation. This is awesome 😎