graphql 0.16.0 → 2.0.15

data/lib/graphql/tracing.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+require "graphql/tracing/active_support_notifications_tracing"
+require "graphql/tracing/platform_tracing"
+require "graphql/tracing/appoptics_tracing"
+require "graphql/tracing/appsignal_tracing"
+require "graphql/tracing/data_dog_tracing"
+require "graphql/tracing/new_relic_tracing"
+require "graphql/tracing/scout_tracing"
+require "graphql/tracing/statsd_tracing"
+require "graphql/tracing/prometheus_tracing"
+
+if defined?(PrometheusExporter::Server)
+  require "graphql/tracing/prometheus_tracing/graphql_collector"
+end
+
+module GraphQL
+  # Library entry point for performance metric reporting.
+  #
+  # @example Sending custom events
+  #   query.trace("my_custom_event", { ... }) do
+  #     # do stuff ...
+  #   end
+  #
+  # @example Adding a tracer to a schema
+  #  class MySchema < GraphQL::Schema
+  #    tracer MyTracer # <= responds to .trace(key, data, &block)
+  #  end
+  #
+  # @example Adding a tracer to a single query
+  #   MySchema.execute(query_str, context: { backtrace: true })
+  #
+  # Events:
+  #
+  # Key | Metadata
+  # ----|---------
+  # lex | `{ query_string: String }`
+  # parse | `{ query_string: String }`
+  # validate | `{ query: GraphQL::Query, validate: Boolean }`
+  # analyze_multiplex |  `{ multiplex: GraphQL::Execution::Multiplex }`
+  # analyze_query | `{ query: GraphQL::Query }`
+  # execute_multiplex | `{ multiplex: GraphQL::Execution::Multiplex }`
+  # execute_query | `{ query: GraphQL::Query }`
+  # execute_query_lazy | `{ query: GraphQL::Query?, multiplex: GraphQL::Execution::Multiplex? }`
+  # execute_field | `{ owner: Class, field: GraphQL::Schema::Field, query: GraphQL::Query, path: Array<String, Integer>, ast_node: GraphQL::Language::Nodes::Field}`
+  # execute_field_lazy | `{ owner: Class, field: GraphQL::Schema::Field, query: GraphQL::Query, path: Array<String, Integer>, ast_node: GraphQL::Language::Nodes::Field}`
+  # authorized | `{ context: GraphQL::Query::Context, type: Class, object: Object, path: Array<String, Integer> }`
+  # authorized_lazy | `{ context: GraphQL::Query::Context, type: Class, object: Object, path: Array<String, Integer> }`
+  # resolve_type | `{ context: GraphQL::Query::Context, type: Class, object: Object, path: Array<String, Integer> }`
+  # resolve_type_lazy | `{ context: GraphQL::Query::Context, type: Class, object: Object, path: Array<String, Integer> }`
+  #
+  # Note that `execute_field` and `execute_field_lazy` receive different data in different settings:
+  #
+  # - When using {GraphQL::Execution::Interpreter}, they receive `{field:, path:, query:}`
+  # - Otherwise, they receive `{context: ...}`
+  #
+  module Tracing
+    # Objects may include traceable to gain a `.trace(...)` method.
+    # The object must have a `@tracers` ivar of type `Array<<#trace(k, d, &b)>>`.
+    # @api private
+    module Traceable
+      # @param key [String] The name of the event in GraphQL internals
+      # @param metadata [Hash] Event-related metadata (can be anything)
+      # @return [Object] Must return the value of the block
+      def trace(key, metadata, &block)
+        return yield if @tracers.empty?
+        call_tracers(0, key, metadata, &block)
+      end
+
+      private
+
+      # If there's a tracer at `idx`, call it and then increment `idx`.
+      # Otherwise, yield.
+      #
+      # @param idx [Integer] Which tracer to call
+      # @param key [String] The current event name
+      # @param metadata [Object] The current event object
+      # @return Whatever the block returns
+      def call_tracers(idx, key, metadata, &block)
+        if idx == @tracers.length
+          yield
+        else
+          @tracers[idx].trace(key, metadata) { call_tracers(idx + 1, key, metadata, &block) }
+        end
+      end
+    end
+
+    module NullTracer
+      module_function
+      def trace(k, v)
+        yield
+      end
+    end
+  end
+end

data/lib/graphql/type_kinds.rb

