elasticgraph-support 0.18.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a6c3aca3ffb3ca4835a6e051afe7dee323348ef1d819a30dca05b1f6d06d452
+  data.tar.gz: a52ecb10ebd1065e9780aa3dabf71848200e96409b110122f00bd5569e485fa7
+SHA512:
+  metadata.gz: 6ab3fb42baad12fcab9414a262f0b2ddfddb20d90cbd0913f65fb0a1dfecbb1e5c9b17231ea337d0a1a3ea20854ce310b8ecf905fb528a975e14406f6e46905d
+  data.tar.gz: 391e5007037fbdfd29134d2dd6cbaa5313fa8b031b2a4366c58d8c036940ef318d1571d16aee18aeab520eca2c8275f1d79b5842b07943cebed143797d069ac5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Block, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,6 @@
+# ElasticGraph::Support
+
+This gem provides support utilities for the rest of the ElasticGraph gems. As
+such, it is not intended to provide any public APIs for ElasticGraph users.
+
+Importantly, it is intended to have *zero* dependencies.

data/elasticgraph-support.gemspec

@@ -0,0 +1,16 @@
+# 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_relative "../gemspec_helper"
+
+ElasticGraphGemspecHelper.define_elasticgraph_gem(gemspec_file: __FILE__, category: :core) do |spec, eg_version|
+  spec.summary = "ElasticGraph gem providing support utilities to the other ElasticGraph gems."
+
+  spec.add_development_dependency "faraday", "~> 2.10"
+  spec.add_development_dependency "rake", "~> 13.2"
+end

data/lib/elastic_graph/constants.rb

