ruby-jira 0.1.0

data/lib/jira/request/rate_limiting.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Jira
+  class Request
+    # Implements Jira Cloud rate-limit retry policy.
+    #
+    # Follows the official Atlassian guidance:
+    # 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)
+    class RetryPolicy
+      IDEMPOTENT_HTTP_METHODS = %w[get head put delete options].freeze
+
+      # Unix timestamp threshold: values above this are epoch seconds, not second-counts.
+      UNIX_TIMESTAMP_THRESHOLD = 1_000_000_000
+
+      # Jitter range recommended by Atlassian docs: multiply backoff by factor in [0.7, 1.3].
+      JITTER_RANGE = (0.7..1.3)
+
+      def initialize(request:, rand_proc: method(:rand))
+        @request = request
+        @rand_proc = rand_proc
+      end
+
+      def sleep_before_retry(response:, retries_left:)
+        sleep(wait_seconds(response: response, retries_left: retries_left))
+      end
+
+      def retryable?(error:, method:, response:, retries_left:)
+        return false if retries_left <= 1
+        return false unless IDEMPOTENT_HTTP_METHODS.include?(method.to_s)
+        return true if error.is_a?(Jira::Error::TooManyRequests)
+
+        response_has_rate_limit_hint?(response)
+      end
+
+      def wait_seconds(response:, retries_left:)
+        retry_after = parse_retry_after(response)
+        return retry_after if retry_after
+
+        reset_delay = parse_rate_limit_reset(response)
+        return reset_delay if reset_delay
+
+        exponential_backoff_wait(retries_left)
+      end
+
+      private
+
+      # Retry-After: integer seconds (e.g. "5").
+      def parse_retry_after(response)
+        value = response&.headers&.[]("Retry-After")
+        return nil unless value
+
+        parse_seconds_or_timestamp(value)
+      end
+
+      # X-RateLimit-Reset: ISO 8601 timestamp (e.g. "2024-01-15T10:30:00.000Z").
+      # Also accepts RateLimit-Reset as fallback.
+      def parse_rate_limit_reset(response)
+        value = response&.headers&.[]("X-RateLimit-Reset") || response&.headers&.[]("RateLimit-Reset")
+        return nil unless value
+
+        seconds = parse_seconds_or_timestamp(value)
+        return nil if seconds.nil?
+
+        [seconds, 0.0].max
+      end
+
+      # Parses a header value that can be:
+      #   - integer seconds:      "5"
+      #   - Unix epoch timestamp: "1705314600"
+      #   - ISO 8601 datetime:    "2024-01-15T10:30:00.000Z"  (Jira Cloud standard)
+      #   - HTTP date:            "Mon, 15 Jan 2024 10:30:00 GMT"
+      def parse_seconds_or_timestamp(value)
+        numeric = Float(value)
+        return numeric if numeric < UNIX_TIMESTAMP_THRESHOLD
+
+        [numeric - Time.now.to_f, 0.0].max
+      rescue ArgumentError, TypeError
+        parse_datetime_string(value.to_s)
+      end
+
+      def parse_datetime_string(value)
+        [Time.iso8601(value).to_f - Time.now.to_f, 0.0].max
+      rescue ArgumentError
+        begin
+          [Time.httpdate(value).to_f - Time.now.to_f, 0.0].max
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      # Exponential backoff with proportional jitter, per Atlassian recommendations:
+      # base_delay * 2^attempt, capped at max_delay, multiplied by rand(0.7..1.3).
+      def exponential_backoff_wait(retries_left)
+        retry_attempt = ratelimit_retries - retries_left
+        backoff = [ratelimit_base_delay * (2**retry_attempt), ratelimit_max_delay].min
+        jitter_factor = @rand_proc.call(JITTER_RANGE)
+        [backoff * jitter_factor, ratelimit_max_delay].min
+      end
+
+      def response_has_rate_limit_hint?(response)
+        headers = response&.headers || {}
+        headers.key?("Retry-After") || headers.key?("X-RateLimit-Reset") || headers.key?("RateLimit-Reset")
+      end
+
+      def ratelimit_retries
+        @request.ratelimit_retries || Configuration::DEFAULT_RATELIMIT_RETRIES
+      end
+
+      def ratelimit_base_delay
+        @request.ratelimit_base_delay || Configuration::DEFAULT_RATELIMIT_BASE_DELAY
+      end
+
+      def ratelimit_max_delay
+        @request.ratelimit_max_delay || Configuration::DEFAULT_RATELIMIT_MAX_DELAY
+      end
+    end
+  end
+end

