elasticgraph-query_registry 0.18.0.0

data/lib/elastic_graph/query_registry/rake_tasks.rb

@@ -0,0 +1,195 @@
+# 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"
+require "elastic_graph/support/from_yaml_file"
+require "pathname"
+require "rake/tasklib"
+
+module ElasticGraph
+  module QueryRegistry
+    class RakeTasks < ::Rake::TaskLib
+      # @dynamic self.from_yaml_file
+      extend Support::FromYamlFile::ForRakeTasks.new(ElasticGraph::GraphQL)
+
+      def initialize(registered_queries_by_client_dir, require_eg_latency_slo_directive: false, output: $stdout, &load_graphql)
+        @registered_queries_by_client_dir = Pathname.new(registered_queries_by_client_dir)
+        @require_eg_latency_slo_directive = require_eg_latency_slo_directive
+        @output = output
+        @load_graphql = load_graphql
+
+        define_tasks
+      end
+
+      private
+
+      def define_tasks
+        namespace :query_registry do
+          desc "Validates the queries registered in `#{@registered_queries_by_client_dir}`"
+          task :validate_queries do
+            perform_query_validation
+          end
+
+          desc "Updates the registered information about query variables for a specific client (and optionally, a specific query)."
+          task :dump_variables, :client, :query do |_, args|
+            dump_variables("#{args.fetch(:client)}/#{args.fetch(:query, "*")}.graphql")
+          end
+
+          namespace :dump_variables do
+            desc "Updates the registered information about query variables for all clients."
+            task :all do
+              dump_variables("*/*.graphql")
+            end
+          end
+        end
+      end
+
+      def dump_variables(query_glob)
+        # We defer the loading of these dependencies until the task is running. As a general rule,
+        # we want rake tasks to only load their dependencies when they are run--that way, `rake -T`
+        # stays snappy, and when we run a rake task, only that task's dependencies are loaded
+        # instead of dependencies for all rake tasks.
+        require "elastic_graph/query_registry/variable_dumper"
+        require "yaml"
+
+        variable_dumper = VariableDumper.new(graphql.schema.graphql_schema)
+
+        @registered_queries_by_client_dir.glob(query_glob) do |file|
+          dumped_variables = variable_dumper.dump_variables_for_query(file.read)
+          variables_file = variable_file_name_for(file.to_s)
+          ::File.write(variables_file, variable_file_docs(variables_file) + ::YAML.dump(dumped_variables))
+          @output.puts "- Dumped `#{variables_file}`."
+        end
+      end
+
+      def variable_file_name_for(query_file_name)
+        query_file_name.delete_suffix(".graphql") + ".variables.yaml"
+      end
+
+      def variable_file_docs(file_name)
+        client_name = file_name[%r{/([^/]+)/[^/]+\.variables\.yaml}, 1]
+        query_name = file_name[%r{/[^/]+/([^/]+)\.variables\.yaml}, 1]
+
+        <<~EOS
+          # Generated by `rake "query_registry:dump_variables[#{client_name}, #{query_name}]"`.
+          # DO NOT EDIT BY HAND. Any edits will be lost the next time the rake task is run.
+          #
+          # This file exists to allow `elasticgraph-query_registry` to track the structure of
+          # the variables for the `#{client_name}/#{query_name}` query, so that we can detect
+          # when the schema structure of an object or enum variable changes in a way that might
+          # break the client.
+        EOS
+      end
+
+      def perform_query_validation
+        # We defer the loading of these dependencies until the task is running. As a general rule,
+        # we want rake tasks to only load their dependencies when they are run--that way, `rake -T`
+        # stays snappy, and when we run a rake task, only that task's dependencies are loaded
+        # instead of dependencies for all rake tasks.
+        require "elastic_graph/query_registry/query_validator"
+        require "json"
+        require "yaml"
+
+        validator = QueryValidator.new(
+          graphql.schema,
+          require_eg_latency_slo_directive: @require_eg_latency_slo_directive
+        )
+
+        all_errors = @registered_queries_by_client_dir.children.sort.flat_map do |client_dir|
+          @output.puts "For client `#{client_dir.basename}`:"
+          validate_client_queries(validator, client_dir).tap do
+            @output.puts
+          end
+        end
+
+        unless all_errors.empty?
+          raise "Found #{count_description(all_errors, "validation error")} total across all queries."
+        end
+      end
+
+      def validate_client_queries(validator, client_dir)
+        # @type var file_name_by_operation_name: ::Hash[::String, ::Pathname]
+        file_name_by_operation_name = {}
+
+        client_dir.glob("*.graphql").sort.flat_map do |query_file|
+          previously_dumped_variables = previously_dumped_variables_for(query_file.to_s)
+          errors_by_operation_name = validator.validate(
+            query_file.read,
+            client_name: client_dir.basename.to_s,
+            query_name: query_file.basename.to_s.delete_suffix(".graphql"),
+            previously_dumped_variables: previously_dumped_variables
+          )
+
+          @output.puts "  - #{query_file.basename} (#{count_description(errors_by_operation_name, "operation")}):"
+
+          errors_by_operation_name.flat_map do |op_name, errors|
+            if (conflicting_file_name = file_name_by_operation_name[op_name.to_s])
+              errors += [conflicting_operation_name_error(client_dir, op_name, conflicting_file_name)]
+            else
+              file_name_by_operation_name[op_name.to_s] = query_file
+            end
+
+            op_name ||= "(no operation name)"
+            if errors.empty?
+              @output.puts "    - #{op_name}: ✅"
+            else
+              @output.puts "    - #{op_name}: 🛑. Got #{count_description(errors, "validation error")}:\n"
+
+              errors.each_with_index do |error, index|
+                @output.puts format_error(query_file, index, error)
+              end
+            end
+
+            errors
+          end
+        end
+      end
+
+      def previously_dumped_variables_for(query_file_name)
+        file_name = variable_file_name_for(query_file_name)
+        return nil unless ::File.exist?(file_name)
+        ::YAML.safe_load_file(file_name)
+      end
+
+      def conflicting_operation_name_error(client_dir, operation_name, conflicting_file_name)
+        message = "A `#{operation_name}` query already exists for `#{client_dir.basename}` in " \
+          "`#{conflicting_file_name.basename}`. Each query operation must have a unique name."
+
+        {"message" => message}
+      end
+
+      def format_error(file_name, index, error_hash)
+        file_locations = (error_hash["locations"] || []).map do |location|
+          "   source: #{file_name}:#{location["line"]}:#{location["column"]}"
+        end
+
+        path = error_hash["path"]&.join(".")
+
+        detail_lines = (error_hash["extensions"] || {})
+          .merge(error_hash.except("message", "locations", "path", "extensions"))
+          .map { |key, value| "   #{key}: #{value}" }
+
+        [
+          "      #{index + 1}) #{error_hash["message"]}",
+          ("   path: #{path}" if path),
+          *file_locations,
+          *detail_lines
+        ].compact.join("\n      ") + "\n\n"
+      end
+
+      def count_description(collection, noun)
+        return "1 #{noun}" if collection.size == 1
+        "#{collection.size} #{noun}s"
+      end
+
+      def graphql
+        @graphql ||= @load_graphql.call
+      end
+    end
+  end
+end

