elasticgraph-graphql 0.18.0.0

data/lib/elastic_graph/graphql/decoded_cursor.rb

@@ -0,0 +1,120 @@
+# 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 "base64"
+require "elastic_graph/constants"
+require "elastic_graph/error"
+require "elastic_graph/support/memoizable_data"
+require "json"
+
+module ElasticGraph
+  class GraphQL
+    # Provides the in-memory representation of a cursor after it has been decoded, as a simple hash of sort values.
+    #
+    # The datastore's `search_after` pagination uses an array of values (which represent values of the fields you are
+    # sorting by). A cursor returned when we applied one sort is generally not valid when we apply a completely
+    # different sort. To ensure we can detect this, the encoder encodes a hash of sort fields and values, ensuring
+    # each value in the cursor is properly labeled with what field it came from. This allows us
+    # to detect situations where the client uses a cursor with a completely different sort applied, while
+    # allowing some minor variation in the sort. The following are still allowed:
+    #
+    #   - Changing the direction of the sort (from `asc` to `desc` or vice-versa)
+    #   - Re-ordering the sort (e.g. changing from `[amount_money_DESC, created_at_ASC]`
+    #     to `[created_at_ASC, amount_money_DESC]`
+    #   - Removing fields from the sort (e.g. changing from `[amount_money_DESC, created_at_ASC]`
+    #     to `[amount_money_DESC]`) -- but adding fields is not allowed
+    #
+    # While we don't necessarily recommend clients change these things between pagination requests (the
+    # behavior may be surprising to the user), there is no ambiguity in how to support them, and we do not
+    # feel like it makes sense to restrict it at this point.
+    class DecodedCursor < Support::MemoizableData.define(:sort_values)
+      # Methods provided by `MemoizableData.define`:
+      # @dynamic initialize, sort_values
+
+      # Tries to decode the given string cursor, returning `nil` if it is invalid.
+      def self.try_decode(string)
+        decode!(string)
+      rescue InvalidCursorError
+        nil
+      end
+
+      # Tries to decode the given string cursor, raising an `InvalidCursorError` if it's invalid.
+      def self.decode!(string)
+        return SINGLETON if string == SINGLETON_CURSOR
+        json = ::Base64.urlsafe_decode64(string)
+        new(::JSON.parse(json))
+      rescue ::ArgumentError, ::JSON::ParserError
+        raise InvalidCursorError, "`#{string}` is an invalid cursor."
+      end
+
+      # Encodes the cursor to a string using JSON and Base64 encoding.
+      def encode
+        @encode ||= begin
+          json = ::JSON.fast_generate(sort_values)
+          ::Base64.urlsafe_encode64(json, padding: false)
+        end
+      end
+
+      # A special cursor instance for when we need a cursor but have only a static collection of a single
+      # element without any sort of key we can encode.
+      SINGLETON = new({}).tap do |sc|
+        # Ensure the special string value is returned even though our `sort_values` are empty.
+        def sc.encode
+          SINGLETON_CURSOR
+        end
+      end
+
+      # Used to build decoded cursor values for the given `sort_fields`.
+      class Factory < Data.define(:sort_fields)
+        # Methods provided by `Data.define`:
+        # @dynamic initialize, sort_fields
+
+        # Builds a factory from a list like:
+        # `[{ 'amount_money.amount' => 'asc' }, { 'created_at' => 'desc' }]`.
+        def self.from_sort_list(sort_list)
+          sort_fields = sort_list.map do |hash|
+            if hash.values.any? { |v| !v.is_a?(::Hash) } || hash.values.flat_map(&:keys) != ["order"]
+              raise InvalidSortFieldsError,
+                "Given `sort_list` contained an invalid entry. Each must be a flat hash with one entry. Got: #{sort_list.inspect}"
+            end
+
+            # Steep thinks it could be `nil` because `hash.keys` could be empty, but we raise an error above in
+            # that case, so we know this will wind up being a `String`. `_` here silences Steep's type check error.
+            _ = hash.keys.first
+          end
+
+          if sort_fields.uniq.size < sort_fields.size
+            raise InvalidSortFieldsError,
+              "Given `sort_list` contains a duplicate field, which the CursorEncoder cannot handler. " \
+              "The caller is responsible for de-duplicating the sort list fist. Got: #{sort_list.inspect}"
+          end
+
+          new(sort_fields)
+        end
+
+        def build(sort_values)
+          unless sort_values.size == sort_fields.size
+            raise CursorEncodingError,
+              "size of sort values (#{sort_values.inspect}) does not match the " \
+              "size of sort fields (#{sort_fields.inspect})"
+          end
+
+          DecodedCursor.new(sort_fields.zip(sort_values).to_h)
+        end
+
+        alias_method :to_s, :inspect
+
+        module Null
+          def self.build(sort_values)
+            DecodedCursor.new(sort_values.map(&:to_s).zip(sort_values).to_h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/filtering/boolean_query.rb

@@ -0,0 +1,45 @@
+# 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 Filtering
+      # BooleanQuery is an internal class for composing a datastore query:
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html
+      #
+      # It is composed of:
+      #   1) The occurrence type (:must, :filter, :should, or :must_not)
+      #   2) A list of query clauses evaluated by the given occurrence type
+      #   3) An optional flag indicating whether the occurrence should be negated
+      class BooleanQuery < ::Data.define(:occurrence, :clauses)
+        def self.must(*clauses)
+          new(:must, clauses)
+        end
+
+        def self.filter(*clauses)
+          new(:filter, clauses)
+        end
+
+        def self.should(*clauses)
+          new(:should, clauses)
+        end
+
+        def merge_into(bool_node)
+          bool_node[occurrence].concat(clauses)
+        end
+
+        # For `any_of: []` we need a way to force the datastore to match no documents, but
+        # I haven't found any sort of literal `false` we can pass in the compound expression
+        # or even a literal `1 = 0` as is sometimes used in SQL. Instead, we use this for that
+        # case.
+        empty_array = [] # : ::Array[untyped]
+        ALWAYS_FALSE_FILTER = filter({ids: {values: empty_array}})
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/filtering/field_path.rb

@@ -0,0 +1,81 @@
+# 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
+  class GraphQL
+    module Filtering
+      # Tracks state related to field paths as we traverse our filtering data structure in order to translate
+      # it to its Elasticsearch/OpenSearch form.
+      #
+      # Instances of this class are immutable--callers must use the provided APIs (`+`, `counts_path`, `nested`)
+      # to get back new instances with state changes applied.
+      FieldPath = ::Data.define(
+        # The path from the overall document root.
+        :from_root,
+        # The path from the current parent document. Usually `from_parent` and `from_root` are the same,
+        # but they'll be different when we encounter a list field indexed using the `nested` mapping type.
+        # When we're traversing a subfield of a `nested` field, `from_root` will contain the full path from
+        # the original, overall document root, while `from_parent` will contain the path from the current
+        # nested document's root.
+        :from_parent
+      ) do
+        # @implements FieldPath
+
+        # Builds an empty instance.
+        def self.empty
+          new([], [])
+        end
+
+        def self.of(parts)
+          new(parts, parts)
+        end
+
+        # Used when we encounter a `nested` field to restart the `from_parent` path (while preserving the `from_root` path).
+        def nested
+          FieldPath.new(from_root, [])
+        end
+
+        # Creates a new instance with `sub_path` appended.
+        def +(other)
+          FieldPath.new(from_root + [other], from_parent + [other])
+        end
+
+        # Converts the current paths to what they need to be to be able to query our hidden `__counts` field (which
+        # is a map containing the counts of elements of every list field on the document). The `__counts` field
+        # sits a the root of every document (for both an overall root document and a `nested` document). Here's an
+        # example (which assumes `seasons` and `seasons.players` fields which are both `nested` and an `awards` field
+        # which is a list of strings). Given a filter like this:
+        #
+        # filter: {seasons: {any_satisfy: {players: {any_satisfy: {results: {awards: {count: {gt: 1}}}}}}}}
+        #
+        # ...after processing the `awards` key, our `FieldPath` will be:
+        #
+        # FieldPath.new(["seasons", "players", "results", "awards"], ["results", "awards"])
+        #
+        # When we then reach the `count` sub field and `counts_path` is called on it, the following will be returned:
+        #
+        # FieldPath.new(["seasons", "players", LIST_COUNTS_FIELD, "results|awards"], [LIST_COUNTS_FIELD, "results|awards"])
+        #
+        # This gives us what we want:
+        # - The path from the root is `seasons.players.__counts.results|awards`.
+        # - The path from the (nested) parent is `__counts.results|awards`.
+        #
+        # Note that our `__counts` field is a flat map which uses `|` (the `LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR` character)
+        # to separate its parts (hence, it's `results|awards` instead of `results.awards`).
+        def counts_path
+          from_root_to_parent_of_counts_field = from_root[0...-from_parent.size] # : ::Array[::String]
+          counts_sub_field = [LIST_COUNTS_FIELD, from_parent.join(LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR)]
+
+          FieldPath.new(from_root_to_parent_of_counts_field + counts_sub_field, counts_sub_field)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql/filtering/filter_args_translator.rb

@@ -0,0 +1,58 @@
+# 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 Filtering
+      # Responsible for translating a `filter` expression from GraphQL field names to the internal
+      # `name_in_index` of each field. This is necessary so that when a field is defined with
+      # an alternate `name_in_index`, the query against the index uses that name even while
+      # the name in the GraphQL schema is different.
+      #
+      # In addition, we translate the enum value names to enum value objects, so that any runtime
+      # metadata associated with that enum value is available to our `FilterInterpreter`.
+      class FilterArgsTranslator < ::Data.define(:filter_arg_name)
+        def initialize(schema_element_names:)
+          super(filter_arg_name: schema_element_names.filter)
+        end
+
+        # Translates the `filter` expression from the given `args` and `field` into their equivalent
+        # form using the `name_in_index` for any fields that are named differently in the index
+        # vs GraphQL.
+        def translate_filter_args(field:, args:)
+          return nil unless (filter_hash = args[filter_arg_name])
+          filter_type = field.schema.type_from(field.graphql_field.arguments[filter_arg_name].type)
+          convert(filter_type, filter_hash)
+        end
+
+        private
+
+        def convert(parent_type, filter_object)
+          case filter_object
+          when ::Hash
+            filter_object.to_h do |key, value|
+              field = parent_type.field_named(key)
+              [field.name_in_index.to_s, convert(field.type.unwrap_fully, value)]
+            end
+          when ::Array
+            filter_object.map { |value| convert(parent_type, value) }
+          when nil
+            nil
+          else
+            if parent_type.enum?
+              # Replace the name of an enum value with the value itself.
+              parent_type.enum_value_named(filter_object)
+            else
+              filter_object
+            end
+          end
+        end
+      end
+    end
+  end
+end