elasticgraph-apollo 0.18.0.3 → 0.18.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dae49f79841e10b6f077fd5b3970ec089d2aa99860b38aa72cb9c4f148a964f4
-  data.tar.gz: '0419de0b47e8a5a3365c880ee9e4426d6b46a21417db7b0c2ce9355beef459d3'
+  metadata.gz: 3235e538afce544de3826c7a362fe218f5e964b79cab3d6920ea10ac2c4b9472
+  data.tar.gz: f2f70701103e038b6aef58ede5336246515a6b8366d00d60f2d01074be7572ad
 SHA512:
-  metadata.gz: 28483d6a323c35504c470525e79a237411e26d407d82379945f083b004e1f16da0d3c76d76c1090116b9ed8c6e0f1c4ef5896e61f717c018044a1b9b636866b0
-  data.tar.gz: c4bb68144864c3c020fded7129ae4ec8708e5d3f90d9c04c79133ccdb8ab1a37352d9c71813b9b88c7f41c1d0012d09e74d365534e8de7bce4bd25bc8d17575f
+  metadata.gz: 2983677d53e108788a4ce91d53992eafa620910a972ca66dabb40900795df1c5a9761b8bfffe91256c1e64412c3f76ad6900fa167fbdfdb62c04a3232d2ab033
+  data.tar.gz: f757d64002f6da0a093cca909eb29340df512f5f9eb2503dc328dc197319e05b1081512f3f7ff41a44457cc90c5187faa4c15c372b6ecc44ea9ed4d44c87b5b8

data/apollo_tests_implementation/config/products_schema.rb

@@ -6,6 +6,7 @@
 #
 # frozen_string_literal: true
 
+# @private
 module ApolloTestImpl
   module GraphQLSDLEnumeratorExtension
     # The `apollo-federation-subgraph-compatibility` project requires[^1] that each tested implementation provide
@@ -38,6 +39,7 @@ module ApolloTestImpl
     end
   end
 
+  # @private
   module SchemaDefFactoryExtension
     def new_graphql_sdl_enumerator(all_types_except_root_query_type)
       super(all_types_except_root_query_type).tap do |enum|

data/apollo_tests_implementation/lib/test_implementation_extension.rb

@@ -13,6 +13,7 @@
 # it.
 #
 # This defines an extension that injects a custom resolver that supports the field.
+# @private
 module ApolloTestImplementationExtension
   def graphql_resolvers
     @graphql_resolvers ||= [product_field_resolver] + super
@@ -26,6 +27,7 @@ module ApolloTestImplementationExtension
     )
   end
 
+  # @private
   class ProductFieldResolver
     def initialize(datastore_query_builder:, product_index_def:, datastore_router:)
       @datastore_query_builder = datastore_query_builder

data/lib/elastic_graph/apollo/graphql/engine_extension.rb

@@ -8,10 +8,17 @@
 
 module ElasticGraph
   module Apollo
+    # Namespace for all Apollo GraphQL enging logic.
+    #
+    # @note This module provides no public types or APIs. It will be used automatically when you use
+    #   {SchemaDefinition::APIExtension} as a schema definition extension module.
     module GraphQL
       # ElasticGraph application extension module designed to hook into the ElasticGraph
       # GraphQL engine in order to support Apollo-specific fields.
+      #
+      # @private
       module EngineExtension
+        # @private
         def graphql_resolvers
           @graphql_resolvers ||= begin
             require "elastic_graph/apollo/graphql/entities_field_resolver"
@@ -27,6 +34,7 @@ module ElasticGraph
           end
         end
 
+        # @private
         def graphql_gem_plugins
           @graphql_gem_plugins ||= begin
             require "apollo-federation/tracing/proto"
@@ -40,6 +48,7 @@ module ElasticGraph
           end
         end
 
+        # @private
         def graphql_http_endpoint
           @graphql_http_endpoint ||= super.tap do |endpoint|
             require "elastic_graph/apollo/graphql/http_endpoint_extension"

data/lib/elastic_graph/apollo/graphql/entities_field_resolver.rb

@@ -6,7 +6,7 @@
 #
 # frozen_string_literal: true
 