data/lib/elastic_graph/query_registry/registry.rb

@@ -0,0 +1,101 @@
+# 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/query_registry/query_validators/for_registered_client"
+require "elastic_graph/query_registry/query_validators/for_unregistered_client"
+require "graphql"
+require "pathname"
+
+module ElasticGraph
+  module QueryRegistry
+    # An abstraction that implements a registry of GraphQL queries. Callers should use
+    # `build_and_validate_query` to get `GraphQL::Query` objects so that clients are properly
+    # limited in what queries we execute on their behalf.
+    #
+    # Note that this class is designed to be as efficient as possible:
+    #
+    # - Registered GraphQL queries are only parsed once, and then the parsed form is used
+    #   each time that query is submitted. In our benchmarking, parsing of large queries
+    #   can be significant, taking ~10ms or so.
+    # - We delay parsing a registered client's queries until the first time that client
+    #   sends us a query. That way, we don't have to pay any parsing cost for queries
+    #   that were registered by an old client that no longer sends us requests.
+    # - Likewise, we defer reading a client's registered query strings off of disk until
+    #   the first time it submits a request.
+    #
+    # In addition, it's worth noting that we support some basic "fuzzy" matching of query
+    # strings, based on the query canonicalization performed by the GraphQL gem. Semantically
+    # insignificant changes to the query string from a registered query (such as whitespace
+    # differences, or comments) are tolerated.
+    class Registry
+      # Public factory method, which builds a `Registry` instance from the given directory.
+      # Subdirectories are treated as client names, and the files in them are treated as
+      # individually registered queries.
+      def self.build_from_directory(schema, directory, allow_unregistered_clients:, allow_any_query_for_clients:)
+        directory = Pathname.new(directory)
+
+        new(
+          schema,
+          client_names: directory.children.map { |client_dir| client_dir.basename.to_s },
+          allow_unregistered_clients: allow_unregistered_clients,
+          allow_any_query_for_clients: allow_any_query_for_clients
+        ) do |client_name|
+          # Lazily read queries off of disk when we need to for a given client.
+          (directory / client_name).glob("*.graphql").map { |file| ::File.read(file.to_s) }
+        end
+      end
+
+      # Builds a `GraphQL::Query` object for the given query string, and validates that it is
+      # an allowed query. Returns a list of registry validation errors in addition to the built
+      # query object. The list of validation errors will be empty if the query should be allowed.
+      # A query can be allowed either by virtue of being registered for usage by the given clent,
+      # or by being for a completely unregistered client (if `allow_unregistered_clients` is `true`).
+      #
+      # This is also tolerant of some minimal differences in the query string (such as comments
+      # and whitespace). If the query differs in a significant way from a registered query, it
+      # will not be recognized as registered.
+      def build_and_validate_query(query_string, client:, variables: {}, operation_name: nil, context: {})
+        validator =
+          if @registered_client_validator.applies_to?(client)
+            @registered_client_validator
+          else
+            @unregistered_client_validator
+          end
+
+        validator.build_and_validate_query(query_string, client: client, variables: variables, operation_name: operation_name, context: context) do
+          ::GraphQL::Query.new(
+            @graphql_schema,
+            query_string,
+            variables: variables,
+            operation_name: operation_name,
+            context: context
+          )
+        end
+      end
+
+      private
+
+      def initialize(schema, client_names:, allow_unregistered_clients:, allow_any_query_for_clients:, &provide_query_strings_for_client)
+        @graphql_schema = schema.graphql_schema
+        allow_any_query_for_clients_set = allow_any_query_for_clients.to_set
+
+        @registered_client_validator = QueryValidators::ForRegisteredClient.new(
+          schema: schema,
+          client_names: client_names,
+          allow_any_query_for_clients: allow_any_query_for_clients_set,
+          provide_query_strings_for_client: provide_query_strings_for_client
+        )
+
+        @unregistered_client_validator = QueryValidators::ForUnregisteredClient.new(
+          allow_unregistered_clients: allow_unregistered_clients,
+          allow_any_query_for_clients: allow_any_query_for_clients_set
+        )
+      end
+    end
+  end
+end

