elasticgraph-graphql 0.18.0.0

data/lib/elastic_graph/graphql/resolvers/query_adapter.rb

@@ -0,0 +1,85 @@
+# 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
+  class GraphQL
+    module Resolvers
+      # Responsible for taking raw GraphQL query arguments and transforming
+      # them into a DatastoreQuery object.
+      class QueryAdapter
+        def initialize(datastore_query_builder:, datastore_query_adapters:)
+          @datastore_query_builder = datastore_query_builder
+          @datastore_query_adapters = datastore_query_adapters
+        end
+
+        def build_query_from(field:, args:, lookahead:, context: {})
+          monotonic_clock_deadline = context[:monotonic_clock_deadline]
+
+          # Building an `DatastoreQuery` is not cheap; we do a lot of work to:
+          #
+          # 1) Convert the `args` to their schema form.
+          # 2) Reduce over our different query builders into a final `Query` object
+          # 3) ...and those individual query builders often do a lot of work (traversing lookaheads, etc).
+          #
+          # So it is beneficial to avoid re-creating the exact same `DatastoreQuery` object when
+          # we are resolving the same field in the context of a different object. For example,
+          # consider a query like:
+          #
+          # query {
+          #   widgets {
+          #     components {
+          #       id
+          #       parts {
+          #         id
+          #       }
+          #     }
+          #   }
+          # }
+          #
+          # Here `components` and `parts` are nested relation fields. If we load 50 of each collection,
+          # this `build_query_from` method will be called 50 times for the `Widget.components` field,
+          # and 2500 times (50 * 50) for the `Component.parts` field...but for a given field, the
+          # built `DatastoreQuery` will be exactly the same.
+          #
+          # Therefore, it is beneficial to memoize the `DatastoreQuery` to avoid re-doing the same work
+          # over and over again, provided we can do so safely.
+          #
+          # `context` is a hash-like `GraphQL::Query::Context` object. Each executed query gets its own
+          # instance, so we can safely cache things in it and trust that it will not "leak" to another
+          # query execution. We carefully build a cache key below to ensure that we only ever reuse
+          # the same `DatastoreQuery` in a situation that would produce the exact same `DatastoreQuery`.
+          context[:datastore_query_cache] ||= {}
+          context[:datastore_query_cache][cache_key_for(field, args, lookahead)] ||=
+            build_new_query_from(field, args, lookahead, context, monotonic_clock_deadline)
+        end
+
+        private
+
+        def build_new_query_from(field, args, lookahead, context, monotonic_clock_deadline)
+          unwrapped_type = field.type.unwrap_fully
+
+          initial_query = @datastore_query_builder.new_query(
+            search_index_definitions: unwrapped_type.search_index_definitions,
+            monotonic_clock_deadline: monotonic_clock_deadline
+          )
+
+          @datastore_query_adapters.reduce(initial_query) do |query, adapter|
+            adapter.call(query: query, field: field, args: args, lookahead: lookahead, context: context)
+          end
+        end
+
+        def cache_key_for(field, args, lookahead)
+          # Unfortunately, `Lookahead` does not define `==` according to its internal state,
+          # so `l1 == l2` with the same internal state returns false. So we have to pull
+          # out its individual state fields in the cache key for our caching to work here.
+          [field, args, lookahead.ast_nodes, lookahead.field, lookahead.owner_type]
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/query_source.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
+
+require "graphql/dataloader/source"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # Provides a way to avoid N+1 query problems by batching up multiple
+      # datastore queries into one `msearch` call. In general, it is recommended
+      # that you use this from any resolver that needs to query the datastore, to
+      # maximize our ability to combine multiple datastore requests. Importantly,
+      # this should never be instantiated directly; instead use the `execute` method from below.
+      class QuerySource < ::GraphQL::Dataloader::Source
+        def initialize(datastore_router, query_tracker)
+          @datastore_router = datastore_router
+          @query_tracker = query_tracker
+        end
+
+        def fetch(queries)
+          responses_by_query = @datastore_router.msearch(queries, query_tracker: @query_tracker)
+          @query_tracker.record_datastore_queries_for_single_request(queries)
+          queries.map { |q| responses_by_query[q] }
+        end
+
+        def self.execute_many(queries, for_context:)
+          datastore_router = for_context.fetch(:datastore_search_router)
+          query_tracker = for_context.fetch(:elastic_graph_query_tracker)
+          dataloader = for_context.dataloader
+
+          responses = dataloader.with(self, datastore_router, query_tracker).load_all(queries)
+          queries.zip(responses).to_h
+        end
+
+        def self.execute_one(query, for_context:)
+          execute_many([query], for_context: for_context).fetch(query)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/relay_connection/array_adapter.rb