-require "elastic_graph/error"
+require "elastic_graph/errors"
 require "elastic_graph/graphql/query_adapter/requested_fields"
 require "elastic_graph/graphql/resolvers/query_source"
 
@@ -16,6 +16,8 @@ module ElasticGraph
       # GraphQL resolver for the Apollo `Query._entities` field. For details on this field, see:
       #
       # https://www.apollographql.com/docs/federation/subgraph-spec/#resolve-requests-for-entities
+      #
+      # @private
       class EntitiesFieldResolver
         def initialize(datastore_query_builder:, schema_element_names:)
           @datastore_query_builder = datastore_query_builder
@@ -100,7 +102,7 @@ module ElasticGraph
 
           type = begin
             schema.type_named(typename)
-          rescue ElasticGraph::NotFoundError
+          rescue ElasticGraph::Errors::NotFoundError
             notify_error.call("has an unrecognized `__typename`: #{typename}")
           end
 
@@ -145,6 +147,8 @@ module ElasticGraph
         end
 
         # A simple value object containing a parsed form of an `_Any` representation when there's an `id` field.
+        #
+        # @private
         class RepresentationWithId < ::Data.define(:type, :id, :other_fields, :schema_element_names, :adapter)
           def initialize(type:, id:, other_fields:, schema_element_names:)
             super(
@@ -225,6 +229,8 @@ module ElasticGraph
         end
 
         # A simple value object containing a parsed form of an `_Any` representation when there's no `id` field.
+        #
+        # @private
         class RepresentationWithoutId < ::Data.define(:type, :fields, :schema_element_names)
           # @dynamic type
 
@@ -277,6 +283,7 @@ module ElasticGraph
           end
         end
 
+        # @private
         class RepresentationWithoutIndex < ::Data.define(:type, :representation_hash)
           # @dynamic type
           def adapter

data/lib/elastic_graph/apollo/graphql/http_endpoint_extension.rb

@@ -23,6 +23,8 @@ module ElasticGraph
       #
       # This extension handles the latter requirement. For more info, see:
       # https://github.com/Gusto/apollo-federation-ruby#tracing
+      #
+      # @private
       module HTTPEndpointExtension
         def with_context(request)
           # Steep has an error here for some reason:

data/lib/elastic_graph/apollo/graphql/service_field_resolver.rb

@@ -10,6 +10,8 @@ module ElasticGraph
   module Apollo
     module GraphQL
       # GraphQL resolver for the Apollo `Query._service` field.
+      #
+      # @private
       class ServiceFieldResolver
         def can_resolve?(field:, object:)
           field.parent_type.name == :Query && field.name == :_service

data/lib/elastic_graph/apollo/schema_definition/api_extension.rb

@@ -6,7 +6,7 @@
 #
 # frozen_string_literal: true
 
-require "elastic_graph/error"
+require "elastic_graph/errors"
 require "elastic_graph/version"
 require "elastic_graph/apollo/graphql/engine_extension"
 require "elastic_graph/apollo/schema_definition/entity_type_extension"
@@ -14,17 +14,52 @@ require "elastic_graph/apollo/schema_definition/factory_extension"
 require "elastic_graph/apollo/schema_definition/state_extension"
 
 module ElasticGraph
+  # ElasticGraph extension library that implements the [Apollo subgraph federation
+  # spec](https://www.apollographql.com/docs/federation/subgraph-spec/), turning
+  # any ElasticGraph instance into an Apollo subgraph.
+  #
+  # `ElasticGraph::Apollo` has two parts:
+  #
+  # * {Apollo::SchemaDefinition} is an extension used while defining an ElasticGraph schema. It includes all schema elements that are part
+  #   of the Apollo spec, including `_Entity` and the various directives.
+  # * {Apollo::GraphQL} is an extension used by `elasticgraph-graphql` to support queries against Apollo's subgraph schema additions (e.g.
+  #   `_service` and `_entities`). It includes [reference resolvers](https://www.apollographql.com/docs/federation/entities/#2-define-a-reference-resolver)
+  #   for all indexed types in your schema.
+  #
+  # To use `elasticgraph-apollo`, simply use {Apollo::SchemaDefinition::APIExtension} as a schema definition extension module. The GraphQL
+  # extension module will get used by `elasticgraph-graphql` automatically.
+  #
+  # @example Use elasticgraph-apollo in a project
+  #   require "elastic_graph/apollo/schema_definition/api_extension"
+  #
+  #   ElasticGraph::Local::RakeTasks.new(
+  #     local_config_yaml: "config/settings/local.yaml",
+  #     path_to_schema: "config/schema.rb"
+  #   ) do |tasks|
+  #     tasks.schema_definition_extension_modules = [ElasticGraph::Apollo::SchemaDefinition::APIExtension]
+  #   end
   module Apollo
+    # Namespace for all Apollo schema definition support.
+    #
+    # {SchemaDefinition::APIExtension} is the primary entry point and should be used as a schema definition extension module.
     module SchemaDefinition
-      # Module designed to be extended onto an `ElasticGraph::SchemaDefinition::API` instance
-      # to customize the schema artifacts based on the Apollo Federation subgraph spec:
+      # Module designed to be extended onto an {ElasticGraph::SchemaDefinition::API} instance
+      # to customize the schema artifacts based on the [Apollo Federation subgraph
+      # spec](https://www.apollographql.com/docs/federation/subgraph-spec/).
       #
-      # https://www.apollographql.com/docs/federation/subgraph-spec/
+      # To use this module, pass it in `schema_definition_extension_modules` when defining your {ElasticGraph::Local::RakeTasks}.
       #
-      # Note that at this time we do not yet support extending a type owned by another
-      # subgraph (which the `@requires`, `@provides`, `@extends`, and `@external`
-      # directives are used for).
+      # @example Define local rake tasks with this extension module
+      #   require "elastic_graph/apollo/schema_definition/api_extension"
+      #
+      #   ElasticGraph::Local::RakeTasks.new(
+      #     local_config_yaml: "config/settings/local.yaml",
+      #     path_to_schema: "config/schema.rb"
+      #   ) do |tasks|
+      #     tasks.schema_definition_extension_modules = [ElasticGraph::Apollo::SchemaDefinition::APIExtension]
+      #   end
       module APIExtension
+        # @private
         def results
           register_graphql_extension GraphQL::EngineExtension, defined_at: "elastic_graph/apollo/graphql/engine_extension"
           define_apollo_schema_elements
@@ -32,18 +67,37 @@ module ElasticGraph
           super
         end
 
-        # Called from the public API, as:
-        #   schema.tag_built_in_types_with "tag-name", except: ["IntAggregatedValues", ...]
+        # Applies an apollo tag to built-in types so that they are included in the Apollo contract schema.
+        #
+        # @param name [String] tag name
+        # @param except [Array<String>] built-in types not to tag
+        # @return [void]
+        # @see ApolloDirectives::Tag
+        # @see FieldExtension#tag_with
+        #
+        # @example Tag all built-in types (except two) for inclusion in the `public` schema
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.tag_built_in_types_with "public", except: ["IntAggregatedValue", "FloatAggregatedValues"]
+        #   end
         def tag_built_in_types_with(name, except: [])
           except_set = except.to_set
           on_built_in_types do |type|
-            type.directive("tag", name: name) unless except_set.include?(type.name)
+            apollo_type = (_ = type) # : ApolloDirectives::Tag
+            apollo_type.apollo_tag(name: name) unless except_set.include?(type.name)
           end
         end
 
         # Picks which version of Apollo federation to target. By default, the latest supported version is
         # targeted, but you can call this to pick an earlier version, which may be necessary if your
-        # organization is running an old version of Apollo studio.
+        # organization is on an older version of Apollo federation.
+        #
+        # @param version [String] version number
+        # @return [void]
+        #
+        # @example Set the Apollo Federation Version
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.target_apollo_federation_version "2.6"
+        #   end
         def target_apollo_federation_version(version)
           # Allow the version to have the `v` prefix, but don't require it.
           version = version.delete_prefix("v")
@@ -53,7 +107,7 @@ module ElasticGraph
               "v#{version_number}"
             end.join(", ")
 
-            raise SchemaError, "elasticgraph-apollo v#{ElasticGraph::VERSION} does not support Apollo federation v#{version}. " \
+            raise Errors::SchemaError, "elasticgraph-apollo v#{ElasticGraph::VERSION} does not support Apollo federation v#{version}. " \
               "Pick one of the supported versions (#{supported_version_descriptions}) instead."
           end
         end
@@ -390,7 +444,7 @@ module ElasticGraph
             end
 
           if unresolvable_field_errors.any?
-            raise SchemaError, unresolvable_field_errors.join("\n#{"-" * 100}\n")
+            raise Errors::SchemaError, unresolvable_field_errors.join("\n#{"-" * 100}\n")
           end
         end
       end

data/lib/elastic_graph/apollo/schema_definition/apollo_directives.rb

@@ -9,106 +9,274 @@
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Namespace for mixins that provide support for Apollo's [federation directives](https://www.apollographql.com/docs/federation/federated-schemas/federated-directives/).
+      # Each Apollo federation directive is offered via an API starting with `apollo`. For example, `apollo_key` can be used to define an
+      # Apollo `@key`.
       module ApolloDirectives
+        # Supports Apollo's [`@authenticated` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#authenticated).
         module Authenticated
-          # Extension method designed to support Apollo's authenticated directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#authenticated
+          # Adds the [`@authenticated` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#authenticated)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@authenticated` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_authenticated
+          #     end
+          #   end
           def apollo_authenticated
             directive "authenticated"
           end
         end
 
+        # Supports Apollo's [`@extends` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#extends).
         module Extends
-          # Extension method designed to support Apollo's extends directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#extends
+          # Adds the [`@extends` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#extends)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@extends` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_extends
+          #     end
+          #   end
           def apollo_extends
             directive "extends"
           end
         end
 
+        # Supports Apollo's [`@external` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#external).
         module External
-          # Extension method designed to support Apollo's external directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#external
+          # Adds the [`@external` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#external)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@external` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_external
+          #     end
+          #   end
           def apollo_external
             directive "external"
           end
         end
 
+        # Supports Apollo's [`@inaccessible` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#inaccessible).
         module Inaccessible
-          # Extension method designed to support Apollo's inaccessible directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#inaccessible
+          # Adds the [`@inaccessible` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#inaccessible)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@inaccessible` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_inaccessible
+          #     end
+          #   end
           def apollo_inaccessible
             directive "inaccessible"
           end
         end
 
+        # Supports Apollo's [`@interfaceObject` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#interfaceobject).
         module InterfaceObject
-          # Extension method designed to support Apollo's interfaceObject directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#interfaceObject
+          # Adds the [`@interfaceObject` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#interfaceobject)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@interfaceObject` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_interface_object
+          #     end
+          #   end
           def apollo_interface_object
             directive "interfaceObject"
           end
         end
 
+        # Supports Apollo's [`@key` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#key).
         module Key
-          # Extension method designed to support Apollo's key directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#key
+          # Adds the [`@key` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#key)
+          # to the schema element.
+          #
+          # @param fields [String] A GraphQL selection set (provided as a string) of fields and subfields that contribute to the entity's
+          #   unique key.
+          # @param resolvable [Boolean] If false, indicates to the Apollo router that this subgraph doesn't define a reference resolver for
+          #   this entity. This means that router query plans can't "jump to" this subgraph to resolve fields that aren't defined in another
+          #   subgraph.
+          # @return [void]
+          #
+          # @example Define a `@key` on a non-indexed type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.field "organizationId", "ID"
+          #       t.field "id", "ID"
+          #       t.apollo_key fields: "id organizationId", resolvable: false
+          #     end
+          #   end
+          #
+          # @note ElasticGraph automatically defines an `apollo_key` of `id` for every indexed type. This API is only needed when defining
+          #   additional keys on an indexed type, or defining a key for a non-indexed type.
           def apollo_key(fields:, resolvable: true)
             directive "key", fields: fields, resolvable: resolvable
           end
         end
 
+        # Supports Apollo's [`@override` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#override).
         module Override
-          # Extension method designed to support Apollo's override directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#override
+          # Adds the [`@override` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#override)
+          # to the schema element.
+          #
+          # @param from [String] The name of the other subgraph that no longer resolves the field.
+          # @return [void]
+          #
+          # @example Add `@override` to a field
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Product" do |t|
+          #       t.field "inStock", "Boolean" do |f|
+          #         f.apollo_override from: "Products"
+          #       end
+          #     end
+          #   end
           def apollo_override(from:)
             directive "override", from: from
           end
         end
 
+        # Supports Apollo's [`@policy` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#policy).
         module Policy
-          # Extension method designed to support Apollo's policy directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#policy
+          # Adds the [`@policy` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#policy)
+          # to the schema element.
+          #
+          # @param policies [Array<String>] List of authorization policies.
+          # @return [void]
+          #
+          # @example Add `@policy` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_policy policies: ["Policy1", "Policy2"]
+          #     end
+          #   end
           def apollo_policy(policies:)
             directive "policy", policies: policies
           end
         end
 
+        # Supports Apollo's [`@provides` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#provides).
         module Provides
-          # Extension method designed to support Apollo's provides directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#provides
+          # Adds the [`@provides` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#provides)
+          # to the schema element.
+          #
+          # @param fields [String] A GraphQL selection set (provided as a string) of object fields and subfields that the subgraph can
+          #   resolve only at this query path.
+          # @return [void]
+          #
+          # @example Add `@provides` to a field
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Product" do |t|
+          #       t.field "name", "String"
+          #     end
+          #
+          #     schema.object_type "StoreLocation" do |t|
+          #       t.field "products", "[Product!]!" do |f|
+          #         f.mapping type: "nested"
+          #         f.apollo_provides fields: "name"
+          #       end
+          #     end
+          #   end
           def apollo_provides(fields:)
             directive "provides", fields: fields
           end
         end
 
+        # Supports Apollo's [`@requires` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#requires).
         module Requires
-          # Extension method designed to support Apollo's requires directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#requires
+          # Adds the [`@requires` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#requires)
+          # to the schema element.
+          #
+          # @param fields [String] A GraphQL selection set (provided as a string) of object fields and subfields that the subgraph can
+          #   resolve only at this query path.
+          # @return [void]
+          #
+          # @example Add `@requires` to a field
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Product" do |t|
+          #       t.field "size", "Int"
+          #       t.field "weight", "Int"
+          #       t.field "shippingEstimate", "String" do |f|
+          #         f.apollo_requires fields: "size weight"
+          #       end
+          #     end
+          #   end
           def apollo_requires(fields:)
             directive "requires", fields: fields
           end
         end
 
+        # Supports Apollo's [`@requiresScopes` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#requiresscopes).
         module RequiresScopes
-          # Extension method designed to support Apollo's requiresScopes directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#requiresscopes
+          # Adds the [`@requiresScopes` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#requiresscopes)
+          # to the schema element.
+          #
+          # @param scopes [Array<String>] List of JWT scopes that must be granted to the user in order to access the underlying element data.
+          # @return [void]
+          #
+          # @example Add `@requiresScopes` to a field
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Product" do |t|
+          #       t.field "shippingEstimate", "String" do |f|
+          #         f.apollo_requires_scopes scopes: "shipping"
+          #       end
+          #     end
+          #   end
           def apollo_requires_scopes(scopes:)
             directive "requiresScopes", scopes: scopes
           end
         end
 
+        # Supports Apollo's [`@shareable` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#shareable).
         module Shareable
-          # Extension method designed to support Apollo's shareable directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#shareable
+          # Adds the [`@shareable` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#shareable)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@shareable` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_shareable
+          #     end
+          #   end
           def apollo_shareable
             directive "shareable"
           end
         end
 
+        # Supports Apollo's [`@tag` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#tag).
         module Tag
-          # Extension method designed to support Apollo's tag directive:
-          # https://www.apollographql.com/docs/federation/federated-types/federated-directives/#tag
+          # Adds the [`@tag` directive](https://www.apollographql.com/docs/federation/federated-types/federated-directives/#tag)
+          # to the schema element.
+          #
+          # @return [void]
+          #
+          # @example Add `@tag` to a type
+          #   ElasticGraph.define_schema do |schema|
+          #     schema.object_type "Campaign" do |t|
+          #       t.apollo_tag name: "public"
+          #     end
+          #   end
+          #
+          # @see APIExtension#tag_built_in_types_with
+          # @see FieldExtension#tag_with
           def apollo_tag(name:)
             directive "tag", name: name
           end

data/lib/elastic_graph/apollo/schema_definition/argument_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::Argument} to offer Apollo argument directives.
       module ArgumentExtension
         include ApolloDirectives::Inaccessible
         include ApolloDirectives::Tag

