theorygeek
commented
7 years ago I spent some time the past few days rigging up a subscription system using graphql-ruby, so here are some of my preliminary thoughts.
Problems
The first thing that I ran into when setting up subscriptions was essentially, "Here's a GraphQL document with a subscription query; what is the user subscribing to?" In other words, this is the process of mapping the fields in the subscription query back to events in the system.
Given this GraphQL document for example:
subscription {
somethingHappened(id: "...") { stuff }
somethingElseHappened(id: "...") { moreStuff }
}I need to somehow know that the user just subscribed to somethingHappened and also somethingElseHappened, and it's also important to know how they subscribed to. That probably involves looking at the arguments passed in, but maybe it involves the query context.
I looked at this problem from a couple of angles:
- Parse the query and do some kung-fu on the AST. This gets really crazy when fragments, aliases, and variables start getting involved. Way too complicated.
- Do a dry run execution of the query, and collect the list of fields/arguments that actually get executed (eg, maybe in middleware that adds stuff to the context)
The thing that kinda sucks about the dry-run approach is two things:
- I might not actually want to execute the query. After all, I'm just trying to figure out what they subscribed to; having the result of the query is at best just a nice side effect.
- It might not really make sense to execute the query in the abstract. For example, if the subscription is called
newUserJoinedChat, it only really makes sense to execute the query for that subscription when I also have some sort of event data available.
Here's another problem that I ran into pretty quickly: The arguments that the user supplied to the subscription might need to be transformed (quite a bit) before it gives me information that I can use as a hook to my underlying event system. Just an example, the user might be passing in global node ID's, but those global ID's are really only a concept inside of my GraphQL layer. My subscription layer is publishing messages using database ID's or other information, not node ID's.
A third problem I ran into was: What if the user puts multiple subscriptions into the GraphQL document? If I'm only firing the somethingHappened subscription, how can I execute just that part of the query (and not the somethingElseHappened bit)? Maybe go back to doing some AST kung-fu to slice the query apart?
And the final problem I ran into: If the subscription is in response to an event, how do I get event-specific data into the field resolver?
Solution
Pulling all of this together, it seems that the subscriptions feature should have these characteristics:
- It should be able to distinguish between the initial execution and subsequent executions (https://github.com/facebook/graphql/pull/267#issuecomment-282138153)
- There should be a way to inject some event-specific data into the field resolver (https://github.com/facebook/graphql/pull/267#issuecomment-280740586)
So perhaps an API for creating a subscription could look like this:
# Much like mutations, subscriptions seem like they'll have a decent amount of boiler-plate. So
# that can all get pulled into its own define API.
NewUserJoinedChatSubscription = GraphQL::Subscription.define do
# Name is used to derive the name of the auto-generated object type
name "NewUserJoinedChat"
# Specify the arguments for the subscription field. Unlike mutations, these are first-class
# arguments, rather than being wrapped inside an input object type.
argument :channelId, !types.ID
argument :friendsOnly, types.Boolean, default_value: true
# This is an optional, special resolver. It's executed on the initial execution of the subscription
# query, so that you can return any data that helps you figure out how to tie into your underlying
# event source.
# Default behavior is to just return the arguments that were passed in
metadata_resolve -> (root_object, arguments, context) {
{
channel_id: Node.item_id(arguments[:channelId]),
user_id: context[:access_token].user_id,
friends_only: arguments[:friendsOnly]
}
}
# Specify the fields that are on the auto-generated object type
return_field :newUser, UserType
return_field :channel, ChannelType
# Finally, specify a resolver
resolve -> (root_object, arguments, context) {
# normal resolve that we all know and love
}
endOnce you've defined a subscription using that API, you attach it to your root subscription type as a field, the same way as you do with a mutation.
The real magic happens when you execute a subscription query. Instead of getting your normal response, what you get is instead an array of object that return the metadata about the user's subscription:
subscription_query = <<~GRAPHQL
subscription {
somethingHappened(id: "...") { ...f1 }
}
fragment f1 on SomethingHappenedPayload {
stuff
Ā otherStuff
}
GRAPHQL
result = Schema.execute(subscription_query, variables: {}, context: {})
# => Array
# Here's how I imagine you could interact with result:
result.each do |item|
# Get the name of the subscription
item.subscription.name
# => "SomethingHappened"
# Get the metadata from the `metadata_resolve`. By default, it just returns the arguments:
item.metadata
# => { "id" => "..." }
# Callable that you can use to execute just this particular part of the query
# To inject event-specific data, you can override the root_value, or you can add more stuff
# to the query context:
item.execute(root_value: some_event, extra_context: { "event" => some_event })
# => { "data" => { "somethingHappened" => { ... } }, "errors" => [] }
endI think this would be enough to implement a subscription system for almost any transport. You can take the metadata you get from the initial run of the query and use it to figure out what events to listen to. And whenever the event happens, you can execute the corresponding query and send the results to the client through whatever transport mechanism.
The nice thing about the callable approach is that it's probably the easier thing to build, and I'm guessing it's suitable for all websocket-like use cases. The downside is that you might want your subscriptions to be durable (ie, maybe you shovel it into a database), or maybe an entirely different process is going to execute the query and transmit the results).
So an alternative to the callable approach would be to produce an already-sliced GraphQL document and set of variables, which could be easily serialized. And then sometime later you could just execute that sliced query with those variables.
Those are my preliminary thoughts. I'd be interested to hear what others think?
rmosolgo
mull
mgwidmann
Jose4gg
blevine
Right now we accept a subscription root type, but we don't provide any special support for registering , managing or delivering them. With the RFC well on it's way, what should be added to this library to support a third-party subscription backend?
I don't think this library should include a subscription backend, except maybe an in-memory one for prototyping. What could we support here that would actually be widely useful? ActionCable is cool, but I haven't heard of anyone actually running it in production yet (and not many folks are on Rails 5 to begin with). Using Redis Pub/Sub directly would be cool, but I think delivering those subscriptions would require a Websocket server outside the Rails server. Another option is Pusher, which I currently use to deliver live updates and which manages subscription status & delivery "for you".
So, certainly to start, I'd like to figure out what's missing in order to support subscriptions over those various backends. (Or, perhaps it's impossible to generalize about them!)