jenkins_api_client 0.14.1 → 1.0.0

data/lib/jenkins_api_client/client.rb

@@ -35,7 +35,7 @@ require 'logger'
 #
 module JenkinsApi
   # This is the client class that acts as the bridge between the subclasses and
-  # Jnekins. This class contains methods that performs GET and POST requests
+  # Jenkins. This class contains methods that performs GET and POST requests
   # for various operations.
   #
   class Client
@@ -44,6 +44,8 @@ module JenkinsApi
     DEFAULT_SERVER_PORT = 8080
     # Default timeout in seconds to be used while performing operations
     DEFAULT_TIMEOUT = 120
+    DEFAULT_HTTP_OPEN_TIMEOUT = 10
+    DEFAULT_HTTP_READ_TIMEOUT = 120
     # Parameters that are permitted as options while initializing the client
     VALID_PARAMS = [
       "server_url",
@@ -58,53 +60,39 @@ module JenkinsApi
       "log_location",
       "log_level",
       "timeout",
+      "http_open_timeout",
+      "http_read_timeout",
       "ssl",
       "follow_redirects",
-      "identity_file"
+      "identity_file",
+      "cookies"
     ].freeze
 
     # Initialize a Client object with Jenkins CI server credentials
     #
     # @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
+    # @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). This can include username/password. :username/:password options will override any user/pass value in the URL
+    # @option args [String] :username the username used for connecting to the server (optional)
+    # @option args [String] :password the password or API Key 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/<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 (false)
-    #   indicates if Jenkins is accessible over HTTPS
-    # @option args [Boolean] :follow_redirects
-    #   This argument causes the client to follow a redirect (jenkins can
+    # @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
+    #   <Server IP>:<Server Port>/user/<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 (false) indicates if Jenkins is accessible over HTTPS
+    # @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 (120)
-    #   This argument sets the timeout for operations that take longer (in
-    #   seconds)
-    # @option args [String] :log_location (STDOUT)
-    #   The location for the log file
-    # @option args [Fixnum] :log_level (Logger::INFO)
-    #   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)
+    # @option args [Fixnum] :timeout (120) This argument sets the timeout for operations that take longer (in seconds)
+    # @option args [String] :log_location (STDOUT) the location for the log file
+    # @option args [Fixnum] :log_level (Logger::INFO) 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)
+    # @option args [String] :cookies Cookies to be sent with all requests in the format: name=value; name2=value2
     #
     # @return [JenkinsApi::Client] a client object to Jenkins API
     #
@@ -117,12 +105,26 @@ module JenkinsApi
         end
       end if args.is_a? Hash
 
-      # Server IP or Server URL must be specifiec
+      # Server IP or Server URL must be specific
       unless @server_ip || @server_url
         raise ArgumentError, "Server IP or Server URL is required to connect" +
           " to Jenkins"
       end
 
+      # 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
+
+        # read username and password from the URL
+        # only set if @username and @password are not already set via explicit options
+        @username ||= server_uri.user
+        @password ||= server_uri.password
+      end
+
       # Username/password are optional as some jenkins servers do not require
       # authentication
       if @username && !(@password || @password_base64)
@@ -133,19 +135,12 @@ module JenkinsApi
           " both left nil"
       end
 
-      # 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
+      @http_open_timeout = DEFAULT_HTTP_OPEN_TIMEOUT unless @http_open_timeout
+      @http_read_timeout = DEFAULT_HTTP_READ_TIMEOUT unless @http_read_timeout
       @ssl ||= false
 
       # Setting log options
@@ -212,6 +207,15 @@ module JenkinsApi
       JenkinsApi::Client::BuildQueue.new(self)
     end
 
+    # Creates an instance to the PluginManager by passing a reference to self
+    #
+    # @return [JenkinsApi::Client::PluginManager] an object to PluginManager
+    #  subclass
+    #
+    def plugin
+      JenkinsApi::Client::PluginManager.new(self)
+    end
+
     # Creates an instance of the User class by passing a reference to self
     #
     # @return [JenkinsApi::Client::User] An object of User subclass