data/lib/elastic_graph/query_registry/variable_backward_incompatibility_detector.rb

@@ -0,0 +1,104 @@
+# 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 QueryRegistry
+    # Responsible for comparing old and new variable type info to see if any changes are backwards
+    # incompatible (and thus my break the client). Incompatibilities are identified by path and described.
+    class VariableBackwardIncompatibilityDetector
+      # Entry point. Given the old variables for an operation, and the new variables for it, describes
+      # any backward incompatibilities in them.
+      def detect(old_op_vars:, new_op_vars:)
+        detect_incompatibilities(old_op_vars, new_op_vars, "$", "variable")
+      end
+
+      private
+
+      # Given an `old` and `new` hash (which could be hashes of variables, or hashes of object fields),
+      # describes the incompatibities in them.
+      def detect_incompatibilities(old, new, path, entry_type)
+        removals = old.keys - new.keys
+        additions = new.keys - old.keys
+        commonalities = old.keys & new.keys
+
+        incompatible_removals = removals.map do |name|
+          # All removals are incompatible, because the client might pass a value for the variable or field.
+          Incompatibility.new("#{path}#{name}", "removed")
+        end
+
+        incompatible_commonalities = commonalities.flat_map do |name|
+          incompatibilities_for("#{path}#{name}", normalize_type_info(old[name]), normalize_type_info(new[name]))
+        end
+
+        incompatible_additions = additions.filter_map do |name|
+          # Additions are only incompatible if it's required (non-nullable).
+          _ = if normalize_type_info(new[name]).fetch("type").end_with?("!")
+            Incompatibility.new("#{path}#{name}", "new required #{entry_type}")
+          end
+        end
+
+        incompatible_removals + incompatible_commonalities + incompatible_additions
+      end
+
+      # Describes the incompatibilities between the old and new type info.
+      def incompatibilities_for(path, old_type_info, new_type_info)
+        type_incompatibilities(path, old_type_info.fetch("type"), new_type_info.fetch("type")) +
+          enum_value_incompatibilities(path, old_type_info["values"], new_type_info["values"]) +
+          object_field_incompatibilities(path, old_type_info["fields"], new_type_info["fields"])
+      end
+
+      # Describes the incompatibilities between the old and new type names.
+      def type_incompatibilities(path, old_type, new_type)
+        if new_type == "#{old_type}!"
+          # If the variable or field is being required for the first time, the client may not pass a value
+          # for it and could be broken by this change.
+          [Incompatibility.new(path, "required for the first time")]
+        elsif old_type == "#{new_type}!"
+          [] # nullability was relaxed. That can't break the client so it's fine.
+        elsif new_type == old_type
+          [] # the type did not change.
+        else
+          # The type name changed. While some type name changes are compatible (e.g. from `ID` to `String`),
+          # we don't attempt to figure things out at that granularity.
+          [Incompatibility.new(path, "type changed from `#{old_type}` to `#{new_type}`")]
+        end
+      end
+
+      # Describes the incompatibilities between the old and new enum values for a field or variable.
+      def enum_value_incompatibilities(path, old_enum_values, new_enum_values)
+        return [] unless old_enum_values && new_enum_values
+        removed_values = old_enum_values - new_enum_values
+        return [] if removed_values.empty?
+
+        # Removed enum values could break the client if it ever passes a removed value in a query.
+        [Incompatibility.new(path, "removed enum values: #{removed_values.join(", ")}")]
+      end
+
+      # Describes the incompatibilities between old and new object fields via recursion.
+      def object_field_incompatibilities(path, old_fields, new_fields)
+        return [] unless old_fields && new_fields
+        detect_incompatibilities(old_fields, new_fields, "#{path}.", "field")
+      end
+
+      # Handles the fact that `type_info` can sometimes be a simple string, normalizing
+      # it to a hash so that we can consistently treat all type infos as hashes with a `type` field.
+      def normalize_type_info(type_info)
+        return {"type" => type_info} if type_info.is_a?(::String)
+        _ = type_info
+      end
+
+      # Represents a single incompatibility.
+      Incompatibility = ::Data.define(:path, :explanation) do
+        # @implements Incompatibility
+        def description
+          "#{path} (#{explanation})"
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/query_registry/variable_dumper.rb

