Add schema definition extension plumbing

Rakefile

@@ -46,7 +46,6 @@ end
 
 configure_local_rake_tasks = ->(tasks) do
   tasks.schema_element_name_form = :snake_case
-  tasks.enforce_json_schema_version = false
   tasks.index_document_sizes = true
   tasks.env_port_mapping = {test: test_port}
   tasks.output = schema_def_output

config/schema.rb

@@ -8,6 +8,7 @@
 
 ElasticGraph.define_schema do |schema|
   schema.json_schema_version 1
+  schema.enforce_json_schema_version false
 end
 
 # Note: anytime you add a file to load here, you'll also have to update the list here:

config/site/Rakefile

@@ -448,7 +448,6 @@ module ElasticGraph
               namespace schema_name do
                 ::ElasticGraph::Local::RakeTasks.new(local_config_yaml: settings_file, path_to_schema: schema_file) do |tasks|
                   tasks.opensearch_versions = []
-                  tasks.enforce_json_schema_version = false
                 end
 
                 task validate: ["schema_artifacts:dump"] do

config/site/support/doctest_helper.rb

@@ -82,7 +82,6 @@ module ElasticGraph
         artifacts_manager = @api.factory.new_schema_artifact_manager(
           schema_definition_results: @api.results,
           schema_artifacts_directory: "#{@tmp_dir}/schema_artifacts",
-          enforce_json_schema_version: true,
           output: ::StringIO.new
         )
 

elasticgraph-admin/spec/integration/elastic_graph/admin/index_definition_configurator/for_index_template_spec.rb

@@ -167,7 +167,6 @@ def fetch_artifact_configuration(schema_artifacts, index_def_name)
               factory.new_schema_artifact_manager(
                 schema_definition_results: schema_def_results,
                 schema_artifacts_directory: Dir.pwd,
-                enforce_json_schema_version: true,
                 output: output_io
               ).dump_artifacts
 

elasticgraph-apollo/README.md

@@ -69,9 +69,6 @@ index 2943335..26633c3 100644
    path_to_schema: "#{project_root}/config/schema.rb"
  ) do |tasks|
 +  tasks.schema_definition_extension_modules = [ElasticGraph::Apollo::SchemaDefinition::APIExtension]
