jenkins_api_client 0.12.1 → 0.13.0

data/lib/jenkins_api_client/build_queue.rb

@@ -34,6 +34,7 @@ module JenkinsApi
       #
       def initialize(client)
         @client = client
+        @logger = @client.logger
       end
 
       # Returns a string representation of BuildQueue class.
@@ -45,6 +46,7 @@ module JenkinsApi
       # Gives the number of jobs currently in the build queue
       #
       def size
+        @logger.info "Obtaining the number of tasks in build queue"
         response_json = @client.api_get_request("/queue")
         response_json["items"].size
       end
@@ -52,6 +54,7 @@ module JenkinsApi
       # Lists all tasks currently in the build queue
       #
       def list
+        @logger.info "Obtaining the tasks currently in the build queue"
         response_json = @client.api_get_request("/queue")
         tasks = []
         response_json["items"].each do |item|
@@ -67,6 +70,8 @@ module JenkinsApi
       # @return [Fixnum] age in seconds
       #
       def get_age(task_name)
+        @logger.info "Obtaining the age of task '#{task_name}' from the" +
+          " build queue"
         age = nil
         details = get_details(task_name)
         unless details.empty?
@@ -82,6 +87,8 @@ module JenkinsApi
       # @return [Hash] Queue details of the specified task/job
       #
       def get_details(task_name)
+        @logger.info "Obtaining the details of task '#{task_name}' from the" +
+          " build queue"
         response_json = @client.api_get_request("/queue")
         details = {}
         response_json["items"].each do |item|
@@ -90,6 +97,17 @@ module JenkinsApi
         details
       end
 
+      # Obtain the item in the queue provided the ID of the task
+      #
+      # @param task_id [String] the ID of the task
+      #
+      # @return [Hash] the details of the item in the queue
+      #
+      def get_item_by_id(task_id)
+        @logger.info "Obtaining the details of task with ID '#{task_id}'"
+        @client.api_get_request("/queue/item/#{task_id}")
+      end
+
       # Obtains the causes from the build queue for the specified task
       #
       # @param [String] task_name
@@ -97,6 +115,8 @@ module JenkinsApi
       # @return [Array] causes for the task to be in queue
       #
       def get_causes(task_name)
+        @logger.info "Obtaining the causes of task '#{task_name}' from the" +
+          " build queue"
         causes = nil
         details = get_details(task_name)
         unless details.empty?
@@ -115,6 +135,8 @@ module JenkinsApi
       # @return [String] reason for being in queue, nil if no task found
       #
       def get_reason(task_name)
+        @logger.info "Obtaining the reason of task '#{task_name}' from the" +
+          " build queue"
         reason = nil
         details = get_details(task_name)
         unless details.empty?
@@ -131,6 +153,8 @@ module JenkinsApi
       #                  tasks with no ETA info.
       #
       def get_eta(task_name)
+        @logger.info "Obtaining the ETA for the task '#{task_name}' from the" +
+          " build queue"
         eta = nil
         details = get_details(task_name)
         unless details.empty?
@@ -153,6 +177,8 @@ module JenkinsApi
       # @return [String] ID of the task, nil of no task is found
       #
       def get_id(task_name)
+        @logger.info "Obtaining the ID of task '#{task_name}' from the" +
+          " build queue"
         id = nil
         details = get_details(task_name)
         unless details.empty?
@@ -168,6 +194,8 @@ module JenkinsApi
       # @return [String] params, nil if the no task is found
       #
       def get_params(task_name)
+        @logger.info "Obtaining the build parameters of task '#{task_name}'" +
+          " from the build queue"
         params = nil
         details = get_details(task_name)
         unless details.empty?
@@ -183,6 +211,8 @@ module JenkinsApi
       # @return [TrueClass|FalseClass] buildable or not
       #
       def is_buildable?(task_name)
+        @logger.info "Checking if task '#{task_name}' from the build queue" +
+          " is buildable"
         buildable = nil
         details = get_details(task_name)
         unless details.empty?
@@ -198,6 +228,8 @@ module JenkinsApi
       # @return [TrueClass|FalseClass] blocked or not
       #
       def is_blocked?(task_name)