@@ -240,7 +244,9 @@ module JenkinsApi
         " @crumbs_enabled=#{@crumbs_enabled.inspect}," +
         " @follow_redirects=#{@follow_redirects.inspect}," +
         " @jenkins_path=#{@jenkins_path.inspect}," +
-        " @timeout=#{@timeout.inspect}>"
+        " @timeout=#{@timeout.inspect}>," +
+        " @http_open_timeout=#{@http_open_timeout.inspect}>," +
+        " @http_read_timeout=#{@http_read_timeout.inspect}>"
     end
 
     # Connects to the Jenkins server, sends the specified request and returns
@@ -253,6 +259,7 @@ module JenkinsApi
     #
     def make_http_request(request, follow_redirect = @follow_redirects)
       request.basic_auth @username, @password if @username
+      request['Cookie'] = @cookies if @cookies
 
       if @proxy_ip
         http = Net::HTTP::Proxy(@proxy_ip, @proxy_port).new(@server_ip, @server_port)
@@ -265,6 +272,9 @@ module JenkinsApi
         http.verify_mode = OpenSSL::SSL::VERIFY_NONE
       end
 
+      http.open_timeout = @http_open_timeout
+      http.read_timeout = @http_read_timeout
+
       response = http.request(request)
       case response
         when Net::HTTPRedirection then
@@ -278,6 +288,11 @@ module JenkinsApi
             )
           end
       end
+
+      # Pick out some useful header info before we return
+      @jenkins_version = response['X-Jenkins']
+      @hudson_version = response['X-Hudson']
+
       return response
     end
     protected :make_http_request
@@ -288,8 +303,8 @@ module JenkinsApi
     # @return [Net::HTTP::Response] Response from Jenkins for "/"
     #
     def get_root
-      @logger.info "GET /"
-      request = Net::HTTP::Get.new("/")
+      @logger.info "GET #{@jenkins_path}/"
+      request = Net::HTTP::Get.new("#{@jenkins_path}/")
       make_http_request(request)
     end
 
@@ -301,7 +316,7 @@ module JenkinsApi
     # @param [Boolean] raw_response Return complete Response object instead of
     #   JSON body of response
     #
-    # @return [String, JSON] JSON response from Jenkins
+    # @return [String, Hash] JSON response from Jenkins
     #
     def api_get_request(url_prefix, tree = nil, url_suffix ="/api/json",
                         raw_response = false)
@@ -312,7 +327,6 @@ module JenkinsApi
       else
         to_get = "#{url_prefix}#{url_suffix}"
       end
-      to_get = URI.escape(to_get)
       request = Net::HTTP::Get.new(to_get)
       @logger.info "GET #{to_get}"
       response = make_http_request(request)
@@ -337,10 +351,8 @@ module JenkinsApi
 
         # 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}")
+        request = Net::HTTP::Post.new("#{@jenkins_path}#{url_prefix}")
         @logger.info "POST #{url_prefix}"
-        request.content_type = 'application/json'
         if @crumbs_enabled
           request[@crumb["crumbRequestField"]] = @crumb["crumb"]
         end
@@ -377,8 +389,7 @@ module JenkinsApi
     # @return [String] XML configuration obtained from Jenkins
     #
     def get_config(url_prefix)
-      url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
-      request = Net::HTTP::Get.new("#{url_prefix}/config.xml")
+      request = Net::HTTP::Get.new("#{@jenkins_path}#{url_prefix}/config.xml")
       @logger.info "GET #{url_prefix}/config.xml"
       response = make_http_request(request)
       handle_exception(response, "body")
@@ -392,15 +403,22 @@ module JenkinsApi
     # @return [String] Response code returned from Jenkins
     #
     def post_config(url_prefix, xml)
+      post_data(url_prefix, xml, 'application/xml')
+    end
+
+    def post_json(url_prefix, json)
+      post_data(url_prefix, json, 'application/json')
+    end
+
+    def post_data(url_prefix, data, content_type)
       retries = @crumb_max_retries
       begin
         refresh_crumbs
 
-        url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
-        request = Net::HTTP::Post.new("#{url_prefix}")
+        request = Net::HTTP::Post.new("#{@jenkins_path}#{url_prefix}")
         @logger.info "POST #{url_prefix}"
