zendesk_api 3.1.1 → 4.0.0.pre.1

data/lib/zendesk_api/collection.rb

@@ -1,7 +1,7 @@
-require 'zendesk_api/resource'
-require 'zendesk_api/resources'
-require 'zendesk_api/search'
-require 'zendesk_api/pagination'
+require_relative "resource"
+require_relative "resources"
+require_relative "search"
+require_relative "pagination"
 
 module ZendeskAPI
   # Represents a collection of resources. Lazily loaded, resources aren't
@@ -50,8 +50,8 @@ module ZendeskAPI
     end
 
     # Methods that take a Hash argument
-    methods = %w{create find update update_many destroy create_or_update}
-    methods += methods.map { |method| method + "!" }
+    methods = %w[create find update update_many destroy create_or_update]
+    methods += methods.map { |method| "#{method}!" }
     methods.each do |deferrable|
       # Passes arguments and the proper path to the resource class method.
       # @param [Hash] options Options or attributes to pass
@@ -61,14 +61,14 @@ module ZendeskAPI
         end
 
         args << {} unless args.last.is_a?(Hash)
-        args.last.merge!(:association => @association)
+        args.last[:association] = @association
 
         @resource_class.send(deferrable, @client, *args)
       end
     end
 
     # Methods that take an Array argument
-    methods = %w{create_many! destroy_many!}
+    methods = %w[create_many! destroy_many!]
     methods.each do |deferrable|
       # Passes arguments and the proper path to the resource class method.
       # @param [Array] array arguments
@@ -153,7 +153,7 @@ module ZendeskAPI
 
     # The API path to this collection
     def path
-      @association.generate_path(:with_parent => true)
+      @association.generate_path(with_parent: true)
     end
 
     # Executes actual GET from API and loads resources into proper class.
@@ -161,7 +161,7 @@ module ZendeskAPI
     def fetch!(reload = false)
       if @resources && (!@fetchable || !reload)
         return @resources
-      elsif association && association.options.parent && association.options.parent.new_record?
+      elsif association&.options&.parent&.new_record?
         return (@resources = [])
       end
 
@@ -188,24 +188,24 @@ module ZendeskAPI
 
     # Calls #each on every page with the passed in block
     # @param [Block] block Passed to #each
-    def all!(start_page = @options["page"], &block)
-      _all(start_page, :bang, &block)
+    def all!(start_page = @options["page"], &)
+      _all(start_page, :bang, &)
     end
 
     # Calls #each on every page with the passed in block
     # @param [Block] block Passed to #each
-    def all(start_page = @options["page"], &block)
-      _all(start_page, &block)
+    def all(start_page = @options["page"], &)
+      _all(start_page, &)
     end
 
-    def each_page!(*args, &block)
+    def each_page!(...)
       warn "ZendeskAPI::Collection#each_page! is deprecated, please use ZendeskAPI::Collection#all!"
-      all!(*args, &block)
+      all!(...)
     end
 
-    def each_page(*args, &block)
+    def each_page(...)
       warn "ZendeskAPI::Collection#each_page is deprecated, please use ZendeskAPI::Collection#all"
-      all(*args, &block)
+      all(...)
     end
 
     # Replaces the current (loaded or not) resources with the passed in collection
@@ -271,13 +271,13 @@ module ZendeskAPI
     end
 
     # Sends methods to underlying array of resources.
-    def method_missing(name, *args, &block)
+    def method_missing(name, ...)
       if resource_methods.include?(name)
-        collection_method(name, *args, &block)
+        collection_method(name, ...)
       elsif [].respond_to?(name, false)
-        array_method(name, *args, &block)
+        array_method(name, ...)
       else
-        next_collection(name, *args, &block)
+        next_collection(name, ...)
       end
     end
 
@@ -289,11 +289,11 @@ module ZendeskAPI
         inspect = []
         inspect << "options=#{@options.inspect}" if @options.any?
         inspect << "path=#{path}"