@@ -0,0 +1,220 @@
+# 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
+
+# Enumerates constants that are used from multiple places in the code.
+module ElasticGraph
+  # The datastore date format used by ElasticGraph. Matches ISO-8601/RFC-3339.
+  # See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#built-in-date-formats
+  DATASTORE_DATE_FORMAT = "strict_date"
+
+  # The datastore date time format used by ElasticGraph. Matches ISO-8601/RFC-3339.
+  # See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#built-in-date-formats
+  DATASTORE_DATE_TIME_FORMAT = "strict_date_time"
+
+  # HTTP header that ElasticGraph HTTP implementations (e.g. elasticgraph-rack, elasticgraph-lambda)
+  # look at to determine a client-specified request timeout.
+  TIMEOUT_MS_HEADER = "ElasticGraph-Request-Timeout-Ms"
+
+  # Min/max values for the `Int` type.
+  # Based on the GraphQL spec:
+  #
+  # > If the integer internal value represents a value less than -2^31 or greater
+  # > than or equal to 2^31, a field error should be raised.
+  #
+  # (from http://spec.graphql.org/June2018/#sec-Int)
+  INT_MIN = -(2**31).to_int
+  INT_MAX = -INT_MIN - 1
+
+  # Min/max values for our `JsonSafeLong` type.
+  # Based on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
+  JSON_SAFE_LONG_MIN = -((2**53) - 1).to_int
+  JSON_SAFE_LONG_MAX = -JSON_SAFE_LONG_MIN
+
+  # Min/max values for our `LongString` type.
+  # This range is derived from the Elasticsearch docs on its longs:
+  # > A signed 64-bit integer with a minimum value of -2^63 and a maximum value of 2^63 - 1.
+  # (from https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html)
+  LONG_STRING_MIN = -(2**63).to_int
+  LONG_STRING_MAX = -LONG_STRING_MIN - 1
+
+  # When indexing large string values into the datastore, we've observed errors like:
+  #
+  # > bytes can be at most 32766 in length
+  #
+  # This is also documented on the Elasticsearch docs site, under "Choosing a keyword family field type":
+  # https://www.elastic.co/guide/en/elasticsearch/reference/8.2/keyword.html#wildcard-field-type
+  #
+  # Note that it's a byte limit, but JSON schema's maxLength is a limit on the number of characters.
+  # UTF8 uses up to 4 bytes per character so to guard against a maliciously crafted payload, we limit
+  # the length to a quarter of 32766.
+  DEFAULT_MAX_KEYWORD_LENGTH = 32766 / 4
+
+  # Strings indexed as `text` can be much larger than `keyword` fields. In fact, there's no limitation
+  # on the `text` length, except for the overall size of the HTTP request body when we attempt to index
+  # a `text` field. By default it's limited to 100MB via the `http.max_content_length` setting:
+  #
+  # https://www.elastic.co/guide/en/elasticsearch/reference/8.11/modules-network.html#http-settings
+  #
+  # Note: there's no guarantee that `text` values shorter than this will succeed when indexing them--it
+  # depends on how many other fields and documents are included in the indexing payload, since the limit
+  # is on the overall payload size, and not on the size of one field. Given that, there's not really a
+  # discrete value we can use for the max length that guarantees successful indexing. But we know that
+  # values larger than this will fail, so this is the limit we use.
+  DEFAULT_MAX_TEXT_LENGTH = 100 * (2**20).to_int
+
+  # The name of the JSON schema definition for the ElasticGraph event envelope.
+  EVENT_ENVELOPE_JSON_SCHEMA_NAME = "ElasticGraphEventEnvelope"
+
+  # For some queries, we wind up needing a pagination cursor for a collection
+  # that will only ever contain a single value (and has no "key" to speak of
+  # to encode into a cursor). In those contexts, we'll use this as the cursor value.
+  # Ideally, we want this to be a value that could never be produced by our normal
+  # cursor encoding logic. This cursor is encoded from data that includes a UUID,
+  # which we can trust is unique.
+  SINGLETON_CURSOR = "eyJ1dWlkIjoiZGNhMDJkMjAtYmFlZS00ZWU5LWEwMjctZmVlY2UwYTZkZTNhIn0="
+
+  # Schema artifact file names.
+  GRAPHQL_SCHEMA_FILE = "schema.graphql"
+  JSON_SCHEMAS_FILE = "json_schemas.yaml"
+  DATASTORE_CONFIG_FILE = "datastore_config.yaml"
+  RUNTIME_METADATA_FILE = "runtime_metadata.yaml"
+
+  # Name for directory that contains versioned json_schemas files.
+  JSON_SCHEMAS_BY_VERSION_DIRECTORY = "json_schemas_by_version"
+  # Name for field in json schemas files that represents schema "version".
+  JSON_SCHEMA_VERSION_KEY = "json_schema_version"
+
+  # String that goes in the middle of a rollover index name, used to mark it as a rollover
+  # index (and split on to parse a rollover index name).
+  ROLLOVER_INDEX_INFIX_MARKER = "_rollover__"
+
+  DERIVED_INDEX_FAILURE_MESSAGE_PREAMBLE = "Derived index update failed due to bad input data"
+
+  # The current id of our static `index_data` update script. Verified by a test so you can count
+  # on it being accurate. We expose this as a constant so that we can detect this specific script
+  # in environments where we can't count on `elasticgraph-schema_definition` (where the script is
+  # defined) being available, since that gem is usually only used in development.
+  #
+  # Note: this constant is automatically kept up-to-date by our `schema_artifacts:dump` rake task.
+  INDEX_DATA_UPDATE_SCRIPT_ID = "update_index_data_d577eb4b07ee3c53b59f2f6d6c7b2413"
+
+  # The id of the old version of the update data script before ElasticGraph v0.9. For now, we are maintaining
+  # backwards compatibility with how it recorded event versions, and we have test coverage for that which relies
+  # upon this id.
+  #
+  # TODO: Drop this when we no longer need to maintain backwards-compatibility.
+  OLD_INDEX_DATA_UPDATE_SCRIPT_ID = "update_index_data_9b97090d5c97c4adc82dc7f4c2b89bc5"
+
+  # When an update script has a no-op result we often want to communicate more information about
+  # why it was a no-op back to ElatsicGraph from the script. The only way to do that is to throw
+  # an exception with an error message, but, as far as I can tell, painless doesn't let you define
+  # custom exception classes. To allow elasticgraph-indexer to detect that the script "failed" due
+  # to a no-op (rather than a true failure) we include this common preamble in the exception message
+  # thrown from our update scripts for the no-op case.
+  UPDATE_WAS_NOOP_MESSAGE_PREAMBLE = "ElasticGraph update was a no-op: "
+
+  # The name used to refer to a document's own/primary source event (that is, the event that has a `type`
+  # matching the document's type). The name here was chosen to avoid naming collisions with relationships
+  # defined via the `relates_to_one`/`relates_to_many` APIs. The GraphQL spec reserves the double-underscore
+  # prefix on field names, which means that users cannot define a relationship named `__self` via the
+  # `relates_to_one`/`relates_to_many` APIs.
+  SELF_RELATIONSHIP_NAME = "__self"
+
+  # This regex aligns with the datastore format of HH:mm:ss || HH:mm:ss.S || HH:mm:ss.SS || HH:mm:ss.SSS
+  # See https://rubular.com/r/NHjBWrpZvzOTJO for examples.
+  VALID_LOCAL_TIME_REGEX = /\A(([0-1][0-9])|(2[0-3])):[0-5][0-9]:[0-5][0-9](\.[0-9]{1,3})?\z/
+
+  # `VALID_LOCAL_TIME_REGEX`, expressed as a JSON schema pattern. JSON schema supports a subset of
+  # Ruby Regexp features and is expressed as a String object. Here we convert from the Ruby Regexp
+  # start-and-end-of-string anchors (\A and \z) and convert them to the JSON schema ones (^ and $).
+  #
+  # For more info, see:
+  # https://json-schema.org/understanding-json-schema/reference/regular_expressions.html
+  # http://www.rexegg.com/regex-anchors.html
+  VALID_LOCAL_TIME_JSON_SCHEMA_PATTERN = VALID_LOCAL_TIME_REGEX.source.sub(/\A\\A/, "^").sub(/\\z\z/, "$")
+
+  # Special hidden field defined in an index where we store the count of elements in each list field.
+  # We index the list counts so that we can offer a `count` filter operator on list fields, allowing
+  # clients to query on the count of list elements.
+  #
+  # The field name has a leading `__` because the GraphQL spec reserves that prefix for its own use,
+  # and we can therefore assume that no GraphQL fields have this name.
+  LIST_COUNTS_FIELD = "__counts"
+
+  # Character used to separate parts of a field path for the keys in the special `__counts`
+  # field which contains the counts of the various list fields. We were going to use a dot
+  # (as you'd expect) but ran into errors like this from the datastore:
+  #
+  # > can't merge a non object mapping [seasons.players.__counts.seasons] with an object mapping
+  #
+  # When we have a list of `object`, and then a list field on that object type, we want to
+  # store the count of both the parent list and the child list, but if we use dots then the datastore
+  # treats it like a nested JSON object, and the JSON entry at the parent path can't both be an integer
+  # (for the parent list count) and an object containing counts of its child lists.
+  #
+  # By using `|` instead of `.`, we avoid this problem.
+  LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR = "|"
+
+  # The set of datastore field types which have no `properties` in the mapping, but which
+  # can be represented as a JSON object at indexing time.
+  #
+  # I built this list by auditing the full list of index field mapping types:
+  # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/mapping-types.html
+  DATASTORE_PROPERTYLESS_OBJECT_TYPES = [
+    "aggregate_metric_double", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/aggregate-metric-double.html
+    "completion", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-suggesters.html#completion-suggester
+    "flattened", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/flattened.html
+    "geo_point", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/geo-point.html
+    "geo_shape", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/geo-shape.html
+    "histogram", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/histogram.html
+    "join", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/parent-join.html
+    "percolator", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/percolator.html
+    "point", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/point.html
+    "range", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/range.html
+    "rank_features", # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/rank-features.html
+    "shape" # https://www.elastic.co/guide/en/elasticsearch/reference/8.9/shape.html
+  ].to_set
+
+  # This pattern matches the spec for a valid GraphQL name:
+  # http://spec.graphql.org/June2018/#sec-Names
+  #
+  # ...however, it allows additional non-valid characters before and after it.
+  GRAPHQL_NAME_WITHIN_LARGER_STRING_PATTERN = /[_A-Za-z][_0-9A-Za-z]*/
+
+  # This pattern exactly matches a valid GraphQL name, with no extra characters allowed before or after.
+  GRAPHQL_NAME_PATTERN = /\A#{GRAPHQL_NAME_WITHIN_LARGER_STRING_PATTERN}\z/
+
+  # Description in English of the requirements for GraphQL names. (Used in multiple error messages).
+  GRAPHQL_NAME_VALIDITY_DESCRIPTION = "Names are limited to ASCII alphanumeric characters (plus underscore), and cannot start with a number."
+
+  # The standard set of scalars that are defined by the GraphQL spec:
+  # https://spec.graphql.org/October2021/#sec-Scalars
+  STOCK_GRAPHQL_SCALARS = %w[Boolean Float ID Int String].to_set.freeze
+
+  # The current variant of JSON schema that we use.
+  JSON_META_SCHEMA = "http://json-schema.org/draft-07/schema#"
+
+  # Filter the bulk response payload with a comma separated list using dot notation.
+  # https://www.elastic.co/guide/en/elasticsearch/reference/7.10/common-options.html#common-options-response-filtering
+  #
+  # Note: anytime you change this constant, be sure to check all the comments in the unit specs that mention this constant.
+  # When stubbing a datastore client test double, it doesn't respect this filtering obviously, so it's up to us
+  # to accurately mimic the filtering in our stubbed responses.
+  DATASTORE_BULK_FILTER_PATH = [
+    # The key under `items` names the type of operation (e.g. `index` or `update`) and
+    # we use a `*` for it since we always use that key, regardless of which operation it is.
+    "items.*.status", "items.*.result", "items.*.error"
+  ].join(",")
+
+  # HTTP header set by `elasticgraph-graphql_lambda` to indicate the AWS ARN of the caller.
+  GRAPHQL_LAMBDA_AWS_ARN_HEADER = "X-AWS-LAMBDA-CALLER-ARN"
+
+  # TODO(steep): it complains about `define_schema` not being defined but it is defined
+  # in another file; I shouldn't have to say it's dynamic here. For now this works though.
+  # @dynamic self.define_schema
+end

