graphql 0.16.0 → 2.0.15

data/lib/graphql/subscriptions/action_cable_subscriptions.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+module GraphQL
+  class Subscriptions
+    # A subscriptions implementation that sends data
+    # as ActionCable broadcastings.
+    #
+    # Some things to keep in mind:
+    #
+    # - No queueing system; ActiveJob should be added
+    # - Take care to reload context when re-delivering the subscription. (see {Query#subscription_update?})
+    # - Avoid the async ActionCable adapter and use the redis or PostgreSQL adapters instead. Otherwise calling #trigger won't work from background jobs or the Rails console.
+    #
+    # @example Adding ActionCableSubscriptions to your schema
+    #   class MySchema < GraphQL::Schema
+    #     # ...
+    #     use GraphQL::Subscriptions::ActionCableSubscriptions
+    #   end
+    #
+    # @example Implementing a channel for GraphQL Subscriptions
+    #   class GraphqlChannel < ApplicationCable::Channel
+    #     def subscribed
+    #       @subscription_ids = []
+    #     end
+    #
+    #     def execute(data)
+    #       query = data["query"]
+    #       variables = ensure_hash(data["variables"])
+    #       operation_name = data["operationName"]
+    #       context = {
+    #         # Re-implement whatever context methods you need
+    #         # in this channel or ApplicationCable::Channel
+    #         # current_user: current_user,
+    #         # Make sure the channel is in the context
+    #         channel: self,
+    #       }
+    #
+    #       result = MySchema.execute(
+    #         query: query,
+    #         context: context,
+    #         variables: variables,
+    #         operation_name: operation_name
+    #       )
+    #
+    #       payload = {
+    #         result: result.to_h,
+    #         more: result.subscription?,
+    #       }
+    #
+    #       # Track the subscription here so we can remove it
+    #       # on unsubscribe.
+    #       if result.context[:subscription_id]
+    #         @subscription_ids << result.context[:subscription_id]
+    #       end
+    #
+    #       transmit(payload)
+    #     end
+    #
+    #     def unsubscribed
+    #       @subscription_ids.each { |sid|
+    #         MySchema.subscriptions.delete_subscription(sid)
+    #       }
+    #     end
+    #
+    #     private
+    #
+    #       def ensure_hash(ambiguous_param)
+    #         case ambiguous_param
+    #         when String
+    #           if ambiguous_param.present?
+    #             ensure_hash(JSON.parse(ambiguous_param))
+    #           else
+    #             {}
+    #           end
+    #         when Hash, ActionController::Parameters
+    #           ambiguous_param
+    #         when nil
+    #           {}
+    #         else
+    #           raise ArgumentError, "Unexpected parameter: #{ambiguous_param}"
+    #         end
+    #       end
+    #   end
+    #
+    class ActionCableSubscriptions < GraphQL::Subscriptions
+      SUBSCRIPTION_PREFIX = "graphql-subscription:"
+      EVENT_PREFIX = "graphql-event:"
+
+      # @param serializer [<#dump(obj), #load(string)] Used for serializing messages before handing them to `.broadcast(msg)`
+      # @param namespace [string] Used to namespace events and subscriptions (default: '')
+      def initialize(serializer: Serialize, namespace: '', action_cable: ActionCable, action_cable_coder: ActiveSupport::JSON, **rest)
+        # A per-process map of subscriptions to deliver.
+        # This is provided by Rails, so let's use it
+        @subscriptions = Concurrent::Map.new
+        @events = Concurrent::Map.new { |h, k| h[k] = Concurrent::Map.new { |h2, k2| h2[k2] = Concurrent::Array.new } }
+        @action_cable = action_cable
+        @action_cable_coder = action_cable_coder
+        @serializer = serializer
+        @serialize_with_context = case @serializer.method(:load).arity
+        when 1
+          false
+        when 2
+          true
+        else
+          raise ArgumentError, "#{@serializer} must repond to `.load` accepting one or two arguments"
+        end
+        @transmit_ns = namespace
+        super
+      end
+
+      # An event was triggered; Push the data over ActionCable.
+      # Subscribers will re-evaluate locally.
+      def execute_all(event, object)
+        stream = stream_event_name(event)
+        message = @serializer.dump(object)
+        @action_cable.server.broadcast(stream, message)
+      end
+
+      # This subscription was re-evaluated.
+      # Send it to the specific stream where this client was waiting.
+      def deliver(subscription_id, result)
+        payload = { result: result.to_h, more: true }
+        @action_cable.server.broadcast(stream_subscription_name(subscription_id), payload)
+      end
+
+      # A query was run where these events were subscribed to.
+      # Store them in memory in _this_ ActionCable frontend.
+      # It will receive notifications when events come in
+      # and re-evaluate the query locally.
+      def write_subscription(query, events)
+        unless (channel = query.context[:channel])
+          raise GraphQL::Error, "This GraphQL Subscription client does not support the transport protocol expected"\
+            "by the backend Subscription Server implementation (graphql-ruby ActionCableSubscriptions in this case)."\
+            "Some official client implementation including Apollo (https://graphql-ruby.org/javascript_client/apollo_subscriptions.html), "\
+            "Relay Modern (https://graphql-ruby.org/javascript_client/relay_subscriptions.html#actioncable)."\
+            "GraphiQL via `graphiql-rails` may not work out of box (#1051)."
+        end
+        subscription_id = query.context[:subscription_id] ||= build_id
+        stream = stream_subscription_name(subscription_id)
+        channel.stream_from(stream)
+        @subscriptions[subscription_id] = query
+        events.each do |event|
+          # Setup a new listener to run all events with this topic in this process
+          setup_stream(channel, event)
+          # Add this event to the list of events to be updated
+          @events[event.topic][event.fingerprint] << event
+        end
+      end
+
+      # Every subscribing channel is listening here, but only one of them takes any action.
+      # This is so we can reuse payloads when possible, and make one payload to send to
+      # all subscribers.
+      #
+      # But the problem is, any channel could close at any time, so each channel has to
+      # be ready to take over the primary position.
+      #
+      # To make sure there's always one-and-only-one channel building payloads,
+      # let the listener belonging to the first event on the list be
+      # the one to build and publish payloads.
+      #
+      def setup_stream(channel, initial_event)
+        topic = initial_event.topic
+        channel.stream_from(stream_event_name(initial_event), coder: @action_cable_coder) do |message|
+          events_by_fingerprint = @events[topic]
+          object = nil
+          events_by_fingerprint.each do |_fingerprint, events|
+            if events.any? && events.first == initial_event
+              # The fingerprint has told us that this response should be shared by all subscribers,
+              # so just run it once, then deliver the result to every subscriber
+              first_event = events.first
+              first_subscription_id = first_event.context.fetch(:subscription_id)
+              object ||= load_action_cable_message(message, first_event.context)
+              result = execute_update(first_subscription_id, first_event, object)
+              if !result.nil?
+                # Having calculated the result _once_, send the same payload to all subscribers
+                events.each do |event|
+                  subscription_id = event.context.fetch(:subscription_id)
+                  deliver(subscription_id, result)
+                end
+              end
+            end
+          end
+          nil
+        end
+      end
+
+      # This is called to turn an ActionCable-broadcasted string (JSON)
+      # into a query-ready application object.
+      # @param message [String] n ActionCable-broadcasted string (JSON)
+      # @param context [GraphQL::Query::Context] the context of the first event for a given subscription fingerprint
+      def load_action_cable_message(message, context)
+        if @serialize_with_context
+          @serializer.load(message, context)
+        else
+          @serializer.load(message)
+        end
+      end
+
+      # Return the query from "storage" (in memory)
+      def read_subscription(subscription_id)
+        query = @subscriptions[subscription_id]
+        if query.nil?
+          # This can happen when a subscription is triggered from an unsubscribed channel,
+          # see https://github.com/rmosolgo/graphql-ruby/issues/2478.
+          # (This `nil` is handled by `#execute_update`)
+          nil
+        else
+          {
+            query_string: query.query_string,
+            variables: query.provided_variables,
+            context: query.context.to_h,
+            operation_name: query.operation_name,
+          }
+        end
+      end
+
+      # The channel was closed, forget about it.
+      def delete_subscription(subscription_id)
+        query = @subscriptions.delete(subscription_id)
+        # In case this came from the server, tell the client to unsubscribe:
+        @action_cable.server.broadcast(stream_subscription_name(subscription_id), { more: false })
+        # This can be `nil` when `.trigger` happens inside an unsubscribed ActionCable channel,
+        # see https://github.com/rmosolgo/graphql-ruby/issues/2478
+        if query
+          events = query.context.namespace(:subscriptions)[:events]
+          events.each do |event|
+            ev_by_fingerprint = @events[event.topic]
+            ev_for_fingerprint = ev_by_fingerprint[event.fingerprint]
+            ev_for_fingerprint.delete(event)
+            if ev_for_fingerprint.empty?
+              ev_by_fingerprint.delete(event.fingerprint)
+            end
+          end
+        end
+      end
+
+      private
+
+      def stream_subscription_name(subscription_id)
+        [SUBSCRIPTION_PREFIX, @transmit_ns, subscription_id].join
+      end
+
+      def stream_event_name(event)
+        [EVENT_PREFIX, @transmit_ns, event.topic].join
+      end
+    end
+  end
+end

