graphql 1.9.5 → 1.13.19

data/lib/graphql/schema/timeout.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    # This plugin will stop resolving new fields after `max_seconds` have elapsed.
+    # After the time has passed, any remaining fields will be `nil`, with errors added
+    # to the `errors` key. Any already-resolved fields will be in the `data` key, so
+    # you'll get a partial response.
+    #
+    # You can subclass `GraphQL::Schema::Timeout` and override `max_seconds` and/or `handle_timeout`
+    # to provide custom logic when a timeout error occurs.
+    #
+    # Note that this will stop a query _in between_ field resolutions, but
+    # it doesn't interrupt long-running `resolve` functions. Be sure to use
+    # timeout options for external connections. For more info, see
+    # www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/
+    #
+    # @example Stop resolving fields after 2 seconds
+    #   class MySchema < GraphQL::Schema
+    #     use GraphQL::Schema::Timeout, max_seconds: 2
+    #   end
+    #
+    # @example Notifying Bugsnag and logging a timeout
+    #   class MyTimeout < GraphQL::Schema::Timeout
+    #     def handle_timeout(error, query)
+    #        Rails.logger.warn("GraphQL Timeout: #{error.message}: #{query.query_string}")
+    #        Bugsnag.notify(error, {query_string: query.query_string})
+    #     end
+    #   end
+    #
+    #   class MySchema < GraphQL::Schema
+    #     use MyTimeout, max_seconds: 2
+    #   end
+    #
+    class Timeout
+      def self.use(schema, **options)
+        tracer = new(**options)
+        schema.tracer(tracer)
+      end
+
+      # @param max_seconds [Numeric] how many seconds the query should be allowed to resolve new fields
+      def initialize(max_seconds:)
+        @max_seconds = max_seconds
+      end
+
+      def trace(key, data)
+        case key
+        when 'execute_multiplex'
+          data.fetch(:multiplex).queries.each do |query|
+            timeout_duration_s = max_seconds(query)
+            timeout_state = if timeout_duration_s == false
+              # if the method returns `false`, don't apply a timeout
+              false
+            else
+              now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+              timeout_at = now + (max_seconds(query) * 1000)
+              {
+                timeout_at: timeout_at,
+                timed_out: false
+              }
+            end
+            query.context.namespace(self.class)[:state] = timeout_state
+          end
+
+          yield
+        when 'execute_field', 'execute_field_lazy'
+          query_context = data[:context] || data[:query].context
+          timeout_state = query_context.namespace(self.class).fetch(:state)
+          # If the `:state` is `false`, then `max_seconds(query)` opted out of timeout for this query.
+          if timeout_state != false && Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) > timeout_state.fetch(:timeout_at)
+            error = if data[:context]
+              GraphQL::Schema::Timeout::TimeoutError.new(query_context.parent_type, query_context.field)
+            else
+              field = data.fetch(:field)
+              GraphQL::Schema::Timeout::TimeoutError.new(field.owner, field)
+            end
+
+            # Only invoke the timeout callback for the first timeout
+            if !timeout_state[:timed_out]
+              timeout_state[:timed_out] = true
+              handle_timeout(error, query_context.query)
+            end
+
+            error
+          else
+            yield
+          end
+        else
+          yield
+        end
+      end
+
+      # Called at the start of each query.
+      # The default implementation returns the `max_seconds:` value from installing this plugin.
+      #
+      # @param query [GraphQL::Query] The query that's about to run
+      # @return [Integer, false] The number of seconds after which to interrupt query execution and call {#handle_error}, or `false` to bypass the timeout.
+      def max_seconds(query)
+        @max_seconds
+      end
+
+      # Invoked when a query times out.
+      # @param error [GraphQL::Schema::Timeout::TimeoutError]
+      # @param query [GraphQL::Error]
+      def handle_timeout(error, query)
+        # override to do something interesting
+      end
+
+      # This error is raised when a query exceeds `max_seconds`.
+      # Since it's a child of {GraphQL::ExecutionError},
+      # its message will be added to the response's `errors` key.
+      #
+      # To raise an error that will stop query resolution, use a custom block
+      # to take this error and raise a new one which _doesn't_ descend from {GraphQL::ExecutionError},
+      # such as `RuntimeError`.
+      class TimeoutError < GraphQL::ExecutionError
+        def initialize(parent_type, field)
+          super("Timeout on #{parent_type.graphql_name}.#{field.graphql_name}")
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/timeout_middleware.rb