-+
-   # Set this to true once you're beyond the prototyping stage.
-   tasks.enforce_json_schema_version = false
 
 ```
 

elasticgraph-apollo/apollo_tests_implementation/Rakefile

@@ -17,6 +17,5 @@ ElasticGraph::SchemaDefinition::RakeTasks.new(
   index_document_sizes: false,
   path_to_schema: project_root / "config/products_schema.rb",
   schema_artifacts_directory: project_root / "config/schema/artifacts",
-  extension_modules: [ElasticGraph::Apollo::SchemaDefinition::APIExtension],
-  enforce_json_schema_version: false
+  extension_modules: [ElasticGraph::Apollo::SchemaDefinition::APIExtension]
 )

elasticgraph-apollo/apollo_tests_implementation/config/products_schema.rb

@@ -18,6 +18,7 @@ module ApolloTestImpl
   # https://github.com/apollographql/apollo-federation-subgraph-compatibility/blob/2.0.0/COMPATIBILITY.md#products-schema-to-be-implemented-by-library-maintainers
   ElasticGraph.define_schema do |schema|
     schema.json_schema_version 1
+    schema.enforce_json_schema_version false
     schema.target_apollo_federation_version(federation_version) if federation_version
 
     unless federation_version == "2.0"

elasticgraph-graphql/spec/acceptance/schema_evolution_spec.rb

@@ -68,7 +68,6 @@ def dump_schema_artifacts(json_schema_version:, team_extras: "")
           index_document_sizes: true,
           path_to_schema: path_to_schema,
           schema_artifacts_directory: "config/schema/artifacts",
-          enforce_json_schema_version: true,
           output: output
         )
       end

elasticgraph-indexer/spec/acceptance/schema_evolution_spec.rb

@@ -404,7 +404,6 @@ def dump_artifacts
           index_document_sizes: true,
           path_to_schema: path_to_schema,
           schema_artifacts_directory: "config/schema/artifacts",
-          enforce_json_schema_version: true,
           output: output
         )
       end

elasticgraph-local/lib/elastic_graph/local/rake_tasks.rb

@@ -213,33 +213,6 @@ class RakeTasks < ::Rake::TaskLib
       # @dynamic schema_definition_extension_modules, schema_definition_extension_modules=
       attr_accessor :schema_definition_extension_modules
 
-      # Whether or not to enforce the requirement that the JSON schema version is incremented every time
-      # dumping the JSON schemas results in a changed artifact. Defaults to `true`.
-      #
-      # @note Generally speaking, you will want this to be `true` for any ElasticGraph application that is in
-      #    production as the versioning of JSON schemas is what supports safe schema evolution as it allows
-      #    ElasticGraph to identify which version of the JSON schema the publishing system was operating on
-      #    when it published an event.
-      #
-      #    It can be useful to set it to `false` before your application is in production, as you do not want
-      #    to be forced to bump the version after every single schema change while you are building an initial
-      #    prototype.
-      #
-      # @return [Boolean] whether to require `json_schema_version` to be incremented on changes that impact `json_schemas.yaml`
-      # @see SchemaDefinition::API#json_schema_version
-      #
-      # @example Disable enforcement during initial prototyping
-      #   ElasticGraph::Local::RakeTasks.new(
-      #     local_config_yaml: "config/settings/local.yaml",
-      #     path_to_schema: "config/schema.rb"
-      #   ) do |tasks|
-      #     # TODO: remove this once we're past the prototyping stage
-      #     tasks.enforce_json_schema_version = false
-      #   end
-      #
-      # @dynamic enforce_json_schema_version, enforce_json_schema_version=
-      attr_accessor :enforce_json_schema_version
-
       # List of Elasticsearch versions you want to be able to boot. Rake tasks will be defined for each version to support booting and
       # halting Elasticsearch locally. If the configuration of `local_config_yaml` only configures `opensearch` as a cluster backend,
       # will default to an empty array. Otherwise, defaults to the versions of Elasticsearch that are exercised by the ElasticGraph test suite, as
@@ -362,7 +335,6 @@ def initialize(local_config_yaml:, path_to_schema:)
         self.type_name_overrides = {}
         self.enum_value_overrides_by_type = {}
         self.schema_definition_extension_modules = []
-        self.enforce_json_schema_version = true
         self.env_port_mapping = {}
         self.output = $stdout
         self.daemon_timeout = 300
@@ -394,7 +366,6 @@ def initialize(local_config_yaml:, path_to_schema:)
           type_name_overrides: type_name_overrides,
           enum_value_overrides_by_type: enum_value_overrides_by_type,
           extension_modules: schema_definition_extension_modules,
-          enforce_json_schema_version: enforce_json_schema_version,
           output: output
         )
 

elasticgraph-local/sig/elastic_graph/local/rake_tasks.rbs

@@ -8,7 +8,6 @@ module ElasticGraph
       attr_accessor type_name_overrides: ::Hash[::Symbol, ::String]
       attr_accessor enum_value_overrides_by_type: ::Hash[::Symbol, ::Hash[::Symbol, ::String]]
       attr_accessor schema_definition_extension_modules: ::Array[::Module]
-      attr_accessor enforce_json_schema_version: bool
       attr_accessor elasticsearch_versions: ::Array[::String]
       attr_accessor opensearch_versions: ::Array[::String]
       attr_accessor env_port_mapping: ::Hash[::String, ::Integer]

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb

@@ -77,7 +77,7 @@ def initialize(
 
         @factory = @state.factory
 
-        extension_modules.each { |mod| extend(mod) }
+        extension_modules.uniq.each { |mod| extend(mod) }
 
         # These lines must come _after_ the extension modules are applied, so that the extension modules
         # have a chance to hook into the factory in order to customize built in types if desired.
@@ -460,11 +460,11 @@ def results
       #
       # @note While this is an important part of how ElasticGraph is designed to support schema evolution, it can be annoying constantly
       #   have to increment this while rapidly changing the schema during prototyping. You can disable the requirement to increment this
-      #   on every JSON schema change by setting `enforce_json_schema_version` to `false` in your `Rakefile`.
+      #   on every JSON schema change with {#enforce_json_schema_version}.
       #
       # @param version [Integer] current version number of the JSON schema artifact
       # @return [void]
-      # @see Local::RakeTasks#enforce_json_schema_version
+      # @see #enforce_json_schema_version
       #
       # @example Set the JSON schema version to 1
       #   ElasticGraph.define_schema do |schema|
@@ -484,6 +484,25 @@ def json_schema_version(version)
         nil
       end
 
+      # Configures whether {SchemaArtifactManager} enforces that {#json_schema_version} gets bumped every time the JSON schemas artifact
+      # changes. This should generally remain enabled for production applications, but disabling it can be useful during early prototyping.
+      #
+      # @param value [Boolean] whether JSON schema version bumps should be enforced
+      # @return [void]
+      #
+      # @example Disable JSON schema version enforcement while prototyping
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.enforce_json_schema_version false
+      #   end
+      def enforce_json_schema_version(value)
+        unless value == true || value == false
+          raise Errors::SchemaError, "`enforce_json_schema_version` must be a boolean. Specified value: #{value.inspect}"
+        end
+
+        @state.enforce_json_schema_version = value
+        nil
+      end
+
       # Defines strictness of the JSON schema validation. By default, the JSON schema will require all fields to be provided by the
       # publisher (but they can be nullable) and will ignore extra fields that are not defined in the schema. Use this method to
       # configure this behavior.

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/factory.rb

@@ -59,6 +59,10 @@ module SchemaDefinition
     class Factory
       include Mixins::HasReadableToSAndInspect.new
 
+      # @dynamic state
+      # @return [State] schema definition state shared with the factory's API
+      attr_reader :state
+
       def initialize(state)
         @state = state
       end
@@ -297,14 +301,12 @@ def new_results
       def new_schema_artifact_manager(
         schema_definition_results:,
         schema_artifacts_directory:,
-        enforce_json_schema_version:,
         output:,
         max_diff_lines: 50
       )
         @@schema_artifact_manager_new.call(
           schema_definition_results:,
           schema_artifacts_directory:,
-          enforce_json_schema_version:,
           output:,
           max_diff_lines:
         )

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/rake_tasks.rb

@@ -41,12 +41,6 @@ class RakeTasks < ::Rake::TaskLib
       #   specific enum types. For example, to rename the `DayOfWeek.MONDAY` enum to `DayOfWeek.MON`, pass `{DayOfWeek: {MONDAY: "MON"}}`.
       # @param extension_modules [Array<Module>] List of Ruby modules to extend onto the `SchemaDefinition::API` instance. Designed to
       #   support ElasticGraph extension gems (such as `elasticgraph-apollo`).
-      # @param enforce_json_schema_version [Boolean] Whether or not to enforce the requirement that the JSON schema version is incremented
-      #   every time dumping the JSON schemas results in a changed artifact. Generally speaking, you will want this to be `true` for any
-      #   ElasticGraph application that is in production as the versioning of JSON schemas is what supports safe schema evolution as it
-      #   allows ElasticGraph to identify which version of the JSON schema the publishing system was operating on when it published an
-      #   event. It can be useful to set it to `false` before your application is in production, as you do not want to be forced to bump
-      #   the version after every single schema change while you are building an initial prototype.
       # @param output [IO] used for printing task output
       #
       # @example Minimal setup with defaults
@@ -117,7 +111,6 @@ def initialize(
         type_name_overrides: {},
         enum_value_overrides_by_type: {},
         extension_modules: [],
-        enforce_json_schema_version: true,
         output: $stdout
       )
         @schema_element_names = SchemaArtifacts::RuntimeMetadata::SchemaElementNames.new(
@@ -131,7 +124,6 @@ def initialize(
         @index_document_sizes = index_document_sizes
         @path_to_schema = path_to_schema
         @schema_artifacts_directory = schema_artifacts_directory
-        @enforce_json_schema_version = enforce_json_schema_version
         @extension_modules = extension_modules
         @output = output
 
@@ -164,7 +156,6 @@ def schema_artifact_manager
         schema_def_api.factory.new_schema_artifact_manager(
           schema_definition_results: schema_def_api.results,
           schema_artifacts_directory: @schema_artifacts_directory.to_s,
-          enforce_json_schema_version: @enforce_json_schema_version,
           output: @output,
           max_diff_lines: max_diff_lines
         )

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_artifact_manager.rb

@@ -31,10 +31,9 @@ class SchemaArtifactManager
       # @dynamic schema_definition_results
       attr_reader :schema_definition_results
 
-      def initialize(schema_definition_results:, schema_artifacts_directory:, enforce_json_schema_version:, output:, max_diff_lines: 50)
+      def initialize(schema_definition_results:, schema_artifacts_directory:, output:, max_diff_lines: 50)
         @schema_definition_results = schema_definition_results
         @schema_artifacts_directory = schema_artifacts_directory
-        @enforce_json_schema_version = enforce_json_schema_version
         @output = output
         @max_diff_lines = max_diff_lines
 
@@ -51,7 +50,7 @@ def initialize(schema_definition_results:, schema_artifacts_directory:, enforce_
       # Dumps all the schema artifacts to disk.
       def dump_artifacts
         check_if_needs_json_schema_version_bump do |recommended_json_schema_version|
-          if @enforce_json_schema_version
+          if schema_definition_results.state.enforce_json_schema_version
             # @type var setter_location: ::Thread::Backtrace::Location
             # We use `_ =` because while `json_schema_version_setter_location` can be nil,
             # it'll never be nil if we get here and we want the type to be non-nilable.
@@ -62,12 +61,12 @@ def dump_artifacts
               "increase the schema's version, and then run the `bundle exec rake schema_artifacts:dump` command again.\n\n" \
               "To update the schema version to the expected version, change line #{setter_location.lineno} at `#{setter_location_path}` to:\n" \
               "  `schema.json_schema_version #{recommended_json_schema_version}`\n\n" \