-        "#{Inflection.singular(@resource)} collection [#{inspect.join(',')}]"
+        "#{Inflection.singular(@resource)} collection [#{inspect.join(",")}]"
       end
     end
 
-    alias to_str to_s
+    alias_method :to_str, :to_s
 
     def to_param
       map(&:to_param)
@@ -303,7 +303,7 @@ module ZendeskAPI
       link = original_response_body["links"]["next"]
       result_key = @resource_class.model_key || "results"
       while link
-        response = @client.connection.send("get", link).body
+        response = @client.connection.send(:get, link).body
 
         original_response_body[result_key] = original_response_body[result_key] + response[result_key]
 
@@ -338,7 +338,7 @@ module ZendeskAPI
       page(start_page)
       clear_cache
 
-      while (bang ? fetch! : fetch)
+      while bang ? fetch! : fetch
         each do |resource|
           block.call(resource, @options["page"] || 1)
         end
@@ -370,7 +370,7 @@ module ZendeskAPI
       # some params use comma-joined strings instead of query-based arrays for multiple values
       @options.each do |k, v|
         if SPECIALLY_JOINED_PARAMS.include?(k.to_sym) && v.is_a?(Array)
-          @options[k] = v.join(',')
+          @options[k] = v.join(",")
         end
       end
     end
@@ -378,9 +378,9 @@ module ZendeskAPI
     def set_association_from_options
       @collection_path = @options.delete(:collection_path)
 
-      association_options = { :path => @options.delete(:path) }
+      association_options = {path: @options.delete(:path)}
       association_options[:path] ||= @collection_path.join("/") if @collection_path
-      @association = @options.delete(:association) || Association.new(association_options.merge(:class => @resource_class))
+      @association = @options.delete(:association) || Association.new(association_options.merge(class: @resource_class))
       @collection_path ||= [@resource]
     end
 
@@ -389,9 +389,9 @@ module ZendeskAPI
       @client.connection.send(@verb || "get", path) do |req|
         opts = @options.delete_if { |_, v| v.nil? }
 
-        req.params.merge!(:include => @includes.join(",")) if @includes.any?
+        req.params[:include] = @includes.join(",") if @includes.any?
 
-        if %w{put post}.include?(@verb.to_s)
+        if %w[put post].include?(@verb.to_s)
           req.body = opts
         else
           req.params.merge!(opts)
@@ -440,11 +440,11 @@ module ZendeskAPI
       when Array
         wrap_resource(Hash[*res], with_association)
       when Hash
-        res = res.merge(:association => @association) if with_association
+        res = res.merge(association: @association) if with_association
         @resource_class.new(@client, res)
       else
-        res = { :id => res }
-        res.merge!(:association => @association) if with_association
+        res = {id: res}
+        res[:association] = @association if with_association
         @resource_class.new(@client, res)
       end
     end
@@ -457,22 +457,23 @@ module ZendeskAPI
 
     ## Method missing
 
-    def array_method(name, *args, &block)
-      to_a.public_send(name, *args, &block)
+    def array_method(name, ...)
+      to_a.public_send(name, ...)
     end
 
     # If you call client.tickets.foo - and foo is not an attribute nor an association, it ends up here, as a new collection
-    def next_collection(name, *args, &block)
+    def next_collection(name, *args, &)
       opts = args.last.is_a?(Hash) ? args.last : {}
-      opts.merge!(collection_path: [*@collection_path, name], page: nil)
+      opts[:collection_path] = [*@collection_path, name]
+      opts[:page] = nil
       # Why `page: nil`?
       # when you do client.tickets.fetch followed by client.tickets.foos => the request to /tickets/foos will
       # have the options page set to whatever the last options were for the tickets collection
       self.class.new(@client, @resource_class, @options.merge(opts))
     end
 
-    def collection_method(name, *args, &block)
-      @resource_class.send(name, @client, *args, &block)
+    def collection_method(name, ...)
+      @resource_class.send(name, @client, ...)
     end
 
     def resource_methods