-        request.body = xml
-        request.content_type = 'application/xml'
+        request.body = data
+        request.content_type = content_type
         if @crumbs_enabled
           request[@crumb["crumbRequestField"]] = @crumb["crumb"]
         end
@@ -425,6 +443,24 @@ module JenkinsApi
       end
     end
 
+    def init_update_center
+      @logger.info "Initializing Jenkins Update Center..."
+      @logger.debug "Obtaining the JSON data for Update Center..."
+      # TODO: Clean me up
+      update_center_data = open("http://updates.jenkins-ci.org/update-center.json").read
+      # The Jenkins mirror returns the data in the following format
+      #   updateCenter.post(
+      #     {.. JSON data...}
+      #   );
+      # which is used by the Javascript used by the Jenkins UI to send to Jenkins.
+      #
+      update_center_data.gsub!("updateCenter.post(\n", "")
+      update_center_data.gsub!("\n);", "")
+
+      @logger.debug "Posting the obtained JSON to Jenkins Update Center..."
+      post_json("/updateCenter/byId/default/postBack", update_center_data)
+    end
+
     # Checks if Jenkins uses crumbs (i.e) the XSS disable option is checked in
     # Jenkins' security settings
     #
@@ -445,21 +481,64 @@ module JenkinsApi
     end
 
     # Obtains the jenkins version from the API
+    # Only queries Jenkins if the version is not already stored.
+    # Note that the version is auto-updated after every request made to Jenkins
+    # since it is returned as a header in every response
     #
-    # @return Jenkins version
+    # @return [String] Jenkins version
     #
     def get_jenkins_version
-      response = get_root
-      response["X-Jenkins"]
+      get_root if @jenkins_version.nil?
+      @jenkins_version
     end
 
     # Obtain the Hudson version of the CI server
+    # Only queries Hudson/Jenkins if the version is not already stored.
+    # Note that the version is auto-updated after every request made to Jenkins
+    # since it is returned as a header in every response
     #
     # @return [String] Version of Hudson on Jenkins server
     #
     def get_hudson_version
-      response = get_root
-      response["X-Hudson"]
+      get_root if @hudson_version.nil?
+      @hudson_version
+    end
+
+    # Converts a version string to a list of integers
+    # This makes it easier to compare versions since in 'version-speak',
+    # v 1.2 is a lot older than v 1.102 - and simple < > on version
+    # strings doesn't work so well
+    def deconstruct_version_string(version)
+      match = version.match(/^(\d+)\.(\d+)(?:\.(\d+))?$/)
+
+      # Match should have 4 parts [0] = input string, [1] = major
+      # [2] = minor, [3] = patch (possibly blank)
+      if match && match.size == 4
+        return [match[1].to_i, match[2].to_i, match[3].to_i || 0]
+      else
+        return nil
+      end
+    end
+
+    # Compare two version strings (A and B)
+    # if A == B, returns 0
+    # if A > B, returns 1
+    # if A < B, returns -1
+    def compare_versions(version_a, version_b)
+      if version_a == version_b
+        return 0
+      else
+        version_a_d = deconstruct_version_string(version_a)
+        version_b_d = deconstruct_version_string(version_b)
+
+        if version_a_d[0] > version_b_d[0] ||
+          (version_a_d[0] == version_b_d[0] && version_a_d[1] > version_b_d[1]) ||
+          (version_a_d[0] == version_b_d[0] && version_a_d[1] == version_b_d[1] && version_a_d[2] > version_b_d[2])
+          return 1
+        else
+          return -1
+        end
+      end
     end
 
     # Obtain the date of the Jenkins server
@@ -471,6 +550,17 @@ module JenkinsApi
       response["Date"]
     end
 
+    # Executes the provided groovy script on the Jenkins CI server
+    #
+    # @param [String] script_text The text of the groovy script to execute
+    #
+    # @return [String] The output of the executed groovy script
+    #
+    def exec_script(script_text)
+      response = api_post_request('/scriptText', {'script' => script_text}, true)
+      response.body
+    end
+
     # Execute the Jenkins CLI
     #
     # @param command [String] command name
