ruby-jira 0.1.0 → 0.2.0

data/lib/jira/pagination/paginated_response.rb

@@ -3,64 +3,41 @@
 require "uri"
 
 module Jira
-  # Wrapper for Jira offset-paginated responses (values/isLast style).
+  # Wrapper for Jira offset-paginated responses.
   #
-  # Endpoints like GET /project/search and GET /workflow/search return a body of:
-  #   { values: [...], isLast: bool, total: int, nextPage: url, startAt: int, maxResults: int }
+  # Supports two formats:
+  # - Classic: { values: [...], isLast: bool, nextPage: url, startAt: int, maxResults: int, total: int }
+  #   (GET /project/search, GET /issue/{key}/changelog, POST /comment/list)
+  # - Legacy: { <items_key>: [...], startAt: int, maxResults: int, total: int }
+  #   (GET /issue/{key}/comment, GET /issue/{key}/worklog)
+  #
+  # For legacy format, items key is auto-detected (first non-metadata Array value).
+  # When nextPage URL is absent, a next_page_fetcher proc set by the Request layer
+  # drives pagination by incrementing startAt.
   class PaginatedResponse
-    attr_accessor :client
+    include Logging
+    include Pagination::CollectionBehavior
+
+    METADATA_KEYS = %i[
+      isLast maxResults nextPage self startAt total pageSize nextPageToken expand warningMessages
+    ].freeze
+
+    attr_accessor :client, :next_page_fetcher
     attr_reader :total, :max_results, :start_at, :self_url
 
-    def initialize(body)
+    def initialize(body) # rubocop:disable Metrics/AbcSize
       @body = body
-      @array = wrap_items(body.fetch(:values, []))
-      @is_last = body.fetch(:isLast, false)
-      @max_results = body.fetch(:maxResults, 0).to_i
+      items_key, items = detect_items(body)
+      log "PaginatedResponse: items_key=#{items_key.inspect} count=#{items.length}"
+      @array = wrap_items(items)
+      @is_last = body.key?(:isLast) ? body[:isLast] : (@array.length + body.fetch(:startAt, 0) >= body.fetch(:total, 0))
+      @max_results = (body[:maxResults] || body[:pageSize] || items.length).to_i
       @next_page = body.fetch(:nextPage, "")
       @self_url = body.fetch(:self, "")
       @start_at = body.fetch(:startAt, 0).to_i
       @total = body.fetch(:total, 0).to_i
     end
 
-    def inspect
-      @array.inspect
-    end
-
-    def method_missing(name, *, &)
-      return @array.send(name, *, &) if @array.respond_to?(name)
-
-      super
-    end
-
-    def respond_to_missing?(method_name, include_private = false)
-      super || @array.respond_to?(method_name, include_private)
-    end
-
-    def each_page
-      current = self
-      yield current
-      while current.has_next_page?
-        current = current.next_page
-        yield current
-      end
-    end
-
-    def lazy_paginate
-      to_enum(:each_page).lazy.flat_map(&:to_ary)
-    end
-
-    def auto_paginate(&block)
-      return lazy_paginate.to_a unless block
-
-      lazy_paginate.each(&block)
-    end
-
-    def paginate_with_limit(limit, &block)
-      return lazy_paginate.take(limit).to_a unless block
-
-      lazy_paginate.take(limit).each(&block)
-    end
-
     def last_page?
       @is_last == true
     end
@@ -72,14 +49,20 @@ module Jira
     alias has_first_page? first_page?
 
     def next_page?
-      @is_last == false && !@next_page.to_s.empty?
+      !last_page? && (!@next_page.to_s.empty? || !@next_page_fetcher.nil?)
     end
     alias has_next_page? next_page?
 
     def next_page
-      return nil unless has_next_page?
+      return nil unless next_page?
+      return next_page_by_link unless @next_page.to_s.empty?
+      raise Error::MissingCredentials, "next_page_fetcher not set on PaginatedResponse" unless @next_page_fetcher
 
-      @client.get(client_relative_path(@next_page))
+      @next_page_fetcher.call(@start_at + @max_results)
+    end
+
+    def pagination_progress_marker
+      [@start_at, @next_page.to_s]
     end
 
     def client_relative_path(link)
