shopify_api-graphql-tiny 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be69f222bb991d00b37c44d8aea2ad9caee713527ce23c60121a401d8d2a8b39
-  data.tar.gz: 5a35aaada946e0f0ef1dc50ea7962da2252a7f70a111a911f660b1c8eab3a79a
+  metadata.gz: c827a0b468aeb34cfb05760a7a1a25e641c61f21f6d2d15c4ed8a05b29bd383b
+  data.tar.gz: 23b357593431fb8beda6a29689b6b90e4101fde3cac2eaaad38c7a2cb48f1437
 SHA512:
-  metadata.gz: be94db6e155cc11d0136a229e6ee728ac808c655896f5489a657fc4ba82b7d5ab8403989bc356cfaaa617766077220e8234c60ff6d9aa9a651d484490cb161c3
-  data.tar.gz: 166c19ddde4a76d8d216bffac16d3844c9add39f9884eb70adac3477ce5b222e19cba820c1bae1204f58424239be38a1ec063d8e75a977f337f0d5df5afc6452
+  metadata.gz: 7fe6d5f27b0936703ce4f7f45875406ab11069d41f8e83e9d57a873ce5dd63d1093e88219cd8b5b69eed2bdd3b39bb233292360aa8bb4534f5a799690cceab5f
+  data.tar.gz: d7231b2be188d9bedbfa92f6de69a0ee4c082b8801633db73c570c7cef6c6a349afc81e942e2f36b685edf26a02d9e74817595d7b4988298f42092182a49a718

data/.env.template

@@ -4,11 +4,13 @@
 #   2. Fill-in the below variables with valid values.
 #      These values will be used by the tests. Data will be written to SHOPIFY_DOMAIN
 #
+
+# Must be full domain as it's used in test assertions
 SHOPIFY_DOMAIN=
 SHOPIFY_TOKEN=
 
-# Will result in the creation of a private metadafield
+# Will result in the creation of a metadafield on the customer. write_customers permission required
 SHOPIFY_CUSTOMER_ID=
 
-# Must have more than 1 variant
+# Must have more than 1 variant values
 SHOPIFY_PRODUCT_ID=

data/.github/workflows/ci.yml

@@ -15,10 +15,10 @@ jobs:
 
     strategy:
       matrix:
-        ruby: ["3.2", "3.1", "3.0", "2.7.2", "2.6.6", "2.5.8", "2.4.10"]
+        ruby: ['3.4', '3.3', '3.2', '3.1', '3.0', '2.7']
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true

data/Changes

@@ -1,3 +1,12 @@
+2026-01-20  v1.0.0
+--------------------
+* Add support for exponential backoff and remove ShopifyAPIRetry
+* Support HTTP status and Shopify error codes as retry options
+
+2026-01-20  v0.2.0
+--------------------
+* Deprecate :retry with a Hash value
+
 2023-02-12  v0.1.1
 --------------------
 * Add pagination support

data/README.md

@@ -1,6 +1,6 @@
 # ShopifyAPI::GraphQL::Tiny
 
-Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry.
+Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry
 
 [![CI](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions/workflows/ci.yml/badge.svg)](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions)
 
