jira-ruby 1.6.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5433f708b438c961d0ca07b8aa60ae7733382aecb7374d4cc3ea3af1947f0e7f
-  data.tar.gz: d6757f05e80e8c005ad0f20461fac98d5509f87f0e0bebaea025e43e7d180d3e
+  metadata.gz: 113ad755633d6eb87e63d7a97d3228f6649828547c01dee1ae1900ef0d575e2d
+  data.tar.gz: d59620f52976814ee7db58df10213bdb512f042a8b8214789ed07288f2899b65
 SHA512:
-  metadata.gz: 25f924c28544baf800585f9243d6d29622b0facab654aa03cf620bf76e4133731334b649c6af725fb0f246c68e3f5aa17bd8623eba5c2dd66303d2f2b2766dd2
-  data.tar.gz: b15c6540010df98f03acd562a50520dd90705bfa58cb2815070bc0ba3a535aea00d092c61a0f58bd3e3f23345c8ee48cf14e5d602fe324c3f7197b408d64e252
+  metadata.gz: e523698732b5cef8a220259ccf5c42c568ac7eea435ee2ed2f2018cdd25959597d23337a67fac037e00be85a8838d9d32a2c79a156da008380699d2c9529cb03
+  data.tar.gz: cefe63455cb070951d73420dc1144b0c0a4651836427f507d218d3eb0780936e6a740842f6f2df8f68b14be8034bb196b4f5069d21ac0c3cd9e2a4292e43b456

data/.gitignore