@@ -23,21 +23,24 @@ module GraphQL
     #    Bugsnag.notify(timeout_error, {query_string: query_ctx.query.query_string})
     #   end
     #
+    # @api deprecated
+    # @see Schema::Timeout
     class TimeoutMiddleware
       # @param max_seconds [Numeric] how many seconds the query should be allowed to resolve new fields
       def initialize(max_seconds:, context_key: nil, &block)
         @max_seconds = max_seconds
         if context_key
-          warn("TimeoutMiddleware's `context_key` is ignored, timeout data is now stored in isolated storage")
+          GraphQL::Deprecation.warn("TimeoutMiddleware's `context_key` is ignored, timeout data is now stored in isolated storage")
         end
         @error_handler = block
       end
 
       def call(parent_type, parent_object, field_definition, field_args, query_context)
         ns = query_context.namespace(self.class)
-        timeout_at = ns[:timeout_at] ||= Time.now + @max_seconds
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        timeout_at = ns[:timeout_at] ||= now + @max_seconds
 
-        if timeout_at < Time.now
+        if timeout_at < now
           on_timeout(parent_type, parent_object, field_definition, field_args, query_context)
         else
           yield

data/lib/graphql/schema/traversal.rb

@@ -113,7 +113,7 @@ Some late-bound types couldn't be resolved:
           # Find the starting points, then visit them
           visit_roots = [member.query, member.mutation, member.subscription]
           if @introspection
-            introspection_types = schema.introspection_system.object_types
+            introspection_types = schema.introspection_system.types.values
             visit_roots.concat(introspection_types)
             if member.query
               member.introspection_system.entry_points.each do |introspection_field|
@@ -173,7 +173,7 @@ Some late-bound types couldn't be resolved:
           end
         when Class
           if member.respond_to?(:graphql_definition)
-            graphql_member = member.graphql_definition
+            graphql_member = member.graphql_definition(silence_deprecation_warning: true)
             visit(schema, graphql_member, context_description)
           else
             raise GraphQL::Schema::InvalidTypeError.new("Unexpected traversal member: #{member} (#{member.class.name})")

data/lib/graphql/schema/type_expression.rb

@@ -5,29 +5,37 @@ module GraphQL
     module TypeExpression
       # Fetch a type from a type map by its AST specification.
       # Return `nil` if not found.
-      # @param types [GraphQL::Schema::TypeMap]
+      # @param type_owner [#get_type] A thing for looking up types by name
       # @param ast_node [GraphQL::Language::Nodes::AbstractNode]
-      # @return [GraphQL::BaseType, nil]
-      def self.build_type(types, ast_node)
+      # @return [Class, GraphQL::Schema::NonNull, GraphQL::Schema:List]
+      def self.build_type(type_owner, ast_node)
         case ast_node
         when GraphQL::Language::Nodes::TypeName
-          types.fetch(ast_node.name, nil)
+          type_owner.get_type(ast_node.name) # rubocop:disable Development/ContextIsPassedCop -- this is a `context` or `warden`, it's already query-aware
         when GraphQL::Language::Nodes::NonNullType
           ast_inner_type = ast_node.of_type
-          inner_type = build_type(types, ast_inner_type)
-          wrap_type(inner_type, GraphQL::NonNullType)
+          inner_type = build_type(type_owner, ast_inner_type)
+          wrap_type(inner_type, :to_non_null_type)
         when GraphQL::Language::Nodes::ListType
           ast_inner_type = ast_node.of_type
-          inner_type = build_type(types, ast_inner_type)
-          wrap_type(inner_type, GraphQL::ListType)
+          inner_type = build_type(type_owner, ast_inner_type)
+          wrap_type(inner_type, :to_list_type)
+        else
+          raise "Invariant: unexpected type from ast: #{ast_node.inspect}"
         end
       end
 