data/lib/jira/request/request_building.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Jira
+  class Request
+    class UrlBuilder
+      OAUTH_API_BASE = "https://api.atlassian.com/ex/jira"
+      PLATFORM_API_PATH = "/rest/api/3"
+
+      def initialize(request:, authenticator:)
+        @request = request
+        @authenticator = authenticator
+      end
+
+      def build(path)
+        "#{api_base_url}#{normalize_path(path)}"
+      end
+
+      def api_request_path
+        URI.parse(api_base_url).request_uri
+      end
+
+      private
+
+      def api_base_url
+        case @authenticator.auth_type
+        when :basic
+          "#{normalized_endpoint}#{PLATFORM_API_PATH}"
+        when :oauth2
+          "#{OAUTH_API_BASE}/#{@request.cloud_id}#{PLATFORM_API_PATH}"
+        end
+      end
+
+      def normalized_endpoint
+        @request.endpoint.to_s.delete_suffix("/")
+      end
+
+      def normalize_path(path)
+        string_path = path.to_s
+        string_path.start_with?("/") ? string_path : "/#{string_path}"
+      end
+    end
+
+    class ParamsBuilder
+      def initialize(request:, authenticator:)
+        @request = request
+        @authenticator = authenticator
+      end
+
+      def build(options)
+        params = options.dup
+        merge_httparty_config!(params)
+        add_authorization_header!(params) unless params[:unauthenticated]
+        serialize_json_body!(params)
+        params
+      end
+
+      private
+
+      def merge_httparty_config!(params)
+        params.merge!(@request.httparty) if @request.httparty
+      end
+
+      def add_authorization_header!(params)
+        params[:headers] ||= {}
+        params[:headers].merge!(@authenticator.authorization_header)
+      end
+
+      def serialize_json_body!(params)
+        return unless params[:body].is_a?(Hash)
+        return if params[:multipart] == true
+
+        params[:headers] ||= {}
+        params[:headers]["Content-Type"] ||= "application/json"
+        params[:body] = params[:body].to_json
+      end
+    end
+  end
+end

data/lib/jira/request/response_parsing.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Jira
+  class Request
+    class ResponseParser
+      class << self
+        def parse(body) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          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
+
+          raise Error::Parsing, "Couldn't parse a response body"
+        end
+
+        def decode(response)
+          return {} if response.nil? || response.empty?
+
+          JSON.parse(response, symbolize_names: true)
+        rescue JSON::ParserError
+          raise Error::Parsing, "The response is not a valid JSON '#{response}'"
+        end
+
+        private
+
+        # Offset-based pagination: GET /project/search, GET /workflow/search, etc.
+        # Requires :values and at least one offset-pagination hint.
+        def offset_paginated?(body)
+          body.is_a?(Hash) &&
+            body.key?(:values) &&
+            (body.key?(:isLast) || body.key?(:nextPage) || body.key?(:startAt))
+        end
+
+        # Cursor-based pagination: POST /search/jql, etc.
+        # The token drives the next request; items live under a variable key.
+        def cursor_paginated?(body)
+          body.is_a?(Hash) && body.key?(:nextPageToken)
+        end
+      end
+    end
+  end
+end