data/lib/elastic_graph/apollo/schema_definition/entity_type_extension.rb

@@ -16,6 +16,8 @@ module ElasticGraph
       #   usually cause it to be treated as indexed!).
       # - A merged set of `graphql_fields_by_name` cannot be safely computed. That method raises errors if a field with the same name
       #   has conflicting definitions on different subtypes, but we must allow that on `_Entity` subtypes.
+      #
+      # @private
       module EntityTypeExtension
         def graphql_fields_by_name
           {}

data/lib/elastic_graph/apollo/schema_definition/enum_type_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::EnumType} to offer Apollo enum type directives.
       module EnumTypeExtension
         include ApolloDirectives::Authenticated
         include ApolloDirectives::Inaccessible

data/lib/elastic_graph/apollo/schema_definition/enum_value_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::EnumValue} to offer Apollo enum value directives.
       module EnumValueExtension
         include ApolloDirectives::Inaccessible
         include ApolloDirectives::Tag

data/lib/elastic_graph/apollo/schema_definition/factory_extension.rb

@@ -21,6 +21,8 @@ module ElasticGraph
   module Apollo
     module SchemaDefinition
       # Extension module applied to `ElasticGraph::SchemaDefinition::Factory` to add Apollo tagging support.
+      #
+      # @private
       module FactoryExtension
         # Steep has a hard type with the arg splats here.
         __skip__ = def new_field(**kwargs)

