elasticgraph-support 0.18.0.4 → 0.18.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 877b7b0239bb8bf71a90c6b902caea22e9d896639c36559f8131a399baea2174
-  data.tar.gz: d9d00fd7c6e1d64623558d349d0c21cefa9917174fd3968fd36550dd8620ab33
+  metadata.gz: 3401374bff1226e88aa850996bb72ad365262290e06607d726ce10277fa43aee
+  data.tar.gz: fc8c31921a4e4200d1e3e2ec0a2dfeea9c5356d2a6a178daff1d601e78e7e8a1
 SHA512:
-  metadata.gz: 3bc7f20e71e4e2a01e75154f3f426b60175237d945b9cc6b615c1e17ca0ae8cc69fcfeb32cba432f0fd185f35ef9c88796ec665ef12a2892d35b1d58138b0783
-  data.tar.gz: 28039deba22250e2017713182b8a977de0af9dac17493c7343585e01932bc03c8649cfb92ba76480573c32146dcd296f4417300cd649470d8cb1d022448d9323
+  metadata.gz: 3ea8a800cd282d70a9799515112efdc1682a24e0ad990145b57450ac26941f8f140601882a3919da69e16eca2e97a1ef78532c5a3da9071fac1ec8d57f10acf2
+  data.tar.gz: e5517df699d8fcffa6db5e5064a995173cf7993022920a832c02e0376eb872b3ebaa35b053d59056e2cf275fe1053500c706718f69ef453e37b54dfe03a09328

data/lib/elastic_graph/constants.rb

@@ -6,18 +6,23 @@
 #
 # frozen_string_literal: true
 
-# Enumerates constants that are used from multiple places in the code.
+# Root namespace for all ElasticGraph code.
 module ElasticGraph
+  # Here we enumerate constants that are used from multiple places in the code.
+
   # 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
+  # @private
   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
+  # @private
   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.
+  # @private
   TIMEOUT_MS_HEADER = "ElasticGraph-Request-Timeout-Ms"
 
   # Min/max values for the `Int` type.
@@ -27,19 +32,25 @@ module ElasticGraph
   # > than or equal to 2^31, a field error should be raised.
   #
   # (from http://spec.graphql.org/June2018/#sec-Int)
+  # @private
   INT_MIN = -(2**31).to_int
+  # @private
   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
+  # @private
   JSON_SAFE_LONG_MIN = -((2**53) - 1).to_int
+  # @private
   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)
+  # @private
   LONG_STRING_MIN = -(2**63).to_int
+  # @private
   LONG_STRING_MAX = -LONG_STRING_MIN - 1
 
   # When indexing large string values into the datastore, we've observed errors like:
@@ -52,6 +63,7 @@ module ElasticGraph
   # 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.
+  # @private
   DEFAULT_MAX_KEYWORD_LENGTH = 32766 / 4
 
   # Strings indexed as `text` can be much larger than `keyword` fields. In fact, there's no limitation
@@ -65,9 +77,11 @@ module ElasticGraph
   # 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.
+  # @private
   DEFAULT_MAX_TEXT_LENGTH = 100 * (2**20).to_int
 
   # The name of the JSON schema definition for the ElasticGraph event envelope.
+  # @private
   EVENT_ENVELOPE_JSON_SCHEMA_NAME = "ElasticGraphEventEnvelope"
 
   # For some queries, we wind up needing a pagination cursor for a collection
@@ -76,23 +90,32 @@ module ElasticGraph
   # 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.
+  # @private
   SINGLETON_CURSOR = "eyJ1dWlkIjoiZGNhMDJkMjAtYmFlZS00ZWU5LWEwMjctZmVlY2UwYTZkZTNhIn0="
 
   # Schema artifact file names.
+  # @private
   GRAPHQL_SCHEMA_FILE = "schema.graphql"
+  # @private
   JSON_SCHEMAS_FILE = "json_schemas.yaml"
+  # @private
   DATASTORE_CONFIG_FILE = "datastore_config.yaml"
+  # @private
   RUNTIME_METADATA_FILE = "runtime_metadata.yaml"
 
   # Name for directory that contains versioned json_schemas files.
+  # @private
   JSON_SCHEMAS_BY_VERSION_DIRECTORY = "json_schemas_by_version"
   # Name for field in json schemas files that represents schema "version".
+  # @private
   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).
+  # @private
   ROLLOVER_INDEX_INFIX_MARKER = "_rollover__"
 
+  # @private
   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
@@ -101,6 +124,7 @@ module ElasticGraph
   # 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.
+  # @private
   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
@@ -108,6 +132,7 @@ module ElasticGraph
   # upon this id.
   #
   # TODO: Drop this when we no longer need to maintain backwards-compatibility.
