Middleware via hooks in the "round-trip" of a field

[lancelafontaine]

This issue is part-feature request and part-inquiry as to how this pattern can best be achieved:

When an argument is passed to a field, have the argument's value be accessible to only the "sub-fields" in the subsequent tree of fields that are queried from that point.

Here's an example of having a configuration value like a session ID be accessible for every field under the one in which the session is provided.

query problemDomain {
    a(configurationValue: "1"){ # before hook to set configuration value
        aa { # is aware of configurationValue "1"
            ab # is aware of configurationValue "1"
        }
        ac # is aware of configurationValue "1"
    } # after hook to unset configuration value
    b { # nothing to set
        ba { # has no configurationValue
            bb # has no configurationValue
        }
        bc # has no configurationValue
    } # nothing to unset
    c(configurationValue: "2") { # before hook to set configuration value
        ca { # is aware of configurationValue "2"
            cb # is aware of configurationValue "2"
        }
        cc # is aware of configurationValue "2"
    } # after hook to unset configuration value
}

This example relies on this propagation occurring and having a trigger or hook to stop the propagation at the end of a field's "round-trip" and unset the configuration value.

I've found this requirement conceptually similar to middleware, a useful pattern often seen in the Node.js and Elixir worlds to avoid manipulating global mutable states from any arbitrary point within the request. I can imagine a similar concept being applied here, but instead of at the request level, at the field/resolver level. Some of the use cases off the top of my head:

• Session management (see above)
• Logging
• Benchmarking
• Prefetching and caching dependent objects
• Parsing inputs and context
• Authentication

graphql-ruby already offers field extensions as a concept, which are similar in nature to what this is attempting to solve, but the after_resolve hook only triggers immediately after a field's resolver, not on the field's "round-trip".

From what I can tell, without a primitive, the only option for enabling this sort of pattern is to change the backing model of all GraphQL objects to be a decorator which can manually propagate the argument value through every resolver. Even then, this approach only solves the session management / configuration value use case, and doesn't address any case which relies on an explicit after_round_trip hook.

Hoping to get some feedback on the general pattern, whether there are any other viable options for enabling such use cases, and whether such a primitive would make sense alongside constructs like field extensions. Thanks!

[eapache]

Another approach to solving this might be some sort of mutable context namespaces scoped to parts of the AST?

[rmosolgo]

the only option for enabling this sort of pattern is to change the backing model of all GraphQL objects to be a decorator

Yes, that's right!

However, I'm definitely open to an improvement in this area. The question comes up often. Personally, I'd rather avoid the AST (it gets tricky with fragments, of course). But a runtime structure would be conceptually very similar to an AST-based one.

Here is the problem: there is "no" existing data structure that structure that works this way, so there's nowhere to "just add" this feature. (Background: ctx used to kind of work this way -- it allocated a new object for every field resolution though, which resulted in a lot of wasted time and space.) I use quotes for "no" because there is actually one data structure which works this way. Namely, the Ruby stack of interpreter/runtime.rb follows this pattern. Each method call passes arguments to method calls down the stack, and receives the return value. So, it might fit there.

Here's an example:

graphql-ruby/lib/graphql/execution/interpreter/runtime.rb

Line 281 in 05a7b02

def continue_field(path, value, field, type, ast_node, next_selections, is_non_null, owner_object, arguments) # rubocop:disable Metrics/ParameterLists

^^ This method is called to resolve a field. If the field returns an object (or a list of objects), it will continue GraphQL execution by calling more methods. For example:

graphql-ruby/lib/graphql/execution/interpreter/runtime.rb

Line 314 in 05a7b02

evaluate_selections(path, continue_value, type, next_selections)

So, any kind of object created during that method could be passed "down" to subsequent fields without affecting fields "above" it or "beside" it. But, there's no data structure that already follows that lifecycle.

When it comes to implementation, I want to take care to incur no overhead when we can avoid it. Also, we should implement it in a way that is abstracted away from the interpreter's implementation.

For example, I could imagine an API like this:

field :a, ... do 
  argument :configuration_value, String, required: true 
end 

def a(configuration_value:)
  # Make `context[:config_val]` work for any field which happens _below_ this one 
  context.scoped_merge!(config_val: configuration_value) 
end 