+        @logger.info "Checking if task '#{task_name}' from the build queue" +
+          " is blocked"
         blocked = nil
         details = get_details(task_name)
         unless details.empty?
@@ -213,6 +245,8 @@ module JenkinsApi
       # @return [TrueClass|FalseClass] stuck or not
       #
       def is_stuck?(task_name)
+        @logger.info "Checking if task '#{task_name}' from the build queue" +
+          " is stuck"
         stuck = nil
         details = get_details(task_name)
         unless details.empty?

data/lib/jenkins_api_client/cli/job.rb

@@ -89,20 +89,15 @@ module JenkinsApi
       desc "console JOB", "Print the progressive console output of a job"
       method_option :sleep, :aliases => "-z",
         :desc => "Time to wait between querying the API for console output"
-      # CLI command to obtain console output for a job
+      # CLI command to obtain console output for a job. Make sure the log
+      # location is set to something other than STDOUT. By default it is set to
+      # STDOUT. If the log messages are printed on the same console, the
+      # console output will get garbled.
       #
       # @param [String] job Name of the job
       #
       def console(job)
         @client = Helper.setup(parent_options)
-        # If debug is enabled, disable it. It shouldn't interfere
-        # with console output.
-        debug_changed = false
-        if @client.debug == true
-          @client.debug = false
-          debug_changed = true
-        end
-
         # Print progressive console output
         response = @client.job.get_console_output(job)
         puts response['output'] unless response['more']
@@ -114,8 +109,6 @@ module JenkinsApi
         end
         # Print the last few lines
         puts response['output'] unless response['output'].chomp.empty?
-        # Change the debug back if we changed it now
-        @client.toggle_debug if debug_changed
       end
 
       desc "restrict JOB", "Restricts a job to a specific node"

data/lib/jenkins_api_client/client.rb

@@ -26,7 +26,9 @@ require 'net/http'
 require 'net/https'
 require 'nokogiri'
 require 'base64'
-require "mixlib/shellout"
+require 'mixlib/shellout'
+require 'uri'
+require 'logger'
 
 # The main module that contains the Client class and all subclasses that
 # communicate with the Jenkins's Remote Access API.
@@ -37,7 +39,7 @@ module JenkinsApi
   # for various operations.
   #
   class Client
-    attr_accessor :debug, :timeout
+    attr_accessor :timeout, :logger
     # Default port to be used to connect to Jenkins
     DEFAULT_SERVER_PORT = 8080
     # Default timeout in seconds to be used while performing operations
@@ -53,27 +55,54 @@ module JenkinsApi
       "username",
       "password",
       "password_base64",
-      "debug",
+      "log_location",
+      "log_level",
       "timeout",
       "ssl",
-      "follow_redirects"
+      "follow_redirects",
+      "identity_file"
     ].freeze
 
     # Initialize a Client object with Jenkins CI server credentials
     #