@@ -0,0 +1,110 @@
+# 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"
+
+module ElasticGraph
+  module QueryRegistry
+    # Responsible for dumping structural information about query variables.
+    #
+    # This is necessary for the query registry to be able to support object and enum variables.
+    # To understand why, consider what happens when a field is removed from an input object
+    # variable used by a client's query. Whether or not it that will break the client depends
+    # on which fields of the input object the client populates when sending the query to
+    # ElasticGraph. Similarly, if an enum value is removed from an enum value variable used by
+    # a client, it could be a breaking change (but only if the client ever passes the removed
+    # enum value).
+    #
+    # To detect this situation, we use this to dump the structural information about all variables.
+    # When the structure of variables changes, we can then tell the engineer that they need to verify
+    # that it won't break the client.
+    class VariableDumper
+      def initialize(graphql_schema)
+        @graphql_schema = graphql_schema
+      end
+
+      # Returns a hash of operations from the given query string. For each operation, the value
+      # is a hash of variables.
+      def dump_variables_for_query(query_string)
+        query = ::GraphQL::Query.new(@graphql_schema, query_string, validate: false)
+
+        if query.document.nil?
+          # If the query was unparsable, we don't know anything about the variables and must just return an empty hash.
+          {}
+        else
+          # @type var operations: ::Array[::GraphQL::Language::Nodes::OperationDefinition]
+          operations = _ = query.document.definitions.grep(::GraphQL::Language::Nodes::OperationDefinition)
+          dump_variables_for_operations(operations)
+        end
+      end
+
+      # Returns a hash containing the variables for each operation.
+      def dump_variables_for_operations(operations)
+        operations.each_with_index.to_h do |operation, index|
+          [operation.name || "(Anonymous operation #{index + 1})", variables_for_op(operation)]
+        end
+      end
+
+      private
+
+      # Returns a hash of variables for the given GraphQL operation.
+      def variables_for_op(operation)
+        operation.variables.sort_by(&:name).to_h do |variable|
+          type_info =
+            if (type = @graphql_schema.type_from_ast(variable.type))
+              type_info(type)
+            else
+              # We should only get here if a variable references a type that is undefined. Since we
+              # don't know anything about the type other than the name, that's all we can return.
+              variable.type.to_query_string
+            end
+
+          [variable.name, type_info]
+        end
+      end
+
+      # Returns information about the given type.
+      #
+      # Note that this is optimized for human readability over data structure consistency.
+      # We don't *do* anything with this dumped data (other than comparing its equality
+      # against the dumped results for the same query in the future), so we don't need
+      # the sort of data structure consistency we'd normally want.
+      #
+      # For scalars (and lists-of-scalars) the *only* meaningful structural information
+      # is the type signature (e.g. `[ID!]`). On the other hand, we need the `fields` for
+      # an input object, and the `values` for an enum (along with the type signature for
+      # those, to distinguish list vs not and nullable vs not).
+      #
+      # So, while we return a hash for object/enum variables, for all others we just return
+      # the type signature string.
+      def type_info(type)
+        unwrapped_type = type.unwrap
+
+        if unwrapped_type.kind.input_object?
+          {"type" => type.to_type_signature, "fields" => fields_for(_ = unwrapped_type)}
+        elsif unwrapped_type.kind.enum?
+          {"type" => type.to_type_signature, "values" => (_ = unwrapped_type).values.keys.sort}
+        else
+          type.to_type_signature
+        end
+      end
+
+      # Returns a hash of input object fields for the given type.
+      def fields_for(variable_type)
+        variable_type.arguments.values.sort_by(&:name).to_h do |arg|
+          if arg.type.unwrap == variable_type
+            # Don't recurse (it would never terminate); just dump a reference to the type.
+            [arg.name, arg.type.to_type_signature]
+          else
+            [arg.name, type_info(arg.type)]
+          end
+        end
+      end
+    end
+  end
+end