elasticgraph-graphql 0.18.0.0

data/lib/elastic_graph/graphql/schema/enum_value.rb

@@ -0,0 +1,30 @@
+# 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"
+
+module ElasticGraph
+  class GraphQL
+    class Schema
+      # Represents an enum value within a GraphQL schema.
+      class EnumValue < ::Data.define(:name, :type, :runtime_metadata)
+        def sort_clauses
+          sort_clause = runtime_metadata&.sort_field&.then { |sf| {sf.field_path => {"order" => sf.direction.to_s}} } ||
+            raise(SchemaError, "Runtime metadata provides no `sort_field` for #{type.name}.#{name} enum value.")
+
+          [sort_clause]
+        end
+
+        def to_s
+          "#<#{self.class.name} #{type.name}.#{name}>"
+        end
+        alias_method :inspect, :to_s
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/schema/field.rb

@@ -0,0 +1,147 @@
+# 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/graphql/schema/relation_join"
+require "elastic_graph/graphql/schema/arguments"
+
+module ElasticGraph
+  class GraphQL
+    class Schema
+      # Represents a field within a GraphQL type.
+      class Field
+        # The type in which the field resides.
+        attr_reader :parent_type
+
+        attr_reader :schema, :schema_element_names, :graphql_field, :name_in_index, :relation, :computation_detail
+
+        def initialize(schema, parent_type, graphql_field, runtime_metadata)
+          @schema = schema
+          @schema_element_names = schema.element_names
+          @parent_type = parent_type
+          @graphql_field = graphql_field
+          @relation = runtime_metadata&.relation
+          @computation_detail = runtime_metadata&.computation_detail
+          @name_in_index = runtime_metadata&.name_in_index&.to_sym || name
+
+          # Adds the :extras required by ElasticGraph. For now, this blindly adds `:lookahead`
+          # to each field so that we have access to what the child selections are, as described here:
+          #
+          # https://graphql-ruby.org/queries/lookahead
+          #
+          # Currently we only need this when building an `DatastoreQuery` (which is not done for all
+          # fields) so a future optimization may only add this to fields where we actually need it.
+          # For now we add it to all fields because it's simplest and it's not clear if there is
+          # any performance benefit to not adding it when we do not use it.
+          #
+          # Note: input fields do not respond to `extras`, which is why we do it conditionally here.
+          #
+          # Note: on GraphQL gem introspection types (e.g. `__Field`), the fields respond to `:extras`,
+          # but that later causes a weird error (`ArgumentError: unknown keyword: :lookahead`)
+          # when those types are accessed in a Query. We don't really want to mutate the fields on the
+          # built-in types by adding `:lookahead` so it's best to avoid setting that extra on the built
+          # in types.
+          if @graphql_field.respond_to?(:extras) && !BUILT_IN_TYPE_NAMES.include?(parent_type.name.to_s)
+            @graphql_field.extras([:lookahead])
+          end
+        end
+
+        def type
+          @type ||= @schema.type_from(@graphql_field.type)
+        end
+
+        def name
+          @name ||= @graphql_field.name.to_sym
+        end
+
+        # Returns an object that knows how this field joins to its relation.
+        # Used by ElasticGraph::Resolvers::NestedRelationships.
+        def relation_join
+          # Not every field has a join relation, so it can be nil. But we do not want
+          # to re-compute that on every call, so we return @relation_join if it's already
+          # defined rather than if its truthy.
+          return @relation_join if defined?(@relation_join)
+          @relation_join = RelationJoin.from(self)
+        end
+
+        # Given an array of sort enums, returns an array of datastore compatible sort clauses
+        def sort_clauses_for(sorts)
+          Array(sorts).flat_map { |sort| sort_argument_type.enum_value_named(sort).sort_clauses }
+        end
+
+        # Indicates if this is an aggregated field (used inside an `Aggregation` type).
+        def aggregated?
+          type.unwrap_non_null.elasticgraph_category == :scalar_aggregated_values
+        end
+
+        def args_to_schema_form(args)
+          Arguments.to_schema_form(args, @graphql_field)
+        end
+
+        # Returns a list of field names that are required from the datastore in order
+        # to resolve this field at GraphQL query handling time.
+        def index_field_names_for_resolution
+          # For an embedded object, we do not require any fields because it is the nested fields
+          # that we will request from the datastore, which will be required to resolve them. But
+          # we do not need to request the embedded object field itself.
+          return [] if type.embedded_object?
+          return [] if parent_type.relay_connection? || parent_type.relay_edge?
+          return index_id_field_names_for_relation if relation_join
+
+          [name_in_index.to_s]
+        end
+
+        # Indicates this field should be hidden in the GraphQL schema so as to not be queryable.
+        # We only hide a field if resolving it would require using a datastore cluster that
+        # we can't access. For the most part, this just delegates to `Type#hidden_from_queries?`
+        # which does the index accessibility check.
+        def hidden_from_queries?
+          # The type has logic to check if the backing datastore index is accessible, so we just
+          # delegate to that logic here.
+          type.unwrap_fully.hidden_from_queries?
+        end
+
+        def coerce_result(result)
+          return result unless parent_type.graphql_only_return_type
+          type.coerce_result(result)
+        end
+
+        def description
+          "#{@parent_type.name}.#{name}"
+        end
+
+        def to_s
+          "#<#{self.class.name} #{description}>"
+        end
+        alias_method :inspect, :to_s
+
+        private
+
+        # Returns the `order_by` arguments type field (unwrapped)
+        def sort_argument_type
+          @sort_argument_type ||= begin
+            graphql_argument = @graphql_field.arguments.fetch(schema_element_names.order_by) do
+              raise SchemaError, "`#{schema_element_names.order_by}` argument not defined for field `#{parent_type.name}.#{name}`."
+            end
+            @schema.type_from(graphql_argument.type.unwrap)
+          end
+        end
+
+        def index_id_field_names_for_relation
+          if type.unwrap_fully == parent_type # means its a self-referential relation (e.g. child to parent of same type)
+            # Since it's self-referential, the `filter_id_field` (which lives on the "remote" type) also must
+            # exist as a field in our DatastoreCore::IndexDefinition.
+            [relation_join.document_id_field_name, relation_join.filter_id_field_name]
+          else
+            [relation_join.document_id_field_name]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/schema/relation_join.rb