+  # @private
   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
@@ -116,6 +141,7 @@ module ElasticGraph
   # 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.
+  # @private
   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`
@@ -123,10 +149,12 @@ module ElasticGraph
   # 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.
+  # @private
   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.
+  # @private
   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
@@ -136,6 +164,7 @@ module ElasticGraph
   # For more info, see:
   # https://json-schema.org/understanding-json-schema/reference/regular_expressions.html
   # http://www.rexegg.com/regex-anchors.html
+  # @private
   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.
@@ -144,6 +173,7 @@ module ElasticGraph
   #
   # 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.
+  # @private
   LIST_COUNTS_FIELD = "__counts"
 
   # Character used to separate parts of a field path for the keys in the special `__counts`
@@ -158,6 +188,7 @@ module ElasticGraph
   # (for the parent list count) and an object containing counts of its child lists.
   #
   # By using `|` instead of `.`, we avoid this problem.
+  # @private
   LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR = "|"
 
   # The set of datastore field types which have no `properties` in the mapping, but which
@@ -165,6 +196,7 @@ module ElasticGraph
   #
   # 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
+  # @private
   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
@@ -184,19 +216,24 @@ module ElasticGraph
   # http://spec.graphql.org/June2018/#sec-Names
   #
   # ...however, it allows additional non-valid characters before and after it.
+  # @private
   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.
+  # @private
   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).
+  # @private
   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
+  # @private
   STOCK_GRAPHQL_SCALARS = %w[Boolean Float ID Int String].to_set.freeze
 
   # The current variant of JSON schema that we use.
+  # @private
   JSON_META_SCHEMA = "http://json-schema.org/draft-07/schema#"
 
   # Filter the bulk response payload with a comma separated list using dot notation.
@@ -205,6 +242,7 @@ module ElasticGraph
   # 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.
+  # @private
   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.
@@ -212,6 +250,7 @@ module ElasticGraph
   ].join(",")
 
   # HTTP header set by `elasticgraph-graphql_lambda` to indicate the AWS ARN of the caller.
+  # @private
   GRAPHQL_LAMBDA_AWS_ARN_HEADER = "X-AWS-LAMBDA-CALLER-ARN"
 
   # TODO(steep): it complains about `define_schema` not being defined but it is defined

data/lib/elastic_graph/errors.rb

@@ -0,0 +1,84 @@
+# 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
+  # @private
+  module Errors
+    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 InvalidMergeError < 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 InvalidExtensionError < Error
+    end
+
+    class ConfigError < Error
+    end
+
+    class ConfigSettingNotSetError < ConfigError
+    end
+
+    class InvalidScriptDirectoryError < Error
+    end
+
+    class MissingSchemaArtifactError < Error
+    end
+
+    class S3OperationFailedError < Error
+    end
+
+    class MessageIdsMissingError < Error
+    end
+
+    class BadDatastoreRequest < Error
+    end
+  end
+end

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

@@ -8,6 +8,7 @@
 
 module ElasticGraph
   module Support
+    # @private
     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

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

@@ -7,10 +7,11 @@
 # frozen_string_literal: true
 
 require "elastic_graph/constants"
-require "elastic_graph/error"
+require "elastic_graph/errors"
 
 module ElasticGraph
   module Support
+    # @private
     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
@@ -28,7 +29,7 @@ module ElasticGraph
 
           app.call(env)
         rescue ::Faraday::TimeoutError
-          raise RequestExceededDeadlineError, "Datastore request exceeded timeout of #{timeout_ms} ms."
+          raise Errors::RequestExceededDeadlineError, "Datastore request exceeded timeout of #{timeout_ms} ms."
         end
       end
     end

data/lib/elastic_graph/support/from_yaml_file.rb

@@ -9,7 +9,10 @@
 require "yaml"
 
 module ElasticGraph
+  # Provides support utilities for the rest of the ElasticGraph gems. As such, it is not intended
+  # to provide public APIs for ElasticGraph users.
   module Support
+    # @private
     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.

data/lib/elastic_graph/support/graphql_formatter.rb

@@ -11,6 +11,8 @@ require "json"
 module ElasticGraph
   module Support
     # Utility module that provides helper methods for generating well-formatted GraphQL syntax.
+    #
+    # @private
     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

data/lib/elastic_graph/support/hash_util.rb

@@ -8,6 +8,7 @@
 
 module ElasticGraph
   module Support
+    # @private
     class HashUtil
       # Fetches a key from a hash (just like `Hash#fetch`) but with a more verbose error message when the key is not found.
       # The error message indicates the available keys unlike `Hash#fetch`.

data/lib/elastic_graph/support/logger.rb