@@ -89,6 +72,19 @@ module Jira
 
     private
 
+    def next_page_by_link
+      raise Error::MissingCredentials, "client not set on PaginatedResponse" unless @client
+
+      @client.get(client_relative_path(@next_page))
+    end
+
+    def detect_items(body)
+      return [:values, body[:values]] if body.key?(:values)
+
+      body.each { |k, v| return [k, v] if !METADATA_KEYS.include?(k) && v.is_a?(Array) }
+      [nil, []]
+    end
+
     def wrap_items(items)
       items.map { |item| item.is_a?(Hash) ? ObjectifiedHash.new(item) : item }
     end

data/lib/jira/request/rate_limiting.rb

@@ -8,12 +8,12 @@ module Jira
     # https://developer.atlassian.com/cloud/jira/platform/rate-limiting/
     #
     # Supported response headers (enforced by Jira Cloud):
-    #   Retry-After        — seconds to wait before retrying (429 and some 503)
-    #   X-RateLimit-Reset  — ISO 8601 timestamp when the window resets (429 only)
-    #   X-RateLimit-Limit  — max request rate for the current scope
-    #   X-RateLimit-Remaining — remaining capacity in the current window
-    #   X-RateLimit-NearLimit — "true" when < 20% capacity remains
-    #   RateLimit-Reason   — which limit was exceeded (burst/quota/per-issue)
+    #   Retry-After           - seconds to wait before retrying (429 and some 503)
+    #   X-RateLimit-Reset     - ISO 8601 timestamp when the window resets (429 only)
+    #   X-RateLimit-Limit     - max request rate for the current scope
+    #   X-RateLimit-Remaining - remaining capacity in the current window
+    #   X-RateLimit-NearLimit - "true" when < 20% capacity remains
+    #   RateLimit-Reason      - which limit was exceeded (burst/quota/per-issue)
     class RetryPolicy
       IDEMPOTENT_HTTP_METHODS = %w[get head put delete options].freeze
 

data/lib/jira/request/response_parsing.rb

@@ -4,16 +4,12 @@ module Jira
   class Request
     class ResponseParser
       class << self
-        def parse(body) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def parse(body)
           decoded = decode(body)
-          return PaginatedResponse.new(decoded) if offset_paginated?(decoded)
-          return CursorPaginatedResponse.new(decoded) if cursor_paginated?(decoded)
-          return ObjectifiedHash.new(decoded) if decoded.is_a?(Hash)
-          return decoded.map { |item| item.is_a?(Hash) ? ObjectifiedHash.new(item) : item } if decoded.is_a?(Array)
-          return true if decoded
-          return false unless decoded
+          paginated = parse_paginated(decoded)
+          return paginated if paginated
 
-          raise Error::Parsing, "Couldn't parse a response body"
+          parse_non_paginated(decoded)
         end
 
         def decode(response)
@@ -26,18 +22,88 @@ module Jira
 
         private
 
-        # Offset-based pagination: GET /project/search, GET /workflow/search, etc.
-        # Requires :values and at least one offset-pagination hint.
+        def parse_paginated(decoded)
+          case pagination_model(decoded)
+          when :cursor
+            CursorPaginatedResponse.new(decoded)
+          when :offset
+            PaginatedResponse.new(decoded)
+          end
+        end
+
+        def parse_non_paginated(decoded)
+          return ObjectifiedHash.new(decoded) if decoded.is_a?(Hash)
+          return decoded.map { |item| item.is_a?(Hash) ? ObjectifiedHash.new(item) : item } if decoded.is_a?(Array)
+          return true if decoded
+          return false unless decoded
+
+          raise Error::Parsing, "Couldn't parse a response body"
+        end
+
+        def pagination_model(body)
+          return nil unless body.is_a?(Hash)
+          return :cursor if cursor_paginated?(body)
+          return :offset if offset_paginated?(body)
+
+          nil
+        end
+
+        # Offset-based pagination:
+        # - PageBean responses: startAt/maxResults/total/isLast/nextPage + values
+        # - Legacy page responses: startAt/maxResults/total + endpoint-specific items key
         def offset_paginated?(body)