@@ -0,0 +1,103 @@
+# 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/graphql/datastore_response/search_response"
+
+module ElasticGraph
+  class GraphQL
+    class Schema
+      # Represents the join between documents for a relation.
+      #
+      # Note that this class assumes a valid, well-formed schema definition, and makes no
+      # attempt to provide user-friendly errors when that is not the case. For example,
+      # we assume that a nested relationship field has at most one relationship directive.
+      # The (as yet unwritten) schema linter should validate such things eventually.
+      # When we do encounter errors at runtime (such as getting a scalar where we expect
+      # a list, or vice-versa), this class attempts to deal with as best as it can (sometimes
+      # simply picking one record or id from many!) and logs a warning.
+      #
+      # Note: this class isn't driven directly by tests. It exist purely to serve the needs
+      # of ElasticGraph::Resolvers::NestedRelationships, and is driven by that class's tests.
+      # It lives here because it's useful to expose it off of a `Field` since it's a property
+      # of the field and that lets us memoize it on the field itself.
+      class RelationJoin < ::Data.define(:field, :document_id_field_name, :filter_id_field_name, :id_cardinality, :doc_cardinality, :additional_filter, :foreign_key_nested_paths)
+        def self.from(field)
+          return nil if (relation = field.relation).nil?
+
+          doc_cardinality = field.type.collection? ? Cardinality::Many : Cardinality::One
+
+          if relation.direction == :in
+            # An inbound foreign key has some field (such as `foo_id`) on another document that points
+            # back to the `id` field on the document with the relation.
+            #
+            # The cardinality of the document id field on an inbound relation is always 1 since
+            # it is always the primary key `id` field.
+            new(field, "id", relation.foreign_key, Cardinality::One, doc_cardinality, relation.additional_filter, relation.foreign_key_nested_paths)
+          else
+            # An outbound foreign key has some field (such as `foo_id`) on the document with the relation
+            # that point out to the `id` field of another document.
+            new(field, relation.foreign_key, "id", doc_cardinality, doc_cardinality, relation.additional_filter, relation.foreign_key_nested_paths)
+          end
+        end
+
+        def blank_value
+          doc_cardinality.blank_value
+        end
+
+        # Extracts a single id or a list of ids from the given document, as required by the relation.
+        def extract_id_or_ids_from(document, log_warning)
+          id_or_ids = document.fetch(document_id_field_name) do
+            log_warning.call(document: document, problem: "#{document_id_field_name} is missing from the document")
+            blank_value
+          end
+
+          normalize_ids(id_or_ids) do |problem|
+            log_warning.call(document: document, problem: "#{document_id_field_name}: #{problem}")
+          end
+        end
+
+        # Normalizes the given documents, ensuring it has the expected cardinality.
+        def normalize_documents(response, &handle_warning)
+          doc_cardinality.normalize(response, handle_warning: handle_warning, &:id)
+        end
+
+        private
+
+        def normalize_ids(id_or_ids, &handle_warning)
+          id_cardinality.normalize(id_or_ids, handle_warning: handle_warning, &:itself)
+        end
+
+        module Cardinality
+          module Many
+            def self.normalize(list_or_scalar, handle_warning:)
+              return list_or_scalar if list_or_scalar.is_a?(Enumerable)
+              handle_warning.call("scalar instead of a list")
+              Array(list_or_scalar)
+            end
+
+            def self.blank_value
+              DatastoreResponse::SearchResponse::EMPTY
+            end
+          end
+
+          module One
+            def self.normalize(list_or_scalar, handle_warning:, &deterministic_comparator)
+              return list_or_scalar unless list_or_scalar.is_a?(Enumerable)
+              handle_warning.call("list of more than one item instead of a scalar") if list_or_scalar.size > 1
+              list_or_scalar.min_by(&deterministic_comparator)
+            end
+
+            def self.blank_value
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/schema/type.rb