@@ -74,6 +74,69 @@ GQL
 p result.dig("data", "customerUpdate", "userErrors")
 ```
 
+### Automatically Retrying Failed Requests
+
+There are 2 types of retries: 1) request is rate-limited by Shopify 2) request fails due to an exception or non-200 HTTP response.
+
+When a request is rate-limited by Shopify retry occurs according to [Shopify's `throttleStatus`](https://shopify.dev/docs/api/admin-graphql/unstable#rate-limits)
+
+When a request fails due to an exception or non-200 HTTP status a retry will be attempted after an exponential backoff waiting period.
+This is controlled by `ShopifyAPI::GraphQL::Tiny::DEFAULT_BACKOFF_OPTIONS`. It contains:
+
+* `:base_delay` - `0.5`
+* `:jitter` - `true`
+* `:max_attempts` - `10`
+* `:max_delay` - `60`
+* `:multiplier` - `2.0`
+
+`:max_attempts` dictates how many retry attempts will be made **for all** types of retries.
+
+These can be overridden globally (by assigning to the constant) or per instance:
+
+```rb
+gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, :max_attempts => 20, :max_delay => 90)
+```
+
+`ShopifyAPI::GraphQL::Tiny::DEFAULT_RETRY_ERRORS` determines what is retried. It contains and HTTP statuses codes, Shopify GraphQL errors codes, and exceptions.
+By default it contains:
+
+* `"5XX"` - Any HTTP 5XX status
+* `"INTERNAL_SERVER_ERROR"` - Shopify GraphQL error code
+* `"TIMEOUT"` - Shopify GraphQL error code
+* `EOFError`
+* `Errno::ECONNABORTED`
+* `Errno::ECONNREFUSED`
+* `Errno::ECONNRESET`
+* `Errno::EHOSTUNREACH`
+* `Errno::EINVAL`
+* `Errno::ENETUNREACH`
+* `Errno::ENOPROTOOPT`
+* `Errno::ENOTSOCK`
+* `Errno::EPIPE`
+* `Errno::ETIMEDOUT`
+* `Net::HTTPBadResponse`
+* `Net::HTTPHeaderSyntaxError`
+* `Net::ProtocolError`
+* `Net::ReadTimeout`
+* `OpenSSL::SSL::SSLError`
+* `SocketError`
+* `Timeout::Error`
+
+These can be overridden globally (by assigning to the constant) or per instance:
+
+```rb
+# Only retry on 2 errors
+gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, :retry => [SystemCallError, "500"])
+```
+
+#### Disabling Automatic Retry
+
+To disable retries set the `:retry` option to `false`:
+
+```rb
+gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, :retry => false)
+```
+
 ### Pagination
 
 In addition to built-in request retry `ShopifyAPI::GraphQL::Tiny` also builds in support for pagination.
@@ -196,19 +259,21 @@ pager.execute(query) { |page| }
 
 The `"data"` and `"pageInfo"` keys are automatically added if not provided.
 
-### Automatically Retrying Failed Requests
-
-See [the docs](https://rubydoc.info/gems/shopify_api-graphql-tiny) for more information.
-
 ## Testing
 
 `cp env.template .env` and fill-in `.env` with the missing values. This requires a Shopify store.
 
+To elicit a request that will be rate-limited by Shopify run following Rake task:
+
+```sh
+bundle exec rake rate_limit SHOPIFY_DOMAIN=your-domain SHOPIFY_TOKEN=your-token
+```
+
 ## See Also
 
 - [Shopify Dev Tools](https://github.com/ScreenStaring/shopify-dev-tools) - Command-line program to assist with the development and/or maintenance of Shopify apps and stores
-- [Shopify ID Export](https://github.com/ScreenStaring/shopify_id_export/) Dump Shopify product and variant IDs —along with other identifiers— to a CSV or JSON file
-- [ShopifyAPIRetry](https://github.com/ScreenStaring/shopify_api_retry) - Retry a ShopifyAPI request if rate-limited or other errors occur (REST and GraphQL APIs)
+- [Shopify ID Export](https://github.com/ScreenStaring/shopify_id_export/) - Dump Shopify product and variant IDs —along with other identifiers— to a CSV or JSON file
+- [`TinyGID`](https://github.com/sshaw/tiny_gid/) - Build Global ID (gid://) URI strings from scalar values
 
 ## License
 

data/Rakefile

@@ -4,3 +4,161 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+desc "Elicit a Shopify rate limit"
+task :rate_limit do
+  require "shopify_api/graphql/tiny"
+
+  query =<<-GQL
+    query {
+      products(first: 50, sortKey: UPDATED_AT, reverse: true) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        edges {
+          node {
+            id
+            title
+            handle
+            status
+            createdAt
+            updatedAt
+            publishedAt
+            vendor
+            productType
+            tags
+            descriptionHtml
+            description
+            onlineStoreUrl
+            options(first: 3) {
+              id
+              name
+              position
+              values
+            }
+            variants(first: 80) {
+              edges {
+                node {
+                  id
+                  title
+                  price
+                  compareAtPrice
+                  sku
+                  barcode
+                  inventoryItem {
+                    id
+                    unitCost {
+                      amount
+                      currencyCode
+                    }
+                    countryCodeOfOrigin
+                    harmonizedSystemCode
+                  }
+                  inventoryPolicy
+                  taxable
+                  availableForSale
+                  metafields(first: 20) {
+                    edges {
+                      node {
+                        id
+                        namespace
+                        key
+                        value
+                        type
+                        description
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            media(first: 20) {
+              edges {
+                node {
+                  __typename
+                  alt
+                  status
+                  ... on MediaImage {
+                    id
+                    preview {
+                      image {
+                        url
+                      }
+                    }
+                    image {
+                      id
+                      url
+                      width
+                      height
+                      altText
+                    }
+                  }
+                  ... on Video {
+                    id
+                    sources {
+                      url
+                      format
+                      height
+                      width
+                    }
+                  }
+                  ... on ExternalVideo {
+                    id
+                    originUrl
+                    embedUrl
+                  }
+                }
+              }
+            }
+            images(first: 20) {
+              edges {
+                node {
+                  id
+                  url
+                  altText
+                  width
+                  height
+                }
+              }
+            }
+            seo {
+              title
+              description
+            }
+            metafields(first: 30) {
+              edges {
+                node {
+                  id
+                  namespace
+                  key
+                  value
+                  type
+                  ownerType
+                }
+              }
+            }
+            collections(first: 10) {
+              edges {
+                node {
+                  id
+                  title
+                  handle
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  GQL
+
+  threads = 5.times.map do
+    Thread.new do
+      gql = ShopifyAPI::GQL::Tiny.new(ENV.fetch("SHOPIFY_DOMAIN"), ENV.fetch("SHOPIFY_TOKEN"), :debug => true)
+      pp gql.execute(query).dig("extensions", "cost", "throttleStatus")
+    end
+  end
+
+  threads.each(&:join)
+end

data/lib/shopify_api/graphql/tiny/version.rb

@@ -3,7 +3,7 @@
 module ShopifyAPI
   module GraphQL
     class Tiny
-      VERSION = "0.2.0"
+      VERSION = "1.0.0"
     end
   end
 end

data/lib/shopify_api/graphql/tiny.rb

@@ -2,18 +2,22 @@
 require "json"
 require "net/http"
 
-require "shopify_api_retry"
+require "net_http_timeout_errors"
 require "shopify_api/graphql/tiny/version"
 
 module ShopifyAPI
   module GraphQL
     ##
-    # Client to make Shopify GraphQL Admin API requests with built-in retries.
+    # Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry
     #
     class Tiny
       Error = Class.new(StandardError)
       ConnectionError = Class.new(Error)
 
+      ERROR_CODE_THROTTLED = "THROTTLED"
+      ERROR_CODE_TIMEOUT = "TIMEOUT"
+      ERROR_CODE_SERVER_ERROR = "INTERNAL_SERVER_ERROR"
+
       class GraphQLError < Error
         # Hash of failed GraphQL response
         attr_reader :response
@@ -44,18 +48,26 @@ module ShopifyAPI
 
       DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
 
-      # Retry rules to be used for all instances if no rules are specified via the +:retry+ option when creating an instance
-      DEFAULT_RETRY_OPTIONS = {
-        ConnectionError => { :wait => 3, :tries => 20 },
-        GraphQLError => { :wait => 3, :tries => 20 },
-        HTTPError => { :wait => 3, :tries => 20 }
+      DEFAULT_BACKOFF_OPTIONS = {
+        :base_delay => 0.5,
+        :jitter => true,
+        :max_attempts => 10,
+        :max_delay => 60,
+        :multiplier => 2.0
       }
 
+      DEFAULT_RETRY_ERRORS = [
+        "5XX",
+        ERROR_CODE_SERVER_ERROR,
+        ERROR_CODE_TIMEOUT,
+        *NetHttpTimeoutErrors.all
+      ]
+
       ENDPOINT = "https://%s/admin/api%s/graphql.json"       # Note that we omit the "/" after API for the case where there's no version.
 
       ##
       #
-      # Create a new GraphQL client.
+      # Create a new GraphQL client
       #
       # === Arguments
       #
@@ -65,8 +77,12 @@ module ShopifyAPI
       #
       # === Options
       #
-      # [:retry (Boolean|Hash)] +Hash+ can be retry config options. For the format see {ShopifyAPIRetry}[https://github.com/ScreenStaring/shopify_api_retry/#usage]. Defaults to +true+
+      # [:retry (Boolean|Array)] If +false+ disable retries or an +Array+ of errors to retry. Can be HTTP status codes, GraphQL errors, or exception classes.
       # [:version (String)] Shopify API version to use. Defaults to the latest version.
+      # [:max_attempts (Integer)] Maximum number of retry attempts across all errors. Defaults to +10+
+      # [:base_delay (Float)] Exponential backoff base delay. Defaults to +0.5+
+      # [:jitter (Boolean)] Exponential backoff jitter (random delay added to backoff). Defaults to +true+
+      # [:multiplier (Float)] Exponential backoff multiplier. Defaults to +2.0+
       # [:debug (Boolean|IO)] Output the HTTP request/response to +STDERR+ or to its value if it's an +IO+. Defaults to +false+.
       #
       # === Errors
@@ -83,17 +99,27 @@ module ShopifyAPI
 
         @headers = DEFAULT_HEADERS.dup
         @headers[ACCESS_TOKEN_HEADER] = token
-        @headers[QUERY_COST_HEADER] = "true" if retry?
+        @headers[QUERY_COST_HEADER] = "true" unless @options[:retry] == false
 
         @endpoint = URI(sprintf(ENDPOINT, @domain, !@options[:version].to_s.strip.empty? ? "/#{@options[:version]}" : ""))
+        @backoff_options = DEFAULT_BACKOFF_OPTIONS.merge(@options.slice(*DEFAULT_BACKOFF_OPTIONS.keys))
+
+        if @options[:debug]
+          @debug = @options[:debug].is_a?(IO) ? @options[:debug] : $stderr
+        end
 
-        if @options[:retry].is_a?(Hash)
-          warn "DEPRECATION WARNING from #{self.class}: specifying retry options as a Hash via the :retry option is deprecated and will be removed in v1.0"
+        case @options[:retry]
+        when false
+          @retryable = []
+        when Array
+          @retryable = @options[:retry]
+        else
+          @retryable = DEFAULT_RETRY_ERRORS
         end
       end
 
       #
-      # Execute a GraphQL query or mutation.
+      # Execute a GraphQL query or mutation
       #
       # === Arguments
       #
@@ -104,6 +130,8 @@ module ShopifyAPI
       #
       # ArgumentError, ConnectionError, HTTPError, RateLimitError, GraphQLError
       #
+      # Outside of ArgumentError these are raised after exhausing the configured retry.
+      #
       # * An ShopifyAPI::GraphQL::Tiny::HTTPError is raised of the response does not have 200 status code
       # * A ShopifyAPI::GraphQL::Tiny::RateLimitError is raised if rate-limited and retries are disabled or if still
       #   rate-limited after the configured number of retry attempts
@@ -117,8 +145,9 @@ module ShopifyAPI
       def execute(q, variables = nil)
         raise ArgumentError, "query required" if q.nil? || q.to_s.strip.empty?
 
-        config = retry? ? @options[:retry] || DEFAULT_RETRY_OPTIONS : {}
-        ShopifyAPIRetry::GraphQL.retry(config) { post(q, variables) }
+        @request_attempts = 0
+
+        make_request(q, variables)
       end
 
       ##
@@ -169,57 +198,134 @@ module ShopifyAPI
 
       private
 
-      def retry?
-        @options[:retry] != false
-      end
+      def make_request(query, variables = nil)
+        response = nil
+        exceptions = @retryable.select { |target| target.is_a?(Class) }
 
-      def shopify_domain(host)
-        domain = host.sub(%r{\Ahttps?://}i, "")
-        domain << SHOPIFY_DOMAIN unless domain.end_with?(SHOPIFY_DOMAIN)
-        domain
+        begin
+          @request_attempts += 1
+          response = post(query, variables)
+        rescue => e
+          retry if exceptions.include?(e.class) && wait_to_retry
+          raise ConnectionError.new("failed to execute query for #@domain: #{e.message}")
+        end
+
+        if response.code != "200"
+          return make_request(query, variables) if handle_http_error(response.code)
+          raise HTTPError.new("failed to execute query for #@domain: #{response.body}", response.code)
+        end
+
+        json = parse_json(response.body)
+        return json unless json.include?("errors")
+
+        return make_request(query, variables) if handle_graphql_error(json)
+
+        message = error_message(json["errors"])
+        raise GraphQLError.new("failed to execute query for #@domain: #{message}", json)
       end
 
       def post(query, variables = nil)
-        begin
-          # Newer versions of Ruby
-          # response = Net::HTTP.post(@endpoint, query, @headers)
-          params = { :query => query }
-          params[:variables] = variables if variables
+        # Newer versions of Ruby:
+        # response = Net::HTTP.post(@endpoint, query, @headers)
+        params = { :query => query }
+        params[:variables] = variables if variables
 
-          post = Net::HTTP::Post.new(@endpoint.path)
-          post.body = params.to_json
-          post["User-Agent"] = USER_AGENT
+        post = Net::HTTP::Post.new(@endpoint.path)
+        post.body = params.to_json
+        post["User-Agent"] = USER_AGENT
 
-          @headers.each { |k,v| post[k] = v }
+        @headers.each { |k,v| post[k] = v }
 
-          request = Net::HTTP.new(@endpoint.host, @endpoint.port)
-          request.use_ssl = true
+        request = Net::HTTP.new(@endpoint.host, @endpoint.port)
+        request.use_ssl = true
+        request.set_debug_output(@debug) if @debug
 
-          if @options[:debug]
-            request.set_debug_output(
-              @options[:debug].is_a?(IO) ? @options[:debug] : $stderr
-            )
-          end
+        request.start { |http| http.request(post) }
+      end
 
-          response = request.start { |http| http.request(post) }
-        rescue => e
-          raise ConnectionError, "request to #@endpoint failed: #{e}"
+      def handle_graphql_error(json)
+        errors = json["errors"]
+        codes = errors.map { |error| error.dig("extensions", "code") }
+
+        if codes.include?(ERROR_CODE_THROTTLED)
+          return true if wait_for_shopify_retry(json.dig("extensions", "cost"))
+
+          raise RateLimitError.new(error_message(errors), json)
         end
 
-        # TODO: Even if non-200 check if JSON. See: https://shopify.dev/api/admin-graphql
-        prefix = "failed to execute query for #@domain: "
-        raise HTTPError.new("#{prefix}#{response.body}", response.code) if response.code != "200"
+        return true if @retryable.any? { |error| codes.include?(error) } && wait_to_retry
 
-        json = JSON.parse(response.body)
-        return json unless json.include?("errors")
+        false
+      end
 
-        errors = json["errors"].map { |e| e["message"] }.join(", ")
-        if json.dig("errors", 0, "extensions", "code") == "THROTTLED"
-          raise RateLimitError.new(errors, json) unless retry?
-          return json
-        end
+      def handle_http_error(status)
+        return false unless @retryable.include?(status) || @retryable.any? { |error| error.is_a?(String) && error.size == 3 && error.end_with?("XX") && error[0] == status[0] }
+
+        wait_to_retry
+      end
+
+      def wait_to_retry
+        return false unless request_attempts_remain?
+
+        backoff(@request_attempts)
+
+        true
+      end
+
+      def wait_for_shopify_retry(cost)
+        return false if cost.nil? || cost["actualQueryCost"] || !request_attempts_remain?
+
+        status = cost["throttleStatus"]
+        time = (cost["requestedQueryCost"] - status["currentlyAvailable"]) / status["restoreRate"]
+
+        debug("retrying rate-limited request (retry count: #@request_attempts, status: #{status}, sleep: #{time})")
+
+        sleep(time)
+
+        true
+      end
+
+      def backoff(attempts)
+        delay = @backoff_options[:base_delay] * (@backoff_options[:multiplier] ** (attempts - 1))
+        delay = [delay, @backoff_options[:max_delay]].min if @backoff_options[:max_delay]
+        delay = rand * delay if @backoff_options[:jitter]
+
+        debug("backoff sleeping for #{delay}")
+
+        sleep(delay)
+      end
+
+      def shopify_domain(host)
+        domain = host.sub(%r{\Ahttps?://}i, "")
+        domain << SHOPIFY_DOMAIN unless domain.end_with?(SHOPIFY_DOMAIN)
+        domain
+      end
+
+      def parse_json(json)
+        JSON.parse(json)
+      rescue JSON::ParserError => e
+        raise Error, "failed to parse JSON response: #{e.message}"
+      end
+
+      def error_message(errors)
+        errors.map do |e|
+          message = e["message"]
+
+          path = e["path"]
+          message << sprintf(" at %s", path.join(".")) if path
+
+          message
+        end.join(", ")
+      end
+
+      def request_attempts_remain?
+        @request_attempts < @backoff_options[:max_attempts]
+      end
+
+      def debug(message)
+        return unless @debug
 
-        raise GraphQLError.new(prefix + errors, json)
+        @debug.puts "#{self.class}: #{message}"
       end
     end
 

data/shopify_api-graphql-tiny.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
     "source_code_uri"   => "https://github.com/ScreenStaring/shopify_api-graphql-tiny",
   }
 
-  spec.add_dependency "shopify_api_retry", "~> 0.2"
+  spec.add_dependency "net_http_timeout_errors"
   spec.add_development_dependency "webmock", "~> 3.0"
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", ">= 12.3.3"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api-graphql-tiny
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Skye Shaw
@@ -10,19 +10,19 @@ cert_chain: []
 date: 2026-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: shopify_api_retry
+  name: net_http_timeout_errors
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement