elasticgraph-graphql 0.18.0.0

data/lib/elastic_graph/graphql/schema.rb

@@ -0,0 +1,164 @@
+# 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 "digest/md5"
+require "forwardable"
+require "graphql"
+require "elastic_graph/constants"
+require "elastic_graph/error"
+require "elastic_graph/graphql/monkey_patches/schema_field"
+require "elastic_graph/graphql/monkey_patches/schema_object"
+require "elastic_graph/graphql/schema/field"
+require "elastic_graph/graphql/schema/type"
+require "elastic_graph/support/hash_util"
+
+module ElasticGraph
+  # Wraps a GraphQL::Schema object in order to provide higher-level, more convenient APIs
+  # on top of that. The schema is assumed to be immutable, so this class memoizes many
+  # computations it does, ensuring we never need to traverse the schema graph multiple times.
+  class GraphQL
+    class Schema
+      BUILT_IN_TYPE_NAMES = (
+        scalar_types = ::GraphQL::Schema::BUILT_IN_TYPES.keys # Int, ID, String, etc
+        introspection_types = ::GraphQL::Schema.types.keys # __Type, __Schema, etc
+        scalar_types.to_set.union(introspection_types)
+      )
+
+      attr_reader :element_names, :defined_types, :config, :graphql_schema, :runtime_metadata
+
+      def initialize(
+        graphql_schema_string:,
+        config:,
+        runtime_metadata:,
+        index_definitions_by_graphql_type:,
+        graphql_gem_plugins:,
+        &build_resolver
+      )
+        @element_names = runtime_metadata.schema_element_names
+        @config = config
+        @runtime_metadata = runtime_metadata
+
+        @types_by_graphql_type = Hash.new do |hash, key|
+          hash[key] = Type.new(
+            self,
+            key,
+            index_definitions_by_graphql_type[key.graphql_name] || [],
+            runtime_metadata.object_types_by_name[key.graphql_name],
+            runtime_metadata.enum_types_by_name[key.graphql_name]
+          )
+        end
+
+        @types_by_name = Hash.new { |hash, key| hash[key] = lookup_type_by_name(key) }
+        @build_resolver = build_resolver
+
+        # Note: as part of loading the schema, the GraphQL gem may use the resolver (such
+        # when a directive has a custom scalar) so we must wait to instantiate the schema
+        # as late as possible here. If we do this before initializing some of the instance
+        # variables above we'll get `NoMethodError` on `nil`.
+        @graphql_schema = ::GraphQL::Schema.from_definition(
+          graphql_schema_string,
+          default_resolve: LazyResolverAdapter.new(method(:resolver)),
+          using: graphql_gem_plugins
+        )
+
+        # Pre-load all defined types so that all field extras can get configured as part
+        # of loading the schema, before we execute the first query.
+        @defined_types = build_defined_types_array(@graphql_schema)
+      end
+
+      def type_from(graphql_type)
+        @types_by_graphql_type[graphql_type]
+      end
+
+      # Note: this does not support "wrapped" types (e.g. `Int!` or `[Int]` compared to `Int`),
+      # as the graphql schema object does not give us an index of those by name. You can still
+      # get type objects for wrapped types, but you need to get it from a field object of that
+      # type.
+      def type_named(type_name)
+        @types_by_name[type_name.to_s]
+      end
+
+      def document_type_stored_in(index_definition_name)
+        indexed_document_types_by_index_definition_name.fetch(index_definition_name) do
+          if index_definition_name.include?(ROLLOVER_INDEX_INFIX_MARKER)
+            raise ArgumentError, "`#{index_definition_name}` is the name of a rollover index; pass the name of the parent index definition instead."
+          else
+            raise NotFoundError, "The index definition `#{index_definition_name}` does not appear to exist. Is it misspelled?"
+          end
+        end
+      end
+
+      def field_named(type_name, field_name)
+        type_named(type_name).field_named(field_name)
+      end
+
+      def enum_value_named(type_name, enum_value_name)
+        type_named(type_name).enum_value_named(enum_value_name)
+      end
+
+      # The list of user-defined types that are indexed document types. (Indexed aggregation types will not be included in this.)
+      def indexed_document_types
+        @indexed_document_types ||= defined_types.select(&:indexed_document?)
+      end
+
+      def to_s
+        "#<#{self.class.name} 0x#{__id__.to_s(16)} indexed_document_types=#{indexed_document_types.map(&:name).sort.to_s.delete(":")}>"
+      end
+      alias_method :inspect, :to_s
+
+      private
+
+      # Adapter class to allow us to lazily load the resolver instance.
+      #
+      # Necessary because the resolver must be provided to `GraphQL::Schema.from_definition`,
+      # but the resolver logic itself depends upon the loaded schema to know how to resolve.
+      # To work around the circular dependency, we build the schema with this lazy adapter,
+      # then build the resolver with the schema, and then the lazy resolver lazily loads the resolver.
+      LazyResolverAdapter = Struct.new(:builder) do
+        def resolver
+          @resolver ||= builder.call
+        end
+
+        extend Forwardable
+        def_delegators :resolver, :call, :resolve_type, :coerce_input, :coerce_result
+      end
+
+      def lookup_type_by_name(type_name)
+        type_from(@graphql_schema.types.fetch(type_name))
+      rescue KeyError => e
+        msg = "No type named #{type_name} could be found"
+        msg += "; Possible alternatives: [#{e.corrections.join(", ").delete('"')}]." if e.corrections.any?
+        raise NotFoundError, msg
+      end
+
+      def resolver
+        @resolver ||= @build_resolver.call(self)
+      end
+
+      def build_defined_types_array(graphql_schema)
+        graphql_schema
+          .types
+          .values
+          .reject { |t| BUILT_IN_TYPE_NAMES.include?(t.graphql_name) }
+          .map { |t| type_named(t.graphql_name) }
+      end
+
+      def indexed_document_types_by_index_definition_name
+        @indexed_document_types_by_index_definition_name ||= indexed_document_types.each_with_object({}) do |type, hash|
+          type.index_definitions.each do |index_def|
+            if hash.key?(index_def.name)
+              raise SchemaError, "DatastoreCore::IndexDefinition #{index_def.name} is used multiple times: #{type} vs #{hash[index_def.name]}"
+            end
+
+            hash[index_def.name] = type
+          end
+        end.freeze
+      end
+    end
+  end
+end

