elasticgraph-schema_definition 0.18.0.0

data/lib/elastic_graph/schema_definition/mixins/has_documentation.rb

@@ -0,0 +1,74 @@
+# 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 SchemaDefinition
+    module Mixins
+      # Supports GraphQL documentation.
+      module HasDocumentation
+        # @dynamic doc_comment, doc_comment=
+        # @!attribute doc_comment
+        # @return [String, nil] current documentation string for the schema element
+        attr_accessor :doc_comment
+
+        # Sets the documentation of the schema element.
+        #
+        # @param comment [String] the documentation string
+        # @return [void]
+        #
+        # @example Define documentation on an object type and on a field
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.documentation "A marketing campaign."
+        #
+        #       t.field "id", "ID" do |f|
+        #         f.documentation <<~EOS
+        #           The identifier of the campaign.
+        #
+        #           Note: this is randomly generated.
+        #         EOS
+        #       end
+        #     end
+        #   end
+        def documentation(comment)
+          self.doc_comment = comment
+        end
+
+        # Appends some additional documentation to the existing documentation string.
+        #
+        # @param comment [String] additional documentation
+        # @return [void]
+        def append_to_documentation(comment)
+          new_documentation = doc_comment ? "#{doc_comment}\n\n#{comment}" : comment
+          documentation(new_documentation)
+        end
+
+        # Formats the documentation using GraphQL SDL syntax.
+        #
+        # @return [String] formatted documentation string
+        def formatted_documentation
+          return nil unless (comment = doc_comment)
+          %("""\n#{comment.chomp}\n"""\n)
+        end
+
+        # Generates a documentation string that is derived from the schema elements existing documentation.
+        #
+        # @param intro [String] string that goes before the schema element's existing documentation
+        # @param outro [String, nil] string that goes after the schema element's existing documentation
+        # @return [String]
+        def derived_documentation(intro, outro = nil)
+          outro &&= "\n\n#{outro}."
+          return "#{intro}.#{outro}" unless doc_comment
+
+          quoted_doc = doc_comment.split("\n").map { |line| "> #{line}" }.join("\n")
+          "#{intro}:\n\n#{quoted_doc}#{outro}"
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/has_indices.rb