data/lib/elastic_graph/error.rb

@@ -0,0 +1,99 @@
+# 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 Error < StandardError
+  end
+
+  class CursorEncoderError < Error
+  end
+
+  class InvalidSortFieldsError < CursorEncoderError
+  end
+
+  class InvalidCursorError < CursorEncoderError
+  end
+
+  class CursorEncodingError < CursorEncoderError
+  end
+
+  class CountUnavailableError < Error
+  end
+
+  class InvalidArgumentValueError < Error
+  end
+
+  class InvalidAggregationKeyError < Error
+  end
+
+  class InvalidMergeError < Error
+  end
+
+  class QueryMergeError < Error
+  end
+
+  class SchemaError < Error
+  end
+
+  class InvalidGraphQLNameError < SchemaError
+  end
+
+  class NotFoundError < Error
+  end
+
+  class SearchFailedError < Error
+  end
+
+  class RequestExceededDeadlineError < SearchFailedError
+  end
+
+  class IdentifyDocumentVersionsFailedError < Error
+  end
+
+  class IndexOperationError < Error
+  end
+
+  class ClusterOperationError < Error
+  end
+
+  class InvalidEventIDError < Error
+  end
+
+  class UnsupportedOperationError < Error
+  end
+
+  class InvalidExtensionError < Error
+  end
+
+  class ConfigError < Error
+  end
+
+  class ConfigSettingNotSetError < ConfigError
+  end
+
+  class ConfigCannotBeMutatedError < ConfigError
+  end
+
+  class UnknownYAMLSettingError < ConfigError
+  end
+
+  class InvalidScriptDirectoryError < Error
+  end
+
+  class MissingSchemaArtifactError < Error
+  end
+
+  class S3OperationFailedError < Error
+  end
+
+  class MessageIdsMissingError < Error
+  end
+
+  class BadDatastoreRequest < Error
+  end
+end