data/lib/graphql/subscriptions/broadcast_analyzer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Subscriptions
+    # Detect whether the current operation:
+    # - Is a subscription operation
+    # - Is completely broadcastable
+    #
+    # Assign the result to `context.namespace(:subscriptions)[:subscription_broadcastable]`
+    # @api private
+    # @see Subscriptions#broadcastable? for a public API
+    class BroadcastAnalyzer < GraphQL::Analysis::AST::Analyzer
+      def initialize(subject)
+        super
+        @default_broadcastable = subject.schema.subscriptions.default_broadcastable
+        # Maybe this will get set to false while analyzing
+        @subscription_broadcastable = true
+      end
+
+      # Only analyze subscription operations
+      def analyze?
+        @query.subscription?
+      end
+
+      def on_enter_field(node, parent, visitor)
+        if (@subscription_broadcastable == false) || visitor.skipping?
+          return
+        end
+
+        current_field = visitor.field_definition
+        apply_broadcastable(current_field)
+
+        current_type = visitor.parent_type_definition
+        if current_type.kind.interface?
+          pt = @query.possible_types(current_type)
+          pt.each do |object_type|
+            ot_field = @query.get_field(object_type, current_field.graphql_name)
+            # Inherited fields would be exactly the same object;
+            # only check fields that are overrides of the inherited one
+            if ot_field && ot_field != current_field
+              apply_broadcastable(ot_field)
+            end
+          end
+        end
+      end
+
+      # Assign the result to context.
+      # (This method is allowed to return an error, but we don't need to)
+      # @return [void]
+      def result
+        query.context.namespace(:subscriptions)[:subscription_broadcastable] = @subscription_broadcastable
+        nil
+      end
+
+      private
+
+      # Modify `@subscription_broadcastable` based on `field_defn`'s configuration (and/or the default value)
+      def apply_broadcastable(field_defn)
+        current_field_broadcastable = field_defn.introspection? || field_defn.broadcastable?
+        case current_field_broadcastable
+        when nil
+          # If the value wasn't set, mix in the default value:
+          # - If the default is false and the current value is true, make it false
+          # - If the default is true and the current value is true, it stays true
+          # - If the default is false and the current value is false, keep it false
+          # - If the default is true and the current value is false, keep it false
+          @subscription_broadcastable = @subscription_broadcastable && @default_broadcastable
+        when false
+          # One non-broadcastable field is enough to make the whole subscription non-broadcastable
+          @subscription_broadcastable = false
+        when true
+          # Leave `@broadcastable_query` true if it's already true,
+          # but don't _set_ it to true if it was set to false by something else.
+          # Actually, just leave it!
+        else
+          raise ArgumentError, "Unexpected `.broadcastable?` value for #{field_defn.path}: #{current_field_broadcastable}"
+        end
+      end
+    end
+  end
+end