-      def self.wrap_type(type, wrapper)
-        if type.nil?
-          nil
-        else
-          wrapper.new(of_type: type)
+      class << self
+        private
+
+        def wrap_type(type, wrapper_method)
+          if type.nil?
+            nil
+          elsif wrapper_method == :to_list_type || wrapper_method == :to_non_null_type
+            type.public_send(wrapper_method)
+          else
+            raise ArgumentError, "Unexpected wrapper method: #{wrapper_method.inspect}"
+          end
         end
       end
     end

data/lib/graphql/schema/type_membership.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    # This class joins an object type to an abstract type (interface or union) of which
+    # it is a member.
+    class TypeMembership
+      # @return [Class<GraphQL::Schema::Object>]
+      attr_accessor :object_type
+
+      # @return [Class<GraphQL::Schema::Union>, Module<GraphQL::Schema::Interface>]
+      attr_reader :abstract_type
+
+      # Called when an object is hooked up to an abstract type, such as {Schema::Union.possible_types}
+      # or {Schema::Object.implements} (for interfaces).
+      #
+      # @param abstract_type [Class<GraphQL::Schema::Union>, Module<GraphQL::Schema::Interface>]
+      # @param object_type [Class<GraphQL::Schema::Object>]
+      # @param options [Hash] Any options passed to `.possible_types` or `.implements`
+      def initialize(abstract_type, object_type, **options)
+        @abstract_type = abstract_type
+        @object_type = object_type
+        @options = options
+      end
+
+      # @return [Boolean] if false, {#object_type} will be treated as _not_ a member of {#abstract_type}
+      def visible?(ctx)
+        warden = Warden.from_context(ctx)
+        (@object_type.respond_to?(:visible?) ? warden.visible_type?(@object_type, ctx) : true) &&
+          (@abstract_type.respond_to?(:visible?) ? warden.visible_type?(@abstract_type, ctx) : true)
+      end
+
+      def graphql_name
+        "#{@object_type.graphql_name}.#{@abstract_type.kind.interface? ? "implements" : "belongsTo" }.#{@abstract_type.graphql_name}"
+      end
+
+      def path
+        graphql_name
+      end
+
+      def inspect
+        "#<#{self.class} #{@object_type.inspect} => #{@abstract_type.inspect}>"
+      end
+
+      alias :type_class :itself
+    end
+  end
+end

data/lib/graphql/schema/union.rb

@@ -3,23 +3,44 @@ module GraphQL
   class Schema
     class Union < GraphQL::Schema::Member
       extend GraphQL::Schema::Member::AcceptsDefinition
+      extend GraphQL::Schema::Member::HasUnresolvedTypeError
 
       class << self
-        def possible_types(*types)
+        def inherited(child_class)
+          add_unresolved_type_error(child_class)
+          super
+        end
+
+        def possible_types(*types, context: GraphQL::Query::NullContext, **options)
           if types.any?
-            @possible_types = types
+            types.each do |t|
+              assert_valid_union_member(t)
+              type_memberships << type_membership_class.new(self, t, **options)
+            end
           else
-            all_possible_types = @possible_types || []
-            all_possible_types += super if defined?(super)
-            all_possible_types.uniq
+            visible_types = []
+            warden = Warden.from_context(context)
+            type_memberships.each do |type_membership|
+              if warden.visible_type_membership?(type_membership, context)
+                visible_types << type_membership.object_type
+              end
+            end
+            visible_types
           end
         end
 
+        def all_possible_types
+          type_memberships.map(&:object_type)
+        end
+
+        prepend GraphQL::Schema::Member::CachedGraphQLDefinition::DeprecatedToGraphQL
+
         def to_graphql
           type_defn = GraphQL::UnionType.new
           type_defn.name = graphql_name
           type_defn.description = description
-          type_defn.possible_types = possible_types
+          type_defn.ast_node = ast_node
+          type_defn.type_memberships = type_memberships
           if respond_to?(:resolve_type)
             type_defn.resolve_type = method(:resolve_type)
           end
@@ -27,9 +48,49 @@ module GraphQL
           type_defn
         end
 
