Custom execution adapter

docs/graphql.md

@@ -147,15 +147,16 @@ during your boot process.
 The goal is to have all clients created at boot so there's no schema loading,
 parsing, or client instantiation done during runtime when your app serves a request.
 
-## Using a custom client
-`ShopifyAPI::GraphQL::HTTPClient` inherits from `::GraphQL::Client::HTTP` and instruments
-the headers, url and api version for you. However, you may find that you wish to add
-additional functionality to the client responsible for executing and parsing queries.
-For instance, you may wish to create a client which loads responses from a file for your
-tests, or you may want to implement a client which raises errors instead of passing them
-back through the results object.
-
-To set a custom client set `ShopifyAPI::GraphQL.client_klass` to your client:
+## Using a custom query execution adapter
+Github's GraphQL Client uses an adapter pattern so that you can define how you interact
+with GraphQL API's. Shopify provides a minimal implementation in `ShopifyAPI::GraphQL::HTTPClient`.
+If you need to add additional functionality pre, during or post query execution you can
+consider implementing these within a custom query execution adapter, inheriting from
+`ShopifyAPI::GraphQL::HTTPClient` which provides the necessary implementation for
+headers, url, and api versions
+
+
+To set a custom query executiona dapter set `ShopifyAPI::GraphQL.execution_adapter` to your client:
 ```ruby
 class RaisingHTTPClient < ShopifyAPI::GraphQL::HTTPClient
   def execute(document:, operation_name: nil, variables: {}, context: {})
@@ -170,9 +171,12 @@ class RaisingHTTPClient < ShopifyAPI::GraphQL::HTTPClient
   end
 end
 
-ShopifyAPI::GraphQL.client_klass = RaisingHTTPClient
+ShopifyAPI::GraphQL.execution_adapter = RaisingHTTPClient
 ```
 
+Note, the execution adapter has `client` in the name. This is to remain consistent with
+the naming conventions within the Github GraphQL Client library.
+
 ## Migration guide
 Prior to shopify_api v9.0 the GraphQL client implementation was limited and almost
 unusable due to the client making dynamic introspection queries to Shopify's API.

lib/shopify_api/graphql.rb

@@ -5,7 +5,7 @@ require 'shopify_api/graphql/http_client'
 module ShopifyAPI
   module GraphQL
     DEFAULT_SCHEMA_LOCATION_PATH = Pathname('shopify_graphql_schemas')
-    DEFAULT_CLIENT_KLASS = HTTPClient
+    DEFAULT_EXECUTION_ADAPTER = HTTPClient
 
     InvalidSchema = Class.new(StandardError)
     InvalidClient = Class.new(StandardError)
@@ -58,7 +58,7 @@ module ShopifyAPI
           end
 
           schema = ::GraphQL::Client.load_schema(schema_file.to_s)
-          client = ::GraphQL::Client.new(schema: schema, execute: client_klass.new(api_version)).tap do |c|
+          client = ::GraphQL::Client.new(schema: schema, execute: execution_adapter.new(api_version)).tap do |c|
             c.allow_dynamic_queries = true
           end
 
@@ -74,12 +74,12 @@ module ShopifyAPI
         @schema_location = Pathname(path)
       end
 
-      def client_klass
-        @client_klass || DEFAULT_CLIENT_KLASS
+      def execution_adapter
+        @execution_adapter || DEFAULT_EXECUTION_ADAPTER
       end
 
-      def client_klass=(client)
-        @client_klass = client
+      def execution_adapter=(executor)
+        @execution_adapter = executor
       end
 
       private

test/graphql_test.rb

@@ -143,20 +143,20 @@ class GraphQLTest < Test::Unit::TestCase
     end
   end
 
-  test '#client creates client based off configured class' do
-    class SuperDuperClient < ShopifyAPI::GraphQL::HTTPClient
+  test '#client creates execution adapter based off configured class' do
+    class SuperDuperExecutionAdapter < ShopifyAPI::GraphQL::HTTPClient
     end
 
-    ShopifyAPI::GraphQL.client_klass = SuperDuperClient
+    ShopifyAPI::GraphQL.execution_adapter = SuperDuperExecutionAdapter
     version_fixtures('unstable') do |dir|
       ShopifyAPI::Base.api_version = 'unstable'
 
       ShopifyAPI::GraphQL.initialize_clients
 
-      assert_instance_of SuperDuperClient, ShopifyAPI::GraphQL.client('unstable').execute
+      assert_instance_of SuperDuperExecutionAdapter, ShopifyAPI::GraphQL.client('unstable').execute
     end
 
-    ShopifyAPI::GraphQL.client_klass = nil
+    ShopifyAPI::GraphQL.execution_adapter = nil
   end
 
   private