@@ -0,0 +1,281 @@
+# 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/schema_definition/indexing/update_target_factory"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # Provides APIs for defining datastore indices.
+      module HasIndices
+        # @dynamic runtime_metadata_overrides
+        # @private
+        attr_accessor :runtime_metadata_overrides
+
+        # @private
+        def initialize(*args, **options)
+          super(*args, **options)
+          self.runtime_metadata_overrides = {}
+          yield self
+
+          # Freeze `indices` so that the indexable status of a type does not change after instantiation.
+          # (That would cause problems.)
+          indices.freeze
+        end
+
+        # Converts the current type from being an _embedded_ type (that is, a type that is embedded within another indexed type) to an
+        # _indexed_ type that resides in the named index definition. Indexed types are directly indexed into the datastore, and will be
+        # queryable from the root `Query` type.
+        #
+        # @note Use {#root_query_fields} on indexed types to name the field that will be exposed on `Query`.
+        # @note Indexed types must also define an `id` field, which ElasticGraph will use as the primary key.
+        # @note Datastore index settings can also be defined (or overridden) in an environment-specific settings YAML file. Index settings
+        #   that you want to configure differently for different environments (such as `index.number_of_shards`—-production and staging
+        #   will probably need different numbers!) should be configured in the per-environment YAML configuration files rather than here.
+        #
+        # @param name [String] name of the index. See the [Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/indices-create-index.html#indices-create-api-path-params)
+        #   for restrictions.
+        # @param settings [Hash<Symbol, Object>] datastore index settings you want applied to every environment. See the [Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/index-modules.html#index-modules-settings)
+        #   for a list of valid settings, but be sure to omit the `index.` prefix here.
+        # @yield [Indexing::Index] the index, so it can be customized further
+        # @return [void]
+        #
+        # @example Define a `campaigns` index
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID"
+        #
+        #       t.index(
+        #         "campaigns",
+        #         # Configure `index.refresh_interval`.
+        #         refresh_interval: "1s",
+        #         # Use `index.search` to log warnings for any search query that take more than five seconds.
+        #         search: {slowlog: {level: "WARN", threshold: {query: {warn: "5s"}}}}
+        #       ) do |i|
+        #         # The index can be customized further here.
+        #       end
+        #     end
+        #   end
+        def index(name, **settings, &block)
+          indices.replace([Indexing::Index.new(name, settings, schema_def_state, self, &block)])
+        end
+
+        # List of indices. (Currently we only store one but we may support multiple in the future).
+        #
+        # @private
+        def indices
+          @indices ||= []
+        end
+
+        # @return [Boolean] true if this type has an index
+        def indexed?
+          indices.any?
+        end
+
+        # Abstract types are rare, so return false. This can be overridden in the host class.
+        #
+        # @private
+        def abstract?
+          false
+        end
+
+        # Configures the ElasticGraph indexer to derive another type from this indexed type, using the `from_id` field as
+        # the source of the `id` of the derived type, and the provided block for the definitions of the derived fields.
+        #
+        # @param name [String] name of the derived type
+        # @param from_id [String] path to the source type field with `id` values for the derived type
+        # @param route_with [String, nil] path to the source type field with values for shard routing on the derived type
+        # @param rollover_with [String, nil] path to the source type field with values for index rollover on the derived type
+        # @yield [Indexing::DerivedIndexedType] configuration object for field derivations
+        # @return [void]
+        #
+        # @example Derive a `Course` type from `StudentCourseEnrollment` events
+        #   ElasticGraph.define_schema do |schema|
+        #     # `StudentCourseEnrollment` is a directly indexed type.
+        #     schema.object_type "StudentCourseEnrollment" do |t|
+        #       t.field "id", "ID"
+        #       t.field "courseId", "ID"
+        #       t.field "courseName", "String"
+        #       t.field "studentName", "String"
+        #       t.field "courseStartDate", "Date"
+        #
+        #       t.index "student_course_enrollments"
+        #
+        #       # Here we define how the `Course` indexed type  is derived when we index `StudentCourseEnrollment` events.
+        #       t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+        #         # `derive` is an instance of `DerivedIndexedType`.
+        #         derive.immutable_value "name", from: "courseName"
+        #         derive.append_only_set "students", from: "studentName"
+        #         derive.min_value "firstOfferedDate", from: "courseStartDate"
+        #         derive.max_value "mostRecentlyOfferedDate", from: "courseStartDate"
+        #       end
+        #     end
+        #
+        #     # `Course` is an indexed type that is derived entirely from `StudentCourseEnrollment` events.
+        #     schema.object_type "Course" do |t|
+        #       t.field "id", "ID"
+        #       t.field "name", "String"
+        #       t.field "students", "[String!]!"
+        #       t.field "firstOfferedDate", "Date"
+        #       t.field "mostRecentlyOfferedDate", "Date"
+        #
+        #       t.index "courses"
+        #     end
+        #   end
+        def derive_indexed_type_fields(
+          name,
+          from_id:,
+          route_with: nil,
+          rollover_with: nil,
+          &block
+        )
+          Indexing::DerivedIndexedType.new(
+            source_type: self,
+            destination_type_ref: schema_def_state.type_ref(name).to_final_form,
+            id_source: from_id,
+            routing_value_source: route_with,
+            rollover_timestamp_value_source: rollover_with,
+            &block
+          ).tap { |dit| derived_indexed_types << dit }
+        end
+
+        # @return [Array<Indexing::DerivedIndexedType>] list of derived types for this source type
+        def derived_indexed_types
+          @derived_indexed_types ||= []
+        end
+
+        # @private
+        def runtime_metadata(extra_update_targets)
+          SchemaArtifacts::RuntimeMetadata::ObjectType.new(
+            update_targets: derived_indexed_types.map(&:runtime_metadata_for_source_type) + [self_update_target].compact + extra_update_targets,
+            index_definition_names: indices.map(&:name),
+            graphql_fields_by_name: runtime_metadata_graphql_fields_by_name,
+            elasticgraph_category: nil,
+            source_type: nil,
+            graphql_only_return_type: graphql_only?
+          ).with(**runtime_metadata_overrides)
+        end
+
+        # Determines what the root `Query` fields will be to query this indexed type. In addition, this method accepts a block, which you
+        # can use to customize the root query field (such as adding a GraphQL directive to it).
+        #
+        # @param plural [String] the plural name of the entity; used for the root `Query` field that queries documents of this indexed type
+        # @param singular [String, nil] the singular name of the entity; used for the root `Query` field (with an `Aggregations` suffix) that
+        #   queries aggregations of this indexed type. If not provided, will derive it from the type name (e.g. converting it to `camelCase`
+        #   or `snake_case`, depending on configuration).
+        # @yield [SchemaElements::Field] field on the root `Query` type used to query this indexed type, to support customization
+        # @return [void]
+        #
+        # @example Set `plural` and `singular` names
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Person" do |t|
+        #       t.field "id", "ID"
+        #
+        #       # Results in `Query.people` and `Query.personAggregations`.
+        #       t.root_query_fields plural: "people", singular: "person"
+        #
+        #       t.index "people"
+        #     end
+        #   end
+        #
+        # @example Customize `Query` fields
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Person" do |t|
+        #       t.field "id", "ID"
+        #
+        #       t.root_query_fields plural: "people", singular: "person" do |f|
+        #         # Marks `Query.people` and `Query.personAggregations` as deprecated.
+        #         f.directive "deprecated"
+        #       end
+        #
+        #       t.index "people"
+        #     end
+        #   end
+        def root_query_fields(plural:, singular: nil, &customization_block)
+          @plural_root_query_field_name = plural
+          @singular_root_query_field_name = singular
+          @root_query_fields_customizations = customization_block
+        end
+
+        # @return [String] the plural name of the entity; used for the root `Query` field that queries documents of this indexed type
+        def plural_root_query_field_name
+          @plural_root_query_field_name || naively_pluralize_type_name(name)
+        end
+
+        # @return [String] the singular name of the entity; used for the root `Query` field (with an `Aggregations` suffix) that queries
+        #   aggregations of this indexed type. If not provided, will derive it from the type name (e.g. converting it to `camelCase` or
+        #   `snake_case`, depending on configuration).
+        def singular_root_query_field_name
+          @singular_root_query_field_name || to_field_name(name)
+        end
+
+        # @private
+        def root_query_fields_customizations
+          @root_query_fields_customizations
+        end
+
+        # @private
+        def fields_with_sources
+          indexing_fields_by_name_in_index.values.reject { |f| f.source.nil? }
+        end
+
+        private
+
+        def self_update_target
+          return nil if abstract? || !indexed?
+
+          # We exclude `id` from `data_params` because `Indexer::Operator::Update` automatically includes
+          # `params.id` so we don't want it duplicated at `params.data.id` alongside other data params.
+          #
+          # In addition, we exclude fields that have an alternate `source` -- those fields will get populated
+          # by a different event and we don't want to risk "stomping" their value via this update target.
+          data_params = indexing_fields_by_name_in_index.select { |name, field| name != "id" && field.source.nil? }.to_h do |field|
+            [field, SchemaArtifacts::RuntimeMetadata::DynamicParam.new(source_path: field, cardinality: :one)]
+          end
+
+          index_runtime_metadata = indices.first.runtime_metadata
+
+          Indexing::UpdateTargetFactory.new_normal_indexing_update_target(
+            type: name,
+            relationship: SELF_RELATIONSHIP_NAME,
+            id_source: "id",
+            data_params: data_params,
+            # Some day we may want to consider supporting multiple indices. If/when we add support for that,
+            # we'll need to change the runtime metadata here to have a map of these values, keyed by index
+            # name.
+            routing_value_source: index_runtime_metadata.route_with,
+            rollover_timestamp_value_source: index_runtime_metadata.rollover&.timestamp_field_path
+          )
+        end
+
+        def runtime_metadata_graphql_fields_by_name
+          graphql_fields_by_name.transform_values(&:runtime_metadata_graphql_field)
+        end
+
+        # Provides a "best effort" conversion of a type name to the plural form.
+        # In practice, schema definers should set `root_query_field` on their
+        # indexed types so we don't have to try to convert the type to its plural
+        # form. Still, this has value, particularly given our existing tests
+        # (where I don't want to require that we set this).
+        #
+        # Note: we could pull in ActiveSupport to pluralize more accurately, but I
+        # really don't want to pull in any part of Rails just for that :(.
+        def naively_pluralize_type_name(type_name)
+          normalized = to_field_name(type_name)
+          normalized + (normalized.end_with?("s") ? "es" : "s")
+        end
+
+        def to_field_name(type_name)
+          name_without_leading_uppercase = type_name.sub(/^([[:upper:]])/) { $1.downcase }
+          schema_def_state.schema_elements.normalize_case(name_without_leading_uppercase)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect.rb