data/lib/elastic_graph/apollo/schema_definition/field_extension.rb

@@ -11,7 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
-      # Extension module applied to `ElasticGraph::SchemaDefinition::SchemaElements::Field` to add Apollo tagging support.
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::Field} to offer Apollo field directives.
       module FieldExtension
         include ApolloDirectives::Authenticated
         include ApolloDirectives::External
@@ -24,13 +24,26 @@ module ElasticGraph
         include ApolloDirectives::Shareable
         include ApolloDirectives::Tag
 
-        # Extension method designed to support Apollo's contract variant tagging:
+        # Extension method designed to support Apollo's [contract variant tagging](https://www.apollographql.com/docs/studio/contracts/).
         #
-        # https://www.apollographql.com/docs/studio/contracts/
+        # Calling this method on a field will cause the field and every schema element derived from the field (e.g. the filter field,
+        # he aggregation field, etc), to be tagged with the given `tag_name`, ensuring that all capabilities related to the field are
+        # available in the contract variant.
         #
-        # Calling this method on a field will cause the field to be tagged and also every schema element derived from
-        # the field (e.g. the filter field, the aggregation field, an the sort order enum), ensuring that all capabilities
-        # related to the field are available in the contract variant.
+        # @param tag_name [String] tag to add to schema elements generated for this field
+        # @return [void]
+        #
+        # @example Tag a field (and its derived elements) with "public"
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "name", "String" do |f|
+        #         f.tag_with "public"
+        #       end
+        #     end
+        #   end
+        #
+        # @see ApolloDirectives::Tag
+        # @see APIExtension#tag_built_in_types_with
         def tag_with(tag_name)
           on_each_generated_schema_element do |element|
             needs_tagging =