-          body.is_a?(Hash) &&
-            body.key?(:values) &&
-            (body.key?(:isLast) || body.key?(:nextPage) || body.key?(:startAt))
+          return false unless body.is_a?(Hash)
+          return false if cursor_signature?(body)
+
+          offset_values_signature?(body) || offset_generic_signature?(body)
         end
 
-        # Cursor-based pagination: POST /search/jql, etc.
-        # The token drives the next request; items live under a variable key.
+        # Cursor-based pagination:
+        # - Token: nextPageToken (search/jql and similar)
+        # - Cursor: nextPageCursor/cursor (plans-like)
+        # - URL cursor: nextPage + lastPage without startAt (changed-worklogs style)
+        # - Last page marker in token-based APIs: isLast + array without startAt
         def cursor_paginated?(body)
-          body.is_a?(Hash) && body.key?(:nextPageToken)
+          return false unless body.is_a?(Hash)
+
+          cursor_by_token?(body) ||
+            cursor_by_cursor?(body) ||
+            cursor_by_link?(body) ||
+            cursor_last_page_without_token?(body)
+        end
+
+        def cursor_by_token?(body)
+          body.key?(:nextPageToken)
+        end
+
+        def cursor_by_cursor?(body)
+          body.key?(:nextPageCursor) || body.key?(:cursor)
+        end
+
+        def cursor_by_link?(body)
+          body.key?(:nextPage) && body.key?(:lastPage) && !body.key?(:startAt)
+        end
+
+        def cursor_last_page_without_token?(body)
+          body.key?(:isLast) && !body.key?(:startAt) && !body.key?(:values) && body.values.any?(Array)
+        end
+
+        def cursor_signature?(body)
+          cursor_by_token?(body) || cursor_by_cursor?(body) || cursor_by_link?(body)
+        end
+
+        def offset_values_signature?(body)
+          body.key?(:values) && (body.key?(:isLast) || body.key?(:nextPage) || body.key?(:startAt))
+        end
+
+        def offset_generic_signature?(body)
+          markers_present = body.key?(:maxResults) ||
+                            body.key?(:pageSize) ||
+                            body.key?(:total) ||
+                            body.key?(:isLast) ||
+                            body.key?(:nextPage)
+
+          body.key?(:startAt) && markers_present && body.values.any?(Array)
         end
       end
     end

data/lib/jira/request.rb

@@ -6,6 +6,7 @@ require "json"
 require "time"
 require "uri"
 
+require_relative "logging"
 require_relative "request/authentication"
 require_relative "request/rate_limiting"
 require_relative "request/request_building"
@@ -15,6 +16,7 @@ module Jira
   # @private
   class Request
     include HTTParty
+    include Logging
 
     OAUTH_MISSING_CREDENTIALS_MESSAGE = Authenticator::OAUTH_MISSING_CREDENTIALS_MESSAGE
 
@@ -79,8 +81,10 @@ module Jira
     def execute_request(method, path, options)
       params = params_builder.build(options)
       retries_left = retries_left_for(params)
+      log "#{method.upcase} #{path} #{options.inspect}"
       result = perform_request_with_retry(method, path, params, retries_left)
-      setup_cursor_fetcher!(result, method, path, options) if result.is_a?(CursorPaginatedResponse)
+      log "→ #{result.class}"
+      setup_pagination_fetcher!(result, method, path, options)
       result
     end
 
@@ -90,24 +94,52 @@ module Jira
     rescue Jira::Error::TooManyRequests, Jira::Error::ServiceUnavailable => e
       raise e unless should_retry?(e, method, response, retries_left)
 
+      wait = retry_policy.wait_seconds(response: response, retries_left: retries_left - 1)
+      log "rate limited (HTTP #{response.code}), retrying in #{wait.round(1)}s (#{retries_left - 1} retries left)"
       retry_policy.sleep_before_retry(response: response, retries_left: retries_left - 1)
       retries_left -= 1
       retry
     end
 