+        def type_membership_class(membership_class = nil)
+          if membership_class
+            @type_membership_class = membership_class
+          else
+            @type_membership_class || find_inherited_value(:type_membership_class, GraphQL::Schema::TypeMembership)
+          end
+        end
+
         def kind
           GraphQL::TypeKinds::UNION
         end
+
+        def type_memberships
+          @type_memberships ||= []
+        end
+
+        # Update a type membership whose `.object_type` is a string or late-bound type
+        # so that the type membership's `.object_type` is the given `object_type`.
+        # (This is used for updating the union after the schema as lazily loaded the union member.)
+        # @api private
+        def assign_type_membership_object_type(object_type)
+          assert_valid_union_member(object_type)
+          type_memberships.each { |tm|
+            possible_type = tm.object_type
+            if possible_type.is_a?(String) && (possible_type == object_type.name)
+              # This is a match of Ruby class names, not graphql names,
+              # since strings are used to refer to constants.
+              tm.object_type = object_type
+            elsif possible_type.is_a?(LateBoundType) && possible_type.graphql_name == object_type.graphql_name
+              tm.object_type = object_type
+            end
+          }
+          nil
+        end
+
+        private
+
+        def assert_valid_union_member(type_defn)
+          if type_defn.is_a?(Module) && !type_defn.is_a?(Class)
+            # it's an interface type, defined as a module
+            raise ArgumentError, "Union possible_types can only be object types (not interface types), remove #{type_defn.graphql_name} (#{type_defn.inspect})"
+          end
+        end
       end
     end
   end

data/lib/graphql/schema/unique_within_type.rb

@@ -27,8 +27,7 @@ module GraphQL
       # @param node_id [String] A unique ID generated by {.encode}
       # @return [Array<(String, String)>] The type name & value passed to {.encode}
       def decode(node_id, separator: self.default_id_separator)
-        # urlsafe_decode64 is for forward compatibility
-        Base64Bp.urlsafe_decode64(node_id).split(separator, 2)
+        GraphQL::Schema::Base64Encoder.decode(node_id).split(separator, 2)
       end
     end
   end

data/lib/graphql/schema/validation.rb

@@ -6,6 +6,8 @@ module GraphQL
     # Its {RULES} contain objects that respond to `#call(type)`. Rules are
     # looked up for given types (by class ancestry), then applied to
     # the object until an error is returned.
+    #
+    # Remove this in GraphQL-Ruby 2.0 when schema instances are removed.
     class Validation
       # Lookup the rules for `object` based on its class,
       # Then returns an error message or `nil`
@@ -77,6 +79,18 @@ module GraphQL
           }
         end
 
+        def self.count_at_least(item_name, minimum_count, get_items_proc)
+          ->(type) {
+            items = get_items_proc.call(type)
+
+            if items.size < minimum_count
+              "#{type.name} must define at least #{minimum_count} #{item_name}. #{items.size} defined."
+            else
+              nil
+            end
+          }
+        end
+
         def self.assert_named_items_are_valid(item_name, get_items_proc)
           ->(type) {
             items = get_items_proc.call(type)
@@ -92,7 +106,9 @@ module GraphQL
           }
         end
 
+        HAS_AT_LEAST_ONE_FIELD = Rules.count_at_least("field", 1, ->(type) { type.all_fields })
         FIELDS_ARE_VALID = Rules.assert_named_items_are_valid("field", ->(type) { type.all_fields })