data/lib/graphql/subscriptions/default_subscription_resolve_extension.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+module GraphQL
+  class Subscriptions
+    class DefaultSubscriptionResolveExtension < GraphQL::Schema::FieldExtension
+      def resolve(context:, object:, arguments:)
+        has_override_implementation = @field.resolver ||
+          object.respond_to?(@field.resolver_method)
+
+        if !has_override_implementation
+          if context.query.subscription_update?
+            object.object
+          else
+            context.skip
+          end
+        else
+          yield(object, arguments)
+        end
+      end
+
+      def after_resolve(value:, context:, object:, arguments:, **rest)
+        if value.is_a?(GraphQL::ExecutionError)
+          value
+        elsif (events = context.namespace(:subscriptions)[:events])
+          # This is the first execution, so gather an Event
+          # for the backend to register:
+          event = Subscriptions::Event.new(
+            name: field.name,
+            arguments: arguments_without_field_extras(arguments: arguments),
+            context: context,
+            field: field,
+          )
+          events << event
+          value
+        elsif context.query.subscription_topic == Subscriptions::Event.serialize(
+            field.name,
+            arguments_without_field_extras(arguments: arguments),
+            field,
+            scope: (field.subscription_scope ? context[field.subscription_scope] : nil),
+          )
+          # This is a subscription update. The resolver returned `skip` if it should be skipped,
+          # or else it returned an object to resolve the update.
+          value
+        else
+          # This is a subscription update, but this event wasn't triggered.
+          context.skip
+        end
+      end
+
+      private
+
+      def arguments_without_field_extras(arguments:)
+        arguments.dup.tap do |event_args|
+          field.extras.each { |k| event_args.delete(k) }
+        end
+      end
+    end
+  end
+end