-    def setup_cursor_fetcher!(result, method, path, options)
-      result.next_page_fetcher = lambda do |token|
-        merged = options.dup
-        if method.to_s == "get"
-          merged[:query] = (merged.fetch(:query, nil) || {}).merge(nextPageToken: token)
-        else
-          body = merged[:body].is_a?(Hash) ? merged[:body].dup : {}
-          merged[:body] = body.merge(nextPageToken: token)
-        end
+    def setup_pagination_fetcher!(result, method, path, options)
+      case result
+      when PaginatedResponse
+        setup_fetcher_for(result:, method:, path:, options:, key: :startAt)
+      when CursorPaginatedResponse
+        return unless result.fetcher_based_pagination?
+        return if result.cursor_parameter_key.nil?
+
+        setup_fetcher_for(result:, method:, path:, options:, key: result.cursor_parameter_key)
+      end
+    end
+
+    def setup_fetcher_for(result:, method:, path:, options:, key:)
+      result.next_page_fetcher = lambda do |value|
+        merged = duplicate_request_options(options)
+        inject_pagination_parameter!(options: merged, method:, key:, value:)
         send(method, path, merged)
       end
     end
 
+    def duplicate_request_options(options)
+      duplicated = options.dup
+      duplicated[:query] = options[:query].dup if options[:query].is_a?(Hash)
+      duplicated[:body] = options[:body].dup if options[:body].is_a?(Hash)
+      duplicated
+    end
+
+    def inject_pagination_parameter!(options:, method:, key:, value:)
+      target = pagination_parameter_target(method:, options:)
+      options[target] = (options[target] || {}).merge(key => value)
+    end
+
+    def pagination_parameter_target(method:, options:)
+      return :query if method.to_s == "get"
+      return :body if options[:body].is_a?(Hash)
+
+      :query
+    end
+
     def perform_request(method, path, params)
       self.class.send(method, build_url(path), params)
     end
@@ -116,13 +148,9 @@ module Jira
       params.delete(:ratelimit_retries) || ratelimit_retries || Configuration::DEFAULT_RATELIMIT_RETRIES
     end
 
-    def build_url(path)
-      url_builder.build(path)
-    end
+    def build_url(path) = url_builder.build(path)
 
-    def authorization_header
-      authenticator.authorization_header
-    end
+    def authorization_header = authenticator.authorization_header
 
     def should_retry?(error, method, response, retries_left)
       retry_policy.retryable?(error: error, method: method, response: response, retries_left: retries_left)

data/lib/jira/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jira
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/jira.rb

@@ -2,8 +2,10 @@
 
 require_relative "jira/version"
 require_relative "jira/configuration"
+require_relative "jira/logging"
 require_relative "jira/error"
 require_relative "jira/objectified_hash"
+require_relative "jira/pagination/collection_behavior"
 require_relative "jira/pagination/paginated_response"
 require_relative "jira/pagination/cursor_paginated_response"
 require_relative "jira/request"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jira
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Maciej Kozak
@@ -36,17 +36,24 @@ files:
 - lib/jira.rb
 - lib/jira/api.rb
 - lib/jira/client.rb
+- lib/jira/client/issue_comments.rb
+- lib/jira/client/issue_search.rb
+- lib/jira/client/issue_worklogs.rb
 - lib/jira/client/issues.rb
+- lib/jira/client/project_categories.rb
 - lib/jira/client/project_permission_schemes.rb
+- lib/jira/client/project_properties.rb
 - lib/jira/client/projects.rb
+- lib/jira/client/time_tracking.rb
 - lib/jira/configuration.rb
 - lib/jira/error.rb
+- lib/jira/logging.rb
 - lib/jira/objectified_hash.rb
+- lib/jira/pagination/collection_behavior.rb
 - lib/jira/pagination/cursor_paginated_response.rb
 - lib/jira/pagination/paginated_response.rb
 - lib/jira/request.rb
 - lib/jira/request/authentication.rb
-- lib/jira/request/paginated_response.rb
 - lib/jira/request/rate_limiting.rb
 - lib/jira/request/request_building.rb
 - lib/jira/request/response_parsing.rb

data/lib/jira/request/paginated_response.rb

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-# This file is intentionally empty.
-# PaginatedResponse was moved to Jira::PaginatedResponse (lib/jira/paginated_response.rb).