-    # @param [Hash] args
-    #  * the +:server_ip+ param is the IP address of the Jenkins CI server
-    #  * the +:server_port+ param is the port on which the Jenkins listens
-    #  * the +:server_url+ param is the full URL address of the Jenkins CI server (http/https)
-    #  * the +:username+ param is the username used for connecting to the server (optional)
-    #  * the +:password+ param is the password for connecting to the CI server (optional)
-    #  * the +:proxy_ip+ param is the proxy IP address
-    #  * the +:proxy_port+ param is the proxy port
-    #  * the +:jenkins_path+ param is the optional context path for Jenkins
-    #  * the +:ssl+ param indicates if Jenkins is accessible over HTTPS
-    #    (defaults to false)
-    #  * the +:follow_redirects+ param will cause the client to follow a redirect
-    #    (jenkins can return a 30x when starting a build)
+    # @param args [Hash] Arguments to connect to Jenkins server
+    #
+    # @option args [String] :server_ip
+    #   the IP address of the Jenkins CI server
+    # @option args [String] :server_port
+    #   the port on which the Jenkins listens
+    # @option args [String] :server_url
+    #   the full URL address of the Jenkins CI server (http/https)
+    # @option args [String] :username
+    #   the username used for connecting to the server (optional)
+    # @option args [String] :password
+    #   the password for connecting to the CI server (optional)
+    # @option args [String] :password_base64
+    #   the password with base64 encoded format for connecting to the CI
+    #   server (optional)
+    # @option args [String] :identity_file
+    #   the priviate key file for Jenkins CLI authentication,
+    #   it is used only for executing CLI commands.
+    #   also remember to upload the public key to http://#{server_ip}:#{server_port}/user/#{my_username}/configure
+    # @option args [String] :proxy_ip
+    #   the proxy IP address
+    # @option args [String] :proxy_port
+    #   the proxy port
+    # @option args [String] :jenkins_path
+    #   the optional context path for Jenkins
+    # @option args [Boolean] :ssl
+    #   indicates if Jenkins is accessible over HTTPS (defaults to false)
+    # @option args [Boolean] :follow_redirects
+    #   This argument causes the client to follow a redirect (jenkins can
+    #   return a 30x when starting a build)
+    # @option args [Fixnum] :timeout
+    #   This argument sets the timeout for the jenkins system to become ready
+    # @option args [String] :log_location
+    #   The location for the log file (Defaults to STDOUT)
+    # @option args [Fixnum] :log_level
+    #   The level for messages to be logged. Should be one of:
+    #   Logger::DEBUG (0), Logger::INFO (1), Logger::WARN (2), Logger::ERROR
+    #   (2), Logger::FATAL (3) (Defaults to Logger::INFO)
     #
     # @return [JenkinsApi::Client] a client object to Jenkins API
     #
@@ -85,10 +114,15 @@ module JenkinsApi
           instance_variable_set("@#{key}", value)
         end
       end if args.is_a? Hash
+
+      # Server IP or Server URL must be specifiec
       unless @server_ip || @server_url
-        raise ArgumentError, "Server IP or Server URL is required to connect to Jenkins"
+        raise ArgumentError, "Server IP or Server URL is required to connect" +
+          " to Jenkins"
       end
-      # Username/password are optional as some jenkins servers do not require auth
+
+      # Username/password are optional as some jenkins servers do not require
+      # authentication
       if @username && !(@password || @password_base64)
         raise ArgumentError, "If username is provided, password is required"
       end
@@ -96,23 +130,44 @@ module JenkinsApi
         raise ArgumentError, "Proxy IP and port must both be specified or" +
           " both left nil"
       end
-      @server_uri = URI.parse(@server_url) if @server_url
+
+      # Get info from the server_url, if we got one
+      if @server_url
+        server_uri = URI.parse(@server_url)
+        @server_ip = server_uri.host
+        @server_port = server_uri.port
+        @ssl = server_uri.scheme == "https"
+        @jenkins_path = server_uri.path
+      end
+
+      @jenkins_path ||= ""
+      @jenkins_path.gsub!(/\/$/,"") # remove trailing slash if there is one
       @server_port = DEFAULT_SERVER_PORT unless @server_port
       @timeout = DEFAULT_TIMEOUT unless @timeout
       @ssl ||= false
-      @ssl = @server_uri.scheme == "https" if @server_uri
-      @debug = false unless @debug
+
+      # Setting log options
+      @log_location = STDOUT unless @log_location
+      @log_level = Logger::INFO unless @log_level
+      @logger = Logger.new(@log_location)
+      @logger.level = @log_level
+
 
       # Base64 decode inserts a newline character at the end. As a workaround
       # added chomp to remove newline characters. I hope nobody uses newline
       # characters at the end of their passwords :)
       @password = Base64.decode64(@password_base64).chomp if @password_base64
-    end
 
-    # This method toggles the debug parameter in run time
-    #
-    def toggle_debug
-      @debug = @debug == false ? true : false
+      # No connections are made to the Jenkins server during initialize to
+      # allow the unit tests to behave normally as mocking is simpler this way.
+      # If this variable is nil, the first POST request will query the API and
+      # populate this variable.
+      @crumbs_enabled = nil
+      # The crumbs hash. Store it so that we don't have to obtain the crumb for
+      # every POST request. It appears that the crumb doesn't change often.
+      @crumb = {}
+      # This is the number of times to refetch the crumb if it ever expires.
+      @crumb_max_retries = 3
     end
 
     # Creates an instance to the Job class by passing a reference to self