data/lib/elastic_graph/support/faraday_middleware/msearch_using_get_instead_of_post.rb

@@ -0,0 +1,31 @@
+# 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 Support
+    module FaradayMiddleware
+      # Custom Faraday middleware that forces `msearch` calls to use an HTTP GET instead of an HTTP POST. While not
+      # necessary, it preserves a useful property: all "read" calls made by ElasticGraph use an HTTP GET, and HTTP POST
+      # requests are "write" calls. This allows the access policy to only grant HTTP GET access from the GraphQL endpoint,
+      # which leads to a more secure setup (as the GraphQL endpoint can be blocked from performing any writes).
+      #
+      # Note: before elasticsearch-ruby 7.9.0, `msearch` used an HTTP GET request, so this simply restores that behavior.
+      # This results in an HTTP GET with a request body, but it works just fine and its what the Ruby Elasticsearch client
+      # did for years.
+      #
+      # For more info, see: https://github.com/elastic/elasticsearch-ruby/issues/1005
+      MSearchUsingGetInsteadOfPost = ::Data.define(:app) do
+        # @implements MSearchUsingGetInsteadOfPost
+        def call(env)
+          env.method = :get if env.url.path.to_s.end_with?("/_msearch")
+          app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/support/faraday_middleware/support_timeouts.rb

@@ -0,0 +1,36 @@
+# 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"
+require "elastic_graph/error"
+
+module ElasticGraph
+  module Support
+    module FaradayMiddleware
+      # Faraday supports specifying a timeout at both the client level (when building the Faraday connection) or on a
+      # per-request basis. We want to specify it on a per-request basis, but unfortunately, the Elasticsearch/OpenSearch
+      # clients don't provide any per-request API to specify the timeout (it only supports it when instantiating your
+      # client).
+      #
+      # This middleware helps us work around this deficiency by looking for the TIMEOUT_MS_HEADER. If present, it deletes
+      # it from the headers and instead sets it as the request timeout.
+      SupportTimeouts = ::Data.define(:app) do
+        # @implements SupportTimeouts
+        def call(env)
+          if (timeout_ms = env.request_headers.delete(TIMEOUT_MS_HEADER))
+            env.request.timeout = timeout_ms / 1000.0
+          end
+
+          app.call(env)
+        rescue ::Faraday::TimeoutError
+          raise RequestExceededDeadlineError, "Datastore request exceeded timeout of #{timeout_ms} ms."
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/support/from_yaml_file.rb

