jira-ruby 3.0.0.beta1 → 3.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce094c983bd1fe30eb23f7aa69fe2d1098e72d483e048a8195b7c1cdbbd61525
-  data.tar.gz: 25c34ab3ef66571e69e7a6ba48d53f640dfcd4366b92365493e7adbf28b81862
+  metadata.gz: 433679cf875ed954de485aea9bf822e89fe31a03455ea4c42feb6ccd09b625f4
+  data.tar.gz: f76496cfd565688dd0297579ee63398969770537c3507caa84e2b03ae4a9babe
 SHA512:
-  metadata.gz: 363e629f6830f245fc2a64e337dc1a8eecff9899721467e1cf8fb150e30ed23ab93ef7469ab1eaadfa8e6d600512b33bdeedb6a0510aff66fdaad3c94fe470fb
-  data.tar.gz: d04851879ce041793922c0d26f645f672246af8ab061f26daba8df7666a264db7ed60636fd8dcacce9256c721b227a8561d871b1b87b292a1871295ec77398a4
+  metadata.gz: 3b4c890643c64efc50bc67e80d9583aeff780cceeef08264cefc2a5b9efca858f5b622dfba366c7a7bfbc1c5ffbd9e34d9abb460f5bb10dc7ad39ef5717d2566
+  data.tar.gz: 4b8c10a1873d6aabe8be992c10df1a743d0701db5a96a4306cf0082f6adb3bf9e55f1e08b518bf0aa93f4eb3cf25e431bb778de59cd70ec07319e8ad206c1d49

data/.github/workflows/CI.yml

@@ -10,6 +10,7 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
+          - '3.4'
           - '3.3'
           - '3.2'
           - '3.1'

data/.github/workflows/codeql.yml

@@ -16,14 +16,10 @@ on:
     branches: [ "master" ]
     paths-ignore:
       - '**/*.md'
-      - 'http-basic-example.rb'
-      - 'example.rb'
   pull_request:
     branches: [ "master" ]
     paths-ignore:
       - '**/*.md'
-      - 'http-basic-example.rb'
-      - 'example.rb'
   schedule:
     - cron: '0 13 * * *'
 

data/.gitignore

@@ -8,6 +8,8 @@ pkg/*
 *.pem
 .DS_STORE
 doc
-.ruby-version
+.ruby-version
+.yardoc
+doc
 
 .rakeTasks

data/.rubocop.yml

@@ -1,10 +1,8 @@
-require:
+plugins:
   - rubocop-rspec
 
 AllCops:
   Exclude:
-    - 'example.rb'
-    - 'http-basic-example.rb'
     - 'vendor/**/*'
   NewCops: enable
   TargetRubyVersion: 3.1
@@ -28,18 +26,6 @@ Style/FrozenStringLiteralComment:
 # 
 # We are going to disable these and fix in pull requests
 ##
-Layout/ClosingHeredocIndentation:
-  Enabled: false
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-Layout/EmptyLinesAroundMethodBody:
-  Enabled: false
-
-Layout/HashAlignment:
-  Enabled: false
-
 Layout/LineLength:
   Enabled: false
 
@@ -55,12 +41,6 @@ Lint/IneffectiveAccessModifier:
 Lint/MissingSuper:
   Enabled: false
 
-Lint/RedundantCopDisableDirective:
-  Enabled: false
-
-Lint/UselessAssignment:
-  Enabled: false
-
 Metrics/AbcSize:
   Enabled: false
 
@@ -79,9 +59,6 @@ Metrics/PerceivedComplexity:
 Naming/AccessorMethodName:
   Enabled: false
 
-Naming/BlockForwarding:
-  Enabled: false
-
 Naming/HeredocDelimiterNaming:
   Enabled: false
 
@@ -91,15 +68,6 @@ Naming/PredicateName:
 Naming/VariableNumber:
   Enabled: false
 
-RSpec/AnyInstance:
-  Enabled: false
-
-RSpec/BeEq:
-  Enabled: false
-
-RSpec/ContextWording:
-  Enabled: false
-
 RSpec/ExampleLength:
   Enabled: false
 
@@ -115,9 +83,6 @@ RSpec/InstanceVariable:
 RSpec/LeakyConstantDeclaration:
   Enabled: false
 
-RSpec/MessageChain:
-  Enabled: false
-
 RSpec/MessageSpies:
   Enabled: false
 
@@ -133,56 +98,23 @@ RSpec/NamedSubject:
 RSpec/NestedGroups:
   Enabled: false
 
-RSpec/NoExpectationExample:
-  Enabled: false
-
-RSpec/PredicateMatcher:
-  Enabled: false
-
 RSpec/ReceiveMessages:
   Enabled: false
 