@@ -6,19 +6,21 @@
 #
 # frozen_string_literal: true
 
-require "elastic_graph/error"
+require "elastic_graph/errors"
 require "json"
 require "logger"
 require "pathname"
 
 module ElasticGraph
   module Support
+    # @private
     module Logger
       # Builds a logger instance from the given parsed YAML config.
       def self.from_parsed_yaml(parsed_yaml)
         Factory.build(config: Config.from_parsed_yaml(parsed_yaml))
       end
 
+      # @private
       module Factory
         def self.build(config:, device: nil)
           ::Logger.new(
@@ -29,6 +31,7 @@ module ElasticGraph
         end
       end
 
+      # @private
       class JSONAwareFormatter
         def initialize
           @original_formatter = ::Logger::Formatter.new
@@ -40,6 +43,7 @@ module ElasticGraph
         end
       end
 
+      # @private
       class Config < ::Data.define(
         # Determines what severity level we log. Valid values are `DEBUG`, `INFO`, `WARN`,
         # `ERROR`, `FATAL` and `UNKNOWN`.
@@ -65,7 +69,7 @@ module ElasticGraph
           extra_keys = hash.keys - EXPECTED_KEYS
 
           unless extra_keys.empty?
-            raise ConfigError, "Unknown `logger` config settings: #{extra_keys.join(", ")}"
+            raise Errors::ConfigError, "Unknown `logger` config settings: #{extra_keys.join(", ")}"
           end
 
           new(

data/lib/elastic_graph/support/monotonic_clock.rb

@@ -9,6 +9,8 @@
 module ElasticGraph
   module Support
     # A simple abstraction that provides a monotonic clock.
+    #
+    # @private
     class MonotonicClock
       # Returns an abstract "now" value in integer milliseconds, suitable for calculating
       # a duration or deadline, without being impacted by leap seconds, etc.

data/lib/elastic_graph/support/threading.rb

@@ -8,6 +8,7 @@
 
 module ElasticGraph
   module Support
+    # @private
     module Threading
       # Like Enumerable#map, but performs the map in parallel using one thread per list item.
       # Exceptions that happen in the threads will propagate to the caller at the end.

data/lib/elastic_graph/support/time_set.rb

@@ -20,6 +20,8 @@ module ElasticGraph
     # - An open range: a range with only an upper or lower bound (but not the other).
     # - A closed range: a range with an upper and lower bound.
     # - An empty range: a range that contains no `::Time`s, by virtue of its bounds having no overlap.
+    #
+    # @private
     class TimeSet < ::Data.define(:ranges)
       # Factory method to construct a `TimeSet` using a range with the given bounds.
       def self.of_range(gt: nil, gte: nil, lt: nil, lte: nil)

data/lib/elastic_graph/support/time_util.rb

@@ -8,6 +8,7 @@
 
 module ElasticGraph
   module Support
+    # @private
     module TimeUtil
       NANOS_PER_SECOND = 1_000_000_000
       NANOS_PER_MINUTE = NANOS_PER_SECOND * 60

data/lib/elastic_graph/support/untyped_encoder.rb

@@ -19,6 +19,8 @@ module ElasticGraph
     # Note: change this class with care. Changing the behavior to make `encode` produce different strings may result
     # in breaking queries if the `Untyped`s stored in the index were indexed using previous encoding logic.
     # A backfill into the datastore will likely be required to avoid this issue.
+    #
+    # @private
     module UntypedEncoder
       # Encodes the given untyped value to a String so it can be indexed in a Elasticsearch/OpenSearch `keyword` field.
       def self.encode(value)

data/lib/elastic_graph/version.rb

@@ -8,7 +8,7 @@
 
 module ElasticGraph
   # The version of all ElasticGraph gems.
-  VERSION = "0.18.0.4"
+  VERSION = "0.18.0.5"
 
   # Steep weirdly expects this here...
   # @dynamic self.define_schema

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: elasticgraph-support
 version: !ruby/object:Gem::Version
-  version: 0.18.0.4
+  version: 0.18.0.5
 platform: ruby
 authors:
 - Myron Marston
+- Ben VandenBos
+- Square Engineering
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop-factory_bot
@@ -229,7 +231,7 @@ files:
 - README.md
 - elasticgraph-support.gemspec
 - lib/elastic_graph/constants.rb
-- lib/elastic_graph/error.rb
+- lib/elastic_graph/errors.rb
 - lib/elastic_graph/support/faraday_middleware/msearch_using_get_instead_of_post.rb
 - lib/elastic_graph/support/faraday_middleware/support_timeouts.rb
 - lib/elastic_graph/support/from_yaml_file.rb

data/lib/elastic_graph/error.rb

@@ -1,99 +0,0 @@
-# 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