@@ -0,0 +1,53 @@
+# 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 "yaml"
+
+module ElasticGraph
+  module Support
+    module FromYamlFile
+      # Factory method that will build an instance from the provided `yaml_file`.
+      # `datastore_client_customization_block:` can be passed to customize the datastore clients.
+      # In addition, a block is accepted that can prepare the settings before the object is built
+      # (e.g. to override specific settings).
+      def from_yaml_file(yaml_file, datastore_client_customization_block: nil)
+        parsed_yaml = ::YAML.safe_load_file(yaml_file, aliases: true)
+        parsed_yaml = yield(parsed_yaml) if block_given?
+        from_parsed_yaml(parsed_yaml, &datastore_client_customization_block)
+      end
+
+      # An extension module that provides a `from_yaml_file` factory method on a `RakeTasks` class.
+      #
+      # This is designed for a `RakeTasks` class that needs an ElasticGraph component (e.g. an
+      # `ElasticGraph::GraphQL`, `ElasticGraph::Admin`, or `ElasticGraph::Indexer` instance).
+      # When the schema artifacts are out of date, loading those components can fail. This gracefully
+      # handles that for you, giving you clear instructions of what to do when this happens.
+      #
+      # This requires the `RakeTasks` class to accept the ElasticGraph component instance via a block
+      # so that it happens lazily.
+      class ForRakeTasks < ::Module
+        # @dynamic from_yaml_file
+
+        def initialize(component_class)
+          define_method :from_yaml_file do |yaml_file, *args, **options|
+            __skip__ = new(*args, **options) do
+              component_class.from_yaml_file(yaml_file)
+            rescue => e
+              raise <<~EOS
+                Failed to load `#{component_class}` with `#{yaml_file}`. This can happen if the schema artifacts are out of date.
+                Run `rake schema_artifacts:dump` and try again.
+
+                #{e.class}: #{e.message}
+              EOS
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/support/graphql_formatter.rb

@@ -0,0 +1,66 @@
+# 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 "json"
+
+module ElasticGraph
+  module Support
+    # Utility module that provides helper methods for generating well-formatted GraphQL syntax.
+    module GraphQLFormatter
+      # Formats the given hash as an argument list. If `args` is empty, returns an empty string.
+      # Otherwise, wraps the args list in parens. This allows the returned string to be appended
+      # to a field or directive, and it'll correctly use parens (or not) based on if there are args
+      # or not.
+      def self.format_args(**args)
+        return "" if args.empty?
+        "(#{serialize(args, wrap_hash_with_braces: false)})"
+      end
+
+      # Formats the given value in GraphQL syntax. This method was derived
+      # from a similar method from the graphql-ruby gem:
+      #
+      # https://github.com/rmosolgo/graphql-ruby/blob/v1.11.4/lib/graphql/language.rb#L17-L33
+      #
+      # We don't want to use that method because it is marked as `@api private`, indicating
+      # it could be removed in any release of the graphql gem. If we used it, it could hinder
+      # future upgrades.
+      #
+      # Our implementation here differs in a few ways:
+      #
+      # - case statement instead of multiple `if value.is_a?` checks (a bit cleaner)
+      # - `wrap_hash_with_braces` since we do not want to wrap an args hash with braces.
+      # - Readable spacing has been added so we get `foo: [1, 2], bar: 3` instead of `foo:[1,2],bar:3`.
+      # - Symbol support has been added. Symbols are converted to strings (with no quotes), allowing
+      #   callers to pass them for GraphQL enums.
+      # - We've removed the `quirks_mode: true` flag passed to `JSON.generate` since it has been
+      #   deprecated for a while: https://github.com/flori/json/issues/309
+      def self.serialize(value, wrap_hash_with_braces: true)
+        case value
+        when ::Hash
+          serialized_hash = value.map do |k, v|
+            "#{k}: #{serialize v}"
+          end.join(", ")
+
+          return serialized_hash unless wrap_hash_with_braces
+
+          "{#{serialized_hash}}"
+        when ::Array
+          serialized_array = value.map do |v|
+            serialize v
+          end.join(", ")
+
+          "[#{serialized_array}]"
+        when ::Symbol
+          value.to_s
+        else
+          ::JSON.generate(value)
+        end
+      end
+    end
+  end
+end