data/lib/jira/request.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "base64"
+require "httparty"
+require "json"
+require "time"
+require "uri"
+
+require_relative "request/authentication"
+require_relative "request/rate_limiting"
+require_relative "request/request_building"
+require_relative "request/response_parsing"
+
+module Jira
+  # @private
+  class Request
+    include HTTParty
+
+    OAUTH_MISSING_CREDENTIALS_MESSAGE = Authenticator::OAUTH_MISSING_CREDENTIALS_MESSAGE
+
+    format :json
+    maintain_method_across_redirects true
+    headers "Accept" => "application/json", "Content-Type" => "application/json"
+    parser(proc { |body, _| parse(body) })
+
+    attr_accessor :endpoint,
+      :auth_type,
+      :email,
+      :api_token,
+      :oauth_access_token,
+      :oauth_client_id,
+      :oauth_client_secret,
+      :oauth_refresh_token,
+      :oauth_grant_type,
+      :oauth_token_endpoint,
+      :oauth_access_token_expires_at,
+      :cloud_id,
+      :httparty,
+      :ratelimit_retries,
+      :ratelimit_base_delay,
+      :ratelimit_max_delay
+
+    class << self
+      def parse(body)
+        ResponseParser.parse(body)
+      end
+
+      def decode(response)
+        ResponseParser.decode(response)
+      end
+    end
+
+    %w[get post put patch delete].each do |method|
+      define_method(method) do |path, options = {}|
+        execute_request(method, path, options)
+      end
+    end
+
+    def validate(response)
+      error_klass = Error.klass(response)
+      raise error_klass, response if error_klass
+
+      parsed = response.parsed_response
+      parsed.client = self if parsed.respond_to?(:client=)
+      parsed
+    end
+
+    def request_defaults
+      validate_endpoint!
+      authenticator.validate!
+    end
+
+    def api_request_path
+      url_builder.api_request_path
+    end
+
+    private
+
+    def execute_request(method, path, options)
+      params = params_builder.build(options)
+      retries_left = retries_left_for(params)
+      result = perform_request_with_retry(method, path, params, retries_left)
+      setup_cursor_fetcher!(result, method, path, options) if result.is_a?(CursorPaginatedResponse)
+      result
+    end
+
+    def perform_request_with_retry(method, path, params, retries_left)
+      response = perform_request(method, path, params)
+      validate(response)
+    rescue Jira::Error::TooManyRequests, Jira::Error::ServiceUnavailable => e
+      raise e unless should_retry?(e, method, response, 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
+        send(method, path, merged)
+      end
+    end
+
+    def perform_request(method, path, params)
+      self.class.send(method, build_url(path), params)
+    end
+
+    def retries_left_for(params)
+      params.delete(:ratelimit_retries) || ratelimit_retries || Configuration::DEFAULT_RATELIMIT_RETRIES
+    end
+
+    def build_url(path)
+      url_builder.build(path)
+    end
+
+    def authorization_header
+      authenticator.authorization_header
+    end
+
+    def should_retry?(error, method, response, retries_left)
+      retry_policy.retryable?(error: error, method: method, response: response, retries_left: retries_left)
+    end
+
+    def validate_endpoint!
+      return unless endpoint.to_s.strip.empty?
+
+      raise Error::MissingCredentials, "Please set an endpoint to API"
+    end
+
+    def authenticator
+      @authenticator ||= Authenticator.new(request: self)
+    end
+
+    def retry_policy
+      @retry_policy ||= RetryPolicy.new(request: self)
+    end
+
+    def params_builder
+      @params_builder ||= ParamsBuilder.new(request: self, authenticator: authenticator)
+    end
+
+    def url_builder
+      @url_builder ||= UrlBuilder.new(request: self, authenticator: authenticator)
+    end
+  end
+end

data/lib/jira/version.rb

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

data/lib/jira.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "jira/version"
+require_relative "jira/configuration"
+require_relative "jira/error"
+require_relative "jira/objectified_hash"
+require_relative "jira/pagination/paginated_response"
+require_relative "jira/pagination/cursor_paginated_response"
+require_relative "jira/request"
+require_relative "jira/api"
+require_relative "jira/client"
+
+module Jira
+  extend Configuration
+
+  # Alias for Jira::Client.new
+  #
+  # @return [Jira::Client]
+  def self.client(options = {})
+    Jira::Client.new(options)
+  end
+
+  def self.method_missing(method, ...)
+    return super unless client.respond_to?(method)
+
+    client.send(method, ...)
+  end
+
+  def self.respond_to_missing?(method_name, include_private = false)
+    client.respond_to?(method_name) || super
+  end
+
+  # Delegate to HTTParty.http_proxy
+  def self.http_proxy(address = nil, port = nil, username = nil, password = nil) # rubocop:disable Metrics/ParameterLists
+    Jira::Request.http_proxy(address, port, username, password)
+  end
+
+  # Returns an unsorted array of available client methods.
+  #
+  # @return [Array<Symbol>]
+  def self.actions # rubocop:disable Metrics/MethodLength
+    hidden = Regexp.union(
+      /endpoint/,
+      /auth_type/,
+      /email/,
+      /api_token/,
+      /oauth_access_token/,
+      /oauth_client_id/,
+      /oauth_client_secret/,
+      /oauth_refresh_token/,
+      /oauth_grant_type/,
+      /oauth_token_endpoint/,
+      /cloud_id/,
+      /user_agent/,
+      /get/,
+      /post/,
+      /put/,
+      /patch/,
+      /\Adelete\z/,
+      /validate\z/,
+      /httparty/
+    )
+    (Jira::Client.instance_methods - Object.methods).reject { |method_name| method_name[hidden] }
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: ruby-jira
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maciej Kozak
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+description: A Ruby wrapper for Jira Cloud API
+email:
+- maciej.kozak@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jira.rb
+- lib/jira/api.rb
+- lib/jira/client.rb
+- lib/jira/client/issues.rb
+- lib/jira/client/project_permission_schemes.rb
+- lib/jira/client/projects.rb
+- lib/jira/configuration.rb
+- lib/jira/error.rb
+- lib/jira/objectified_hash.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
+- lib/jira/version.rb
+homepage: https://github.com/macio/ruby-jira
+licenses:
+- BSD-2-Clause
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/macio/ruby-jira
+  source_code_uri: https://github.com/macio/ruby-jira/tree/main
+  changelog_uri: https://github.com/macio/ruby-jira/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client and CLI for Jira Cloud API
+test_files: []