@@ -581,7 +671,7 @@ module JenkinsApi
     # @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
+    # @return [String, Hash] Response returned whether loaded JSON or raw
     #   string
     #
     # @raise [Exceptions::Unauthorized] When invalid credentials are
@@ -633,7 +723,10 @@ module JenkinsApi
       when 404
         raise Exceptions::NotFound.new @logger
       when 500
-        raise Exceptions::InternalServerError.new @logger
+        matched = response.body.match(/Exception: (.*)<br>/)
+        api_message = matched[1] unless matched.nil?
+        @logger.debug "API message: #{api_message}"
+        raise Exceptions::InternalServerError.new(@logger, api_message)
       when 503
         raise Exceptions::ServiceUnavailable.new @logger
       else

data/lib/jenkins_api_client/exceptions.rb

@@ -41,8 +41,8 @@ module JenkinsApi
     #
     class NothingSubmitted < ApiException
       def initialize(logger, message = "", log_level = Logger::ERROR)
-        msg = "Nothing is submitted. #{message}"
-        super(logger, msg)
+        message = "Nothing is submitted." if message.empty?
+        super(logger, message)
       end
     end
 
@@ -80,8 +80,8 @@ module JenkinsApi
     #
     class Unauthorized < ApiException
       def initialize(logger, message = "", log_level = Logger::ERROR)
-        msg = "Invalid credentials are provided. #{message}"
-        super(logger, msg, Logger::FATAL)
+        message = "Invalid credentials are provided." if message.empty?
+        super(logger, message, Logger::FATAL)
       end
     end
     # Support for backward compatibility
@@ -158,8 +158,8 @@ module JenkinsApi
     #
     class CrumbNotFound < NotFound
       def initialize(logger, message = "", log_level = Logger::ERROR)
-        msg = "No crumb available on the server. #{message}"
-        super(logger, msg)
+        message = "No crumb available on the server." if message.empty?
+        super(logger, message)
       end
     end
     # Support for backward compatibility
@@ -196,14 +196,14 @@ module JenkinsApi
     end
 
     # This exception class handles cases where the Jenkins API returns with a
-    # 500 Internel Server Error.
+    # 500 Internal Server Error.
     #
     class InternalServerError < ApiException
       def initialize(logger, message = "", log_level = Logger::ERROR)
-        msg = "Internel Server Error. Perhaps the in-memory configuration of" +
-              " Jenkins is different from the disk configuration." +
-              " Please try to reload the configuration #{message}"
-        super(logger, msg)
+        message = "Internal Server Error. Perhaps the in-memory configuration" +
+          " Jenkins is different from the disk configuration. Please try to" +
+          " reload the configuration" if message.nil? || message.empty?
+        super(logger, message)
       end
     end
     # Support for backward compatibility
@@ -214,10 +214,10 @@ module JenkinsApi
     #
     class ServiceUnavailable < ApiException
       def initialize(logger, message = "", log_level = Logger::ERROR)
-        msg = "Jenkins is being reloaded or restarted. Please wait till" +
-              " Jenkins is completely back online. This can be" +
-              " programatically achieved by System#wait_for_ready #{message}"
-        super(logger, msg)
+        message = "Jenkins is being reloaded or restarted. Please wait till" +
+          " Jenkins is completely back online. This can be" +
+          " programatically achieved by System#wait_for_ready" if message.empty?
+        super(logger, message)
       end
     end
     # Support for backward compatibility
@@ -227,11 +227,20 @@ module JenkinsApi
     #
     class CLIError < ApiException
       def initialize(logger, message = "", log_level = Logger::ERROR)
-        msg = "Execute CLI Error. #{message}"
-        super(logger, msg)
+        message = "Unable to execute the command." if message.empty?
+        super(logger, message)
       end
     end
     # Support for backward compatibility
     CLIException = CLIError
+
+    # Exception when a particular plugin is not found
+    #
+    class PluginNotFound < NotFound
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        message = "The specified plugin is not found" if message.empty?
+        super(logger, message)
+      end
+    end
   end
 end