data/lib/elastic_graph/graphql.rb

@@ -0,0 +1,253 @@
+# 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"
+require "elastic_graph/graphql/config"
+require "elastic_graph/support/from_yaml_file"
+
+module ElasticGraph
+  # The main entry point for ElasticGraph GraphQL handling. Instantiate this to get access to the
+  # different parts of this library.
+  class GraphQL
+    extend Support::FromYamlFile
+
+    # @private
+    # @dynamic config, logger, runtime_metadata, graphql_schema_string, datastore_core, clock
+    attr_reader :config, :logger, :runtime_metadata, :graphql_schema_string, :datastore_core, :clock
+
+    # @private
+    # A factory method that builds a GraphQL instance from the given parsed YAML config.
+    # `from_yaml_file(file_name, &block)` is also available (via `Support::FromYamlFile`).
+    def self.from_parsed_yaml(parsed_yaml, &datastore_client_customization_block)
+      new(
+        config: GraphQL::Config.from_parsed_yaml(parsed_yaml),
+        datastore_core: DatastoreCore.from_parsed_yaml(parsed_yaml, for_context: :graphql, &datastore_client_customization_block)
+      )
+    end
+
+    # @private
+    def initialize(
+      config:,
+      datastore_core:,
+      graphql_adapter: nil,
+      datastore_search_router: nil,
+      filter_interpreter: nil,
+      sub_aggregation_grouping_adapter: nil,
+      monotonic_clock: nil,
+      clock: ::Time
+    )
+      @config = config
+      @datastore_core = datastore_core
+      @graphql_adapter = graphql_adapter
+      @datastore_search_router = datastore_search_router
+      @filter_interpreter = filter_interpreter
+      @sub_aggregation_grouping_adapter = sub_aggregation_grouping_adapter
+      @monotonic_clock = monotonic_clock
+      @clock = clock
+      @logger = @datastore_core.logger
+      @runtime_metadata = @datastore_core.schema_artifacts.runtime_metadata
+      @graphql_schema_string = @datastore_core.schema_artifacts.graphql_schema_string
+
+      # Apply any extension modules that have been configured.
+      @config.extension_modules.each { |mod| extend mod }
+      @runtime_metadata.graphql_extension_modules.each { |ext_mod| extend ext_mod.extension_class }
+    end
+
+    # @private
+    def graphql_http_endpoint
+      @graphql_http_endpoint ||= begin
+        require "elastic_graph/graphql/http_endpoint"
+        HTTPEndpoint.new(
+          query_executor: graphql_query_executor,
+          monotonic_clock: monotonic_clock,
+          client_resolver: config.client_resolver
+        )
+      end
+    end
+
+    # @private
+    def graphql_query_executor
+      @graphql_query_executor ||= begin
+        require "elastic_graph/graphql/query_executor"
+        QueryExecutor.new(
+          schema: schema,
+          monotonic_clock: monotonic_clock,
+          logger: logger,
+          slow_query_threshold_ms: @config.slow_query_latency_warning_threshold_in_ms,
+          datastore_search_router: datastore_search_router
+        )
+      end
+    end
+
+    # @private
+    def schema
+      @schema ||= begin
+        require "elastic_graph/graphql/schema"
+
+        Schema.new(
+          graphql_schema_string: graphql_schema_string,
+          config: config,
+          runtime_metadata: runtime_metadata,
+          index_definitions_by_graphql_type: @datastore_core.index_definitions_by_graphql_type,
+          graphql_gem_plugins: graphql_gem_plugins
+        ) do |schema|
+          @graphql_adapter || begin
+            @schema = schema # assign this so that `#schema` returns the schema when `datastore_query_adapters` is called below
+            require "elastic_graph/graphql/resolvers/graphql_adapter"
+            Resolvers::GraphQLAdapter.new(
+              schema: schema,
+              datastore_query_builder: datastore_query_builder,
+              datastore_query_adapters: datastore_query_adapters,
+              runtime_metadata: runtime_metadata,
+              resolvers: graphql_resolvers
+            )
+          end
+        end
+      end
+    end
+
+    # @private
+    def datastore_search_router
+      @datastore_search_router ||= begin
+        require "elastic_graph/graphql/datastore_search_router"
+        DatastoreSearchRouter.new(
+          datastore_clients_by_name: @datastore_core.clients_by_name,
+          logger: logger,
+          monotonic_clock: monotonic_clock,
+          config: @config
+        )
+      end
+    end
+
+    # @private
+    def datastore_query_builder
+      @datastore_query_builder ||= begin
+        require "elastic_graph/graphql/datastore_query"
+        DatastoreQuery::Builder.with(
+          filter_interpreter: filter_interpreter,
+          runtime_metadata: runtime_metadata,
+          logger: logger,
+          default_page_size: @config.default_page_size,
+          max_page_size: @config.max_page_size
+        )
+      end
+    end
+
+    # @private
+    def graphql_gem_plugins
+      @graphql_gem_plugins ||= begin
+        require "graphql"
+        {::GraphQL::Dataloader => {}}
+      end
+    end
+
+    # @private
+    def graphql_resolvers
+      @graphql_resolvers ||= begin
+        require "elastic_graph/graphql/resolvers/get_record_field_value"
+        require "elastic_graph/graphql/resolvers/list_records"
+        require "elastic_graph/graphql/resolvers/nested_relationships"
+
+        nested_relationships = Resolvers::NestedRelationships.new(
+          schema_element_names: runtime_metadata.schema_element_names,
+          logger: logger
+        )
+
+        list_records = Resolvers::ListRecords.new
+
+        get_record_field_value = Resolvers::GetRecordFieldValue.new(
+          schema_element_names: runtime_metadata.schema_element_names
+        )
+
+        [nested_relationships, list_records, get_record_field_value]
+      end
+    end
+
+    # @private
+    def datastore_query_adapters
+      @datastore_query_adapters ||= begin
+        require "elastic_graph/graphql/aggregation/non_composite_grouping_adapter"
+        require "elastic_graph/graphql/aggregation/query_adapter"
+        require "elastic_graph/graphql/query_adapter/filters"
+        require "elastic_graph/graphql/query_adapter/pagination"
+        require "elastic_graph/graphql/query_adapter/sort"
+        require "elastic_graph/graphql/query_adapter/requested_fields"
+
+        schema_element_names = runtime_metadata.schema_element_names
+
+        [
+          GraphQL::QueryAdapter::Pagination.new(schema_element_names: schema_element_names),
+          GraphQL::QueryAdapter::Filters.new(schema_element_names: schema_element_names, filter_args_translator: filter_args_translator),
+          GraphQL::QueryAdapter::Sort.new(order_by_arg_name: schema_element_names.order_by),
+          Aggregation::QueryAdapter.new(
+            schema: schema,
+            config: config,
+            filter_args_translator: filter_args_translator,
+            runtime_metadata: runtime_metadata,
+            sub_aggregation_grouping_adapter: sub_aggregation_grouping_adapter
+          ),
+          GraphQL::QueryAdapter::RequestedFields.new(schema)
+        ]
+      end
+    end
+
+    # @private
+    def filter_interpreter
+      @filter_interpreter ||= begin
+        require "elastic_graph/graphql/filtering/filter_interpreter"
+        Filtering::FilterInterpreter.new(runtime_metadata: runtime_metadata, logger: logger)
+      end
+    end
+
+    # @private
+    def filter_args_translator
+      @filter_args_translator ||= begin
+        require "elastic_graph/graphql/filtering/filter_args_translator"
+        Filtering::FilterArgsTranslator.new(schema_element_names: runtime_metadata.schema_element_names)
+      end
+    end
+
+    # @private
+    def sub_aggregation_grouping_adapter
+      @sub_aggregation_grouping_adapter ||= begin
+        require "elastic_graph/graphql/aggregation/non_composite_grouping_adapter"
+        Aggregation::NonCompositeGroupingAdapter
+      end
+    end
+
+    # @private
+    def monotonic_clock
+      @monotonic_clock ||= begin
+        require "elastic_graph/support/monotonic_clock"
+        Support::MonotonicClock.new
+      end
+    end
+
+    # @private
+    # Loads dependencies eagerly. In some environments (such as in an AWS Lambda) this is desirable as we to load all dependencies
+    # at boot time instead of deferring dependency loading until we handle the first query. In other environments (such as tests),
+    # it's nice to load dependencies when needed.
+    def load_dependencies_eagerly
+      # run a simple GraphQL query to force load any dependencies needed to handle GraphQL queries
+      graphql_query_executor.execute(EAGER_LOAD_QUERY, client: Client::ELASTICGRAPH_INTERNAL)
+      graphql_http_endpoint # force load this too.
+    end
+
+    private
+
+    EAGER_LOAD_QUERY = <<~EOS.strip
+      query ElasticGraphEagerLoadBootQuery {
+        __schema {
+          types {
+            kind
+          }
+        }
+      }
+    EOS
+  end
+end

data/script/dump_time_zones

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+
+require "fileutils"
+
+updated_code_filename = "#{__dir__}/../../tmp/updated_valid_time_zones.rb"
+
+# Note: CI does not appear to have java 14 or 17 available, so we use java 11 here.
+java_time_zones = `java --source 11 #{__dir__}/dump_time_zones.java`.split("\n")
+
+::File.write(updated_code_filename, <<~EOS)
+  # 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
+        # The set of all valid time zones. We expect this set to align with the official IANA
+        # list[^1][^2][^3], but ultimately we pass these time zones to the datastore and need
+        # to enumerate all time zones it supports. Since Elasticsearch and OpenSearch run on the JVM and the
+        # date format docs[^4] link to Java's `java.time.format.DateTimeFormatter` class, we
+        # can conclude that they support the time zones that the java class supports. This set
+        # is generated by `script/dump_time_zones`, which queries Java's `java.time.ZoneId`[^5]
+        # class to get the set of time zones supported on the JVM.
+        #
+        # DO NOT EDIT BY HAND.
+        #
+        # [^1]: https://www.iana.org/time-zones
+        # [^2]: https://en.wikipedia.org/wiki/Tz_database
+        # [^3]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
+        # [^4]: https://www.elastic.co/guide/en/elasticsearch/reference/7.10/mapping-date-format.html#custom-date-formats
+        # [^5]: https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html
+        VALID_TIME_ZONES = %w[
+          #{java_time_zones.join("\n        ")}
+        ].to_set
+      end
+    end
+  end
+EOS
+
+verify_code_command = %(ruby -r#{updated_code_filename} -e "puts ElasticGraph::GraphQL::ScalarCoercionAdapters::VALID_TIME_ZONES.size")
+verify_code_output = `#{verify_code_command} 2>&1`
+
+if verify_code_output.to_i < 600 # As of Nov 2022 there are 601 time zones.
+  abort <<~EOS.strip
+    It appears that the generated code is invalid. Check `#{updated_code_filename}` to see what was generated.
+
+    Output from `#{verify_code_command}`:
+
+    #{verify_code_output}
+  EOS
+end
+
+if ARGV.include?("--print")
+  puts ::File.read(updated_code_filename)
+else
+  filename = "#{__dir__}/../lib/elastic_graph/graphql/scalar_coercion_adapters/valid_time_zones.rb"
+  ::FileUtils.cp(updated_code_filename, filename)
+  puts "Timezones have been written to `#{filename}`"
+end
+
+# if ARGV.include?("--verify")
+#   existing_contents = ::File.exist?(filename) ? ::File.read(filename) : ""
+#
+#   if existing_contents == valid_timezones_ruby_code
+#     puts "`#{filename}` is up to date!"
+#   else
+#     diff = `git diff --no-index #{"--color" if $stdout.tty?} --binary #{updated_code_filename} #{filename}`
+#
+#     abort <<~EOS.strip
+#       `#{filename}` is not up to date! Rerun `script/dump_time_zones` to correct.
+#
+#       #{diff}
+#     EOS
+#   end
+# else
+# end

data/script/dump_time_zones.java

@@ -0,0 +1,17 @@
+import java.time.ZoneId;
+import java.util.Set;
+
+/**
+ * Run this java file via `java --source 11 script/dump_time_zones.java`.
+ * `script/dump_time_zones` is a higher level wrapper that delegates to this
+ * and applies additional logic.
+ */
+public class DumpTimeZones {
+  public static void main(String[] args) {
+    Set<String> availableZones = ZoneId.getAvailableZoneIds();
+
+    availableZones.stream()
+      .sorted()
+      .forEach(it -> System.out.println(it));
+  }
+}