+        HAS_AT_LEAST_ONE_ARGUMENT = Rules.count_at_least("argument", 1, ->(type) { type.arguments })
 
         HAS_ONE_OR_MORE_POSSIBLE_TYPES = ->(type) {
           type.possible_types.length >= 1 ? nil : "must have at least one possible type"
@@ -104,10 +120,6 @@ module GraphQL
         ARGUMENTS_ARE_VALID =  Rules.assert_named_items_are_valid("argument", ->(type) { type.arguments.values })
 
         DEFAULT_VALUE_IS_VALID_FOR_TYPE = ->(type) {
-          if !type.default_value.nil? && type.type.is_a?(NonNullType)
-            return %Q(Variable #{type.name} of type "#{type.type}" is required and will not use the default value. Perhaps you meant to use type "#{type.type.of_type}".)
-          end
-
           if !type.default_value.nil?
             coerced_value = begin
               type.type.coerce_isolated_result(type.default_value)
@@ -123,9 +135,15 @@ module GraphQL
           end
         }
 
+        DEPRECATED_ARGUMENTS_ARE_OPTIONAL = ->(argument) {
+          if argument.deprecation_reason && argument.type.non_null?
+            "must be optional because it's deprecated"
+          end
+        }
+
         TYPE_IS_VALID_INPUT_TYPE = ->(type) {
           outer_type = type.type
-          inner_type = outer_type.is_a?(GraphQL::BaseType) ? outer_type.unwrap : nil
+          inner_type = outer_type.respond_to?(:unwrap) ? outer_type.unwrap : nil
 
           case inner_type
           when GraphQL::ScalarType, GraphQL::InputObjectType, GraphQL::EnumType
@@ -144,7 +162,7 @@ module GraphQL
         }
 
         SCHEMA_CAN_FETCH_IDS = ->(schema) {
-          has_node_field = schema.query && schema.query.all_fields.any?(&:relay_node_field)
+          has_node_field = schema.query && schema.query.fields.each_value.any?(&:relay_node_field)
           if has_node_field && schema.object_from_id_proc.nil?
             "schema contains `node(id:...)` field, so you must define a `object_from_id -> (id, ctx) { ... }` function"
           else
@@ -185,7 +203,7 @@ module GraphQL
         RESERVED_TYPE_NAME = ->(type) {
           if type.name.start_with?('__') && !type.introspection?
             # TODO: make this a hard failure in a later version
-            warn("Name #{type.name.inspect} must not begin with \"__\", which is reserved by GraphQL introspection.")
+            GraphQL::Deprecation.warn("Name #{type.name.inspect} must not begin with \"__\", which is reserved by GraphQL introspection.")
             nil
           else
             # ok name
@@ -195,7 +213,7 @@ module GraphQL
         RESERVED_NAME = ->(named_thing) {
           if named_thing.name.start_with?('__')
             # TODO: make this a hard failure in a later version
-            warn("Name #{named_thing.name.inspect} must not begin with \"__\", which is reserved by GraphQL introspection.")
+            GraphQL::Deprecation.warn("Name #{named_thing.name.inspect} must not begin with \"__\", which is reserved by GraphQL introspection.")
             nil
           else
             # no worries
@@ -255,8 +273,10 @@ module GraphQL
           Rules::NAME_IS_STRING,
           Rules::RESERVED_NAME,
           Rules::DESCRIPTION_IS_STRING_OR_NIL,
+          Rules.assert_property(:deprecation_reason, String, NilClass),
           Rules::TYPE_IS_VALID_INPUT_TYPE,
           Rules::DEFAULT_VALUE_IS_VALID_FOR_TYPE,
+          Rules::DEPRECATED_ARGUMENTS_ARE_OPTIONAL,
         ],
         GraphQL::BaseType => [
           Rules::NAME_IS_STRING,
@@ -264,11 +284,13 @@ module GraphQL
           Rules::DESCRIPTION_IS_STRING_OR_NIL,
         ],
         GraphQL::ObjectType => [
+          Rules::HAS_AT_LEAST_ONE_FIELD,
           Rules.assert_property_list_of(:interfaces, GraphQL::InterfaceType),
           Rules::FIELDS_ARE_VALID,
           Rules::INTERFACES_ARE_IMPLEMENTED,
         ],
         GraphQL::InputObjectType => [
+          Rules::HAS_AT_LEAST_ONE_ARGUMENT,
           Rules::ARGUMENTS_ARE_STRING_TO_ARGUMENT,
           Rules::ARGUMENTS_ARE_VALID,
         ],

data/lib/graphql/schema/validator/allow_blank_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Validator
+      # Use this to specifically reject values that respond to `.blank?` and respond truthy for that method.
+      #
+      # @example Require a non-empty string for an argument
+      #   argument :name, String, required: true, validate: { allow_blank: false }
+      class AllowBlankValidator < Validator
+        def initialize(allow_blank_positional, allow_blank: nil, message: "%{validated} can't be blank", **default_options)
+          @message = message
+          super(**default_options)
+          @allow_blank = allow_blank.nil? ? allow_blank_positional : allow_blank
+        end
+
+        def validate(_object, _context, value)
+          if value.respond_to?(:blank?) && value.blank?
+            if (value.nil? && @allow_null) || @allow_blank
+              # pass
+            else
+              @message
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/validator/allow_null_validator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Validator
+      # Use this to specifically reject or permit `nil` values (given as `null` from GraphQL).
+      #
+      # @example require a non-null value for an argument if it is provided
+      #   argument :name, String, required: false, validates: { allow_null: false }
+      class AllowNullValidator < Validator
+        MESSAGE = "%{validated} can't be null"
+        def initialize(allow_null_positional, allow_null: nil, message: MESSAGE, **default_options)
+          @message = message
+          super(**default_options)
+          @allow_null = allow_null.nil? ? allow_null_positional : allow_null
+        end
+
+        def validate(_object, _context, value)
+          if value.nil? && !@allow_null
+            @message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/validator/exclusion_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Validator
+      # Use this to specifically reject values from an argument.
+      #
+      # @example disallow certain values
+      #
+      #   argument :favorite_non_prime, Integer, required: true,
+      #     validates: { exclusion: { in: [2, 3, 5, 7, ... ]} }
+      #
+      class ExclusionValidator < Validator
+        # @param message [String]
+        # @param in [Array] The values to reject
+        def initialize(message: "%{validated} is reserved", in:, **default_options)
+          # `in` is a reserved word, so work around that
+          @in_list = binding.local_variable_get(:in)
+          @message = message
+          super(**default_options)
+        end
+
+        def validate(_object, _context, value)
+          if permitted_empty_value?(value)
+            # pass
+          elsif @in_list.include?(value)
+            @message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/validator/format_validator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Validator
+      # Use this to assert that string values match (or don't match) the given RegExp.
+      #
+      # @example requiring input to match a pattern
+      #
+      #   argument :handle, String, required: true,
+      #     validates: { format: { with: /\A[a-z0-9_]+\Z/ } }
+      #
+      # @example reject inputs that match a pattern
+      #
+      #   argument :word_that_doesnt_begin_with_a_vowel, String, required: true,
+      #     validates: { format: { without: /\A[aeiou]/ } }
+      #
+      #   # It's pretty hard to come up with a legitimate use case for `without:`
+      #
+      class FormatValidator < Validator
+        # @param with [RegExp, nil]
+        # @param without [Regexp, nil]
+        # @param message [String]
+        def initialize(
+          with: nil,
+          without: nil,
+          message: "%{validated} is invalid",
+          **default_options
+        )
+          @with_pattern = with
+          @without_pattern = without
+          @message = message
+          super(**default_options)
+        end
+
+        def validate(_object, _context, value)
+          if permitted_empty_value?(value)
+            # Do nothing
+          elsif value.nil? ||
+              (@with_pattern && !value.match?(@with_pattern)) ||
+              (@without_pattern && value.match?(@without_pattern))
+            @message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/validator/inclusion_validator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Validator
+      # You can use this to allow certain values for an argument.
+      #
+      # Usually, a {GraphQL::Schema::Enum} is better for this, because it's self-documenting.
+      #
+      # @example only allow certain values for an argument
+      #
+      #   argument :favorite_prime, Integer, required: true,
+      #     validates: { inclusion: { in: [2, 3, 5, 7, 11, ... ] } }
+      #
+      class InclusionValidator < Validator
+        # @param message [String]
+        # @param in [Array] The values to allow
+        def initialize(in:, message: "%{validated} is not included in the list", **default_options)
+          # `in` is a reserved word, so work around that
+          @in_list = binding.local_variable_get(:in)
+          @message = message
+          super(**default_options)
+        end
+
+        def validate(_object, _context, value)
+          if permitted_empty_value?(value)
+            # pass
+          elsif !@in_list.include?(value)
+            @message
+          end
+        end
+      end
+    end
+  end
+end