@@ -163,6 +218,21 @@ module JenkinsApi
       "#<JenkinsApi::Client>"
     end
 
+    # Overrides the inspect method to get rid of the credentials being shown in
+    # the in interactive IRB sessions and also when the `inspect` method is
+    # called. Just print the important variables.
+    #
+    def inspect
+      "#<JenkinsApi::Client:0x#{(self.__id__ * 2).to_s(16)}" +
+        " @ssl=#{@ssl.inspect}," +
+        " @log_location=#{@log_location.inspect}," +
+        " @log_level=#{@log_level.inspect}," +
+        " @crumbs_enabled=#{@crumbs_enabled.inspect}," +
+        " @follow_redirects=#{@follow_redirects.inspect}," +
+        " @jenkins_path=#{@jenkins_path.inspect}," +
+        " @timeout=#{@timeout.inspect}>"
+    end
+
     # Connects to the Jenkins server, sends the specified request and returns
     # the response.
     #
@@ -174,18 +244,10 @@ module JenkinsApi
     def make_http_request(request, follow_redirect = @follow_redirects)
       request.basic_auth @username, @password if @username
 
-      if @server_uri
-        host = @server_uri.host
-        port = @server_uri.port
-      else
-        host = @server_ip
-        port = @server_port
-      end
-
       if @proxy_ip
-        http = Net::HTTP::Proxy(@proxy_ip, @proxy_port).new(host, port)
+        http = Net::HTTP::Proxy(@proxy_ip, @proxy_port).new(@server_ip, @server_port)
       else
-        http = Net::HTTP.new(host, port)
+        http = Net::HTTP.new(@server_ip, @server_port)
       end
 
       if @ssl
@@ -216,6 +278,7 @@ module JenkinsApi
     # @return [Net::HTTP::Response] Response from Jenkins for "/"
     #
     def get_root
+      @logger.info "GET /"
       request = Net::HTTP::Get.new("/")
       make_http_request(request)
     end
@@ -241,10 +304,10 @@ module JenkinsApi
       end
       to_get = URI.escape(to_get)
       request = Net::HTTP::Get.new(to_get)
-      puts "[INFO] GET #{to_get}" if @debug
+      @logger.info "GET #{to_get}"
       response = make_http_request(request)
       if raw_response
-        response
+        handle_exception(response, "raw")
       else
         handle_exception(response, "body", url_suffix =~ /json/)
       end
@@ -257,16 +320,37 @@ module JenkinsApi
     #
     # @return [String] Response code form Jenkins Response
     #
-    def api_post_request(url_prefix, form_data = {})
-      # Added form_data default {} instead of nil to help with proxies
-      # that barf with empty post
-      url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
-      request = Net::HTTP::Post.new("#{url_prefix}")
-      puts "[INFO] POST #{url_prefix}" if @debug
-      request.content_type = 'application/json'
-      request.set_form_data(form_data)
-      response = make_http_request(request)
-      handle_exception(response)
+    def api_post_request(url_prefix, form_data = {}, raw_response = false)
+      retries = @crumb_max_retries
+      begin
+        # Identify whether to use crumbs if this is the first POST request.
+        @crumbs_enabled = use_crumbs? if @crumbs_enabled.nil?
+        @crumb = get_crumb if @crumbs_enabled && @crumb.empty?
+
+        # Added form_data default {} instead of nil to help with proxies
+        # that barf with empty post
+        url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
+        request = Net::HTTP::Post.new("#{url_prefix}")
+        @logger.info "POST #{url_prefix}"
+        request.content_type = 'application/json'
+        if @crumbs_enabled
+          request[@crumb["crumbRequestField"]] = @crumb["crumb"]
+        end
+        request.set_form_data(form_data)
+        response = make_http_request(request)
+        if raw_response
+          handle_exception(response, "raw")
+        else
+          handle_exception(response)
+        end
+      rescue Exceptions::ForbiddenException
+        @logger.info "Crumb expired. Refetching from the server. Trying" +
+          " #{@crumb_max_retries - retries + 1} out of #{@crumb_max_retries}" +
+          " times..."
+        @crumb = get_crumb
+        retries -= 1
+        retries > 0 ? retry : raise
+      end
     end
 
     # Obtains the configuration of a component from the Jenkins CI server