data/lib/graphql/subscriptions/event.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+module GraphQL
+  class Subscriptions
+    # This thing can be:
+    # - Subscribed to by `subscription { ... }`
+    # - Triggered by `MySchema.subscriber.trigger(name, arguments, obj)`
+    #
+    class Event
+      # @return [String] Corresponds to the Subscription root field name
+      attr_reader :name
+
+      # @return [GraphQL::Execution::Interpreter::Arguments]
+      attr_reader :arguments
+
+      # @return [GraphQL::Query::Context]
+      attr_reader :context
+
+      # @return [String] An opaque string which identifies this event, derived from `name` and `arguments`
+      attr_reader :topic
+
+      def initialize(name:, arguments:, field: nil, context: nil, scope: nil)
+        @name = name
+        @arguments = arguments
+        @context = context
+        field ||= context.field
+        scope_key = field.subscription_scope
+        scope_val = scope || (context && scope_key && context[scope_key])
+        if scope_key &&
+            (subscription = field.resolver) &&
+            (subscription.respond_to?(:subscription_scope_optional?)) &&
+            !subscription.subscription_scope_optional? &&
+            scope_val.nil?
+          raise Subscriptions::SubscriptionScopeMissingError, "#{field.path} (#{subscription}) requires a `scope:` value to trigger updates (Set `subscription_scope ..., optional: true` to disable this requirement)"
+        end
+
+        @topic = self.class.serialize(name, arguments, field, scope: scope_val, context: context)
+      end
+
+      # @return [String] an identifier for this unit of subscription
+      def self.serialize(_name, arguments, field, scope:, context: GraphQL::Query::NullContext)
+        subscription = field.resolver || GraphQL::Schema::Subscription
+        normalized_args = stringify_args(field, arguments.to_h, context)
+        subscription.topic_for(arguments: normalized_args, field: field, scope: scope)
+      end
+
+      # @return [String] a logical identifier for this event. (Stable when the query is broadcastable.)
+      def fingerprint
+        @fingerprint ||= begin
+          # When this query has been flagged as broadcastable,
+          # use a generalized, stable fingerprint so that
+          # duplicate subscriptions can be evaluated and distributed in bulk.
+          # (`@topic` includes field, args, and subscription scope already.)
+          if @context.namespace(:subscriptions)[:subscription_broadcastable]
+            "#{@topic}/#{@context.query.fingerprint}"
+          else
+            # not broadcastable, build a unique ID for this event
+            @context.schema.subscriptions.build_id
+          end
+        end
+      end
+
+      class << self
+        private
+
+        # This method does not support cyclic references in the Hash,
+        # nor does it support Hashes whose keys are not sortable
+        # with respect to their peers ( cases where a <=> b might throw an error )
+        def deep_sort_hash_keys(hash_to_sort)
+          raise ArgumentError.new("Argument must be a Hash") unless hash_to_sort.is_a?(Hash)
+          hash_to_sort.keys.sort.map do |k|
+            if hash_to_sort[k].is_a?(Hash)
+              [k, deep_sort_hash_keys(hash_to_sort[k])]
+            elsif hash_to_sort[k].is_a?(Array)
+              [k, deep_sort_array_hashes(hash_to_sort[k])]
+            else
+              [k, hash_to_sort[k]]
+            end
+          end.to_h
+        end
+
+        def deep_sort_array_hashes(array_to_inspect)
+          raise ArgumentError.new("Argument must be an Array") unless array_to_inspect.is_a?(Array)
+          array_to_inspect.map do |v|
+            if v.is_a?(Hash)
+              deep_sort_hash_keys(v)
+            elsif v.is_a?(Array)
+              deep_sort_array_hashes(v)
+            else
+              v
+            end
+          end
+        end
+
+        def stringify_args(arg_owner, args, context)
+          arg_owner = arg_owner.respond_to?(:unwrap) ? arg_owner.unwrap : arg_owner # remove list and non-null wrappers
+          case args
+          when Hash
+            next_args = {}
+            args.each do |k, v|
+              arg_name = k.to_s
+              camelized_arg_name = GraphQL::Schema::Member::BuildType.camelize(arg_name)
+              arg_defn = get_arg_definition(arg_owner, camelized_arg_name, context)
+
+              if arg_defn
+                normalized_arg_name = camelized_arg_name
+              else
+                normalized_arg_name = arg_name
+                arg_defn = get_arg_definition(arg_owner, normalized_arg_name, context)
+              end
+              arg_base_type = arg_defn.type.unwrap
+              # In the case where the value being emitted is seen as a "JSON"
+              # type, treat the value as one atomic unit of serialization
+              is_json_definition = arg_base_type && arg_base_type <= GraphQL::Types::JSON
+              if is_json_definition
+                sorted_value = if v.is_a?(Hash)
+                  deep_sort_hash_keys(v)
+                elsif v.is_a?(Array)
+                  deep_sort_array_hashes(v)
+                else
+                  v
+                end
+                next_args[normalized_arg_name] = sorted_value.respond_to?(:to_json) ? sorted_value.to_json : sorted_value
+              else
+                next_args[normalized_arg_name] = stringify_args(arg_base_type, v, context)
+              end
+            end
+            # Make sure they're deeply sorted
+            next_args.sort.to_h
+          when Array
+            args.map { |a| stringify_args(arg_owner, a, context) }
+          when GraphQL::Schema::InputObject
+            stringify_args(arg_owner, args.to_h, context)
+          else
+            args
+          end
+        end
+
+        def get_arg_definition(arg_owner, arg_name, context)
+          arg_owner.get_argument(arg_name, context) || arg_owner.arguments(context).each_value.find { |v| v.keyword.to_s == arg_name }
+        end
+      end
+    end
+  end
+end

data/lib/graphql/subscriptions/instrumentation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+module GraphQL
+  class Subscriptions
+    # Wrap the root fields of the subscription type with special logic for:
+    # - Registering the subscription during the first execution
+    # - Evaluating the triggered portion(s) of the subscription during later execution
+    class Instrumentation
+      def initialize(schema:)
+        @schema = schema
+      end
+
+      # If needed, prepare to gather events which this query subscribes to
+      def before_query(query)
+        if query.subscription? && !query.subscription_update?
+          query.context.namespace(:subscriptions)[:events] = []
+        end
+      end
+
+      # After checking the root fields, pass the gathered events to the store
+      def after_query(query)
+        events = query.context.namespace(:subscriptions)[:events]
+        if events && events.any?
+          @schema.subscriptions.write_subscription(query, events)
+        end
+      end
+    end
+  end
+end