elasticgraph-schema_artifacts 0.17.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2533e0bedd54dfb7833aac07d8f4023924cb55ecf3422015a337a9ca2216989
+  data.tar.gz: 6138a4c8e9f5e851584c0db50f8e7099dcc1a52b1f0a0ab9e1b2eee3df14dd8d
+SHA512:
+  metadata.gz: 8e25c1b47147fbd7e8138fe5074ca00ff7fa608c0a6458a383d52b73dc6c40a2704b2f5d57899f61fe2e68a8492636e49cfc6050f52783fbe05178e4dcc0d345
+  data.tar.gz: eecf7b86cf9f34f686736c96b5d50289cb1f016d8717a834746201f346057f70ac0221bffcf763369d7ba211ff99ed10e83e7e8d320570d066a4f71af7a2fdf7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Block, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,3 @@
+# ElasticGraph::SchemaArtifacts
+
+Contains code related to ElasticGraph's generated schema artifacts.

data/elasticgraph-schema_artifacts.gemspec

@@ -0,0 +1,21 @@
+# Copyright 2024 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 "../gemspec_helper"
+
+ElasticGraphGemspecHelper.define_elasticgraph_gem(gemspec_file: __FILE__, category: :core) do |spec, eg_version|
+  spec.summary = "ElasticGraph gem containing code related to generated schema artifacts."
+
+  spec.add_dependency "elasticgraph-support", eg_version
+
+  # Necessary since `ScalarType` references coercion adapters defined in the `elasticgraph-graphql` gem.
+  spec.add_development_dependency "elasticgraph-graphql", eg_version
+
+  # Necessary since `ScalarType` references indexing preparer defined in the `elasticgraph-indexer` gem.
+  spec.add_development_dependency "elasticgraph-indexer", eg_version
+end

data/lib/elastic_graph/schema_artifacts/artifacts_helper_methods.rb

@@ -0,0 +1,34 @@
+# Copyright 2024 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
+
+module ElasticGraph
+  module SchemaArtifacts
+    # Mixin that offers convenient helper methods on top of the basic schema artifacts.
+    # Intended to be mixed into every implementation of the `_SchemaArtifacts` interface.
+    module ArtifactsHelperMethods
+      def datastore_scripts
+        datastore_config.fetch("scripts")
+      end
+
+      def index_templates
+        datastore_config.fetch("index_templates")
+      end
+
+      def indices
+        datastore_config.fetch("indices")
+      end
+
+      # Builds a map of index mappings, keyed by index definition name.
+      def index_mappings_by_index_def_name
+        @index_mappings_by_index_def_name ||= index_templates
+          .transform_values { |config| config.fetch("template").fetch("mappings") }
+          .merge(indices.transform_values { |config| config.fetch("mappings") })
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/from_disk.rb