@@ -9,3 +9,5 @@ pkg/*
 .DS_STORE
 doc
 .ruby-version
+
+.rakeTasks

data/.travis.yml

@@ -1,8 +1,9 @@
 language: ruby
 rvm:
-    - 2.3
     - 2.4
-    - ruby-head
+    - 2.5
+    - 2.6
+    - 2.7
 before_script:
     - rake jira:generate_public_cert
 script: bundle exec rake spec

data/README.md

@@ -50,7 +50,7 @@ rake jira:generate_public_cert
 
 On Mac OS,
 
-* Follow the instructions under "Mac OSX Installer" here: https://developer.atlassian.com/display/DOCS/Install+the+Atlassian+SDK+on+a+Linux+or+Mac+System
+* Follow the instructions under "Mac OSX Installer" here: https://developer.atlassian.com/server/framework/atlassian-sdk/install-the-atlassian-sdk-on-a-linux-or-mac-system
 * From within the archive directory, run:
 
 ```shell
@@ -99,7 +99,7 @@ defaults to HTTP Basic Auth.
 
 Jira supports cookie based authentication whereby user credentials are passed
 to JIRA via a JIRA REST API call.  This call returns a session cookie which must
-then be sent to all following JIRA REST API calls. 
+then be sent to all following JIRA REST API calls.
 
 To enable cookie based authentication, set `:auth_type` to `:cookie`,
 set `:use_cookies` to `true` and set `:username` and `:password` accordingly.
@@ -114,7 +114,7 @@ options = {
   :context_path       => '',
   :auth_type          => :cookie,  # Set cookie based authentication
   :use_cookies        => true,     # Send cookies with each request
-  :additional_cookies => ['AUTH=vV7uzixt0SScJKg7'] # Optional cookies to send 
+  :additional_cookies => ['AUTH=vV7uzixt0SScJKg7'] # Optional cookies to send
                                                    # with each request
 }
 
@@ -134,15 +134,40 @@ cookie to add to the request.
 
 Some authentication schemes that require additional cookies ignore the username
 and password sent in the JIRA REST API call.  For those use cases, `:username`
-and `:password` may be omitted from `options`. 
+and `:password` may be omitted from `options`.
 
+## Configuring JIRA to use Personal Access Tokens Auth
+If your JIRA system is configured to support Personal Access Token authorization, minor modifications are needed in how credentials are communicated to the server.  Specifically, the paremeters `:username` and `:password` are not needed.  Also, the parameter `:default_headers` is needed to contain the api_token, which can be obtained following the official documentation from [Atlassian](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).  Please note that the Personal Access Token can only be used as it is. If it is encoded (with base64 or any other encoding method) then the token will not work correctly and authentication will fail.
+
+```ruby
+require 'jira-ruby'
+
+# NOTE: the token should not be encoded
+api_token = API_TOKEN_OBTAINED_FROM_JIRA_UI
+
+options = {
+  :site               => 'http://mydomain.atlassian.net:443/',
+  :context_path       => '',
+  :username           => '<the email you sign-in to Jira>',
+  :password           => api_token,
+  :auth_type          => :basic
+}
+
+client = JIRA::Client.new(options)
+
+project = client.Project.find('SAMPLEPROJECT')
+
+project.issues.each do |issue|
+  puts "#{issue.id} - #{issue.summary}"
+end
+```
 ## Using the API Gem in a command line application
 
 Using HTTP Basic Authentication, configure and connect a client to your instance
 of JIRA.
 
 Note: If your Jira install is hosted on [atlassian.net](atlassian.net), it will have no context
-path by default. If you're having issues connecting, try setting context_path 
+path by default. If you're having issues connecting, try setting context_path
 to an empty string in the options hash.
 
 ```ruby
@@ -153,14 +178,18 @@ require 'jira-ruby'
 # Consider the use of :use_ssl and :ssl_verify_mode options if running locally
 # for tests.
 
+# NOTE basic auth no longer works with Jira, you must generate an API token, to do so you must have jira instance access rights. You can generate a token here: https://id.atlassian.com/manage/api-tokens
+
+# You will see JIRA::HTTPError (JIRA::HTTPError) if you attempt to use basic auth with your user's password
+
 username = "myremoteuser"
-password = "myuserspassword"
+api_token = "myApiToken"
 
 options = {
             :username => username,
-            :password => password,
-            :site     => 'http://localhost:8080/',
-            :context_path => '/myjira',
+            :password => api_token,
+            :site     => 'http://localhost:8080/', # or 'https://<your_subdomain>.atlassian.net/'
+            :context_path => '/myjira', # often blank
             :auth_type => :basic,
             :read_timeout => 120
           }
@@ -303,7 +332,7 @@ class App < Sinatra::Base
   # site uri, and the request token, access token, and authorize paths
   before do
     options = {
-      :site               => 'http://localhost:2990',
+      :site               => 'http://localhost:2990/',
       :context_path       => '/jira',
       :signature_method   => 'RSA-SHA1',
       :request_token_path => "/plugins/servlet/oauth/request-token",
@@ -401,7 +430,7 @@ require 'pp'
 require 'jira-ruby'
 
 options = {
-            :site               => 'http://localhost:2990',
+            :site               => 'http://localhost:2990/',
             :context_path       => '/jira',
             :signature_method   => 'RSA-SHA1',
             :private_key_file   => "rsakey.pem",

data/Rakefile

@@ -14,13 +14,13 @@ desc 'Prepare and run rspec tests'
 task :prepare do
   rsa_key = File.expand_path('rsakey.pem')
   unless File.exist?(rsa_key)
-    raise 'rsakey.pem does not exist, tests will fail.  Run `rake jira:generate_public_cert` first'
+    Rake::Task['jira:generate_public_cert'].invoke
   end
 end
 
 desc 'Run RSpec tests'
 # RSpec::Core::RakeTask.new(:spec)
-RSpec::Core::RakeTask.new(:spec) do |task|
+RSpec::Core::RakeTask.new(:spec, [] => [:prepare]) do |task|
   task.rspec_opts = ['--color', '--format', 'doc']
 end
 

data/example.rb

@@ -166,6 +166,14 @@ client.Issue.jql(a_normal_jql_search, max_results: 500)
 # # --------------------------
 # issue.comments.first.save({"body" => "an updated comment frome example.rb"})
 
+
+# # Add attachment to Issue
+# # ------------------------
+#  issue = client.Issue.find('PROJ-1')
+#  attachment = issue.attachments.build
+#  attachment.save('file': '/path/to/file')
+#
+
 # List all available link types
 # ------------------------------
 pp client.Issuelinktype.all

data/jira-ruby.gemspec

@@ -13,8 +13,6 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 1.9.3'
 
-  s.rubyforge_project = 'jira-ruby'
-
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
@@ -22,6 +20,7 @@ Gem::Specification.new do |s|
 
   # Runtime Dependencies
   s.add_runtime_dependency 'activesupport'
+  s.add_runtime_dependency 'atlassian-jwt'
   s.add_runtime_dependency 'multipart-post'
   s.add_runtime_dependency 'oauth', '~> 0.5', '>= 0.5.0'
 

data/lib/jira/base.rb

@@ -424,7 +424,7 @@ module JIRA
       end
       if @attrs['self']
         the_url = @attrs['self']
-        the_url = the_url.sub(@client.options[:site], '') if @client.options[:site]
+        the_url = the_url.sub(@client.options[:site].chomp('/'), '') if @client.options[:site]
         the_url
       elsif key_value
         self.class.singular_path(client, key_value.to_s, prefix)

data/lib/jira/client.rb

@@ -6,7 +6,7 @@ module JIRA
   # This class is the main access point for all JIRA::Resource instances.
   #
   # The client must be initialized with an options hash containing
-  # configuration options.  The available options are:
+  # configuration options. The available options are:
   #
   #   :site               => 'http://localhost:2990',
   #   :context_path       => '/jira',
@@ -14,18 +14,33 @@ module JIRA
   #   :request_token_path => "/plugins/servlet/oauth/request-token",
   #   :authorize_path     => "/plugins/servlet/oauth/authorize",
   #   :access_token_path  => "/plugins/servlet/oauth/access-token",
+  #   :private_key        => nil,
   #   :private_key_file   => "rsakey.pem",
   #   :rest_base_path     => "/rest/api/2",
   #   :consumer_key       => nil,
   #   :consumer_secret    => nil,
   #   :ssl_verify_mode    => OpenSSL::SSL::VERIFY_PEER,
+  #   :ssl_version        => nil,
   #   :use_ssl            => true,
   #   :username           => nil,
   #   :password           => nil,
   #   :auth_type          => :oauth,
   #   :proxy_address      => nil,
   #   :proxy_port         => nil,
-  #   :additional_cookies => nil
+  #   :proxy_username     => nil,
+  #   :proxy_password     => nil,
+  #   :use_cookies        => nil,
+  #   :additional_cookies => nil,
+  #   :default_headers    => {},
+  #   :use_client_cert    => false,
+  #   :read_timeout       => nil,
+  #   :http_debug         => false,
+  #   :shared_secret      => nil,
+  #   :cert_path          => nil,
+  #   :key_path           => nil,
+  #   :ssl_client_cert    => nil,
+  #   :ssl_client_key     => nil
+  #   :ca_file            => nil
   #
   # See the JIRA::Base class methods for all of the available methods on these accessor
   # objects.
@@ -44,6 +59,43 @@ module JIRA
 
     def_delegators :@request_client, :init_access_token, :set_access_token, :set_request_token, :request_token, :access_token, :authenticated?
 
+    DEFINED_OPTIONS = [
+      :site,
+      :context_path,
+      :signature_method,
+      :request_token_path,
+      :authorize_path,
+      :access_token_path,
+      :private_key,
+      :private_key_file,
+      :rest_base_path,
+      :consumer_key,
+      :consumer_secret,
+      :ssl_verify_mode,
+      :ssl_version,
+      :use_ssl,
+      :username,
+      :password,
+      :auth_type,
+      :proxy_address,
+      :proxy_port,
+      :proxy_username,
+      :proxy_password,
+      :use_cookies,
+      :additional_cookies,
+      :default_headers,
+      :use_client_cert,
+      :read_timeout,
+      :http_debug,
+      :issuer,
+      :base_url,
+      :shared_secret,
+      :cert_path,
+      :key_path,
+      :ssl_client_cert,
+      :ssl_client_key
+    ].freeze
+
     DEFAULT_OPTIONS = {
       site: 'http://localhost:2990',
       context_path: '/jira',
@@ -52,7 +104,8 @@ module JIRA
       use_ssl: true,
       use_client_cert: false,
       auth_type: :oauth,
-      http_debug: false
+      http_debug: false,
+      default_headers: {}
     }.freeze
 
     def initialize(options = {})
@@ -60,17 +113,23 @@ module JIRA
       @options = options
       @options[:rest_base_path] = @options[:context_path] + @options[:rest_base_path]
 
+      unknown_options = options.keys.reject { |o| DEFINED_OPTIONS.include?(o) }
+      raise ArgumentError, "Unknown option(s) given: #{unknown_options}" unless unknown_options.empty?
+
       if options[:use_client_cert]
-        raise ArgumentError, 'Options: :cert_path must be set when :use_client_cert is true' unless @options[:cert_path]
-        raise ArgumentError, 'Options: :key_path must be set when :use_client_cert is true' unless @options[:key_path]
-        @options[:cert] = OpenSSL::X509::Certificate.new(File.read(@options[:cert_path]))
-        @options[:key] = OpenSSL::PKey::RSA.new(File.read(@options[:key_path]))
+        @options[:ssl_client_cert] = OpenSSL::X509::Certificate.new(File.read(@options[:cert_path])) if @options[:cert_path]
+        @options[:ssl_client_key] = OpenSSL::PKey::RSA.new(File.read(@options[:key_path])) if @options[:key_path]
+
+        raise ArgumentError, 'Options: :cert_path or :ssl_client_cert must be set when :use_client_cert is true' unless @options[:ssl_client_cert]
+        raise ArgumentError, 'Options: :key_path or :ssl_client_key must be set when :use_client_cert is true' unless @options[:ssl_client_key]
       end
 
       case options[:auth_type]
       when :oauth, :oauth_2legged
         @request_client = OauthClient.new(@options)
         @consumer = @request_client.consumer
+      when :jwt
+        @request_client = JwtClient.new(@options)
       when :basic
         @request_client = HttpClient.new(@options)
       when :cookie
@@ -155,6 +214,10 @@ module JIRA
       JIRA::Resource::BoardFactory.new(self)
     end
 
+    def BoardConfiguration
+      JIRA::Resource::BoardConfigurationFactory.new(self)
+    end
+
     def RapidView
       JIRA::Resource::RapidViewFactory.new(self)
     end
@@ -195,12 +258,12 @@ module JIRA
       JIRA::Resource::IssuelinktypeFactory.new(self)
     end
 
-    def Remotelink
-      JIRA::Resource::RemotelinkFactory.new(self)
+    def IssuePickerSuggestions
+      JIRA::Resource::IssuePickerSuggestionsFactory.new(self)
     end
 
-    def Sprint
-      JIRA::Resource::SprintFactory.new(self)
+    def Remotelink
+      JIRA::Resource::RemotelinkFactory.new(self)
     end
 
     def Agile
@@ -226,6 +289,11 @@ module JIRA
       request(:post, path, body, merge_default_headers(headers))
     end
 
+    def post_multipart(path, file, headers = {})
+      puts "post multipart: #{path} - [#{file}]" if @http_debug
+      @request_client.request_multipart(path, file, headers)
+    end
+
     def put(path, body = '', headers = {})
       headers = { 'Content-Type' => 'application/json' }.merge(headers)
       request(:put, path, body, merge_default_headers(headers))
@@ -238,10 +306,15 @@ module JIRA
       @request_client.request(http_method, path, body, headers)
     end
 
+    # Stops sensitive client information from being displayed in logs
+    def inspect
+      "#<JIRA::Client:#{object_id}>"
+    end
+
     protected
 
     def merge_default_headers(headers)
-      { 'Accept' => 'application/json' }.merge(headers)
+      { 'Accept' => 'application/json' }.merge(@options[:default_headers]).merge(headers)
     end
   end
 end

data/lib/jira/http_client.rb

@@ -6,8 +6,8 @@ require 'uri'
 module JIRA
   class HttpClient < RequestClient
     DEFAULT_OPTIONS = {
-      username: '',
-      password: ''
+      username: nil,
+      password: nil
     }.freeze
 
     attr_reader :options
@@ -18,7 +18,7 @@ module JIRA
     end
 
     def make_cookie_auth_request
-      body = { username: @options[:username], password: @options[:password] }.to_json
+      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')
@@ -29,12 +29,15 @@ module JIRA
       path = request_path(url)
       request = Net::HTTP.const_get(http_method.to_s.capitalize).new(path, headers)
       request.body = body unless body.nil?
-      add_cookies(request) if options[:use_cookies]
-      request.basic_auth(@options[:username], @options[:password]) if @options[:username] && @options[:password]
-      response = basic_auth_http_conn.request(request)
-      @authenticated = response.is_a? Net::HTTPOK
-      store_cookies(response) if options[:use_cookies]
-      response
+
+      execute_request(request)
+    end
+
+    def make_multipart_request(url, body, headers = {})
+      path = request_path(url)
+      request = Net::HTTP::Post::Multipart.new(path, body, headers)
+
+      execute_request(request)
     end
 
     def basic_auth_http_conn
@@ -43,23 +46,25 @@ module JIRA
 
     def http_conn(uri)
       if @options[:proxy_address]
-        http_class = Net::HTTP::Proxy(@options[:proxy_address], @options[:proxy_port] || 80)
+        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.use_ssl = @options[:use_ssl]
       if @options[:use_client_cert]
-        http_conn.cert = @options[:cert]
-        http_conn.key = @options[:key]
+        http_conn.cert = @options[:ssl_client_cert]
+        http_conn.key = @options[:ssl_client_key]
       end
       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.ca_file = @options[:ca_file] if @options[:ca_file]
       http_conn
     end
 
     def uri
-      uri = URI.parse(@options[:site])
+      URI.parse(@options[:site])
     end
 
     def authenticated?
@@ -68,6 +73,17 @@ module JIRA
 
     private
 
+    def execute_request(request)
+      add_cookies(request) if options[:use_cookies]
+      request.basic_auth(@options[:username], @options[:password]) if @options[:username] && @options[:password]
+
+      response = basic_auth_http_conn.request(request)
+      @authenticated = response.is_a? Net::HTTPOK
+      store_cookies(response) if options[:use_cookies]
+
+      response
+    end
+
     def request_path(url)
       parsed_uri = URI(url)
 

data/lib/jira/http_error.rb

@@ -8,7 +8,7 @@ module JIRA
 
     def initialize(response)
       @response = response
-      @message = response.try(:message) || response.try(:body)
+      @message = response.try(:message).presence || response.try(:body)
     end
   end
 end

data/lib/jira/jwt_client.rb

@@ -0,0 +1,67 @@
+require 'atlassian/jwt'
+
+module JIRA
+  class JwtClient < HttpClient
+    def make_request(http_method, url, body = '', headers = {})
+      @http_method = http_method
+
+      super(http_method, url, body, headers)
+    end
+
+    def make_multipart_request(url, data, headers = {})
+      @http_method = :post
+
+      super(url, data, headers)
+    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
+
+      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
+
+        JWT.encode claim, shared_secret
+      end
+    end
+
+    private
+
+    attr_reader :http_method
+
+    def request_path(url)
+      JwtUriBuilder.new(
+        url,
+        http_method.to_s,
+        @options[:shared_secret],
+        @options[:site],
+        @options[:issuer]
+      ).build
+    end
+  end
+end

data/lib/jira/oauth_client.rb

@@ -38,13 +38,15 @@ module JIRA
       @options[:request_token_path] = @options[:context_path] + @options[:request_token_path]
       @options[:authorize_path] = @options[:context_path] + @options[:authorize_path]
       @options[:access_token_path] = @options[:context_path] + @options[:access_token_path]
+      # proxy_address does not exist in oauth's gem context but proxy does
+      @options[:proxy] = @options[:proxy_address] if @options[:proxy_address]
       OAuth::Consumer.new(@options[:consumer_key], @options[:consumer_secret], @options)
     end
 
     # 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)
+      @request_token ||= get_request_token(options, *arguments, &block)
     end
 
     # Sets the request token from a given token and secret.
@@ -72,29 +74,39 @@ module JIRA
       @access_token
     end
 
-    def make_request(http_method, path, body = '', headers = {})
+    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
         oauth_params_str = 'oauth_token='
-        uri = URI.parse(path)
+        uri = URI.parse(url)
         uri.query = if uri.query.to_s == ''
                       oauth_params_str
                     else
                       uri.query + '&' + oauth_params_str
                     end
-        path = uri.to_s
+        url = uri.to_s
       end
 
       case http_method
       when :delete, :get, :head
-        response = access_token.send http_method, path, headers
+        response = access_token.send http_method, url, headers
       when :post, :put
-        response = access_token.send http_method, path, body, headers
+        response = access_token.send http_method, url, body, headers
       end
       @authenticated = true
       response
     end
 
+    def make_multipart_request(url, data, headers = {})
+      request = Net::HTTP::Post::Multipart.new url, data, headers
+
+      access_token.sign! request
+
+      response = consumer.http.request(request)
+      @authenticated = true
+      response
+    end
+
     def authenticated?
       @authenticated
     end

data/lib/jira/request_client.rb

@@ -1,7 +1,6 @@
 require 'oauth'
 require 'json'
 require 'net/https'
-# require 'pry'
 
 module JIRA
   class RequestClient
@@ -11,9 +10,22 @@ module JIRA
 
     def request(*args)
       response = make_request(*args)
-      # binding.pry unless response.kind_of?(Net::HTTPSuccess)
       raise HTTPError, response unless response.is_a?(Net::HTTPSuccess)
       response
     end
+
+    def request_multipart(*args)
+      response = make_multipart_request(*args)
+      raise HTTPError, response unless response.is_a?(Net::HTTPSuccess)
+      response
+    end
+
+    def make_request(*args)
+      raise NotImplementedError
+    end
+
+    def make_multipart_request(*args)
+      raise NotImplementedError
+    end
   end
-end
+end