data/lib/zendesk_api/configuration.rb

@@ -54,6 +54,9 @@ module ZendeskAPI
     # specify if you want a (network layer) exception to elicit a retry
     attr_accessor :retry_on_exception
 
+    # specify if you want instrumentation to be used
+    attr_accessor :instrumentation
+
     def initialize
       @client_options = {}
       @use_resource_cache = true
@@ -66,16 +69,16 @@ module ZendeskAPI
     # @return [Hash] Faraday-formatted hash of options.
     def options
       {
-        :headers => {
-          :accept => 'application/json',
-          :accept_encoding => 'gzip;q=1.0,deflate;q=0.6,identity;q=0.3',
-          :user_agent => "ZendeskAPI Ruby #{ZendeskAPI::VERSION}"
+        headers: {
+          accept: "application/json",
+          accept_encoding: "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
+          user_agent: "ZendeskAPI Ruby #{ZendeskAPI::VERSION}"
         },
-        :request => {
-          :open_timeout => 10,
-          :timeout => 60
+        request: {
+          open_timeout: 10,
+          timeout: 60
         },
-        :url => @url
+        url: @url
       }.merge(client_options)
     end
   end

data/lib/zendesk_api/core_ext/inflection.rb

@@ -1,3 +1,3 @@
-require 'inflection'
+require "inflection"
 
-Inflection.plural_rule 'forum', 'forums'
+Inflection.plural_rule "forum", "forums"

data/lib/zendesk_api/delegator.rb

@@ -1,4 +1,4 @@
-require 'delegate'
+require "delegate"
 
 module ZendeskAPI
   class Delegator < SimpleDelegator; end

data/lib/zendesk_api/helpers.rb

@@ -21,10 +21,10 @@ module ZendeskAPI
     # @return [string] a string that can become a class, `Module::ClassName`
     def self.modulize_string(string)
       # gsub('__','/').  # why was this ever here?
-      string.gsub(/__(.?)/) { "::#{$1.upcase}" }.
-        gsub(/\/(.?)/) { "::#{$1.upcase}" }.
-        gsub(/(?:_+|-+)([a-z])/) { $1.upcase }.
-        gsub(/(\A|\s)([a-z])/) { $1 + $2.upcase }
+      string.gsub(/__(.?)/) { "::#{$1.upcase}" }
+        .gsub(/\/(.?)/) { "::#{$1.upcase}" }
+        .gsub(/(?:_+|-+)([a-z])/) { $1.upcase }
+        .gsub(/(\A|\s)([a-z])/) { $1 + $2.upcase }
     end
 
     # From https://github.com/rubyworks/facets/blob/master/lib/core/facets/string/snakecase.rb
@@ -38,12 +38,12 @@ module ZendeskAPI
     #   "Snake  -  Case".snakecase    #=> "snake_case"
     def self.snakecase_string(string)
       # gsub(/::/, '/').
-      string.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
-        gsub(/([a-z\d])([A-Z])/, '\1_\2').
-        tr('-', '_').
-        gsub(/\s/, '_').
-        gsub(/__+/, '_').
-        downcase
+      string.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .gsub(/\s/, "_")
+        .gsub(/__+/, "_")
+        .downcase
     end
   end
 end

data/lib/zendesk_api/middleware/request/api_token_impersonate.rb

@@ -0,0 +1,29 @@
+require "base64"
+
+module ZendeskAPI
+  # @private
+  module Middleware
+    # @private
+    module Request
+      # ApiTokenImpersonate
+      # If Thread.current[:zendesk_thread_local_username] is set, it will modify the Authorization header
+      # to impersonate that user using the API token from the current Authorization header.
+      class ApiTokenImpersonate < Faraday::Middleware
+        def call(env)
+          if Thread.current[:zendesk_thread_local_username] && env[:request_headers][:authorization] =~ /^Basic /
+            current_u_p_encoded = env[:request_headers][:authorization].split(/\s+/)[1]
+            current_u_p = Base64.urlsafe_decode64(current_u_p_encoded)
+            unless current_u_p.include?("/token:") && (parts = current_u_p.split(":")) && parts.length == 2 && parts[0].include?("/token")
+              warn "WARNING: ApiTokenImpersonate passed in invalid format. It should be in the format username/token:APITOKEN"
+              return @app.call(env)
+            end
+
+            next_u_p = "#{Thread.current[:zendesk_thread_local_username]}/token:#{parts[1]}"
+            env[:request_headers][:authorization] = "Basic #{Base64.urlsafe_encode64(next_u_p)}"
+          end
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/zendesk_api/middleware/request/encode_json.rb

@@ -4,13 +4,12 @@ module ZendeskAPI
     # @private
     module Request
       class EncodeJson < Faraday::Middleware
-        CONTENT_TYPE = 'Content-Type'.freeze
-        MIME_TYPE = 'application/json'.freeze
+        CONTENT_TYPE = "Content-Type".freeze
+        MIME_TYPE = "application/json".freeze
 
         def call(env)
           type = env[:request_headers][CONTENT_TYPE].to_s
-          type = type.split(';', 2).first if type.index(';')
-          type
+          type = type.split(";", 2).first if type.index(";")
 
           if env[:body] && !(env[:body].respond_to?(:to_str) && env[:body].empty?) && (type.empty? || type == MIME_TYPE)
             env[:body] = JSON.dump(env[:body])

data/lib/zendesk_api/middleware/request/etag_cache.rb

@@ -9,6 +9,7 @@ module ZendeskAPI
       class EtagCache < Faraday::Middleware
         def initialize(app, options = {})
           @app = app
+          @instrumentation = options[:instrumentation] if options[:instrumentation].respond_to?(:instrument)
           @cache = options[:cache] ||
             raise("need :cache option e.g. ActiveSupport::Cache::MemoryStore.new")
           @cache_key_prefix = options.fetch(:cache_key_prefix, :faraday_etags)
@@ -36,13 +37,35 @@ module ZendeskAPI
               env[:response_body] = cached[:response_body]
 
               env[:response_headers].merge!(
-                :etag => cached[:response_headers][:etag],
-                :content_type => cached[:response_headers][:content_type],
-                :content_length => cached[:response_headers][:content_length],
-                :content_encoding => cached[:response_headers][:content_encoding]
+                etag: cached[:response_headers][:etag],
+                content_type: cached[:response_headers][:content_type],
+                content_length: cached[:response_headers][:content_length],
+                content_encoding: cached[:response_headers][:content_encoding]
               )
+              if @instrumentation
+                begin
+                  @instrumentation.instrument("zendesk.cache_hit",
+                    {
+                      endpoint: env[:url]&.path,
+                      status: env[:status]
+                    })
+                rescue
+                  # Swallow instrumentation errors to maintain cache behavior
+                end
+              end
             elsif env[:status] == 200 && env[:response_headers]["Etag"] # modified and cacheable
               @cache.write(cache_key(env), env.to_hash)
+              if @instrumentation
+                begin
+                  @instrumentation.instrument("zendesk.cache_miss",
+                    {
+                      endpoint: env[:url]&.path,
+                      status: env[:status]
+                    })
+                rescue
+                  # Swallow instrumentation errors to maintain cache behavior
+                end
+              end
             end
           end
         end

data/lib/zendesk_api/middleware/request/raise_rate_limited.rb

@@ -1,5 +1,5 @@
-require 'faraday/middleware'
-require 'zendesk_api/error'
+require "faraday/middleware"
+require_relative "../../error"
 
 module ZendeskAPI
   module Middleware
@@ -19,7 +19,7 @@ module ZendeskAPI
           response = @app.call(env)
 
           if ERROR_CODES.include?(response.env[:status])
-            @logger&.warn 'You have been rate limited. Raising error...'
+            @logger&.warn "You have been rate limited. Raising error..."
             raise Error::RateLimited, env
           else
             response

data/lib/zendesk_api/middleware/request/retry.rb

@@ -1,4 +1,5 @@
 require "faraday/middleware"
+
 module ZendeskAPI
   module Middleware
     # @private
@@ -12,46 +13,81 @@ module ZendeskAPI
         def initialize(app, options = {})
           super(app)
           @logger = options[:logger]
-          @error_codes = options.key?(:retry_codes) && options[:retry_codes] ? options[:retry_codes] : DEFAULT_ERROR_CODES
-          @retry_on_exception = options.key?(:retry_on_exception) && options[:retry_on_exception] ? options[:retry_on_exception] : false
+          @error_codes = (options.key?(:retry_codes) && options[:retry_codes]) ? options[:retry_codes] : DEFAULT_ERROR_CODES
+          @retry_on_exception = (options.key?(:retry_on_exception) && options[:retry_on_exception]) ? options[:retry_on_exception] : false
+          @instrumentation = options[:instrumentation]
         end
 
         def call(env)
+          # Duplicate env for retries but keep attempt counter persistent
           original_env = env.dup
+          original_env[:call_attempt] = (env[:call_attempt] || 0)
+
           exception_happened = false
+          response = nil
+
           if @retry_on_exception
             begin
               response = @app.call(env)
-            rescue StandardError => e
+            rescue => ex
               exception_happened = true
+              exception = ex
             end
           else
+            # Allow exceptions to propagate normally when not retrying
             response = @app.call(env)
           end
 
-          if exception_happened || @error_codes.include?(response.env[:status])
+          if exception_happened
+            original_env[:call_attempt] += 1
+            seconds_left = DEFAULT_RETRY_AFTER.to_i
+            @logger&.warn "An exception happened, waiting #{seconds_left} seconds... #{exception}"
+            instrument_retry(original_env, "exception", seconds_left)
+            sleep_with_logging(seconds_left)
+            return @app.call(original_env)
+          end
 
-            if exception_happened
-              seconds_left = DEFAULT_RETRY_AFTER.to_i
-              @logger.warn "An exception happened, waiting #{seconds_left} seconds... #{e}" if @logger
-            else
-              seconds_left = (response.env[:response_headers][:retry_after] || DEFAULT_RETRY_AFTER).to_i
-            end
+          # Retry once if response has a retryable error code
+          if response && @error_codes.include?(response.env[:status])
+            original_env[:call_attempt] += 1
+            seconds_left = (response.env[:response_headers][:retry_after] || DEFAULT_RETRY_AFTER).to_i
+            @logger&.warn "You may have been rate limited. Retrying in #{seconds_left} seconds..."
+            instrument_retry(original_env, (response.env[:status] == 429) ? "rate_limited" : "server_error", seconds_left)
+            sleep_with_logging(seconds_left)
+            response = @app.call(original_env)
+          end
 
-            @logger.warn "You have been rate limited. Retrying in #{seconds_left} seconds..." if @logger
+          response
+        end
 
-            seconds_left.times do |i|
-              sleep 1
-              time_left = seconds_left - i
-              @logger.warn "#{time_left}..." if time_left > 0 && time_left % 5 == 0 && @logger
-            end
+        private
 
-            @logger.warn "" if @logger
+        def instrument_retry(env, reason, delay)
+          return unless @instrumentation
 
-            @app.call(original_env)
-          else
-            response
+          begin
+            @instrumentation.instrument(
+              "zendesk.retry",
+              {
+                attempt: env[:call_attempt],
+                endpoint: env[:url]&.path,
+                method: env[:method],
+                reason: reason,
+                delay: delay
+              }
+            )
+          rescue => e
+            @logger&.debug("zendesk.retry instrumentation failed: #{e.message}")
+          end
+        end
+
+        def sleep_with_logging(seconds_left)
+          seconds_left.times do |i|
+            sleep 1
+            time_left = seconds_left - i
+            @logger&.warn "#{time_left}..." if time_left > 0 && time_left % 5 == 0
           end
+          @logger&.warn "" if seconds_left > 0
         end
       end
     end

data/lib/zendesk_api/middleware/request/upload.rb

@@ -1,6 +1,6 @@
 require "faraday/middleware"
 require "mini_mime"
-require 'tempfile'
+require "tempfile"
 
 module ZendeskAPI
   module Middleware

data/lib/zendesk_api/middleware/request/url_based_access_token.rb

@@ -11,9 +11,9 @@ module ZendeskAPI
 
         def call(env)
           if env[:url].query
-            env[:url].query += '&'
+            env[:url].query += "&"
           else
-            env[:url].query = ''
+            env[:url].query = ""
           end
 
           env[:url].query += "access_token=#{@token}"

data/lib/zendesk_api/middleware/response/deflate.rb

@@ -7,7 +7,7 @@ module ZendeskAPI
       # @private
       class Deflate < Faraday::Middleware
         def on_complete(env)
-          return if env[:response_headers]['content-encoding'] != "deflate"
+          return if env[:response_headers]["content-encoding"] != "deflate"
           return if env.body.strip.empty?
 
           env.body = Zlib::Inflate.inflate(env.body)

data/lib/zendesk_api/middleware/response/gzip.rb

@@ -1,5 +1,5 @@
-require 'zlib'
-require 'stringio'
+require "zlib"
+require "stringio"
 
 module ZendeskAPI
   # @private
@@ -9,7 +9,7 @@ module ZendeskAPI
       # Faraday middleware to handle content-encoding = gzip
       class Gzip < Faraday::Middleware
         def on_complete(env)
-          return if env[:response_headers]['content-encoding'] != "gzip"
+          return if env[:response_headers]["content-encoding"] != "gzip"
           return if env[:body].force_encoding(Encoding::BINARY).strip.empty?
 
           env[:body] = Zlib::GzipReader.new(StringIO.new(env[:body])).read

data/lib/zendesk_api/middleware/response/logger.rb

@@ -10,13 +10,13 @@ module ZendeskAPI
           super(app)
 
           @logger = logger || begin
-            require 'logger'
-            ::Logger.new(STDOUT)
+            require "logger"
+            ::Logger.new($stdout)
           end
         end
 
         def call(env)
-          @logger.info "#{env[:method]} #{env[:url].to_s}"
+          @logger.info "#{env[:method]} #{env[:url]}"
           @logger.debug dump_debug(env, :request_headers)
 
           @app.call(env).on_complete do |env|

data/lib/zendesk_api/middleware/response/parse_iso_dates.rb

@@ -1,4 +1,4 @@
-require 'time'
+require "time"
 require "faraday/response"
 
 module ZendeskAPI

data/lib/zendesk_api/middleware/response/parse_json.rb

@@ -4,13 +4,13 @@ module ZendeskAPI
     # @private
     module Response
       class ParseJson < Faraday::Middleware
-        CONTENT_TYPE = 'Content-Type'.freeze
+        CONTENT_TYPE = "Content-Type".freeze
 
         def on_complete(env)
           type = env[:response_headers][CONTENT_TYPE].to_s
-          type = type.split(';', 2).first if type.index(';')
+          type = type.split(";", 2).first if type.index(";")
 
-          return unless type == 'application/json'
+          return unless type == "application/json"
 
           unless env[:body].strip.empty?
             env[:body] = JSON.parse(env[:body])

data/lib/zendesk_api/middleware/response/raise_error.rb

@@ -1,4 +1,4 @@
-require 'zendesk_api/error'
+require_relative "../../error"
 
 module ZendeskAPI
   module Middleware

data/lib/zendesk_api/middleware/response/sanitize_response.rb

@@ -3,7 +3,7 @@ module ZendeskAPI
     module Response
       class SanitizeResponse < Faraday::Middleware
         def on_complete(env)
-          env[:body].scrub!('')
+          env[:body].scrub!("")
         end
       end
     end