Write a new execution module for GraphQL-Ruby

[rmosolgo]

I have been spending a lot of time trying to move the existing execution code forward in a compatible way, but I'm finding it impossible :S I mean at least these modules:GraphQL::Execution::Interpreter, Interpreter::Runtime, Interpreter::Arguments (and HasArguments, ArgumentValue), Dataloader, Execution::Lazy.

Writing up all the details is possible but in the interest of getting started, I'll be brief:

• Performance: A lot of possible performance gains have been identified (Memoize selection gathering #5502, Supporting Batch Resolvers in GraphQL-Ruby #5446, Don't check every returned object for lazy? #4426) but are stuck in compatibility land for edge cases
• Correctness: GraphQL-Ruby has received a lot of features over the years, tacked on in different ways. They don't always work right together... it's worth considering which ones can be jettisoned for other approaches (field extras?) or merged together, at least under the hood (prepare:, loads:, validates:?).
• Features: actually, performance is the feature that I'd want from this. I expect most features could be reimplemented one way or another -- or at least a very clear migration path -- with a new core runtime.

So, I'm proposing a project like:

• Build a new runtime in isolation (takes the same inputs as Schema.run, returns the same output; can be used on a query-by-query basis for Scientist-like checks)
• Make sure the new runtime checks the necessary boxes (see below)
• One at a time, reimplement existing features to the degree possible
• Also build a "GraphQL Doctor" which inspects source code and schemas in memory and outputs the result of compatibility checks and links to migration notes

After trying and trying, I don't think a future execution paradigm can be achieved with a perfectly smooth path, but I think it's worth pursing -- Shopify has been using custom execution code to great success for a while now.

New Execution Goals in no specific order:

• Support first-class batching ("batch resolvers"), so you can get the advantages of dataloader or graphql-batch without promises or fibers, using a breadth-first execution algorithm (Supporting Batch Resolvers in GraphQL-Ruby #5446)
• Non-recursive, non-block-based execution algorithm to reduce overhead (Use a queue for execution #5389)
• Properly cache merged AST nodes (Memoize selection gathering #5502)
• Others?

cc @gmac since you've been investigating a lot of these too -- what do you think this approach to improving GraphQL-Ruby?

---

Appendix: essential and non-essential forwards-compatible features

These are things that must have good enough compatibility that a given application can switch between runtimes on a query-by-query basis:

• Everything in the GraphQL spec (including null propagation, @skip/@include, static validation (same code))
• Query analyzers (same code used in both cases)
• Custom scalars
• Resolver classes
• Dataloader
• GraphQL-Batch support
• Schema visibility (same code should work in this new runtime, since it's applied during static validation)
• Multiplex: I expect this to basically work fine in the new flow with a bit of work.
• Connections
• Argument #authorized?
• Field #authorized?
• Type .authorized? and .scope_items
• Tracing
• loads:
• validates:
• prepare:
• Resolver#ready?
• field extras:
  • A few are already implemented; others could be if requested.
• field extensions:
  • Requires implementing new methods
• Custom context and query classes just works

Then there are some features whose forward compatibility I don't consider to be essential. In these cases, supporting both runtimes in your schema might require de-customizing (ie, moving behavior into your app code or into a resolver). However I bet they'll eventually be able to be reimplemented in a very compatible way, and I expect them to be easily identifiable by "GraphQL Doctor":

It turns out everything on this list can stay compatible with minimal overhead.

• GraphQL::Schema::Object .wrap(...) is not called anymore.

[gmac]

Tough one, Robert. You're stuck straddling the fence for sure. Some of the real opportunities just involve narrowing the list of supported patterns. Example: non-statically coercible input. Input is almost always static. If it's not for some reason, it can/should be contextually modified in a resolver. The engine shouldn't need to handle these edge cases. If you're targeting full legacy pattern support, I'm not sure how fruitful this endeavor stands to be.

One other clarifying note:

so you can get the advantages of dataloader or graphql-batch without promises or fibers, using a breadth-first execution algorithm

We do still use promises. Many fields sharing a query need to pool their resolution. However, we can bind a breadth of keys onto a single promise rather than building and resolving promises 1:1 with keys.

[rmosolgo]

I wouldn't target full legacy support -- too costly, like you said. But I'd like to keep an eye on full forward compatibility so that people can migrate.

still use promise

Good point -- if two fields call the same loader and need to do different work when the loader finishes, then one of those coordinating tools is still necessary.

[gmac]

Some thoughts on some essentials:

• Dataloader
• GraphQL-Batch support

Can these be the same thing? We're flattening out lazy workflows into something with very controlled load points. Basically what we've found is that we need a lazy hook for a field result, and a scope preload. We're supporting those two with a single pattern and moving on.

• Resolver classes

These need IOC from the current design IMO. There's a very simple principle that guides a lot of Cardinal: nothing (in the engine) should allocate 1:1 with resolved objects except the result hashes themselves. Following that idea, it was a very obvious choice to have resolver classes become static with execution state injected into them.

As for input features – argument coercions are important. Non-statically-coercable argument concerns are a bit odd though. I eliminated that as a concept. We now provide arguments as raw hashes – amazingly, our code structure is improving as we migrate InputObject classes with hard GraphQL dependencies into pure libraries that we can use and test in isolation. We DO support GraphQL Ruby validates as a validation control interface, however that again eliminated all support for object contextualization. You get one flat pass across all input. Anything else you want to control needs to be done in a resolver that cares about that concern.

[rmosolgo]

Thanks for sharing your thoughts, @gmac. I haven't actually gotten to the code for these topics yet, but my initial impressions below ...

same thing?

Not exactly, in my experience, since their means of coordination are different. At this point though, they're already very close: Dataloader keeps track of Lazies and resolves them in its loop. I think you're right that moving to a more controlled pattern will simplify things, too. Besides field results, GraphQL-Ruby currently supports these loaders in resolve_type, authorized?, argument loads: and prepare: (probably won't continue supporting this, at least not by default), resolving items in a list (ie, a field can return [<Promise>, <Promise>, <Promise>]) and ... maybe others (?).

nothing (in the engine) should allocate 1:1

I definitely agree in principle. My experience with resolvers (and GraphQL::Function before that) is that people want a box to put configuration and logic in, and they expect to assign instance variables and extract behavior into shared methods, and use inheritance. So GraphQL::Schema::Resolver is a largely a non-footgun that fits nicely into plain field resolution (MyResolver.new(...).result, at least in theory).It adds a few allocations, but at least that overhead is predictable and easily removed if necessary.

One way I'd like to improve Resolver support in the future is to prevent core execution code from knowing that Resolvers exist (see from_resolver? in current code). But I think maintaining a lot of core behavior should be easy even within a simpler and better-designed framework, we'll see.

You get one flat pass across all input. Anything else you want to control needs to be done in a resolver that cares about that concern.

🍻 Yes, moving all I/O (at least, dataloaded I/O) to field resolution sounds pretty great, performance and implementation-wise. I hope to provide good migration support for loads: and prepare:, though, probably:

• some new DSL that works in both new and old runtime code, and
• a Rubocop-like rewriter that moves configuration from old to new

Another possibility in my mind is an opt-in implementation that re-implements loads: in such a way that it happens during field resolution, rather than during argument coercion as it does now.

[rmosolgo]

Just a quick update on #5509 in case you're curious. At this point, the new execution module can run queries using MySchema.execute_batching(...). With all the compatibility switches flipped on, it can run just about everything (resolvers, promises, dataloader, automatic connections, .authorized?, loads:, field extensions), although the batching of loads: isn't as good.

With compatibility switches off (and a completely forward-compatible schema), it runs as fast as GraphQL-Cardinal (bench), which I leaned on heavily in writing out the basic algorithm:

$ SIZES=1000 be rake benchmark:execution          

ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin24]
Warming up --------------------------------------
graphql-ruby batching 14002 resolvers
                        28.000 i/100ms
graphql-ruby: 14002 resolvers
                         2.000 i/100ms
graphql-cardinal 14002 resolvers
                        27.000 i/100ms
Calculating -------------------------------------
graphql-ruby batching 14002 resolvers
                        301.889 (± 0.7%) i/s    (3.31 ms/i) -      1.512k in   5.008762s
graphql-ruby: 14002 resolvers
                         21.169 (± 0.0%) i/s   (47.24 ms/i) -    106.000 in   5.007718s
graphql-cardinal 14002 resolvers
                        268.126 (± 0.7%) i/s    (3.73 ms/i) -      1.350k in   5.035182s

Comparison:
graphql-ruby batching 14002 resolvers:      301.9 i/s
graphql-cardinal 14002 resolvers:      268.1 i/s - 1.13x  slower
graphql-ruby: 14002 resolvers:       21.2 i/s - 14.26x  slower

So I think it's going to be possible to take this faster execution paradigm and slap on compatibility patches while working towards getting the full benefit.

On Monday, I'll review that pending pull request and do whatever else is needed to get it on master, then ship a new version (with no new code actually required by default). Then I want to make a few more changes so that I can run my own app with it, and work up some documentation, etc...!

[rmosolgo]

There are a lot of features that I thought I couldn't/shouldn't support, but I have been adding them back in. In the new architecture, it's possible to support them without adding very much overhead. The no-frills benchmark is only ~4% slower than a month ago, despite implementing field extensions, loads:, authorization, extras:, and resolvers:

Calculating -------------------------------------
graphql-ruby batching 14002 resolvers
                        290.158 (± 1.0%) i/s    (3.45 ms/i) -      1.456k in   5.018550s

[rmosolgo]

I'm running Execution::Next in production now and preparing to release and announce it at #5594