Accept Promise to allow Subscription validation & authorization

[KeithGillette]

The Resolver functions for Queries and Mutations can return Promises, which allows them to asynchronously validate input and perform authorization, rejecting the Query or Mutation Promise if either fails or fulfilling it if the validation and authorization pass.

However, it appears that a Subscription Resolver function must only return an AsyncIterator. As suggested in issue #1248, "Best practice to authorize subscriptions in Apollo Server 2", I think the most flexible and consistent way to allow Subscription validation and authorization would be to allow Subscription Resolver functions to also return a Promise for an AsyncIterator, with a rejected Promise cancelling the client Subscription request.

Such a change would also allow the AsyncIterator & its withFilter function to be generated based on async operations, allowing for more sophisticated server-side Subscription configuration.

Absent that capability, how may one best validate and authorize a Subscription request?

[ScripterSugar]

+1 for this feature. Accepting Promise looks like very easy and intuitive way to authorize or pre-process any tasks per subscription.

[spencerwilson]

Does it already work as you describe?

Tracing code

1. First, suppose that apollo-server substantially delegates subscription operation execution to graphql. I think this is typical for projects like apollo-server to do, but more convincingly: the installSubscriptionHandlers function that ApolloServer calls (as do others) seems like it eventually delegates to some relevant-sounding functions from graphql such as subscribe and execute (src).
2. subscribe, in turn, starts here.
3. It eventually reaches here, where it gets the subscribe GraphQLFieldResolver from the field definition. From that point forward it looks like it implements the behavior you've specced out in this question.
4. Then, when executing the operation's selection set (which happens each time an event occurs on the Source Stream), field execution uses the resolver GraphQLFieldResolver from the field definition (src).

TL;DR what folks have been asking for since at least June 2018 seems like it might exist today (and possibly since graphql's inception, before Apollo Server was a thing), albeit not in any documented way? Caveat: I haven't empirically tested if this works. Will do so soon, since I entered this rabbit hole for work.

What about withFilter?

Both subscribe and resolve are GraphQLFieldResolvers, which take the usual arguments and can return promises. withFilter wraps/decorates a given subscription function, disregarding elements that fail a predicate which is called with the same, classic 4 GraphQLFieldResolver arguments. Despite saying

The value you should return from your subscribe resolver must be an AsyncIterator.

That's false; per the above graphql code, it can be a promise, too. In other words, this typedef's return value should be widened to include Promise<AsyncIterator<any>>.

Guidance to people doing subscriptions in Apollo Server

My current tentative understanding of how to do subscriptions in Apollo Server: Work according to the true typedef for a subscription root field definition:

interface SubscriptionRootFieldDefinition<T, V> {
  // The resolver referenced in the spec's `ResolveFieldEventStream`. Called once during initial
  // subscription execution, to prepare the Source Stream.
  // Consider using the data from contextValue.user (or similar) to reject if not authorized.
  // Consider wrapping via `withFilter` to filter out events that shouldn't produce events on
  // this subscription instance's Response Stream (say, because the request principal isn't authorized
  // to receive them.
  // @see https://spec.graphql.org/June2018/#ResolveFieldEventStream()
  subscribe: (rootValue, args, contextValue, info): PromiseOrValue<AsyncIterator<T>>;

  // Used during the spec's `ExecuteSubscriptionEvent`, called once to handle each event on
  // the Source Stream. `rootValue` is a value from the Source Stream. `context` is this same as
  // what was finalized when `onConnect` first completed.
  // Not the place to do anything authorization-related. See `subscription` for that.
  // @see https://spec.graphql.org/June2018/#ExecuteSubscriptionEvent()
  // @see https://www.apollographql.com/docs/graphql-subscriptions/subscriptions-to-schema/#payload-transformation
  resolve: (rootValue: T, args, contextValue, info): PromiseOrValue<V>;
};

I intend to test this soon (O(days)) and confirm whether it seems to all be true.

[spencerwilson]

Ok, successful results here: https://github.com/spencerwilson/apollo-server-subscription-auth

TL;DR everything I said above is accurate, and the behavior is at least ok when using GraphQL Playground as the client; not sure about other clients.

cc @StephenBarlow and @martijnwalraven , since I saw y'all working on this recently in #4880. Either I'm totally off base or subscriptions in Apollo Server could use a lot more docs + clarification. It seems what folks are asking for works, it's just not communicated at all how to do it. Bummer that people were blocked from having flexible authz on subscriptions since at least 2017 just for a docs gap :(

[glasser]

Just as a note, our current thoughts on the near-term future of subscriptions and Apollo Server are at #4354 (comment)