@@ -50,6 +63,10 @@ module ElasticGraph
         end
 
         # Helper method that indicates if the given schema element has a specific tag.
+        #
+        # @param element [Object] element to check
+        # @param tag_name [String] tag to check
+        # @return [Boolean]
         def self.tagged_with?(element, tag_name)
           element.directives.any? { |dir| dir.name == "tag" && dir.arguments == {name: tag_name} }
         end

data/lib/elastic_graph/apollo/schema_definition/graphql_sdl_enumerator_extension.rb

@@ -11,6 +11,8 @@ module ElasticGraph
     module SchemaDefinition
       # Module designed to be extended onto an `ElasticGraph::SchemaDefinition::GraphQLSDLEnumerator`
       # instance to customize the schema artifacts to support Apollo.
+      #
+      # @private
       module GraphQLSDLEnumeratorExtension
         def root_query_type
           super.tap do |type_or_nil|

data/lib/elastic_graph/apollo/schema_definition/input_type_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::InputType} to offer Apollo input type directives.
       module InputTypeExtension
         include ApolloDirectives::Inaccessible
         include ApolloDirectives::Tag

data/lib/elastic_graph/apollo/schema_definition/interface_type_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::InterfaceType} to offer Apollo interface type directives.
       module InterfaceTypeExtension
         include ApolloDirectives::Authenticated
         include ApolloDirectives::Extends