@@ -1,20 +1,25 @@
+# frozen_string_literal: true
 module GraphQL
   # Type kinds are the basic categories which a type may belong to (`Object`, `Scalar`, `Union`...)
   module TypeKinds
     # These objects are singletons, eg `GraphQL::TypeKinds::UNION`, `GraphQL::TypeKinds::SCALAR`.
     class TypeKind
-      attr_reader :name
-      def initialize(name, resolves: false, fields: false, wraps: false, input: false)
+      attr_reader :name, :description
+      def initialize(name, abstract: false, fields: false, wraps: false, input: false, description: nil)
         @name = name
-        @resolves = resolves
+        @abstract = abstract
         @fields = fields
         @wraps = wraps
         @input = input
-        @composite = fields? || resolves?
+        @composite = fields? || abstract?
+        @description = description
       end
 
       # Does this TypeKind have multiple possible implementors?
-      def resolves?;  @resolves;  end
+      # @deprecated Use `abstract?` instead of `resolves?`.
+      def resolves?;  @abstract;  end
+      # Is this TypeKind abstract?
+      def abstract?; @abstract; end
       # Does this TypeKind have queryable fields?
       def fields?;    @fields;    end
       # Does this TypeKind modify another type?
@@ -24,26 +29,49 @@ module GraphQL
       def to_s;       @name;      end
       # Is this TypeKind composed of many values?
       def composite?; @composite; end
-    end
 
-    TYPE_KINDS = [
-      SCALAR =        TypeKind.new("SCALAR", input: true),
-      OBJECT =        TypeKind.new("OBJECT", fields: true),
-      INTERFACE =     TypeKind.new("INTERFACE", resolves: true, fields: true),
-      UNION =         TypeKind.new("UNION", resolves: true),
-      ENUM =          TypeKind.new("ENUM", input: true),
-      INPUT_OBJECT =  TypeKind.new("INPUT_OBJECT", input: true),
-      LIST =          TypeKind.new("LIST", wraps: true),
-      NON_NULL =      TypeKind.new("NON_NULL", wraps: true),
-    ]
+      def scalar?
+        self == TypeKinds::SCALAR
+      end
 
-    KIND_NAMES = TYPE_KINDS.map(&:name)
-    class TypeKind
-      KIND_NAMES.each do |kind_name|
-        define_method("#{kind_name.downcase}?") do
-          self.name == kind_name
-        end
+      def object?
+        self == TypeKinds::OBJECT
+      end
+
+      def interface?
+        self == TypeKinds::INTERFACE
+      end
+
+      def union?
+        self == TypeKinds::UNION
+      end
+
+      def enum?
+        self == TypeKinds::ENUM
+      end
+
+      def input_object?
+        self == TypeKinds::INPUT_OBJECT
+      end
+
+      def list?
+        self == TypeKinds::LIST
+      end
+
+      def non_null?
+        self == TypeKinds::NON_NULL
       end
     end
+
+    TYPE_KINDS = [
+      SCALAR =        TypeKind.new("SCALAR", input: true, description: 'Indicates this type is a scalar.'),
+      OBJECT =        TypeKind.new("OBJECT", fields: true, description: 'Indicates this type is an object. `fields` and `interfaces` are valid fields.'),
+      INTERFACE =     TypeKind.new("INTERFACE", abstract: true, fields: true, description: 'Indicates this type is an interface. `fields` and `possibleTypes` are valid fields.'),
+      UNION =         TypeKind.new("UNION", abstract: true, description: 'Indicates this type is a union. `possibleTypes` is a valid field.'),
+      ENUM =          TypeKind.new("ENUM", input: true, description: 'Indicates this type is an enum. `enumValues` is a valid field.'),
+      INPUT_OBJECT =  TypeKind.new("INPUT_OBJECT", input: true, description: 'Indicates this type is an input object. `inputFields` is a valid field.'),
+      LIST =          TypeKind.new("LIST", wraps: true, description: 'Indicates this type is a list. `ofType` is a valid field.'),
+      NON_NULL =      TypeKind.new("NON_NULL", wraps: true, description: 'Indicates this type is a non-null. `ofType` is a valid field.'),
+    ]
   end
 end