@@ -0,0 +1,263 @@
+# 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/datastore_core/index_definition"
+require "elastic_graph/error"
+require "elastic_graph/graphql/schema/field"
+require "elastic_graph/graphql/schema/enum_value"
+require "forwardable"
+
+module ElasticGraph
+  class GraphQL
+    class Schema
+      # Represents a GraphQL type.
+      class Type
+        attr_reader :graphql_type, :fields_by_name, :index_definitions, :elasticgraph_category, :graphql_only_return_type
+
+        def initialize(
+          schema,
+          graphql_type,
+          index_definitions,
+          object_runtime_metadata,
+          enum_runtime_metadata
+        )
+          @schema = schema
+          @graphql_type = graphql_type
+          @enum_values_by_name = Hash.new do |hash, key|
+            hash[key] = lookup_enum_value_by_name(key)
+          end
+
+          @index_definitions = index_definitions
+          @object_runtime_metadata = object_runtime_metadata
+          @elasticgraph_category = object_runtime_metadata&.elasticgraph_category
+          @graphql_only_return_type = object_runtime_metadata&.graphql_only_return_type
+          @enum_runtime_metadata = enum_runtime_metadata
+          @enum_value_names_by_original_name = (enum_runtime_metadata&.values_by_name || {}).to_h do |name, value|
+            [value.alternate_original_name || name, name]
+          end
+
+          @fields_by_name = build_fields_by_name_hash(schema, graphql_type).freeze
+        end
+
+        def name
+          @name ||= @graphql_type.to_type_signature.to_sym
+        end
+
+        # List of index definitions that should be searched for this type.
+        def search_index_definitions
+          @search_index_definitions ||=
+            if indexed_aggregation?
+              # For an indexed aggregation, we just delegate to its source type. This works better than
+              # dumping index definitions in the runtime metadata of the indexed aggregation type itself
+              # because of abstract (interface/union) types. The source document type handles that (since
+              # there is a supertype/subtype relationship on the document types) but that relationship
+              # does not exist on the indexed aggregation.
+              #
+              # For example, assume we have these indexed document types:
+              # - type Person {}
+              # - type Company {}
+              # - union Inventor = Person | Company
+              #
+              # We can go from `Inventor` to its subtypes to find the search indexes. However, `InventorAggregation`
+              # is NOT a union of `PersonAggregation` and `CompanyAggregation`, so we can't do the same thing on the
+              # indexed aggregation types. Delegating to the source type solves this case.
+              @schema.type_named(@object_runtime_metadata.source_type).search_index_definitions
+            else
+              @index_definitions.union(subtypes.flat_map(&:search_index_definitions))
+            end
+        end
+
+        # List of index definitions that should be indexed into for this type.
+        # For now this is just an alias for `search_index_definitions`, but
+        # in the future we expect to allow these to be different. We don't yet
+        # support defining multiple indices on one GraphQL type, though, which is
+        # where that would prove useful. Still, it's a useful abstraction to have
+        # this method available for callers now.
+        alias_method :indexing_index_definitions, :search_index_definitions
+
+        # Unwraps the non-null type wrapping, if this type is non-null. If this type is nullable,
+        # returns it as-is.
+        def unwrap_non_null
+          return self if nullable?
+          @schema.type_from(@graphql_type.of_type)
+        end
+
+        # Fully unwraps this type, in order to extracts the underlying type (an object or scalar)
+        # from its wrappings. As needed, this will unwrap any of these wrappings:
+        #
+        #   - non-null
+        #   - list
+        #   - relay connection
+        def unwrap_fully
+          @unwrap_fully ||= begin
+            unwrapped = @schema.type_from(@graphql_type.unwrap)
+
+            if unwrapped.relay_connection?
+              unwrapped
+                .field_named(@schema.element_names.edges).type.unwrap_fully
+                .field_named(@schema.element_names.node).type.unwrap_fully
+            else
+              unwrapped
+            end
+          end
+        end
+
+        # Returns the subtypes of this type, if it has any. This is like `#possible_types` provided by the
+        # GraphQL gem, but that includes a type itself when you ask for the possible types of a non-abstract type.
+        def subtypes
+          @subtypes ||= @schema.graphql_schema.possible_types(graphql_type).map { |t| @schema.type_from(t) } - [self]
+        end
+
+        def field_named(field_name)
+          @fields_by_name.fetch(field_name.to_s)
+        rescue KeyError => e
+          msg = "No field named #{field_name} (on type #{name}) could be found"
+          msg += "; Possible alternatives: [#{e.corrections.join(", ").delete('"')}]." if e.corrections.any?
+          raise NotFoundError, msg
+        end
+
+        def enum_value_named(enum_value_name)
+          @enum_values_by_name[enum_value_name.to_s]
+        end
+
+        def coerce_result(result)
+          @enum_value_names_by_original_name.fetch(result, result)
+        end
+
+        def to_s
+          "#<#{self.class.name} #{name}>"
+        end
+        alias_method :inspect, :to_s
+
+        # ********************************************************************************************
+        # Predicates
+        #
+        # Below here are a bunch of predicates that can be used to ask questions of a type. GraphQL's
+        # "wrapping" type system (e.g. non-null wraps nullable; lists wrap objects or scalars) adds
+        # some complexity and nuance here. We have decided to implement these predicates to auto-unwrap
+        # non-null (e.g. SomeType! -> SomeType). For example, `object?` will return `true` from both a
+        # nullable and non-nullable object type, because both are fundamentally objects. Importantly,
+        # we do not ever auto-unwrap a type from its list or relay connection wrapping; if the caller
+        # wants that, they can manually unwrap before calling the predicate.
+        #
+        # Note also that `non_null?` and `nullable?` are an exception: since they check nullability,
+        # we do not auto-unwrap non-null on them, naturally.
+        # ********************************************************************************************
+
+        extend Forwardable
+        def_delegators :@graphql_type, :list?, :non_null?
+
+        def nullable?
+          !non_null?
+        end
+
+        def abstract?
+          return unwrap_non_null.abstract? if non_null?
+          @graphql_type.kind.abstract?
+        end
+
+        def enum?
+          return unwrap_non_null.enum? if non_null?
+          @graphql_type.kind.enum?
+        end
+
+        # Returns `true` if this type serializes as a JSON object, with sub-fields.
+        # Note this is slightly different from the GraphQL gem and GraphQL spec: it considers
+        # inputs to be distinct from objects, but for our purposes we consider inputs to be
+        # objects since they have sub-fields and serialize as JSON objects.
+        def object?
+          return unwrap_non_null.object? if non_null?
+          kind = @graphql_type.kind
+          kind.abstract? || kind.object? || kind.input_object?
+        end
+
+        # Is the type a user-defined document type directly indexed in the index?
+        def indexed_document?
+          return unwrap_non_null.indexed_document? if non_null?
+          return false if indexed_aggregation?
+          return true if subtypes.any? && subtypes.all?(&:indexed_document?)
+          @index_definitions.any?
+        end
+
+        def indexed_aggregation?
+          unwrapped_has_category?(:indexed_aggregation)
+        end
+
+        # Indicates if this type is an object type that is embedded in another indexed type
+        # in the index mapping. Note: we have avoided the term `nested` here because it
+        # is a specific Elasticsearch/OpenSearch mapping type that we will not necessarily be using:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/nested.html
+        def embedded_object?
+          return unwrap_non_null.embedded_object? if non_null?
+          return false if relay_edge? || relay_connection? || @graphql_type.kind.input_object?
+          object? && !indexed_document? && !indexed_aggregation?
+        end
+
+        def collection?
+          list? || relay_connection?
+        end
+
+        def relay_connection?
+          unwrapped_has_category?(:relay_connection)
+        end
+
+        def relay_edge?
+          unwrapped_has_category?(:relay_edge)
+        end
+
+        # Indicates this type should be hidden in the GraphQL schema so as to not be queryable.
+        # We only hide a type if both of the following are true:
+        #
+        # - It's backed by one or more search index definitions
+        # - None of the search index definitions are accessible from queries
+        def hidden_from_queries?
+          return false if search_index_definitions.empty?
+          search_index_definitions.none?(&:accessible_from_queries?)
+        end
+
+        private
+
+        def lookup_enum_value_by_name(enum_value_name)
+          graphql_enum_value = @graphql_type.values.fetch(enum_value_name)
+
+          EnumValue.new(
+            name: graphql_enum_value.graphql_name.to_sym,
+            type: self,
+            runtime_metadata: @enum_runtime_metadata&.values_by_name&.dig(enum_value_name)
+          )
+        rescue KeyError => e
+          msg = "No enum value named #{enum_value_name} (on type #{name}) could be found"
+          msg += "; Possible alternatives: [#{e.corrections.join(", ").delete('"')}]." if e.corrections.any?
+          raise NotFoundError, msg
+        end
+
+        def build_fields_by_name_hash(schema, graphql_type)
+          fields_hash =
+            if graphql_type.respond_to?(:fields)
+              graphql_type.fields
+            elsif graphql_type.kind.input_object?
+              # Unfortunately, input objects do not have a `fields` method; instead it is called `arguments`.
+              graphql_type.arguments
+            else
+              {}
+            end
+
+          # Eagerly fan out and instantiate all `Field` objects so that the :extras
+          # get added to each field as require before we execute the first query
+          fields_hash.each_with_object({}) do |(name, field), hash|
+            hash[name] = Field.new(schema, self, field, @object_runtime_metadata&.graphql_fields_by_name&.dig(name))
+          end
+        end
+
+        def unwrapped_has_category?(category)
+          unwrap_non_null.elasticgraph_category == category
+        end
+      end
+    end
+  end
+end