Implementation-wise, context could hold a reference to the scoped context, eg:

# Use whatever scoped context we get from "above" 
context.current_scoped_context = prev_scoped_context 

resolve_field(... context ...) 

# Maybe this returns the same object as `prev_scoped_context`
# but it _could have_ been replaced during field resolution
next_scoped_context = context.current_scoped_context

class Context 
  # Make a _new_ scoped context object which includes the new values. 
  # Don't mess with the previous scoped context, since it is also used by sibling fields
  # TODO think of a method name 
  def scoped_merge!(new_ctx_vals) 
    new_scoped_context = @current_scoped_context.merge(new_ctx_val) 
    @current_scoped_context = new_scoped_context 
  end 
end 

This would work for passing down the query tree. But it has the same problem as decorators: it doesn't give an after_resolve hook.

Could you tell me more about what you'd like to do with that? I wonder if field extension's after_resolve method might work. I ask because it's a bit tricky to call "after-resolve" hooks, sometimes it means:

• after this field is resolved, but before its child fields are resolved (this is what a field extension will do)

Other times it means:

• after this field is resolved and all its child fields are resolved. (Only Query instrumentation works this way now; I don't know of anything else like this.)

So, I'm curious what kind of usage you have in mind.

[lancelafontaine]

Thanks for such a thorough description of the issue as it stands and how it can best be approached! I'll be getting myself familiar with the codebase over the next couples of days in hopes of contributing here.

The alternate after_resolve hook I was imagining was the latter you mentioned. I would describe this "round trip" as

• after this field and all of it's descendant's fields are resolved

The reason why I feel like this hook is particularly appealing is that at first glance, it enables more of the complex use cases that can't be achieved with field extensions as they are now. An extremely naive API (coming from someone who does not yet know any graphql-ruby internals 🙃) to implement some of these made-up use cases could be to build a construct similar to FieldExtension, or alternatively, expose a new method on FieldExtension, which operates on the round trip hook as defined above:

class MyRoundTripExtension < GraphQL::Schema::FieldExtension
    def apply
        # No change to existing behaviour here
        field.argument(:config_value, String, required: false)
    end

    def resolve(object:, arguments:, context:, **_rest)
        # No change to existing behaviour here
        context[:user].grant_access(:config_value)
        previous_config_value = context[:config_value]
        context[:config_value] = build_complex_config_value_representation(arguments[:config_value])

        memo = { original_time: Time.now_to_i, previous_config_value: previous_config_value }
        yield(object, arguments, memo)
    end

    def after_resolve(value:, memo:, context:, **_rest)
        # No change to existing behaviour here
        puts "Time it took to resolve this field but no child fields: #{Time.now.to_i - memo[:original_time]}"
    end

    def after_field_round_trip(memo:, **rest)
        # This is new functionality which supports other use cases like:

        # - Config (eg. session) management, or pre-parsing/loading inputs
        #   to be made accessible _only_ to all child fields, without leaking it
        #   throughout the entire query
        context[:config_value] = memo[:previous_config_value]

        # - Arbitrary logging / metrics / benchmarking
        puts "Time it took to resolve this field and all child fields: #{Time.now.to_i - memo[:original_time]}"

        # Authorization or permissions-related hooks
        context[:user].revoke_access(:config_value)

        # etc.
    end
end

However, this implementation hinges on being able to successfully trigger this method at the approriate "round trip" time as defined above.

(Only Query instrumentation works this way now; I don't know of anything else like this.)

If you have a minute, could you link to what instrumentation you're referring to here? This sounds super relevant and I wasn't able to pinpoint where this is happening :/

[rmosolgo]

Here's Query instrumentation: https://graphql-ruby.org/queries/instrumentation (I can't really think about how it's relevant, except it came to mind because it's called after everything in query execution!)

Judging by your examples, it looks like you have a couple possible uses is mind:

• Measuring the time of a field and its children
• "Opening" access to a user during execution, then closing it back up when it's done

One possible issue here for me is that branches of GraphQL queries may be run concurrently. Consider a query like this one:

{
  object1 { f1 { f2 } }
  object2 { f1 { f2 } }
}

If these field values are batch-loaded, then the execution of this query will not be sequential. Instead, the fields would be resolved in this order:

• object1
• object2
• object1.f1
• object2.f1
• object1.f1.f2
• object2.f1.f2

In that case, I the timing measure for "object1 and its children" would also include object2's children. Would that be ok for the example above?

Access control deserves the same consideration: with a evaluation order like that, could you be sure that you wouldn't accidentally grant access to something which shouldn't receive access?

To be clear, I would hope to address these issues by looking at each field in isolation. For example, if you recorded the start and end of each field along with its path, you could reconstruct combined timings using the paths and recorded times.

As for adding some "session" data for child fields, I think it could be accomplished with a "scoped context" discussed above, which would be scoped to the field and its own children. But using the normal context object as in the example above would carry risks because of non-sequential field execution.

Anyways, I remain convinced of the usefulness of scoped context, but it's not yet clear to me what an after-self-and-all-children hook could be used for because of non-sequential execution. Could you clarify any more what you'd hope to do with it (and how it handles non-sequential execution)?

[lancelafontaine]

🙈 I misunderstood thinking that query instrumentation would kick in after a specific field is resolved, not after the entire query. You're right that it doesn't seem particularly useful here.

Context#scoped_merge! as seen above could satisfy the configuration value use case (which happens to be my primary use case) as long as we can ensure the passed config value doesn't leak into any adjacent field's resolvers. However, I still think that an after-self-and-all-children hook would generally be a useful addition iff the out-of-order sibling resolver execution was accounted for. I suggested some use cases which are valuable to me, but I'm certain there are many more, in a similar way to how field extensions can be used in an unimaginable variety of ways.

Still trying to ramp up here, so this might be naive, but has using a persistent/immutable data structure for Context (or something like Context) ever been discussed or considered? This seems like the perfect use case for such a pattern, and most "middleware" uses this technique as far as I know.

The out-of-order sibling resolver execution is only problematic because of multiple resolvers writing to a shared context concurrently. A persistent data structure wouldn't lose or share the reference it had or corrupt and leak the value it points to once it had been written to by a resolver. I'm unsure if this is how it works currently, but as long as the update reference to Context is kept as it is modified and propagated to all child resolvers, it would behave in a consistent manner even with out-of-order execution and writes. As a stretch, I could even imagine providing an after-self-and-all-children hook based solely on whether the reference to Context changes without it being modified between field resolutions.

Curious as to your input on this thought 😃

[rmosolgo]

we can ensure the passed config value doesn't leak into any adjacent field's resolvers.

Yes, I think it would work! Similar to the path argument in the various interpreter/runtime.rb methods, we could pass context that way, and be sure that it's only passed to its lexical children (that is, never siblings or parents).

out-of-order sibling resolver execution was accounted for.

I don't know how we'd account for it 😬 I mean, you could know you had S elapsed seconds, but in terms of measuring time, you wouldn't know what else was going on during those seconds. Maybe with a global log you could track time-per-field and then subtract the time from sibling fields. But if you're doing that, why not just log time-per-field and then sum them? I just mean, I can't figure out an advantage 😖

[breathe]

Scoped context seems very useful!

I'm running into what seems like another use case: say you have a Location type -- and a nested graph of children types for which some descendant eventually resolves a time field. Would scoped context above provide a 'correct mechanism' allowing to pass the timezone from the location down to an arbitrarily deeply nested child field who could then compute a time value in the timezone of the location ...?

[lancelafontaine]

@breathe Yep, solving my use case should also solve yours. I've got a PR that I'll be opening shortly which should expose this functionality 😄

I don't know how we'd account for it

There should be some way to account for it, in that the trigger could be when the reference to current_scope_ctx changes. That being said, an API where we can associate arbitrary functions with when a scoped context goes out of scope would have to be designed.

but in terms of measuring time

You're right that because of the concurrent nature of execution, maybe benchmarking isn't the best use case 😖. Although things like logging, closing a socket/connection, removing user permissions, or really any operation that you would normally be put in a ensure block could be compelling here.

That being said, I think I'll put aside this after-self-and-all-children hook for the moment and possible open a separate issue for that, since I think it can merit it's own separate discussion and design. For the moment I'll focus on opening a PR for the scoped_context discussed above. 😃

[lancelafontaine]

The PR which implements this feature, as originally described in #2602 (comment), is here: #2634 🙃