-RSpec/RepeatedSubjectCall:
-  Enabled: false
-
 RSpec/SpecFilePathFormat:
   Enabled: false
 
-RSpec/SpecFilePathSuffix:
-  Enabled: false
-
 RSpec/StubbedMock:
   Enabled: false
 
 RSpec/SubjectStub:
   Enabled: false
 
-RSpec/VerifiedDoubleReference:
-  Enabled: false
-
 RSpec/VerifiedDoubles:
   Enabled: false
 
-Security/Open:
-  Enabled: false
-
-Style/ArgumentsForwarding:
-  Enabled: false
-
-Style/CaseEquality:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
 Style/MissingRespondToMissing:
   Enabled: false
 
-Style/OpenStructUse:
-  Enabled: false
-
 Style/OptionalBooleanParameter:
   Enabled: false
-
-Style/SymbolProc:
-  Enabled: false

data/.yardopts

@@ -0,0 +1,4 @@
+--title "Jira Ruby"
+--no-private
+lib/**/*.rb
+

data/lib/jira/base.rb

@@ -291,11 +291,7 @@ module JIRA
     # and returns true when found, otherwise proxies the
     # call to the superclass.
     def respond_to?(method_name, _include_all = false)
-      if attrs.key?(method_name.to_s)
-        true
-      else
-        super(method_name)
-      end
+      attrs.key?(method_name.to_s) || super(method_name)
     end
 
     # Overrides method_missing to check the attribute hash
@@ -366,7 +362,7 @@ module JIRA
       rescue JIRA::HTTPError => e
         begin
           set_attrs_from_response(e.response) # Merge error status generated by JIRA REST API