@@ -0,0 +1,112 @@
+# Copyright 2024 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 "elastic_graph/constants"
+require "elastic_graph/error"
+require "elastic_graph/schema_artifacts/artifacts_helper_methods"
+require "elastic_graph/schema_artifacts/runtime_metadata/schema"
+require "elastic_graph/support/hash_util"
+require "elastic_graph/support/memoizable_data"
+require "yaml"
+
+module ElasticGraph
+  module SchemaArtifacts
+    # Builds a `SchemaArtifacts::FromDisk` instance using the provided YAML settings.
+    def self.from_parsed_yaml(parsed_yaml, for_context:)
+      schema_artifacts = parsed_yaml.fetch("schema_artifacts") do
+        raise ConfigError, "Config is missing required key `schema_artifacts`."
+      end
+
+      if (extra_keys = schema_artifacts.keys - ["directory"]).any?
+        raise ConfigError, "Config has extra `schema_artifacts` keys: #{extra_keys}"
+      end
+
+      directory = schema_artifacts.fetch("directory") do
+        raise ConfigError, "Config is missing required key `schema_artifacts.directory`."
+      end
+
+      FromDisk.new(directory, for_context)
+    end
+
+    # Responsible for loading schema artifacts from disk.
+    class FromDisk < Support::MemoizableData.define(:artifacts_dir, :context)
+      include ArtifactsHelperMethods
+
+      def graphql_schema_string
+        @graphql_schema_string ||= read_artifact(GRAPHQL_SCHEMA_FILE)
+      end
+
+      def json_schemas_for(version)
+        unless available_json_schema_versions.include?(version)
+          raise MissingSchemaArtifactError, "The requested json schema version (#{version}) is not available. " \
+            "Available versions: #{available_json_schema_versions.sort.join(", ")}."
+        end
+
+        json_schemas_by_version[version]
+      end
+
+      def available_json_schema_versions
+        @available_json_schema_versions ||= begin
+          versioned_json_schemas_dir = ::File.join(artifacts_dir, JSON_SCHEMAS_BY_VERSION_DIRECTORY)
+          if ::Dir.exist?(versioned_json_schemas_dir)
+            ::Dir.entries(versioned_json_schemas_dir).filter_map { |it| it[/v(\d+)\.yaml/, 1]&.to_i }.to_set
+          else
+            ::Set.new
+          end
+        end
+      end
+
+      def latest_json_schema_version
+        @latest_json_schema_version ||= available_json_schema_versions.max || raise(
+          MissingSchemaArtifactError,
+          "The directory for versioned JSON schemas (#{::File.join(artifacts_dir, JSON_SCHEMAS_BY_VERSION_DIRECTORY)}) could not be found. " \
+          "Either the schema artifacts haven't been dumped yet or the schema artifacts directory (#{artifacts_dir}) is misconfigured."
+        )
+      end
+
+      def datastore_config
+        @datastore_config ||= _ = parsed_yaml_from(DATASTORE_CONFIG_FILE)
+      end
+
+      def runtime_metadata
+        @runtime_metadata ||= RuntimeMetadata::Schema.from_hash(
+          parsed_yaml_from(RUNTIME_METADATA_FILE),
+          for_context: context
+        )
+      end
+
+      private
+
+      def read_artifact(artifact_name)
+        file_name = ::File.join(artifacts_dir, artifact_name)
+
+        if ::File.exist?(file_name)
+          ::File.read(file_name)
+        else
+          raise MissingSchemaArtifactError, "Schema artifact `#{artifact_name}` could not be found. " \
+            "Either the schema artifacts haven't been dumped yet or the schema artifacts directory (#{artifacts_dir}) is misconfigured."
+        end
+      end
+
+      def parsed_yaml_from(artifact_name)
+        ::YAML.safe_load(read_artifact(artifact_name))
+      end
+
+      def json_schemas_by_version
+        @json_schemas_by_version ||= ::Hash.new do |hash, json_schema_version|
+          hash[json_schema_version] = load_json_schema(json_schema_version)
+        end
+      end
+
+      # Loads the given JSON schema version from disk.
+      def load_json_schema(json_schema_version)
+        parsed_yaml_from(::File.join(JSON_SCHEMAS_BY_VERSION_DIRECTORY, "v#{json_schema_version}.yaml"))
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/computation_detail.rb

@@ -0,0 +1,34 @@
+# Copyright 2024 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
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      # Details about our aggregation functions.
+      class ComputationDetail < ::Data.define(:empty_bucket_value, :function)
+        FUNCTION = "function"
+        EMPTY_BUCKET_VALUE = "empty_bucket_value"
+
+        def self.from_hash(hash)
+          new(
+            empty_bucket_value: hash[EMPTY_BUCKET_VALUE],
+            function: hash.fetch(FUNCTION).to_sym
+          )
+        end
+
+        def to_dumpable_hash
+          {
+            # Keys here are ordered alphabetically; please keep them that way.
+            EMPTY_BUCKET_VALUE => empty_bucket_value,
+            FUNCTION => function.to_s
+          }
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/enum.rb