data/lib/graphql/types/big_int.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    class BigInt < GraphQL::Schema::Scalar
+      description "Represents non-fractional signed whole numeric values. Since the value may exceed the size of a 32-bit integer, it's encoded as a string."
+
+      def self.coerce_input(value, _ctx)
+        value && parse_int(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.coerce_result(value, _ctx)
+        value.to_i.to_s
+      end
+
+      def self.parse_int(value)
+        value.is_a?(Numeric) ? value : Integer(value, 10)
+      end
+    end
+  end
+end

data/lib/graphql/types/boolean.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    class Boolean < GraphQL::Schema::Scalar
+      description "Represents `true` or `false` values."
+
+      def self.coerce_input(value, _ctx)
+        (value == true || value == false) ? value : nil
+      end
+
+      def self.coerce_result(value, _ctx)
+        !!value
+      end
+
+      default_scalar true
+    end
+  end
+end

data/lib/graphql/types/float.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    class Float < GraphQL::Schema::Scalar
+      description "Represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point)."
+
+      def self.coerce_input(value, _ctx)
+        value.is_a?(Numeric) ? value.to_f : nil
+      end
+
+      def self.coerce_result(value, _ctx)
+        value.to_f
+      end
+
+      default_scalar true
+    end
+  end
+end

data/lib/graphql/types/id.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    class ID < GraphQL::Schema::Scalar
+      graphql_name "ID"
+      description "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID."
+      default_scalar true
+      def self.coerce_result(value, _ctx)
+        value.is_a?(::String) ? value : value.to_s
+      end
+
+      def self.coerce_input(value, _ctx)
+        case value
+        when ::String
+          value
+        when Integer
+          value.to_s
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/int.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    # @see {Types::BigInt} for handling integers outside 32-bit range.
+    class Int < GraphQL::Schema::Scalar
+      description "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1."
+
+      MIN = -(2**31)
+      MAX = (2**31) - 1
+
+      def self.coerce_input(value, ctx)
+        return if !value.is_a?(Integer)
+
+        if value >= MIN && value <= MAX
+          value
+        else
+          err = GraphQL::IntegerDecodingError.new(value)
+          ctx.schema.type_error(err, ctx)
+        end
+      end
+
+      def self.coerce_result(value, ctx)
+        value = value.to_i
+        if value >= MIN && value <= MAX
+          value
+        else
+          err = GraphQL::IntegerEncodingError.new(value, context: ctx)
+          ctx.schema.type_error(err, ctx)
+        end
+      end
+
+      default_scalar true
+    end
+  end
+end

data/lib/graphql/types/iso_8601_date.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    # This scalar takes `Date`s and transmits them as strings,
+    # using ISO 8601 format.
+    #
+    # Use it for fields or arguments as follows:
+    #
+    #     field :published_at, GraphQL::Types::ISO8601Date, null: false
+    #
+    #     argument :deliver_at, GraphQL::Types::ISO8601Date, null: false
+    #
+    # Alternatively, use this built-in scalar as inspiration for your
+    # own Date type.
+    class ISO8601Date < GraphQL::Schema::Scalar
+      description "An ISO 8601-encoded date"
+      specified_by_url "https://tools.ietf.org/html/rfc3339"
+
+      # @param value [Date,Time,DateTime,String]
+      # @return [String]
+      def self.coerce_result(value, _ctx)
+        Date.parse(value.to_s).iso8601
+      end
+
+      # @param str_value [String, Date, DateTime, Time]
+      # @return [Date, nil]
+      def self.coerce_input(value, ctx)
+        if value.is_a?(::Date)
+          value
+        elsif value.is_a?(::DateTime)
+          value.to_date
+        elsif value.is_a?(::Time)
+          value.to_date
+        elsif value.nil?
+          nil
+        else
+          Date.iso8601(value)
+        end
+      rescue ArgumentError, TypeError
+        err = GraphQL::DateEncodingError.new(value)
+        ctx.schema.type_error(err, ctx)
+      end
+    end
+  end
+end

data/lib/graphql/types/iso_8601_date_time.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module GraphQL
+  module Types
+    # This scalar takes `Time`s and transmits them as strings,
+    # using ISO 8601 format.
+    #
+    # Use it for fields or arguments as follows:
+    #
+    #     field :created_at, GraphQL::Types::ISO8601DateTime, null: false
+    #
+    #     argument :deliver_at, GraphQL::Types::ISO8601DateTime, null: false
+    #
+    # Alternatively, use this built-in scalar as inspiration for your
+    # own DateTime type.
+    class ISO8601DateTime < GraphQL::Schema::Scalar
+      description "An ISO 8601-encoded datetime"
+      specified_by_url "https://tools.ietf.org/html/rfc3339"
+
+      # It's not compatible with Rails' default,
+      # i.e. ActiveSupport::JSON::Encoder.time_precision (3 by default)
+      DEFAULT_TIME_PRECISION = 0
+
+      # @return [Integer]
+      def self.time_precision
+        @time_precision || DEFAULT_TIME_PRECISION
+      end
+
+      # @param [Integer] value
+      def self.time_precision=(value)
+        @time_precision = value
+      end
+
+      # @param value [Time,Date,DateTime,String]
+      # @return [String]
+      def self.coerce_result(value, _ctx)
+        case value
+        when Date
+          return value.to_time.iso8601(time_precision)
+        when ::String
+          return Time.parse(value).iso8601(time_precision)
+        else
+          # Time, DateTime or compatible is given:
+          return value.iso8601(time_precision)
+        end
+      rescue StandardError => error
+        raise GraphQL::Error, "An incompatible object (#{value.class}) was given to #{self}. Make sure that only Times, Dates, DateTimes, and well-formatted Strings are used with this type. (#{error.message})"
+      end
+
+      # @param str_value [String]
+      # @return [Time]
+      def self.coerce_input(str_value, _ctx)
+        Time.iso8601(str_value)
+      rescue ArgumentError, TypeError
+        begin
+          dt = Date.iso8601(str_value).to_time
+          # For compatibility, continue accepting dates given without times
+          # But without this, it would zero out given any time part of `str_value` (hours and/or minutes)
+          if dt.iso8601.start_with?(str_value)
+            dt
+          elsif str_value.length == 8 && str_value.match?(/\A\d{8}\Z/)
+            # Allow dates that are missing the "-". eg. "20220404"
+            dt
+          else
+            nil
+          end
+        rescue ArgumentError, TypeError
+          # Invalid input
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    # An untyped JSON scalar that maps to Ruby hashes, arrays, strings, integers, floats, booleans and nils.
+    # This should be used judiciously because it subverts the GraphQL type system.
+    #
+    # Use it for fields or arguments as follows:
+    #
+    #     field :template_parameters, GraphQL::Types::JSON, null: false
+    #
+    #     argument :template_parameters, GraphQL::Types::JSON, null: false
+    #
+    class JSON < GraphQL::Schema::Scalar
+      description "Represents untyped JSON"
+
+      def self.coerce_input(value, _context)
+        value
+      end
+
+      def self.coerce_result(value, _context)
+        value
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/base_connection.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      # Use this to implement Relay connections, or take it as inspiration
+      # for Relay classes in your own app.
+      #
+      # You may wish to copy this code into your own base class,
+      # so you can extend your own `BaseObject` instead of `GraphQL::Schema::Object`.
+      #
+      # @example Implementation a connection and edge
+      #   class BaseObject < GraphQL::Schema::Object; end
+      #
+      #   # Given some object in your app ...
+      #   class Types::Post < BaseObject
+      #   end
+      #
+      #   # Make a couple of base classes:
+      #   class Types::BaseEdge < GraphQL::Types::Relay::BaseEdge; end
+      #   class Types::BaseConnection < GraphQL::Types::Relay::BaseConnection; end
+      #
+      #   # Then extend them for the object in your app
+      #   class Types::PostEdge < Types::BaseEdge
+      #     node_type Types::Post
+      #   end
+      #
+      #   class Types::PostConnection < Types::BaseConnection
+      #     edge_type Types::PostEdge,
+      #               edges_nullable: true,
+      #               edge_nullable: true,
+      #               node_nullable: true,
+      #               nodes_field: true
+      #
+      #     # Alternatively, you can call the class methods followed by your edge type
+      #     # edges_nullable true
+      #     # edge_nullable true
+      #     # nodes_nullable true
+      #     # has_nodes_field true
+      #     # edge_type Types::PostEdge
+      #   end
+      #
+      # @see Relay::BaseEdge for edge types
+      class BaseConnection < Schema::Object
+        include ConnectionBehaviors
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/base_edge.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    module Relay
+      # A class-based definition for Relay edges.
+      #
+      # Use this as a parent class in your app, or use it as inspiration for your
+      # own base `Edge` class.
+      #
+      # For example, you may want to extend your own `BaseObject` instead of the
+      # built-in `GraphQL::Schema::Object`.
+      #
+      # @example Making a UserEdge type
+      #   # Make a base class for your app
+      #   class Types::BaseEdge < GraphQL::Types::Relay::BaseEdge
+      #   end
+      #
+      #   # Then extend your own base class
+      #   class Types::UserEdge < Types::BaseEdge
+      #     node_type(Types::User)
+      #   end
+      #
+      # @see {Relay::BaseConnection} for connection types
+      class BaseEdge < GraphQL::Schema::Object
+        include Types::Relay::EdgeBehaviors
+      end
+    end
+  end
+end