@@ -0,0 +1,46 @@
+# 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 SchemaDefinition
+    module Mixins
+      # Dynamic mixin that provides readable output from `#to_s` and `#inspect`. The default
+      # output Ruby prints for these methods is quite unwieldy for all our schema definition
+      # types, because we have a large interconnected object graph and `Struct` classes print
+      # all their state. In fact, before implementing this, we observed output of more than
+      # 5 million characters long!
+      #
+      # To use this module include a new instance of it:
+      #
+      #   include HasReadableToSAndInspect.new
+      #
+      # Optionally, provide a block that, given an instance of the class, returns a string description for
+      # inclusion in the output:
+      #
+      #   include HasReadableToSAndInspect.new { |obj| obj.name }
+      #
+      # @private
+      class HasReadableToSAndInspect < ::Module
+        def initialize
+          if block_given?
+            define_method :to_s do
+              "#<#{self.class.name} #{yield self}>"
+            end
+          else
+            # When no block is given, we just want to use the stock `Object#to_s`, which renders the memory address.
+            define_method :to_s do
+              ::Object.instance_method(:to_s).bind_call(self)
+            end
+          end
+
+          alias_method :inspect, :to_s
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/has_subtypes.rb

@@ -0,0 +1,116 @@
+# 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_definition/indexing/field_type/union"
+require "elastic_graph/schema_definition/schema_elements/list_counts_state"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # Provides common support for abstract GraphQL types that have subtypes (e.g. union and interface types).
+      #
+      # @private
+      module HasSubtypes
+        def to_indexing_field_type
+          subtypes_by_name = recursively_resolve_subtypes.to_h do |type|
+            [type.name, _ = type.to_indexing_field_type]
+          end
+
+          Indexing::FieldType::Union.new(subtypes_by_name)
+        end
+
+        def graphql_fields_by_name
+          merge_fields_by_name_from_subtypes(&:graphql_fields_by_name)
+        end
+
+        def indexing_fields_by_name_in_index
+          merge_fields_by_name_from_subtypes(&:indexing_fields_by_name_in_index)
+            .merge("__typename" => schema_def_state.factory.new_field(name: "__typename", type: "String", parent_type: _ = self))
+        end
+
+        def indexed?
+          super || subtypes_indexed?
+        end
+
+        def recursively_resolve_subtypes
+          resolve_subtypes.flat_map do |type|
+            type.is_a?(HasSubtypes) ? (_ = type).recursively_resolve_subtypes : [type]
+          end
+        end
+
+        def abstract?
+          true
+        end
+
+        def current_sources
+          resolve_subtypes.flat_map(&:current_sources)
+        end
+
+        def index_field_runtime_metadata_tuples(
+          path_prefix: "",
+          parent_source: SELF_RELATIONSHIP_NAME,
+          list_counts_state: SchemaElements::ListCountsState::INITIAL
+        )
+          resolve_subtypes.flat_map do |t|
+            t.index_field_runtime_metadata_tuples(
+              path_prefix: path_prefix,
+              parent_source: parent_source,
+              list_counts_state: list_counts_state
+            )
+          end
+        end
+
+        private
+
+        def merge_fields_by_name_from_subtypes
+          resolved_subtypes = resolve_subtypes
+
+          resolved_subtypes.reduce(_ = {}) do |fields_by_name, subtype|
+            fields_by_name.merge(yield subtype) do |field_name, def1, def2|
+              if (def1.name_in_index == def2.name_in_index && def1.resolve_mapping != def2.resolve_mapping) || (def1.type.unwrap_non_null != def2.type.unwrap_non_null)
+                def_strings = resolved_subtypes.each_with_object([]) do |st, defs|
+                  field = st.graphql_fields_by_name[field_name]
+                  defs << "on #{st.name}:\n#{field.to_sdl.strip} mapping: #{field.resolve_mapping.inspect}" if st.graphql_fields_by_name.key?(field_name)
+                end
+
+                raise SchemaError,
+                  "Conflicting definitions for field `#{field_name}` on the subtypes of `#{name}`. " \
+                  "Their definitions must agree. Defs:\n\n#{def_strings.join("\n\n")}"
+              end
+
+              def1
+            end
+          end
+        end
+
+        def subtypes_indexed?
+          indexed_by_subtype_name = resolve_subtypes.to_h do |subtype, acc|
+            [subtype.name, subtype.indexed?]
+          end
+
+          uniq_indexed = indexed_by_subtype_name.values.uniq
+
+          if uniq_indexed.size > 1
+            descriptions = indexed_by_subtype_name.map do |name_value|
+              name, value = name_value
+              "#{name}: indexed? = #{value}"
+            end
+
+            raise SchemaError,
+              "The #{self.class.name} #{name} has some indexed subtypes, and some non-indexed subtypes. " \
+              "All subtypes must be indexed or all must NOT be indexed. Subtypes:\n" \
+              "#{descriptions.join("\n")}"
+          end
+
+          !!uniq_indexed.first
+        end
+      end
+    end
+  end
+end