data/lib/elastic_graph/apollo/schema_definition/object_type_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::ObjectType} to offer Apollo object type directives.
       module ObjectTypeExtension
         include ApolloDirectives::Authenticated
         include ApolloDirectives::Extends

data/lib/elastic_graph/apollo/schema_definition/scalar_type_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::ScalarType} to offer Apollo scalar type directives.
       module ScalarTypeExtension
         include ApolloDirectives::Authenticated
         include ApolloDirectives::Inaccessible

data/lib/elastic_graph/apollo/schema_definition/state_extension.rb

@@ -10,6 +10,8 @@ module ElasticGraph
   module Apollo
     module SchemaDefinition
       # Extension module applied to `ElasticGraph::SchemaDefinition::State` to support extra Apollo state.
+      #
+      # @private
       module StateExtension
         # @dynamic apollo_directive_definitions, apollo_directive_definitions=
         attr_accessor :apollo_directive_definitions

data/lib/elastic_graph/apollo/schema_definition/union_type_extension.rb

@@ -11,6 +11,7 @@ require "elastic_graph/apollo/schema_definition/apollo_directives"
 module ElasticGraph
   module Apollo
     module SchemaDefinition
+      # Extends {ElasticGraph::SchemaDefinition::SchemaElements::UnionType} to offer Apollo union type directives.
       module UnionTypeExtension
         include ApolloDirectives::Inaccessible
         include ApolloDirectives::Tag