@@ -278,7 +362,7 @@ module JenkinsApi
     def get_config(url_prefix)
       url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
       request = Net::HTTP::Get.new("#{url_prefix}/config.xml")
-      puts "[INFO] GET #{url_prefix}/config.xml" if @debug
+      @logger.info "GET #{url_prefix}/config.xml"
       response = make_http_request(request)
       handle_exception(response, "body")
     end
@@ -291,18 +375,54 @@ module JenkinsApi
     # @return [String] Response code returned from Jenkins
     #
     def post_config(url_prefix, xml)
-      url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
-      request = Net::HTTP::Post.new("#{url_prefix}")
-      puts "[INFO] POST #{url_prefix}" if @debug
-      request.body = xml
-      request.content_type = 'application/xml'
-      response = make_http_request(request)
-      handle_exception(response)
+      retries = @crumb_max_retries
+      begin
+        # Identify whether to use crumbs if this is the first POST request.
+        @crumbs_enabled = use_crumbs? if @crumbs_enabled.nil?
+        @crumb = get_crumb if @crumbs_enabled && @crumb.empty?
+
+        url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
+        request = Net::HTTP::Post.new("#{url_prefix}")
+        @logger.info "POST #{url_prefix}"
+        request.body = xml
+        request.content_type = 'application/xml'
+        if @crumbs_enabled
+          request[@crumb["crumbRequestField"]] = @crumb["crumb"]
+        end
+        response = make_http_request(request)
+        handle_exception(response)
+      rescue Exceptions::ForbiddenException
+        @logger.info "Crumb expired. Refetching from the server. Trying" +
+          " #{@crumb_max_retries - retries + 1} out of #{@crumb_max_retries}" +
+          " times..."
+        @crumb = get_crumb
+        retries -= 1
+        retries > 0 ? retry : raise
+      end
+    end
+
+    # Checks if Jenkins uses crumbs (i.e) the XSS disable option is checked in
+    # Jenkins' security settings
+    #
+    # @return [Boolean] whether Jenkins uses crumbs or not
+    #
+    def use_crumbs?
+      response = api_get_request("")
+      response["useCrumbs"]
     end
 
-    # Obtain the version of Jenkins CI server
+    # Checks if Jenkins uses security
+    #
+    # @return [Boolean] whether Jenkins uses security or not
     #
-    # @return [String] Version of Jenkins
+    def use_security?
+      response = api_get_request("")
+      response["useSecurity"]
+    end
+
+    # Obtains the jenkins version from the API
+    #
+    # @return Jenkins version
     #
     def get_jenkins_version
       response = get_root
@@ -340,10 +460,11 @@ module JenkinsApi
     def exec_cli(command, args = [])
       base_dir = File.dirname(__FILE__)
       server_url = "http://#{@server_ip}:#{@server_port}/#{@jenkins_path}"
-      cmd = "java -jar #{base_dir}/../../java_deps/jenkins-cli.jar" +
-        " -s #{server_url} #{command}" +
-        " --username #{@username} --password #{@password} " +
-        args.join(' ')
+      cmd = "java -jar #{base_dir}/../../java_deps/jenkins-cli.jar -s #{server_url}"
+      cmd << " -i #{@identity_file}" if @identity_file && !@identity_file.empty?
+      cmd << " #{command}"
+      cmd << " --username #{@username} --password #{@password} " if @identity_file.nil? || @identity_file.empty?
+      cmd << args.join(' ')
       java_cmd = Mixlib::ShellOut.new(cmd)
 
       # Run the command
@@ -354,37 +475,62 @@ module JenkinsApi
         # The stderr has a stack trace of the Java program. We'll already have
         # a stack trace for Ruby. So just display a descriptive message for the
         # error thrown by the CLI.
-        raise Exceptions::CLIException.new(java_cmd.stderr.split("\n").first)
+        raise Exceptions::CLIException.new(
+          @logger,
+          java_cmd.stderr.split("\n").first
+        )
       end
     end
 
     private
 
