Add register_indexer_extension schema definition API (#1299)

## Why

Ingestion format gems need a way to ensure their indexer-side behavior
is active whenever a schema is defined with their schema definition
extension--the same guarantee `register_graphql_extension` provides for
GraphQL extensions (e.g. how `elasticgraph-apollo` registers its engine
extension).

## What

- Add `register_indexer_extension` to the schema definition API,
mirroring `register_graphql_extension`
- Registered extensions are dumped into the `indexer_extension_modules`
runtime metadata added in #1298

## Verification

- `script/lint`, `script/type_check`
- `script/run_gem_specs elasticgraph-schema_definition` (100% coverage)
## Stack
Current PR is marked with `->`.

- [#1298 Add indexer_extension_modules to runtime
metadata](#1298)
- -> [#1299 Add register_indexer_extension schema definition
API](#1299)
- [#1300 Apply indexer extension modules when the Indexer
boots](#1300)
- [#1301 Extract an ingestion adapter seam inside
elasticgraph-indexer](#1301)
- [#1302 Move JSON ingestion into elasticgraph-json_ingestion via an
indexer extension](#1302)

Author: jwils

config/site/support/doctest_helper.rb

@@ -157,6 +157,16 @@ def self.prepare_for_indexing(value)
       ::File.write("artist_resolver.rb", "")
     end
 
+    doctest.before "ElasticGraph::SchemaDefinition::API#register_indexer_extension" do
+      ::FileUtils.mkdir_p "my_gem"
+      ::File.write("my_gem/indexer_extension.rb", <<~EOS)
+        module MyGem
+          module IndexerExtension
+          end
+        end
+      EOS
+    end
+
     [
       "ElasticGraph::Apollo@Use elasticgraph-apollo in a project",
       "ElasticGraph::Apollo::SchemaDefinition::APIExtension@Define local rake tasks with this extension module",

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

@@ -348,6 +348,36 @@ def register_graphql_extension(extension_module, defined_at:, **config)
         nil
       end
 
+      # Registers an indexer extension module that will be loaded and used by `elasticgraph-indexer`. While such
+      # extension modules can also be configured in a settings YAML file, it can be useful to register it here
+      # when you want to ensure that the extension is used in all environments. For example, an ingestion format
+      # library needs to ensure its corresponding indexer extension module is used since events of its format
+      # would not be ingestible otherwise.
+      #
+      # @param extension_module [Module] indexer extension module
+      # @param defined_at [String] the `require` path of the extension module
+      # @param config [Hash<Symbol, Object>] configuration options for the extension module
+      # @return [void]
+      #
+      # @example Register an indexer extension module
+      #   # In `my_gem/indexer_extension.rb`:
+      #   module MyGem
+      #     module IndexerExtension
+      #     end
+      #   end
+      #
+      #   require(indexer_extension_require_path = "./my_gem/indexer_extension")
+      #
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.register_indexer_extension MyGem::IndexerExtension,
+      #       defined_at: indexer_extension_require_path
+      #   end
+      def register_indexer_extension(extension_module, defined_at:, **config)
+        extension = SchemaArtifacts::RuntimeMetadata::Extension.new(extension_module, defined_at, config)
+        @state.indexer_extension_modules << SchemaArtifacts::RuntimeMetadata::ComponentExtension.new(extension.to_dumpable_hash)
+        nil
+      end
+
       # Registers a GraphQL resolver that will be loaded and used by `elasticgraph-graphql`. To use a GraphQL resolver you have
       # registered, set a field's `resolver` to the name you provide when registering your resolver.
       #

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

@@ -125,7 +125,7 @@ def build_runtime_metadata
           schema_element_names: state.schema_elements,
           graphql_extension_modules: state.graphql_extension_modules,
           graphql_resolvers_by_name: state.graphql_resolvers_by_name,
-          indexer_extension_modules: [],
+          indexer_extension_modules: state.indexer_extension_modules,
           static_script_ids_by_scoped_name: STATIC_SCRIPT_REPO.script_ids_by_scoped_name
         ).tap { |rm| verify_runtime_metadata(rm) }
       end

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

@@ -39,6 +39,7 @@ class State < Struct.new(
       :reserved_type_names,
       :graphql_extension_modules,
       :graphql_resolvers_by_name,
+      :indexer_extension_modules,
       :built_in_graphql_resolvers,
       :initially_registered_built_in_types,
       :built_in_types_customization_blocks,
@@ -86,6 +87,7 @@ def self.with(
           reserved_type_names: ::Set.new,
           graphql_extension_modules: [],
           graphql_resolvers_by_name: {},
+          indexer_extension_modules: [],
           built_in_graphql_resolvers: ::Set.new,
           initially_registered_built_in_types: ::Set.new,
           built_in_types_customization_blocks: [],

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

@@ -77,6 +77,7 @@ module ElasticGraph
       @results: Results?
       def results: () -> Results
       def register_graphql_extension: (::Module, defined_at: ::String, **untyped) -> void
+      def register_indexer_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
       def on_root_query_type: () { (SchemaElements::ObjectType) -> void } -> void

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

@@ -17,6 +17,7 @@ module ElasticGraph
       attr_reader reserved_type_names: ::Set[::String]
       attr_reader graphql_extension_modules: ::Array[SchemaArtifacts::RuntimeMetadata::ComponentExtension]
       attr_reader graphql_resolvers_by_name: ::Hash[::Symbol, SchemaArtifacts::RuntimeMetadata::GraphQLResolver]
+      attr_reader indexer_extension_modules: ::Array[SchemaArtifacts::RuntimeMetadata::ComponentExtension]
       attr_reader built_in_graphql_resolvers: ::Set[::Symbol]
       attr_accessor initially_registered_built_in_types: ::Set[::String]
       attr_accessor built_in_types_customization_blocks: ::Array[^(SchemaElements::graphQLType) -> void]
@@ -50,6 +51,7 @@ module ElasticGraph
         reserved_type_names: ::Set[::String],
         graphql_extension_modules: ::Array[SchemaArtifacts::RuntimeMetadata::ComponentExtension],
         graphql_resolvers_by_name: ::Hash[::Symbol, SchemaArtifacts::RuntimeMetadata::GraphQLResolver],
+        indexer_extension_modules: ::Array[SchemaArtifacts::RuntimeMetadata::ComponentExtension],
         built_in_graphql_resolvers: ::Set[::Symbol],
         initially_registered_built_in_types: ::Set[::String],
         built_in_types_customization_blocks: ::Array[^(SchemaElements::graphQLType) -> void],

elasticgraph-schema_definition/spec/unit/elastic_graph/schema_definition/runtime_metadata/indexer_extension_modules_spec.rb

@@ -0,0 +1,41 @@
+# Copyright 2024 - 2026 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require_relative "runtime_metadata_support"
+
+module ElasticGraph
+  module SchemaDefinition
+    RSpec.describe "RuntimeMetadata #indexer_extension_modules" do
+      include_context "RuntimeMetadata support"
+
+      it "includes any modules registered during schema definition" do
+        extension_module1 = Module.new
+        extension_module2 = Module.new
+
+        metadata = define_schema do |s|
+          s.register_indexer_extension extension_module1, defined_at: __FILE__
+          s.register_indexer_extension extension_module2, defined_at: __FILE__
+
+          s.object_type "Widget" do |t|
+            t.field "id", "ID!"
+            t.index "widgets"
+          end
+        end.runtime_metadata
+
+        expect(metadata.indexer_extension_modules).to eq [
+          SchemaArtifacts::RuntimeMetadata::ComponentExtension.new(
+            SchemaArtifacts::RuntimeMetadata::Extension.new(extension_module1, __FILE__, {}).to_dumpable_hash
+          ),
+          SchemaArtifacts::RuntimeMetadata::ComponentExtension.new(
+            SchemaArtifacts::RuntimeMetadata::Extension.new(extension_module2, __FILE__, {}).to_dumpable_hash
+          )
+        ]
+      end
+    end
+  end
+end