data/script/export_docker_env_vars.sh

@@ -1,7 +1,7 @@
 script_dir=$(dirname $0)
 
 # Use the current max Elasticsearch version we test against.
-export VERSION=$(ruby -ryaml -e "puts YAML.load_file('$script_dir/../../config/tested_database_versions.yaml').fetch('elasticsearch').max_by { |v| Gem::Version.new(v) }")
+export VERSION=$(ruby -ryaml -e "puts YAML.load_file('$script_dir/../../config/tested_datastore_versions.yaml').fetch('elasticsearch').max_by { |v| Gem::Version.new(v) }")
 
 # Use the same Ruby version in the docker container as what we are currently using.
 export RUBY_VERSION=$(ruby -e "puts RUBY_VERSION")

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: elasticgraph-apollo
 version: !ruby/object:Gem::Version
-  version: 0.18.0.3
+  version: 0.18.0.5
 platform: ruby
 authors:
 - Myron Marston
+- Ben VandenBos
+- Square Engineering
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-05 00:00:00.000000000 Z
+date: 2024-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop-factory_bot
@@ -266,28 +268,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: elasticgraph-support
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: graphql
   requirement: !ruby/object:Gem::Requirement
@@ -322,70 +324,70 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: elasticgraph-admin
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: elasticgraph-elasticsearch
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: elasticgraph-opensearch
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: elasticgraph-indexer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.3
+        version: 0.18.0.5
 description: 
 email:
 - myron@squareup.com