-        rescue JSON::ParserError => parse_exception
+        rescue JSON::ParserError
           set_attrs('exception' => {
                       'class' => e.response.class.name,
                       'code' => e.response.code,
@@ -383,9 +379,9 @@ module JIRA
     # not nil or is not a json response.
     def set_attrs_from_response(response)
       return if response.body.nil? || (response.body.length < 2)
+
       json = self.class.parse_json(response.body)
       set_attrs(json)
-
     end
 
     # Set the current attributes from a hash.  If clobber is true, any existing
@@ -520,15 +516,11 @@ module JIRA
     end
 
     def self.query_params_for_single_fetch(options)
-      options.select do |k, _v|
-        QUERY_PARAMS_FOR_SINGLE_FETCH.include? k
-      end.to_h
+      options.slice(*QUERY_PARAMS_FOR_SINGLE_FETCH)
     end
 
     def self.query_params_for_search(options)
-      options.select do |k, _v|
-        QUERY_PARAMS_FOR_SEARCH.include? k
-      end.to_h
+      options.slice(*QUERY_PARAMS_FOR_SEARCH)
     end
   end
 end

data/lib/jira/client.rb

@@ -2,7 +2,6 @@
 
 require 'json'
 require 'forwardable'
-require 'ostruct'
 
 module JIRA
   # This class is the main access point for all JIRA::Resource instances.
@@ -55,7 +54,7 @@ module JIRA
     #
     # The authenticated client instance returned by the respective client type
     # (Oauth, Basic)
-    attr_accessor :consumer, :request_client, :http_debug, :cache
+    attr_accessor :consumer, :request_client, :http_debug, :field_map_cache
 
     # The configuration options for this client instance
     attr_reader :options
@@ -113,6 +112,23 @@ module JIRA
       default_headers: {}
     }.freeze
 
+    # Creates a new JIRA::Client instance
+    # @param [Hash] options The configuration options for the client
+    # @option options [Symbol] :auth_type The authentication type to use, :basic, :oauth, :oauth_2legged, or :cookie.
+    # @option options [String] :site The base URL for the JIRA instance
+    # @option options [Boolean] :use_ssl Whether to use HTTPS for requests
+    # @option options [Integer] :ssl_verify_mode The SSL verification mode OpenSSL::SSL::VERIFY_PEER or OpenSSL::SSL::VERIFY_NONE
+    # @option options [Hash] :default_headers Additional headers to send with each request
+    # @option options [String] :cert_path The path to the SSL certificate file to verify the server with
+    # @option options [String] :use_client_cert Whether to use a client certificate for authentication
+    # @option options [String] :ssl_client_cert The client certificate to use
+    # @option options [String] :ssl_client_key The client certificate key to use
+    # @option options [String] :proxy_address The address of the proxy server to use
+    # @option options [Integer] :proxy_port The port of the proxy server to use
+    # @option options [String] :proxy_username The username for the proxy server
+    # @option options [String] :proxy_password The password for the proxy server
+    # @return [JIRA::Client] The client instance
+    # @raise [ArgumentError] If an unknown option is given
     def initialize(options = {})
       options = DEFAULT_OPTIONS.merge(options)
       @options = options
@@ -164,8 +180,6 @@ module JIRA
       @http_debug = @options[:http_debug]
 
       @options.freeze
-
-      @cache = OpenStruct.new
     end
 
     def Project # :nodoc:
@@ -289,29 +303,63 @@ module JIRA
     end
 
     # HTTP methods without a body
+
+    # Make an HTTP DELETE request
+    # @param [String] path The path to request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def delete(path, headers = {})
       request(:delete, path, nil, merge_default_headers(headers))
     end
 
+    # Make an HTTP GET request
+    # @param [String] path The path to request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def get(path, headers = {})
       request(:get, path, nil, merge_default_headers(headers))
     end
 
+    # Make an HTTP HEAD request
+    # @param [String] path The path to request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def head(path, headers = {})
       request(:head, path, nil, merge_default_headers(headers))
     end
 
     # HTTP methods with a body
+
+    # Make an HTTP POST request
+    # @param [String] path The path to request
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
     def post(path, body = '', headers = {})
       headers = { 'Content-Type' => 'application/json' }.merge(headers)
       request(:post, path, body, merge_default_headers(headers))
     end
 
+    # Make an HTTP POST request with a file upload
+    # @param [String] path The path to request
+    # @param [String] file The file to upload
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def post_multipart(path, file, headers = {})
       puts "post multipart: #{path} - [#{file}]" if @http_debug
       @request_client.request_multipart(path, file, merge_default_headers(headers))
     end
 
+    # Make an HTTP PUT request
+    # @param [String] path The path to request
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def put(path, body = '', headers = {})
       headers = { 'Content-Type' => 'application/json' }.merge(headers)
       request(:put, path, body, merge_default_headers(headers))
@@ -319,11 +367,18 @@ module JIRA
 
     # Sends the specified HTTP request to the REST API through the
     # appropriate method (oauth, basic).
+    # @param [Symbol] http_method The HTTP method to use
+    # @param [String] path The path to request
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def request(http_method, path, body = '', headers = {})
       puts "#{http_method}: #{path} - [#{body}]" if @http_debug
       @request_client.request(http_method, path, body, headers)
     end
 
+    # @private
     # Stops sensitive client information from being displayed in logs
     def inspect
       "#<JIRA::Client:#{object_id}>"

data/lib/jira/has_many_proxy.rb

@@ -8,37 +8,39 @@
 #
 # In practice, instances of this class behave exactly like an Array.
 #
-class JIRA::HasManyProxy
-  attr_reader :target_class, :parent
-  attr_accessor :collection
+module JIRA
+  class HasManyProxy
+    attr_reader :target_class, :parent
+    attr_accessor :collection
 
-  def initialize(parent, target_class, collection = [])
-    @parent       = parent
-    @target_class = target_class
-    @collection   = collection
-  end
+    def initialize(parent, target_class, collection = [])
+      @parent       = parent
+      @target_class = target_class
+      @collection   = collection
+    end
 
-  # Builds an instance of this class with the correct parent.
-  # For example, issue.comments.build(attrs) will initialize a
-  # comment as follows:
-  #
-  #   JIRA::Resource::Comment.new(issue.client,
-  #                               :attrs => attrs,
-  #                               :issue => issue)
-  def build(attrs = {})
-    resource = target_class.new(parent.client, :attrs => attrs, parent.to_sym => parent)
-    collection << resource
-    resource
-  end
+    # Builds an instance of this class with the correct parent.
+    # For example, issue.comments.build(attrs) will initialize a
+    # comment as follows:
+    #
+    #   JIRA::Resource::Comment.new(issue.client,
+    #                               :attrs => attrs,
+    #                               :issue => issue)
+    def build(attrs = {})
+      resource = target_class.new(parent.client, :attrs => attrs, parent.to_sym => parent)
+      collection << resource
+      resource
+    end
 
-  # Forces an HTTP request to fetch all instances of the target class that
-  # are associated with the parent
-  def all
-    target_class.all(parent.client, parent.to_sym => parent)
-  end
+    # Forces an HTTP request to fetch all instances of the target class that
+    # are associated with the parent
+    def all
+      target_class.all(parent.client, parent.to_sym => parent)
+    end
 
-  # Delegate any missing methods to the collection that this proxy wraps
-  def method_missing(method_name, ...)
-    collection.send(method_name, ...)
+    # Delegate any missing methods to the collection that this proxy wraps
+    def method_missing(method_name, ...)
+      collection.send(method_name, ...)
+    end
   end
 end

data/lib/jira/http_client.rb

@@ -6,14 +6,48 @@ require 'cgi/cookie'
 require 'uri'
 
 module JIRA
+  # Client using HTTP Basic Authentication
+  # @example Basic authentication
+  #   options = {
+  #     auth_type:        :basic,
+  #     site:             "https://jira.example.com",
+  #     use_ssl:          true,
+  #     ssl_verify_mode:  OpenSSL::SSL::VERIFY_PEER,
+  #     cert_path:        '/usr/local/etc/trusted-certificates.pem',
+  #     username:         'jamie',
+  #     password:         'password'
+  #   }
+  #   client = JIRA::Client.new(options)
+  # @example Bearer token authentication
+  #   options = {
+  #     auth_type:        :basic,
+  #     site:             "https://jira.example.com",
+  #     default_headers:  { 'authorization' => "Bearer #{bearer_token_str}" },
+  #     use_ssl:          true,
+  #     ssl_verify_mode:  OpenSSL::SSL::VERIFY_PEER
+  #     cert_path:        '/usr/local/etc/trusted-certificates.pem',
+  #   }
+  #   client = JIRA::Client.new(options)
   class HttpClient < RequestClient
+    # @private
     DEFAULT_OPTIONS = {
       username: nil,
       password: nil
     }.freeze
 
+    # @!attribute [r] options
+    #   @return [Hash] The client options
     attr_reader :options
 
+    # Generally not used directly, but through JIRA::Client.
+    # See JIRA::Client for documentation.
+    # @param [Hash] options Options as passed from JIRA::Client constructor.
+    # @option options [String] :username The username to authenticate with
+    # @option options [String] :password The password to authenticate with
+    # @option options [Hash] :default_headers Additional headers for requests
+    # @option options [String] :proxy_uri Proxy URI
+    # @option options [String] :proxy_user Proxy user
+    # @option options [String] :proxy_password Proxy Password
     def initialize(options)
       @options = DEFAULT_OPTIONS.merge(options)
       @cookies = {}
@@ -26,6 +60,18 @@ module JIRA
       make_request(:post, "#{@options[:context_path]}/rest/auth/1/session", body, 'Content-Type' => 'application/json')
     end
 
+    # Makes a request to the JIRA server.
+    #
+    # Generally you should not call this method directly, but use the helper methods in JIRA::Client.
+    #
+    # File uploads are not supported with this method.  Use make_multipart_request instead.
+    #
+    # @param [Symbol] http_method The HTTP method to use
+    # @param [String] url The JIRA REST URL to call
+    # @param [String] body The request body
+    # @param [Hash] headers Additional headers to send with the request
+    # @return [Net::HTTPResponse] The response from the server
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def make_request(http_method, url, body = '', headers = {})
       # When a proxy is enabled, Net::HTTP expects that the request path omits the domain name
       path = request_path(url)
@@ -35,6 +81,17 @@ module JIRA
       execute_request(request)
     end
 
+    # Makes a multipart request to the JIRA server.
+    #
+    # This is used for file uploads.
+    #
+    # Generally you should not call this method directly, but use the helper methods in JIRA::Client.
+    #
+    # @param [String] url The JIRA REST URL to call
+    # @param [Hash] body The Net::HTTP::Post::Multipart data to send with the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def make_multipart_request(url, body, headers = {})
       path = request_path(url)
       request = Net::HTTP::Post::Multipart.new(path, body, headers)
@@ -42,10 +99,12 @@ module JIRA
       execute_request(request)
     end
 
+    # @private
     def basic_auth_http_conn
       http_conn(uri)
     end
 
+    # @private
     def http_conn(uri)
       http_conn =
         if @options[:proxy_address]
@@ -67,10 +126,14 @@ module JIRA
       http_conn
     end
 
+    # The URI of the JIRA REST API call
+    # @return [URI] The URI of the JIRA REST API call
     def uri
       URI.parse(@options[:site])
     end
 
+    # Returns true if the client is authenticated.
+    # @return [Boolean] True if the client is authenticated
     def authenticated?
       @authenticated
     end
@@ -99,12 +162,12 @@ module JIRA
     def store_cookies(response)
       cookies = response.get_fields('set-cookie')
       return unless cookies
+
       cookies.each do |cookie|
         data = CGI::Cookie.parse(cookie)
         data.delete('Path')
         @cookies.merge!(data)
       end
-
     end
 
     def add_cookies(request)