+    # Obtains the crumb from Jenkins' crumb issuer
+    #
+    # @return [Hash<String, String>] the crumb response from Jenkins' crumb
+    #   issuer
+    #
+    # @raise Exceptions::CrumbNotFoundException if the crumb is not provided
+    #   (i.e) XSS disable option is not checked in Jenkins' security setting
+    #
+    def get_crumb
+      begin
+        @logger.debug "Obtaining crumb from the jenkins server"
+        api_get_request("/crumbIssuer")
+      rescue Exceptions::NotFoundException
+        raise Exceptions::CrumbNotFoundException.new(
+          @logger,
+          "CSRF protection is not enabled on the server at the moment." +
+          " Perhaps the client was initialized when the CSRF setting was" +
+          " enabled. Please re-initialize the client."
+        )
+      end
+    end
+
     # Private method that handles the exception and raises with proper error
     # message with the type of exception and returns the required values if no
     # exceptions are raised.
     #
     # @param [Net::HTTP::Response] response Response from Jenkins
     # @param [String] to_send What should be returned as a response. Allowed
-    #   values: "code" and "body".
+    #   values: "code", "body", and "raw".
     # @param [Boolean] send_json Boolean value used to determine whether to
     #   load the JSON or send the response as is.
     #
     # @return [String, JSON] Response returned whether loaded JSON or raw
     #   string
     #
-    # @raise [Exceptions::UnauthorizedException] When invalid credentials are
+    # @raise [Exceptions::Unauthorized] When invalid credentials are
     #   provided to connect to Jenkins
-    # @raise [Exceptions::NotFoundException] When the requested page on Jenkins
-    #   is found
-    # @raise [Exceptions::InternelServerErrorException] When Jenkins returns a
-    #   500 Internel Server Error
+    # @raise [Exceptions::NotFound] When the requested page on Jenkins is not
+    #   found
+    # @raise [Exceptions::InternalServerError] When Jenkins returns a 500
+    #   Internal Server Error
     # @raise [Exceptions::ApiException] Any other exception returned from
     #   Jenkins that are not categorized in the API Client.
     #
     def handle_exception(response, to_send = "code", send_json = false)
       msg = "HTTP Code: #{response.code}, Response Body: #{response.body}"
-      puts msg if @debug
+      @logger.debug msg
       case response.code.to_i
       # As of Jenkins version 1.519, the job builds return a 201 status code
       # with a Location HTTP header with the pointing the URL of the item in
@@ -396,24 +542,40 @@ module JenkinsApi
           return response.body
         elsif to_send == "code"
           return response.code
+        elsif to_send == "raw"
+          return response
         end
       when 400
-        case response.body
+        matched = response.body.match(/<p>(.*)<\/p>/)
+        api_message = matched[1] unless matched.nil?
+        @logger.debug "API message: #{api_message}"
+        case api_message
         when /A job already exists with the name/
-          raise Exceptions::JobAlreadyExistsWithName.new
+          raise Exceptions::JobAlreadyExists.new(@logger, api_message)
+        when /A view already exists with the name/
+          raise Exceptions::ViewAlreadyExists.new(@logger, api_message)
+        when /Slave called .* already exists/
+          raise Exceptions::NodeAlreadyExists.new(@logger, api_message)
         when /Nothing is submitted/
-          raise Exceptions::NothingSubmitted.new
+          raise Exceptions::NothingSubmitted.new(@logger, api_message)
         else
-          raise Exceptions::ApiException.new("Error code 400")
+          raise Exceptions::ApiException.new(@logger, api_message)
         end
       when 401
-        raise Exceptions::UnautherizedException.new
+        raise Exceptions::Unauthorized.new @logger
+      when 403
+        raise Exceptions::Forbidden.new @logger
       when 404
-        raise Exceptions::NotFoundException.new
+        raise Exceptions::NotFound.new @logger
       when 500
-        raise Exceptions::InternelServerErrorException.new
+        raise Exceptions::InternalServerError.new @logger
+      when 503
+        raise Exceptions::ServiceUnavailable.new @logger
       else
-        raise Exceptions::ApiException.new("Error code #{response.code}")
+        raise Exceptions::ApiException.new(
+          @logger,
+          "Error code #{response.code}"
+        )
       end
     end