jira-ruby 2.3.0 → 3.0.0.beta2

data/lib/jira/http_client.rb

@@ -1,17 +1,53 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'net/https'
 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 = {}
@@ -21,9 +57,21 @@ module JIRA
       body = { username: @options[:username].to_s, password: @options[:password].to_s }.to_json
       @options.delete(:username)
       @options.delete(:password)
-      make_request(:post, @options[:context_path] + '/rest/auth/1/session', body, 'Content-Type' => 'application/json')
+      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)
@@ -33,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)
@@ -40,17 +99,20 @@ module JIRA
       execute_request(request)
     end
 
+    # @private
     def basic_auth_http_conn
       http_conn(uri)
     end
 
+    # @private
     def http_conn(uri)
-      if @options[:proxy_address]
-        http_class = Net::HTTP::Proxy(@options[:proxy_address], @options[:proxy_port] || 80, @options[:proxy_username], @options[:proxy_password])
-      else
-        http_class = Net::HTTP
-      end
-      http_conn = http_class.new(uri.host, uri.port)
+      http_conn =
+        if @options[:proxy_address]
+          Net::HTTP.new(uri.host, uri.port, @options[:proxy_address], @options[:proxy_port] || 80,
+                        @options[:proxy_username], @options[:proxy_password])
+        else
+          Net::HTTP.new(uri.host, uri.port)
+        end
       http_conn.use_ssl = @options[:use_ssl]
       if @options[:use_client_cert]
         http_conn.cert = @options[:ssl_client_cert]
@@ -59,14 +121,19 @@ module JIRA
       http_conn.verify_mode = @options[:ssl_verify_mode]
       http_conn.ssl_version = @options[:ssl_version] if @options[:ssl_version]
       http_conn.read_timeout = @options[:read_timeout]
+      http_conn.max_retries = @options[:max_retries] if @options[:max_retries]
       http_conn.ca_file = @options[:ca_file] if @options[:ca_file]
       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
@@ -94,12 +161,12 @@ module JIRA
 
     def store_cookies(response)
       cookies = response.get_fields('set-cookie')
-      if cookies
-        cookies.each do |cookie|
-          data = CGI::Cookie.parse(cookie)
-          data.delete('Path')
-          @cookies.merge!(data)
-        end
+      return unless cookies
+
+      cookies.each do |cookie|
+        data = CGI::Cookie.parse(cookie)
+        data.delete('Path')
+        @cookies.merge!(data)
       end
     end
 

data/lib/jira/http_error.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
 require 'forwardable'
+require 'active_support/core_ext/object'
+
 module JIRA
   class HTTPError < StandardError
     extend Forwardable

data/lib/jira/jwt_client.rb

@@ -1,67 +1,43 @@
+# frozen_string_literal: true
+
 require 'atlassian/jwt'
 
 module JIRA
   class JwtClient < HttpClient
     def make_request(http_method, url, body = '', headers = {})
       @http_method = http_method
+      jwt_header = build_jwt_header(url)
 
-      super(http_method, url, body, headers)
+      super(http_method, url, body, headers.merge(jwt_header))
     end
 
     def make_multipart_request(url, data, headers = {})
       @http_method = :post
+      jwt_header = build_jwt_header(url)
 
-      super(url, data, headers)
+      super(url, data, headers.merge(jwt_header))
     end
 
-    class JwtUriBuilder
-      attr_reader :request_url, :http_method, :shared_secret, :site, :issuer
-
-      def initialize(request_url, http_method, shared_secret, site, issuer)
-        @request_url = request_url
-        @http_method = http_method
-        @shared_secret = shared_secret
-        @site = site
-        @issuer = issuer
-      end
-
-      def build
-        uri = URI.parse(request_url)
-        new_query = URI.decode_www_form(String(uri.query)) << ['jwt', jwt_header]
-        uri.query = URI.encode_www_form(new_query)
-
-        return uri.to_s unless uri.is_a?(URI::HTTP)
-
-        uri.request_uri
-      end
+    private
 
-      private
+    attr_reader :http_method
 
-      def jwt_header
-        claim = Atlassian::Jwt.build_claims \
-          issuer,
-          request_url,
-          http_method.to_s,
-          site,
-          (Time.now - 60).to_i,
-          (Time.now + 86_400).to_i
+    def build_jwt_header(url)
+      jwt = build_jwt(url)
 
-        JWT.encode claim, shared_secret
-      end
+      { 'Authorization' => "JWT #{jwt}" }
     end
 