@@ -0,0 +1,65 @@
+# Copyright 2024 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 "elastic_graph/schema_artifacts/runtime_metadata/hash_dumper"
+require "elastic_graph/schema_artifacts/runtime_metadata/sort_field"
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      module Enum
+        # Runtime metadata related to an ElasticGraph enum type.
+        class Type < ::Data.define(:values_by_name)
+          VALUES_BY_NAME = "values_by_name"
+
+          def self.from_hash(hash)
+            values_by_name = hash[VALUES_BY_NAME]&.transform_values do |value_hash|
+              Value.from_hash(value_hash)
+            end || {}
+
+            new(values_by_name: values_by_name)
+          end
+
+          def to_dumpable_hash
+            {
+              # Keys here are ordered alphabetically; please keep them that way.
+              VALUES_BY_NAME => HashDumper.dump_hash(values_by_name, &:to_dumpable_hash)
+            }
+          end
+        end
+
+        # Runtime metadata related to an ElasticGraph enum value.
+        class Value < ::Data.define(:sort_field, :datastore_value, :datastore_abbreviation, :alternate_original_name)
+          DATASTORE_VALUE = "datastore_value"
+          DATASTORE_ABBREVIATION = "datastore_abbreviation"
+          SORT_FIELD = "sort_field"
+          ALTERNATE_ORIGINAL_NAME = "alternate_original_name"
+
+          def self.from_hash(hash)
+            new(
+              sort_field: hash[SORT_FIELD]&.then { |h| SortField.from_hash(h) },
+              datastore_value: hash[DATASTORE_VALUE],
+              datastore_abbreviation: hash[DATASTORE_ABBREVIATION]&.to_sym,
+              alternate_original_name: hash[ALTERNATE_ORIGINAL_NAME]
+            )
+          end
+
+          def to_dumpable_hash
+            {
+              # Keys here are ordered alphabetically; please keep them that way.
+              DATASTORE_ABBREVIATION => datastore_abbreviation&.to_s,
+              DATASTORE_VALUE => datastore_value,
+              ALTERNATE_ORIGINAL_NAME => alternate_original_name,
+              SORT_FIELD => sort_field&.to_dumpable_hash
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/extension.rb

@@ -0,0 +1,51 @@
+# Copyright 2024 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 "elastic_graph/support/hash_util"
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      # Represents an extension--a class or module (potentially from outside the ElasticGraph
+      # code base) that implements a standard interface to plug in custom functionality.
+      #
+      # Extensions are serialized using two fields:
+      # - `extension_name`: the Ruby constant of the extension
+      # - `require_path`: file path to `require` to load the extension
+      #
+      # However, an `Extension` instance represents a loaded, resolved extension.
+      # We eagerly load extensions (and validate them in the `ExtensionLoader`) in
+      # order to surface any issues with the extension as soon as possible. We don't
+      # want to defer errors if we can detect any issues with the extension at boot time.
+      Extension = ::Data.define(:extension_class, :require_path, :extension_config) do
+        # @implements Extension
+
+        # Loads an extension using a serialized hash, via the provided `ExtensionLoader`.
+        def self.load_from_hash(hash, via:)
+          config = Support::HashUtil.symbolize_keys(hash["extension_config"] || {}) # : ::Hash[::Symbol, untyped]
+          via.load(hash.fetch("extension_name"), from: hash.fetch("require_path"), config: config)
+        end
+
+        # The name of the extension (based on the name of the extension class).
+        def extension_name
+          extension_class.name.to_s
+        end
+
+        # The serialized form of an extension.
+        def to_dumpable_hash
+          # Keys here are ordered alphabetically; please keep them that way.
+          {
+            "extension_config" => Support::HashUtil.stringify_keys(extension_config),
+            "extension_name" => extension_name,
+            "require_path" => require_path
+          }.reject { |_, v| v.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/extension_loader.rb

@@ -0,0 +1,125 @@
+# Copyright 2024 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 "elastic_graph/error"
+require "elastic_graph/schema_artifacts/runtime_metadata/extension"
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      # Responsible for loading extensions. This loader requires an interface definition
+      # (a class or module with empty method definitions that just serves to define what
+      # loaded extensions must implement). That allows us to verify the extension implements
+      # the interface correctly at load time, rather than deferring exceptions to when the
+      # extension is later used.
+      #
+      # Note, however, that this does not guarantee no runtime exceptions from the use of the
+      # extension: the extension may return invalid return values, or throw exceptions when
+      # called. But this verifies the interface to the extent that we can.
+      class ExtensionLoader
+        def initialize(interface_def)
+          @interface_def = interface_def
+          @loaded_by_name = {}
+        end
+
+        # Loads the extension using the provided constant name, after requiring the `from` path.
+        # Memoizes the result.
+        def load(constant_name, from:, config:)
+          (@loaded_by_name[constant_name] ||= load_extension(constant_name, from)).tap do |extension|
+            if extension.require_path != from
+              raise InvalidExtensionError, "Extension `#{constant_name}` cannot be loaded from `#{from}`, " \
+                "since it has already been loaded from `#{extension.require_path}`."
+            end
+          end.with(extension_config: config)
+        end
+
+        private
+
+        def load_extension(constant_name, require_path)
+          require require_path
+          extension_class = ::Object.const_get(constant_name).tap { |ext| verify_interface(constant_name, ext) }
+          Extension.new(extension_class, require_path, {})
+        end
+
+        def verify_interface(constant_name, extension)
+          # @type var problems: ::Array[::String]
+          problems = []
+          problems.concat(verify_methods("class", extension.singleton_class, @interface_def.singleton_class))
+
+          if extension.is_a?(::Module)
+            problems.concat(verify_methods("instance", extension, @interface_def))
+
+            # We care about the name exactly matching so that we can dump the extension name in a schema
+            # artifact w/o having to pass around the original constant name.
+            if extension.name != constant_name.delete_prefix("::")
+              problems << "- Exposes a name (`#{extension.name}`) that differs from the provided extension name (`#{constant_name}`)"
+            end
+          else
+            problems << "- Is not a class or module as expected"
+          end
+
+          if problems.any?
+            raise InvalidExtensionError,
+              "Extension `#{constant_name}` does not implement the expected interface correctly. Problems:\n\n" \
+              "#{problems.join("\n")}"
+          end
+        end
+
+        def verify_methods(type, extension, interface)
+          interface_methods = list_instance_interface_methods(interface)
+          extension_methods = list_instance_interface_methods(extension)
+
+          # @type var problems: ::Array[::String]
+          problems = []
+
+          if (missing_methods = interface_methods - extension_methods).any?
+            problems << "- Missing #{type} methods: #{missing_methods.map { |m| "`#{m}`" }.join(", ")}"
+          end
+
+          interface_methods.intersection(extension_methods).each do |method_name|
+            unless parameters_match?(extension, interface, method_name)
+              interface_signature = signature_code_for(interface, method_name)
+              extension_signature = signature_code_for(extension, method_name)
+
+              problems << "- Method signature for #{type} method `#{method_name}` (`#{extension_signature}`) does not match interface (`#{interface_signature}`)"
+            end
+          end
+
+          problems
+        end
+
+        def list_instance_interface_methods(klass)
+          # Here we look at more than just the public methods. This is necessary for `initialize`.
+          # If it's defined on the interface definition, we want to verify it on the extension,
+          # but Ruby makes `initialize` private by default.
+          klass.instance_methods(false) +
+            klass.protected_instance_methods(false) +
+            klass.private_instance_methods(false)
+        end
+
+        def parameters_match?(extension, interface, method_name)
+          interface_parameters = interface.instance_method(method_name).parameters
+          extension_parameters = extension.instance_method(method_name).parameters
+
+          # Here we compare the parameters for exact equality. This is stricter than we need it
+          # to be (it doesn't allow the parameters to have different names, for example) but it's
+          # considerably simpler than us trying to determine what is truly required. For example,
+          # the name doesn't matter on a positional arg, but would matter on a keyword arg.
+          interface_parameters == extension_parameters
+        end
+
+        def signature_code_for(object, method_name)
+          # @type var file_name: ::String?
+          # @type var line_number: ::Integer?
+          file_name, line_number = object.instance_method(method_name).source_location
+          ::File.read(file_name.to_s).split("\n")[line_number.to_i - 1].strip
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/graphql_field.rb

@@ -0,0 +1,54 @@
+# Copyright 2024 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 "elastic_graph/schema_artifacts/runtime_metadata/computation_detail"
+require "elastic_graph/schema_artifacts/runtime_metadata/relation"
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      class GraphQLField < ::Data.define(:name_in_index, :relation, :computation_detail)
+        EMPTY = new(nil, nil, nil)
+        NAME_IN_INDEX = "name_in_index"
+        RELATION = "relation"
+        AGGREGATION_DETAIL = "computation_detail"
+
+        def self.from_hash(hash)
+          new(
+            name_in_index: hash[NAME_IN_INDEX],
+            relation: hash[RELATION]&.then { |rel_hash| Relation.from_hash(rel_hash) },
+            computation_detail: hash[AGGREGATION_DETAIL]&.then { |agg_hash| ComputationDetail.from_hash(agg_hash) }
+          )
+        end
+
+        def to_dumpable_hash
+          {
+            # Keys here are ordered alphabetically; please keep them that way.
+            AGGREGATION_DETAIL => computation_detail&.to_dumpable_hash,
+            NAME_IN_INDEX => name_in_index,
+            RELATION => relation&.to_dumpable_hash
+          }
+        end
+
+        # Indicates if we need this field in our dumped runtime metadata, when it has the given
+        # `name_in_graphql`. Fields that have not been customized in some way do not need to be
+        # included in the dumped runtime metadata.
+        def needed?(name_in_graphql)
+          !!relation || !!computation_detail || name_in_index&.!=(name_in_graphql) || false
+        end
+
+        def with_computation_detail(empty_bucket_value:, function:)
+          with(computation_detail: ComputationDetail.new(
+            empty_bucket_value: empty_bucket_value,
+            function: function
+          ))
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/hash_dumper.rb

@@ -0,0 +1,21 @@
+# Copyright 2024 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
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      module HashDumper
+        def self.dump_hash(hash)
+          hash.sort_by(&:first).to_h do |key, value|
+            [key, yield(value)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/index_definition.rb

@@ -0,0 +1,78 @@
+# Copyright 2024 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 "elastic_graph/schema_artifacts/runtime_metadata/hash_dumper"
+require "elastic_graph/schema_artifacts/runtime_metadata/index_field"
+require "elastic_graph/schema_artifacts/runtime_metadata/sort_field"
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      # Runtime metadata related to a datastore index definition.
+      class IndexDefinition < ::Data.define(:route_with, :rollover, :default_sort_fields, :current_sources, :fields_by_path)
+        ROUTE_WITH = "route_with"
+        ROLLOVER = "rollover"
+        DEFAULT_SORT_FIELDS = "default_sort_fields"
+        CURRENT_SOURCES = "current_sources"
+        FIELDS_BY_PATH = "fields_by_path"
+
+        def initialize(route_with:, rollover:, default_sort_fields:, current_sources:, fields_by_path:)
+          super(
+            route_with: route_with,
+            rollover: rollover,
+            default_sort_fields: default_sort_fields,
+            current_sources: current_sources.to_set,
+            fields_by_path: fields_by_path
+          )
+        end
+
+        def self.from_hash(hash)
+          new(
+            route_with: hash[ROUTE_WITH],
+            rollover: hash[ROLLOVER]&.then { |h| Rollover.from_hash(h) },
+            default_sort_fields: hash[DEFAULT_SORT_FIELDS]&.map { |h| SortField.from_hash(h) } || [],
+            current_sources: hash[CURRENT_SOURCES] || [],
+            fields_by_path: (hash[FIELDS_BY_PATH] || {}).transform_values { |h| IndexField.from_hash(h) }
+          )
+        end
+
+        def to_dumpable_hash
+          {
+            # Keys here are ordered alphabetically; please keep them that way.
+            CURRENT_SOURCES => current_sources.sort,
+            DEFAULT_SORT_FIELDS => default_sort_fields.map(&:to_dumpable_hash),
+            FIELDS_BY_PATH => HashDumper.dump_hash(fields_by_path, &:to_dumpable_hash),
+            ROLLOVER => rollover&.to_dumpable_hash,
+            ROUTE_WITH => route_with
+          }
+        end
+
+        class Rollover < ::Data.define(:frequency, :timestamp_field_path)
+          FREQUENCY = "frequency"
+          TIMESTAMP_FIELD_PATH = "timestamp_field_path"
+
+          # @implements Rollover
+          def self.from_hash(hash)
+            new(
+              frequency: hash.fetch(FREQUENCY).to_sym,
+              timestamp_field_path: hash[TIMESTAMP_FIELD_PATH]
+            )
+          end
+
+          def to_dumpable_hash
+            {
+              # Keys here are ordered alphabetically; please keep them that way.
+              FREQUENCY => frequency.to_s,
+              TIMESTAMP_FIELD_PATH => timestamp_field_path
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_artifacts/runtime_metadata/index_field.rb

@@ -0,0 +1,33 @@
+# Copyright 2024 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 "elastic_graph/constants"
+
+module ElasticGraph
+  module SchemaArtifacts
+    module RuntimeMetadata
+      # Runtime metadata related to a field on a datastore index definition.
+      class IndexField < ::Data.define(:source)
+        SOURCE = "source"
+
+        def self.from_hash(hash)
+          new(
+            source: hash[SOURCE] || SELF_RELATIONSHIP_NAME
+          )
+        end
+
+        def to_dumpable_hash
+          {
+            # Keys here are ordered alphabetically; please keep them that way.
+            SOURCE => source
+          }
+        end
+      end
+    end
+  end
+end