@@ -0,0 +1,71 @@
+# 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/resolvers/resolvable_value"
+require "forwardable"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      module RelayConnection
+        # Relay connection adapter for an array. Implemented primarily by `GraphQL::Relay::ArrayConnection`;
+        # here we just adapt it to the ElasticGraph internal resolver interface.
+        class ArrayAdapter < ResolvableValue.new(:graphql_impl)
+          # `ResolvableValue.new` provides the following methods:
+          # @dynamic initialize, graphql_impl, schema_element_names
+
+          # `def_delegators` provides the following methods:
+          # @dynamic start_cursor, end_cursor, has_next_page, has_previous_page
+          extend Forwardable
+          def_delegators :graphql_impl, :start_cursor, :end_cursor, :has_next_page, :has_previous_page
+
+          def self.build(nodes, args, schema_element_names, context)
+            # ElasticGraph supports any schema elements (like a `first` argument) being renamed,
+            # but `GraphQL::Relay::ArrayConnection` would not understand a renamed argument.
+            # Here we map the args back to the canonical relay args so `ArrayConnection` can
+            # understand them.
+            relay_args = [:first, :after, :last, :before].to_h do |arg_name|
+              [arg_name, args[schema_element_names.public_send(arg_name)]]
+            end.compact
+
+            graphql_impl = ::GraphQL::Pagination::ArrayConnection.new(nodes, context: context, **relay_args)
+            new(schema_element_names, graphql_impl)
+          end
+
+          def total_edge_count
+            graphql_impl.nodes.size
+          end
+
+          def page_info
+            self
+          end
+
+          def edges
+            @edges ||= graphql_impl.nodes.map do |node|
+              Edge.new(schema_element_names, graphql_impl, node)
+            end
+          end
+
+          def nodes
+            @nodes ||= graphql_impl.nodes
+          end
+
+          # Simple edge implementation for a node object.
+          class Edge < ResolvableValue.new(:graphql_impl, :node)
+            # `ResolvableValue.new` provides the following methods:
+            # @dynamic initialize, graphql_impl, schema_element_names, node
+
+            def cursor
+              graphql_impl.cursor_for(node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/relay_connection/generic_adapter.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/graphql/resolvers/relay_connection/page_info"
+require "elastic_graph/graphql/resolvers/resolvable_value"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      module RelayConnection
+        class GenericAdapter < ResolvableValue.new(
+          # Array of nodes for this page of data, before paginator truncation has been added.
+          :raw_nodes,
+          # The paginator that's being used.
+          :paginator,
+          # Lambda that is used to convert a node to a sort value during truncation.
+          :to_sort_value,
+          # Gets an optional count of total edges.
+          :get_total_edge_count
+        )
+          # @dynamic initialize, with, schema_element_names, raw_nodes, paginator, to_sort_value, get_total_edge_count
+
+          def page_info
+            @page_info ||= PageInfo.new(
+              schema_element_names: schema_element_names,
+              before_truncation_nodes: before_truncation_nodes,
+              edges: edges,
+              paginator: paginator
+            )
+          end
+
+          def total_edge_count
+            get_total_edge_count.call
+          end
+
+          def edges
+            @edges ||= nodes.map { |node| Edge.new(schema_element_names, node) }
+          end
+
+          def nodes
+            @nodes ||= paginator.truncate_items(before_truncation_nodes, &to_sort_value)
+          end
+
+          private
+
+          def before_truncation_nodes
+            @before_truncation_nodes ||= paginator.restore_intended_item_order(raw_nodes)
+          end
+
+          # Implements an `Edge` as per the relay spec:
+          # https://facebook.github.io/relay/graphql/connections.htm#sec-Edge-Types
+          class Edge < ResolvableValue.new(:node)
+            # @dynamic initialize, node
+            def cursor = node.cursor.encode
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/relay_connection/page_info.rb

@@ -0,0 +1,82 @@
+# 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/resolvers/resolvable_value"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      module RelayConnection
+        # Provides the `PageInfo` field values required by the relay spec.
+        #
+        # The relay connections spec defines an algorithm behind `hasPreviousPage` and `hasNextPage`:
+        # https://facebook.github.io/relay/graphql/connections.htm#sec-undefined.PageInfo.Fields
+        #
+        # However, it has a couple bugs as currently written (https://github.com/facebook/relay/issues/2787),
+        # so we have implemented our own algorithm instead. It would be nice to calculate `hasPreviousPage`
+        # and `hasNextPage` on-demand in a resolver, so we do not spend any effort on it if the client has
+        # not requested those fields, but it is quite hard to calculate them after the fact: we need to know
+        # whether we removed any leading or trailing items while processing the list to accurately answer
+        # the question, "do we have a page before or after the one we are returning?".
+        #
+        # Note: it's not clear what values `hasPreviousPage` and `hasNextPage` should have when we are returning
+        # a blank page (the client isn't being returned any cursors to continue paginating from!). This logic,
+        # as written, will normally cause both fields to be `true` (our request of `size: size + 1` will get us
+        # a list of 1 document, which will then be removed, causing `items.first` and `items.last` to
+        # both change to `nil`). However, if the datastore returns an empty list to us than `false` will be returned
+        # for one or both fields, based on the presence or absence of the `before`/`after` cursors in the pagination
+        # arguments. Regardless, given that it's not clear what the correct value is, we are just doing the
+        # least-effort thing and not putting any special handling for this case in place.
+        class PageInfo < ResolvableValue.new(
+          # The array of nodes for this page before we applied necessary truncation.
+          :before_truncation_nodes,
+          # The array of edges for this page.
+          :edges,
+          # The paginator built from the field arguments.
+          :paginator
+        )
+          # @dynamic initialize, with, before_truncation_nodes, edges, paginator
+
+          def start_cursor
+            edges.first&.cursor
+          end
+
+          def end_cursor
+            edges.last&.cursor
+          end
+
+          def has_previous_page
+            # If we dropped the first node during truncation then it means we removed some leading docs, indicating a previous page.
+            return true if edges.first&.node != before_truncation_nodes.first
+
+            # Nothing exists both before and after the same cursor, and there is therefore no page before that set of results.
+            return false if paginator.before == paginator.after
+
+            # If an `after` cursor was passed then there is definitely at least one doc before the page we are
+            # returning (the one matching the cursor), assuming the client did not construct a cursor by hand
+            # (which we do not support).
+            !!paginator.after
+          end
+
+          def has_next_page
+            # If we dropped the last node during truncation then it means we removed some trailing docs, indicating a next page.
+            return true if edges.last&.node != before_truncation_nodes.last
+
+            # Nothing exists both before and after the same cursor, and there is therefore no page after that set of results.
+            return false if paginator.before == paginator.after
+
+            # If a `before` cursor was passed then there is definitely at least one doc after the page we are
+            # returning (the one matching the cursor), assuming the client did not construct a cursor by hand
+            # (which we do not support).
+            !!paginator.before
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/relay_connection/search_response_adapter_builder.rb

@@ -0,0 +1,40 @@
+# 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/resolvers/relay_connection/generic_adapter"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      module RelayConnection
+        # Adapts an `DatastoreResponse::SearchResponse` to what the graphql gem expects for a relay connection.
+        class SearchResponseAdapterBuilder
+          def self.build_from(schema_element_names:, search_response:, query:)
+            document_paginator = query.document_paginator
+
+            GenericAdapter.new(
+              schema_element_names: schema_element_names,
+              raw_nodes: search_response.to_a,
+              paginator: document_paginator.paginator,
+              get_total_edge_count: -> { search_response.total_document_count },
+              to_sort_value: ->(document, decoded_cursor) do
+                (_ = document).sort.zip(decoded_cursor.sort_values.values, document_paginator.sort).map do |from_document, from_cursor, sort_clause|
+                  DatastoreQuery::Paginator::SortValue.new(
+                    from_item: from_document,
+                    from_cursor: from_cursor,
+                    sort_direction: sort_clause.values.first.fetch("order").to_sym
+                  )
+                end
+              end
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/relay_connection.rb

@@ -0,0 +1,42 @@
+# 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/aggregation/resolvers/relay_connection_builder"
+require "elastic_graph/graphql/resolvers/relay_connection/search_response_adapter_builder"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # Defines resolver logic related to relay connections. The relay connections spec is here:
+      # https://facebook.github.io/relay/graphql/connections.htm
+      module RelayConnection
+        # Conditionally wraps the given search response in the appropriate relay connection adapter, if needed.
+        def self.maybe_wrap(search_response, field:, context:, lookahead:, query:)
+          return search_response unless field.type.relay_connection?
+
+          schema_element_names = context.fetch(:schema_element_names)
+
+          unless field.type.unwrap_fully.indexed_aggregation?
+            return SearchResponseAdapterBuilder.build_from(
+              schema_element_names: schema_element_names,
+              search_response: search_response,
+              query: query
+            )
+          end
+
+          agg_name = lookahead.ast_nodes.first&.alias || lookahead.name
+          Aggregation::Resolvers::RelayConnectionBuilder.build_from_search_response(
+            schema_element_names: schema_element_names,
+            search_response: search_response,
+            query: query.aggregations.fetch(agg_name)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/resolvers/resolvable_value.rb

@@ -0,0 +1,56 @@
+# 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/support/memoizable_data"
+
+module ElasticGraph
+  class GraphQL
+    module Resolvers
+      # A class builder that is just like `Data` and also adapts itself to our
+      # resolver interface. Can resolve any field that is defined in `schema_element_names`
+      # and also has a corresponding method definition.
+      module ResolvableValue
+        # `MemoizableData.define` provides the following methods:
+        # @dynamic schema_element_names
+
+        def self.new(*fields, &block)
+          Support::MemoizableData.define(:schema_element_names, *fields) do
+            # @implements ResolvableValueClass
+            include ResolvableValue
+            # @type var block: (^() -> void)?
+            class_exec(&block) if block
+          end
+        end
+
+        def resolve(field:, object:, context:, args:, lookahead:)
+          method_name = canonical_name_for(field.name, "Field")
+          public_send(method_name, **args_to_canonical_form(args))
+        end
+
+        def can_resolve?(field:, object:)
+          method_name = schema_element_names.canonical_name_for(field.name)
+          !!method_name && respond_to?(method_name)
+        end
+
+        private
+
+        def args_to_canonical_form(args)
+          args.to_h do |key, value|
+            [canonical_name_for(key, "Argument"), value]
+          end
+        end
+
+        def canonical_name_for(name, element_type)
+          schema_element_names.canonical_name_for(name) ||
+            raise(SchemaError, "#{element_type} `#{name}` is not a defined schema element")
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/scalar_coercion_adapters/cursor.rb

@@ -0,0 +1,35 @@
+# 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/decoded_cursor"
+
+module ElasticGraph
+  class GraphQL
+    module ScalarCoercionAdapters
+      class Cursor
+        def self.coerce_input(value, ctx)
+          case value
+          when DecodedCursor
+            value
+          when ::String
+            DecodedCursor.try_decode(value)
+          end
+        end
+
+        def self.coerce_result(value, ctx)
+          case value
+          when DecodedCursor
+            value.encode
+          when ::String
+            value if DecodedCursor.try_decode(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/scalar_coercion_adapters/date.rb

@@ -0,0 +1,64 @@
+# 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
+  class GraphQL
+    module ScalarCoercionAdapters
+      class Date
+        def self.coerce_input(value, ctx)
+          return value if value.nil?
+
+          # `::Date.iso8601` will happily parse a time ISO8601 string like `2021-11-10T12:30:00Z`
+          # but for simplicity we only want to support a Date string (like `2021-11-10`),
+          # so we detect that case here.
+          raise ::ArgumentError if value.is_a?(::String) && value.include?(":")
+
+          date = ::Date.iso8601(value)
+
+          # Verify we have a 4 digit year. The datastore `strict_date_time` format se use only supports 4 digit years:
+          #
+          # > Most of the below formats have a `strict` companion format, which means that year, month and day parts of the
+          # > week must use respectively 4, 2 and 2 digits exactly, potentially prepending zeros.
+          #
+          # https://www.elastic.co/guide/en/elasticsearch/reference/7.10/mapping-date-format.html#built-in-date-formats
+          raise_coercion_error(value) if date.year < 1000 || date.year > 9999
+
+          # We ultimately wind up passing input args to the datastore as our GraphQL engine receives
+          # them (it doesn't do any formatting of Date args to what the datastore needs) so we do
+          # that here instead. We have configured the datastore to expect Dates in `strict_date`
+          # format, so here we convert it to that format (which is just ISO8601 format). Ultimately,
+          # that means that this method just "roundtrips" the input string back to a string, but it
+          # validates the string is formatted correctly and returns a string in the exact format we
+          # need for the datastore. Also, we technically don't have to do this; ISO8601 format is
+          # the format that `Date` objects are serialized as in JSON, anyway. But we _have_ to do this
+          # for `DateTime` objects so we also do it here for parity/consistency.
+          date.iso8601
+        rescue ArgumentError, ::TypeError
+          raise_coercion_error(value)
+        end
+
+        def self.coerce_result(value, ctx)
+          case value
+          when ::Date
+            value.iso8601
+          when ::String
+            ::Date.iso8601(value).iso8601
+          end
+        rescue ::ArgumentError
+          nil
+        end
+
+        private_class_method def self.raise_coercion_error(value)
+          raise ::GraphQL::CoercionError,
+            "Could not coerce value #{value.inspect} to Date: must be formatted " \
+            "as an ISO8601 Date string (example: #{::Date.today.iso8601.inspect})."
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/scalar_coercion_adapters/date_time.rb

@@ -0,0 +1,60 @@
+# 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 "time"
+
+module ElasticGraph
+  class GraphQL
+    module ScalarCoercionAdapters
+      class DateTime
+        PRECISION = 3 # millisecond precision
+
+        def self.coerce_input(value, ctx)
+          return value if value.nil?
+
+          time = ::Time.iso8601(value)
+
+          # Verify we do not have more than 4 digits for the year. The datastore `strict_date_time` format we use only supports 4 digit years:
+          #
+          # > Most of the below formats have a `strict` companion format, which means that year, month and day parts of the
+          # > week must use respectively 4, 2 and 2 digits exactly, potentially prepending zeros.
+          #
+          # https://www.elastic.co/guide/en/elasticsearch/reference/8.12/mapping-date-format.html#built-in-date-formats
+          raise_coercion_error(value) if time.year > 9999
+
+          # We ultimately wind up passing input args to the datastore as our GraphQL engine receives
+          # them (it doesn't do any formatting of DateTime args to what the datastore needs) so we do
+          # that here instead. We have configured the datastore to expect DateTimes in `strict_date_time`
+          # format, so here we convert it to that format (which is just ISO8601 format). Ultimately,
+          # that means that this method just "roundtrips" the input string back to a string, but it validates
+          # the string is formatted correctly and returns a string in the exact format we need for the datastore.
+          time.iso8601(PRECISION)
+        rescue ::ArgumentError, ::TypeError
+          raise_coercion_error(value)
+        end
+
+        def self.coerce_result(value, ctx)
+          case value
+          when ::Time
+            value.iso8601(PRECISION)
+          when ::String
+            ::Time.iso8601(value).iso8601(PRECISION)
+          end
+        rescue ::ArgumentError
+          nil
+        end
+
+        private_class_method def self.raise_coercion_error(value)
+          raise ::GraphQL::CoercionError,
+            "Could not coerce value #{value.inspect} to DateTime: must be formatted as an ISO8601 " \
+            "DateTime string with a 4 digit year (example: #{::Time.now.getutc.iso8601.inspect})."
+        end
+      end
+    end
+  end
+end