-    private
-
-    attr_reader :http_method
-
-    def request_path(url)
-      JwtUriBuilder.new(
+    def build_jwt(url)
+      claim = Atlassian::Jwt.build_claims \
+        @options[:issuer],
         url,
         http_method.to_s,
-        @options[:shared_secret],
         @options[:site],
-        @options[:issuer]
-      ).build
+        (Time.now - 60).to_i,
+        (Time.now + 86_400).to_i
+
+      JWT.encode claim, @options[:shared_secret]
     end
   end
 end

data/lib/jira/oauth_client.rb

@@ -1,9 +1,20 @@
+# frozen_string_literal: true
+
 require 'oauth'
 require 'json'
 require 'forwardable'
 
 module JIRA
+  # Client using OAuth 1.0
+  #
+  # @!attribute [rw] consumer
+  #   @return [OAuth::Consumer] The oauth consumer object
+  # @!attribute [r] options
+  #   @return [Hash] The oauth connection options
+  # @!attribute [r] access_token
+  #   @return [OAuth::AccessToken] The oauth access token
   class OauthClient < RequestClient
+    # @private
     DEFAULT_OPTIONS = {
       signature_method: 'RSA-SHA1',
       request_token_path: '/plugins/servlet/oauth/request-token',
@@ -29,11 +40,29 @@ module JIRA
 
     def_instance_delegators :@consumer, :key, :secret, :get_request_token
 
+    # Generally not used directly, but through JIRA::Client.
+    # @param [Hash] options Options as passed from JIRA::Client constructor.
+    # @option options [String] :signature_method The signature method to use (defaults to 'RSA-SHA1')
+    # @option options [String] :request_token_path The path to request a token (defaults to '/plugins/servlet/oauth/request-token')
+    # @option options [String] :authorize_path The path to authorize a token (defaults to '/plugins/servlet/oauth/authorize')
+    # @option options [String] :access_token_path The path to access a token (defaults to '/plugins/servlet/oauth/access-token')
+    # @option options [String] :private_key_file The path to the private key file
+    # @option options [String] :consumer_key The OAuth 1.0 consumer key
+    # @option options [String] :consumer_secret The OAuth 1.0 consumer secret
+    # @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)
       @consumer = init_oauth_consumer(@options)
     end
 
+    # @private
+    # Initialises the OAuth consumer object.
+    # Generally you should not call this method directly, it is called by the constructor.
+    # @param [Hash] _options The options hash
+    # @return [OAuth::Consumer] The OAuth consumer object
     def init_oauth_consumer(_options)
       @options[:request_token_path] = @options[:context_path] + @options[:request_token_path]
       @options[:authorize_path] = @options[:context_path] + @options[:authorize_path]
@@ -45,22 +74,31 @@ module JIRA
 
     # Returns the current request token if it is set, else it creates
     # and sets a new token.
-    def request_token(options = {}, *arguments, &block)
-      @request_token ||= get_request_token(options, *arguments, &block)
+    # @param [Hash] options
+    def request_token(options = {}, ...)
+      @request_token ||= get_request_token(options, ...)
     end
 
     # Sets the request token from a given token and secret.
+    # @param [String] token The request token
+    # @param [String] secret The request token secret
+    # @return [OAuth::RequestToken] The request token object
     def set_request_token(token, secret)
       @request_token = OAuth::RequestToken.new(@consumer, token, secret)
     end
 
     # Initialises and returns a new access token from the params hash
     # returned by the OAuth transaction.
+    # @param [Hash] params The params hash returned by the OAuth transaction
+    # @return [OAuth::AccessToken] The access token object
     def init_access_token(params)
       @access_token = request_token.get_access_token(params)
     end
 
     # Sets the access token from a preexisting token and secret.
+    # @param [String] token The access token
+    # @param [String] secret The access token secret
+    # @return [OAuth::AccessToken] The access token object
     def set_access_token(token, secret)
       @access_token = OAuth::AccessToken.new(@consumer, token, secret)
       @authenticated = true
@@ -69,11 +107,25 @@ module JIRA
 
     # Returns the current access token. Raises an
     # JIRA::Client::UninitializedAccessTokenError exception if it is not set.
+    # @return [OAuth::AccessToken] The access token object
     def access_token
       raise UninitializedAccessTokenError unless @access_token
+
       @access_token
     end
 
+    # Makes a request to the JIRA server using the oauth gem.
+    #
+    # 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 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 make_request(http_method, url, body = '', headers = {})
       # When using oauth_2legged we need to add an empty oauth_token parameter to every request.
       if @options[:auth_type] == :oauth_2legged
@@ -82,7 +134,7 @@ module JIRA
         uri.query = if uri.query.to_s == ''
                       oauth_params_str
                     else
-                      uri.query + '&' + oauth_params_str
+                      "#{uri.query}&#{oauth_params_str}"
                     end
         url = uri.to_s
       end
@@ -97,6 +149,17 @@ module JIRA
       response
     end
 
+    # Makes a multipart request to the JIRA server using the oauth gem.
+    #
+    # 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] data 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, data, headers = {})
       request = Net::HTTP::Post::Multipart.new url, data, headers
 
@@ -107,6 +170,8 @@ module JIRA
       response
     end
 
+    # Returns true if the client is authenticated.
+    # @return [Boolean] True if the client is authenticated
     def authenticated?
       @authenticated
     end

data/lib/jira/railtie.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'jira-ruby'
 require 'rails'
 

data/lib/jira/request_client.rb

@@ -1,31 +1,60 @@
+# frozen_string_literal: true
+
 require 'oauth'
 require 'json'
 require 'net/https'
 
 module JIRA
+  # Base class for request clients specific to a particular authentication method.
   class RequestClient
+    # Makes the JIRA REST API call.
+    #
     # Returns the response if the request was successful (HTTP::2xx) and
     # raises a JIRA::HTTPError if it was not successful, with the response
     # attached.
-
+    #
+    # Generally you should not call this method directly, but use derived classes.
+    #
+    # File uploads are not supported with this method.  Use request_multipart instead.
+    #
+    # @param [Array] args Arguments to pass to the request method
+    # @return [Net::HTTPResponse] The response from the server
+    # @raise [JIRA::HTTPError] if it was not successful
     def request(*args)
       response = make_request(*args)
       raise HTTPError, response unless response.is_a?(Net::HTTPSuccess)
+
       response
     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 derived classes.
+    #
+    # @param [Array] args Arguments to pass to the request method
+    # @return [Net::HTTPResponse] The response from the server
+    # @raise [JIRA::HTTPError] if it was not successful
     def request_multipart(*args)
       response = make_multipart_request(*args)
       raise HTTPError, response unless response.is_a?(Net::HTTPSuccess)
+
       response
     end
 
+    # Abstract method to make a request to the JIRA server.
+    # @abstract
+    # @param [Array] args Arguments to pass to the request method
     def make_request(*args)
       raise NotImplementedError
     end
 
+    # Abstract method to make a request to the JIRA server with a file upload.
+    # @abstract
+    # @param [Array] args Arguments to pass to the request method
     def make_multipart_request(*args)
       raise NotImplementedError
     end
   end
-end
+end

data/lib/jira/resource/agile.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cgi'
 
 module JIRA
@@ -25,7 +27,8 @@ module JIRA
         response = client.get(path_base(client) + "/board/#{board_id}/issue?#{hash_to_query_string(options)}")
         json = parse_json(response.body)
         # To get Issue objects with the same structure as for Issue.all
-        return {} if json['issues'].size.zero?
+        return {} if json['issues'].empty?
+
         issue_ids = json['issues'].map do |issue|
           issue['id']
         end
@@ -58,22 +61,17 @@ module JIRA
         parse_json(response.body)
       end
 
-      # def self.find(client, key, options = {})
-      #   options[:maxResults] ||= 100
-      #   fields = options[:fields].join(',') unless options[:fields].nil?
-      #   response = client.get("/rest/api/latest/search?jql=sprint=#{key}&fields=#{fields}&maxResults=#{options[:maxResults]}")
-      #   parse_json(response.body)
-      # end
-
       private
 
       def self.path_base(client)
-        client.options[:context_path] + '/rest/agile/1.0'
+        "#{client.options[:context_path]}/rest/agile/1.0"
       end
 
       def path_base(client)
         self.class.path_base(client)
       end
+
+      private_class_method :path_base
     end
   end
 end

data/lib/jira/resource/applinks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class ApplicationLinkFactory < JIRA::BaseFactory # :nodoc:
@@ -5,7 +7,7 @@ module JIRA
     end
 
     class ApplicationLink < JIRA::Base
-      REST_BASE_PATH = '/rest/applinks/1.0'.freeze
+      REST_BASE_PATH = '/rest/applinks/1.0'
 
       def self.endpoint_name
         'listApplicationlinks'
@@ -24,12 +26,12 @@ module JIRA
         json = parse_json(response.body)
         json = json['list']
         json.map do |attrs|
-          new(client, { attrs: attrs }.merge(options))
+          new(client, { attrs: }.merge(options))
         end
       end
 
       def self.manifest(client)
-        url = full_url(client) + '/manifest'
+        url = "#{full_url(client)}/manifest"
         response = client.get(url)
         json = parse_json(response.body)
         JIRA::Base.new(client, attrs: json)