-              "Alternately, pass `enforce_json_schema_version: false` to `ElasticGraph::SchemaDefinition::RakeTasks.new` to allow the JSON schemas " \
-              "file to change without requiring a version bump, but that is only recommended for non-production applications during initial schema prototyping."
+              "Alternately, call `schema.enforce_json_schema_version false` in your schema definition to allow the JSON schemas file " \
+              "to change without requiring a version bump, but that is only recommended for non-production applications during initial schema prototyping."
           else
             @output.puts <<~EOS
               WARNING: the `json_schemas.yaml` artifact is being updated without the `json_schema_version` being correspondingly incremented.
-              This is not recommended for production applications, but is currently allowed because you have set `enforce_json_schema_version: false`.
+              This is not recommended for production applications, but is currently allowed because you have called `schema.enforce_json_schema_version false`.
             EOS
           end
         end

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/state.rb

@@ -43,6 +43,7 @@ class State < Struct.new(
       :deleted_fields_by_type_name_and_old_field_name,
       :json_schema_version,
       :json_schema_version_setter_location,
+      :enforce_json_schema_version,
       :graphql_extension_modules,
       :graphql_resolvers_by_name,
       :built_in_graphql_resolvers,
@@ -93,6 +94,7 @@ def self.with(
           deleted_fields_by_type_name_and_old_field_name: ::Hash.new { |h, k| h[k] = {} },
           json_schema_version_setter_location: nil,
           json_schema_version: nil,
+          enforce_json_schema_version: true,
           graphql_extension_modules: [],
           graphql_resolvers_by_name: {},
           built_in_graphql_resolvers: ::Set.new,

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/test_support.rb

@@ -7,6 +7,7 @@
 # frozen_string_literal: true
 
 require "elastic_graph/errors"
+require "elastic_graph/schema_artifacts/from_disk"
 require "elastic_graph/schema_artifacts/runtime_metadata/schema_element_names"
 require "elastic_graph/schema_definition/api"
 require "elastic_graph/schema_definition/schema_artifact_manager"
@@ -76,19 +77,19 @@ def define_schema_with_schema_elements(
 
         # Set the json_schema_version to the provided value, if needed.
         if !json_schema_version.nil? && api.state.json_schema_version.nil?
-          api.json_schema_version json_schema_version
+          api.json_schema_version(json_schema_version)
         end
 
         # :nocov: -- the else branch and code past this aren't used by tests in elasticgraph-schema_definition.
         return api.results unless reload_schema_artifacts
 
         # Reloading the schema artifacts takes extra time that we don't usually want to spend (so it's opt-in)
         # but it can be useful in some cases because there is a bit of extra pruning/validation that it applies.
+        api.enforce_json_schema_version false
         tmp_dir = ::Dir.mktmpdir
         artifacts_manager = api.factory.new_schema_artifact_manager(
           schema_definition_results: api.results,
           schema_artifacts_directory: tmp_dir,
-          enforce_json_schema_version: false,
           output: ::StringIO.new
         )
 

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/api.rbs

@@ -78,6 +78,7 @@ module ElasticGraph
       @results: Results?
       def results: () -> Results
       def json_schema_version: (::Integer) -> void
+      def enforce_json_schema_version: (bool) -> void
       def register_graphql_extension: (::Module, defined_at: ::String, **untyped) -> void
       def register_graphql_resolver: (::Symbol, ::Class, defined_at: ::String, ?built_in: bool, **untyped) -> void
       def on_built_in_types: () { (SchemaElements::graphQLType) -> void } -> void

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/factory.rbs

@@ -2,6 +2,7 @@ module ElasticGraph
   module SchemaDefinition
     class Factory
       @state: State
+      attr_reader state: State
       def initialize: (State) -> void
 
       def self.prevent_non_factory_instantiation_of: (::Class) -> ::Method
@@ -129,7 +130,6 @@ module ElasticGraph
       def new_schema_artifact_manager: (
         schema_definition_results: Results,
         schema_artifacts_directory: ::String,
-        enforce_json_schema_version: bool,
         output: io,
         ?max_diff_lines: ::Integer
       ) -> SchemaArtifactManager

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/rake_tasks.rbs

@@ -11,7 +11,6 @@ module ElasticGraph
         ?type_name_overrides: ::Hash[::Symbol, ::String],
         ?enum_value_overrides_by_type: ::Hash[::Symbol, ::Hash[::Symbol, ::String]],
         ?extension_modules: ::Array[::Module],
-        ?enforce_json_schema_version: bool,
         ?output: io
       ) -> void
 
@@ -24,7 +23,6 @@ module ElasticGraph
       @index_document_sizes: bool
       @path_to_schema: ::String | ::Pathname
       @schema_artifacts_directory: ::String | ::Pathname
-      @enforce_json_schema_version: bool
       @extension_modules: ::Array[::Module]
       @output: io
 

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/schema_artifact_manager.rbs

@@ -6,7 +6,6 @@ module ElasticGraph
       def initialize: (
         schema_definition_results: Results,
         schema_artifacts_directory: ::String,
-        enforce_json_schema_version: bool,
         output: io,
         ?max_diff_lines: ::Integer
       ) -> void
@@ -18,7 +17,6 @@ module ElasticGraph
 
       @schema_definition_results: Results
       @schema_artifacts_directory: ::String
-      @enforce_json_schema_version: bool
       @output: io
       @max_diff_lines: ::Integer
       @artifacts: ::Array[SchemaArtifact[untyped]]?