jenkins_api_client 1.0.0.alpha.2 → 1.0.0.beta.1

data/lib/jenkins_api_client/job.rb

@@ -20,12 +20,18 @@
 # THE SOFTWARE.
 #
 
+require 'jenkins_api_client/urihelper'
+
 module JenkinsApi
   class Client
     # This class communicates with the Jenkins "/job" API to obtain details
     # about jobs, creating, deleting, building, and various other operations.
     #
     class Job
+      include JenkinsApi::UriHelper
+
+      # Version that jenkins started to include queued build info in build response
+      JENKINS_QUEUE_ID_SUPPORT_VERSION = '1.519'
 
       # Initialize the Job object and store the reference to Client object
       #
@@ -74,7 +80,7 @@ module JenkinsApi
       #
       def create(job_name, xml)
         @logger.info "Creating job '#{job_name}'"
-        @client.post_config("/createItem?name=#{job_name}", xml)
+        @client.post_config("/createItem?name=#{form_encode job_name}", xml)
       end
 
       # Update a job with the name specified and the xml given
@@ -400,7 +406,7 @@ module JenkinsApi
       #
       def rename(old_job, new_job)
         @logger.info "Renaming job '#{old_job}' to '#{new_job}'"
-        @client.api_post_request("/job/#{old_job}/doRename?newName=#{new_job}")
+        @client.api_post_request("/job/#{path_encode old_job}/doRename?newName=#{form_encode new_job}")
       end
 
       # Delete a job given the name
@@ -411,7 +417,7 @@ module JenkinsApi
       #
       def delete(job_name)
         @logger.info "Deleting job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/doDelete")
+        @client.api_post_request("/job/#{path_encode job_name}/doDelete")
       end
 
       # Deletes all jobs from Jenkins
@@ -432,7 +438,7 @@ module JenkinsApi
       #
       def wipe_out_workspace(job_name)
         @logger.info "Wiping out the workspace of job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/doWipeOutWorkspace")
+        @client.api_post_request("/job/#{path_encode job_name}/doWipeOutWorkspace")
       end
 
       # Stops a running build of a job
@@ -449,10 +455,10 @@ module JenkinsApi
         @logger.info "Stopping job '#{job_name}' Build ##{build_number}"
         # Check and see if the build is running
         is_building = @client.api_get_request(
-          "/job/#{job_name}/#{build_number}"
+          "/job/#{path_encode job_name}/#{build_number}"
         )["building"]
         if is_building
-          @client.api_post_request("/job/#{job_name}/#{build_number}/stop")
+          @client.api_post_request("/job/#{path_encode job_name}/#{build_number}/stop")
         end
       end
       alias_method :stop, :stop_build
@@ -515,7 +521,7 @@ module JenkinsApi
         else
           raise "Mode should either be 'text' or 'html'. You gave: #{mode}"
         end
-        get_msg = "/job/#{job_name}/#{build_num}/logText/progressive#{mode}?"
+        get_msg = "/job/#{path_encode job_name}/#{build_num}/logText/progressive#{mode}?"
         get_msg << "start=#{start}"
         raw_response = true
         api_response = @client.api_get_request(get_msg, nil, nil, raw_response)
@@ -610,7 +616,7 @@ module JenkinsApi
       #
       def list_details(job_name)
         @logger.info "Obtaining the details of '#{job_name}'"
-        @client.api_get_request("/job/#{job_name}")
+        @client.api_get_request("/job/#{path_encode job_name}")
       end
 
       # List upstream projects of a specific job
@@ -620,7 +626,7 @@ module JenkinsApi
       #
       def get_upstream_projects(job_name)
         @logger.info "Obtaining the upstream projects of '#{job_name}'"
-        response_json = @client.api_get_request("/job/#{job_name}")
+        response_json = @client.api_get_request("/job/#{path_encode job_name}")
         response_json["upstreamProjects"]
       end
 
@@ -631,7 +637,7 @@ module JenkinsApi
       #
       def get_downstream_projects(job_name)
         @logger.info "Obtaining the down stream projects of '#{job_name}'"
-        response_json = @client.api_get_request("/job/#{job_name}")
+        response_json = @client.api_get_request("/job/#{path_encode job_name}")
         response_json["downstreamProjects"]
       end
 
@@ -641,7 +647,7 @@ module JenkinsApi
       #
       def get_builds(job_name)
         @logger.info "Obtaining the build details of '#{job_name}'"
-        response_json = @client.api_get_request("/job/#{job_name}")
+        response_json = @client.api_get_request("/job/#{path_encode job_name}")
         response_json["builds"]
       end
 
@@ -683,7 +689,7 @@ module JenkinsApi
       #
       def get_current_build_status(job_name)
         @logger.info "Obtaining the current build status of '#{job_name}'"
-        response_json = @client.api_get_request("/job/#{job_name}")
+        response_json = @client.api_get_request("/job/#{path_encode job_name}")
         color_to_status(response_json["color"])
       end
       alias_method :status, :get_current_build_status
@@ -697,61 +703,248 @@ module JenkinsApi
       #
       def get_current_build_number(job_name)
         @logger.info "Obtaining the current build number of '#{job_name}'"
-        @client.api_get_request("/job/#{job_name}")['nextBuildNumber'].to_i - 1
+        @client.api_get_request("/job/#{path_encode job_name}")['nextBuildNumber'].to_i - 1
       end
       alias_method :build_number, :get_current_build_number
 
-      # Build a job given the name of the job
-      # You can optionally pass in a list of params for Jenkins to use for
-      # parameterized builds
+      # Build a Jenkins job, optionally waiting for build to start and
+      # returning the build number.
+      # Adds support for new/old Jenkins servers where build_queue id may
+      # not be available. Also adds support for periodic callbacks, and
+      # optional cancellation of queued_job if not started within allowable
+      # time window (if build_queue option available)
+      #
+      #   Notes:
+      #     'opts' may be a 'true' or 'false' value to maintain
+      #       compatibility with old method signature, where true indicates
+      #     'return_build_number'. In this case, true is translated to:
+      #       { 'build_start_timeout' => @client_timeout }
+      #       which simulates earlier behavior.
+      #
+      #   progress_proc
+      #     Optional proc that is called periodically while waiting for
+      #     build to start.
+      #     Initial call (with poll_count == 0) indicates build has been
+      #     requested, and that polling is starting.
+      #     Final call will indicate one of build_started or cancelled.
+      #     params:
+      #       max_wait [Integer] Same as opts['build_start_timeout']
+      #       current_wait [Integer]
+      #       poll_count [Integer] How many times has queue been polled
+      #
+      #   completion_proc
+      #     Optional proc that is called <just before> the 'build' method
+      #     exits.
+      #     params:
+      #       build_number [Integer]  Present if build started or nil
+      #       build_cancelled [Boolean]  True if build timed out and was
+      #         successfully removed from build-queue
       #
       # @param [String] job_name the name of the job
-      # @param [Hash] params the parameters for parameterized builds
-      # @param [Boolean] return_build_number whether to wait and obtain the build
-      #   number
-      #
-      # @return [String, Integer] the response code from the build POST request
-      #   if return_build_number is not requested and the build number if the
-      #   return_build_number is requested. nil will be returned if the build
-      #   number is requested and not available. This can happen if there is
-      #   already a job in the queue and concurrent build is disabled.
-      #
-      def build(job_name, params={}, return_build_number = false)
+      # @param [Hash]   params   the parameters for parameterized build
+      # @param [Hash]   opts     options for this method
+      #  * +build_start_timeout+ [Integer] How long to wait for queued
+      #    build to start before giving up. Default: 0/nil
+      #  * +cancel_on_build_start_timeout+ [Boolean] Should an attempt be
+      #    made to cancel the queued build if it hasn't started within
+      #    'build_start_timeout' seconds? This only works on newer versions
+      #    of Jenkins where JobQueue is exposed in build post response.
+      #    Default: false
+      #  * +poll_interval+ [Integer] How often should we check with CI
+      #    Server while waiting for start. Default: 2 (seconds)
+      #  * +progress_proc+ [Proc] A proc that will receive progress notitications. Default: nil
+      #  * +completion_proc+ [Proc] A proc that is called <just before>
+      #    this method (build) exits.  Default: nil
+      #
+      # @return [Integer] build number, or nil if not started (IF TIMEOUT SPECIFIED)
+      # @return [Integer] HTTP response code (per prev. behavior) (NO TIMEOUT SPECIFIED)
+      #
+      def build(job_name, params={}, opts = {})
+        if opts.nil? || opts.class.is_a?(FalseClass)
+          opts = {}
+        elsif opts.class.is_a?(TrueClass)
+          opts = { 'build_start_timeout' => @client_timeout }
+        end
+
+        opts['job_name'] = job_name
+
         msg = "Building job '#{job_name}'"
         msg << " with parameters: #{params.inspect}" unless params.empty?
         @logger.info msg
-        build_endpoint = params.empty? ? "build" : "buildWithParameters"
-        raw_response = return_build_number
-        response =@client.api_post_request(
-          "/job/#{job_name}/#{build_endpoint}",
-          params,
-          raw_response
-        )
-        # If return_build_number is enabled, obtain the queue ID from the location
+
+        # Best-guess build-id
+        # This is only used if we go the old-way below... but we can use this number to detect if multiple
+        # builds were queued
+        current_build_id = get_current_build_number(job_name)
+        expected_build_id = current_build_id > 0 ? current_build_id + 1 : 1
+
+        if (params.nil? or params.empty?)
+          response = @client.api_post_request("/job/#{path_encode job_name}/build",
+            {},
+            true)
+        else
+          response = @client.api_post_request("/job/#{path_encode job_name}/buildWithParameters",
+            params,
+            true)
+        end
+
+        if (opts['build_start_timeout'] || 0) > 0
+          if @client.compare_versions(@client.get_jenkins_version, JENKINS_QUEUE_ID_SUPPORT_VERSION) >= 0
+            return get_build_id_from_queue(response, expected_build_id, opts)
+          else
+            return get_build_id_the_old_way(expected_build_id, opts)
+          end
+        else
+          return response.code
+        end
+      end
+
+      def get_build_id_from_queue(response, expected_build_id, opts)
+        # If we get this far the API hasn't detected an error response (it would raise Exception)
+        # So no need to check response code
+        # Obtain the queue ID from the location
         # header and wait till the build is moved to one of the executors and a
         # build number is assigned
-        if return_build_number
-          if response["location"]
-            task_id_match = response["location"].match(/\/item\/(\d*)\//)
-            task_id = task_id_match.nil? ? nil : task_id_match[1]
-            unless task_id.nil?
-              @logger.debug "Queue task ID for job '#{job_name}': #{task_id}"
-              Timeout::timeout(@client.timeout) do
-                while @client.queue.get_item_by_id(task_id)["executable"].nil?
-                  sleep 5
+        build_start_timeout = opts['build_start_timeout']
+        poll_interval = opts['poll_interval'] || 2
+        poll_interval = 1 if poll_interval < 1
+        progress_proc = opts['progress_proc']
+        completion_proc = opts['completion_proc']
+        job_name = opts['job_name']
+
+        if response["location"]
+          task_id_match = response["location"].match(/\/item\/(\d*)\//)
+          task_id = task_id_match.nil? ? nil : task_id_match[1]
+          unless task_id.nil?
+            @logger.info "Job queued for #{job_name}, will wait up to #{build_start_timeout} seconds for build to start..."
+
+            # Let progress proc know we've queued the build
+            progress_proc.call(build_start_timeout, 0, 0) if progress_proc
+
+            # Wait for the build to start
+            begin
+              start = Time.now.to_i
+              Timeout::timeout(build_start_timeout) do
+                started = false
+                attempts = 0
+
+                while !started
+                  # Don't really care about the response... if we get thru here, then it must have worked.
+                  # Jenkins will return 404's until the job starts
+                  queue_item = @client.queue.get_item_by_id(task_id)
+
+                  if queue_item['executable'].nil?
+                    # Job not started yet
+                    attempts += 1
+
+                    progress_proc.call(build_start_timeout, (Time.now.to_i - start), attempts) if progress_proc
+                    # Every 5 attempts (~10 seconds)
+                    @logger.info "Still waiting..." if attempts % 5 == 0
+
+                    sleep poll_interval
+                  else
+                    build_number = queue_item['executable']['number']
+                    completion_proc.call(build_number, false) if completion_proc
+
+                    return build_number
+                  end
                 end
               end
-              @client.queue.get_item_by_id(task_id)["executable"]["number"]
-            else
-              nil
+            rescue Timeout::Error
+              # Well, we waited - and the job never started building
+              # Attempt to kill off queued job (if flag set)
+              if opts['cancel_on_build_start_timeout']
+                @logger.info "Job for '#{job_name}' did not start in a timely manner, attempting to cancel pending build..."
+
+                begin
+                  @client.api_post_request("/queue/cancelItem?id=#{task_id}")
+                  @logger.info "Job cancelled"
+                  completion_proc.call(nil, true) if completion_proc
+                rescue JenkinsApi::Exceptions::ApiException => e
+                  completion_proc.call(nil, false) if completion_proc
+                  @logger.warn "Error while attempting to cancel pending job for '#{job_name}'. #{e.class} #{e}"
+                  raise
+                end
+              else
+                @logger.info "Jenkins build for '#{job_name}' failed to start in a timely manner"
+                completion_proc.call(nil, false) if completion_proc
+              end
+
+              # Old version used to throw timeout error, so we should let that go thru now
+              raise
+            rescue JenkinsApi::Exceptions::ApiException => e
+              # Jenkins Api threw an error at us
+              completion_proc.call(nil, false) if completion_proc
+              @logger.warn "Problem while waiting for '#{job_name}' build to start.  #{e.class} #{e}"
+              raise
             end
           else
-            nil
+            @logger.warn "Jenkins did not return a queue_id for '#{job_name}' build (location: #{response['location']})"
+            return get_build_id_the_old_way(expected_build_id, opts)
           end
         else
-          response
+          @logger.warn "Jenkins did not return a location header for '#{job_name}' build"
+          return get_build_id_the_old_way(expected_build_id, opts)
         end
       end
+      private :get_build_id_from_queue
+
+      def get_build_id_the_old_way(expected_build_id, opts)
+        # Try to wait until the build starts so we can mimic queue
+        # Wait for the build to start
+        build_start_timeout = opts['build_start_timeout']
+        poll_interval = opts['poll_interval'] || 2
+        poll_interval = 1 if poll_interval < 1
+        progress_proc = opts['progress_proc']
+        completion_proc = opts['completion_proc']
+        job_name = opts['job_name']
+
+        @logger.info "Build requested for '#{job_name}', will wait up to #{build_start_timeout} seconds for build to start..."
+
+        # Let progress proc know we've queued the build
+        progress_proc.call(build_start_timeout, 0, 0) if progress_proc
+
+        begin
+          start = Time.now.to_i
+          Timeout::timeout(build_start_timeout) do
+            attempts = 0
+
+            while true
+              attempts += 1
+
+              # Don't really care about the response... if we get thru here, then it must have worked.
+              # Jenkins will return 404's until the job starts
+              begin
+                get_build_details(job_name, expected_build_id)
+                completion_proc.call(expected_build_number, false) if completion_proc
+
+                return expected_build_id
+              rescue JenkinsApi::Exceptions::NotFound => e
+                progress_proc.call(build_start_timeout, (Time.now.to_i - start), attempts) if progress_proc
+
+                # Every 5 attempts (~10 seconds)
+                @logger.info "Still waiting..." if attempts % 5 == 0
+
+                sleep poll_interval
+              end
+            end
+          end
+        rescue Timeout::Error
+          # Well, we waited - and the job never started building
+          # Now we need to raise an exception so that the build can be officially failed
+          completion_proc.call(nil, false) if completion_proc
+          @logger.info "Jenkins '#{job_name}' build failed to start in a timely manner"
+
+          # Old version used to propagate timeout error
+          raise
+        rescue JenkinsApi::Exceptions::ApiException => e
+          completion_proc.call(nil, false) if completion_proc
+          # Jenkins Api threw an error at us
+          @logger.warn "Problem while waiting for '#{job_name}' build ##{expected_build_number} to start.  #{e.class} #{e}"
+          raise
+        end
+      end
+      private :get_build_id_the_old_way
 
       # Programatically schedule SCM polling for the specified job
       #
@@ -779,7 +972,7 @@ module JenkinsApi
       #
       def disable(job_name)
         @logger.info "Disabling job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/disable")
+        @client.api_post_request("/job/#{path_encode job_name}/disable")
       end
 
       # Obtain the configuration stored in config.xml of a specific job
@@ -790,7 +983,7 @@ module JenkinsApi
       #
       def get_config(job_name)
         @logger.info "Obtaining the config.xml of '#{job_name}'"
-        @client.get_config("/job/#{job_name}")
+        @client.get_config("/job/#{path_encode job_name}")
       end
 
       # Post the configuration of a job given the job name and the config.xml
@@ -802,7 +995,7 @@ module JenkinsApi
       #
       def post_config(job_name, xml)
         @logger.info "Posting the config.xml of '#{job_name}'"
-        @client.post_config("/job/#{job_name}/config.xml", xml)
+        @client.post_config("/job/#{path_encode job_name}/config.xml", xml)
       end
 
       # Obtain the test results for a specific build of a job
@@ -814,7 +1007,7 @@ module JenkinsApi
         build_num = get_current_build_number(job_name) if build_num == 0
         @logger.info "Obtaining the test results of '#{job_name}'" +
           " Build ##{build_num}"
-        @client.api_get_request("/job/#{job_name}/#{build_num}/testReport")
+        @client.api_get_request("/job/#{path_encode job_name}/#{build_num}/testReport")
       rescue Exceptions::NotFound
         # Not found is acceptable, as not all builds will have test results
         # and this is what jenkins throws at us in that case
@@ -831,7 +1024,7 @@ module JenkinsApi
         @logger.info "Obtaining the build details of '#{job_name}'" +
           " Build ##{build_num}"
 
-        @client.api_get_request("/job/#{job_name}/#{build_num}/")
+        @client.api_get_request("/job/#{path_encode job_name}/#{build_num}/")
       end
 
       # Change the description of a specific job
@@ -1207,6 +1400,31 @@ module JenkinsApi
         filtered_job_names[0..parallel-1]
       end
 
+      # Get a list of promoted builds for given job
+      #
+      # @param  [String] job_name
+      # @return [Hash]   Hash map of promitions and the promoted builds. Promotions that didn't took place yet
+      #                  return nil
+      def get_promotions(job_name)
+        result = {}
+
+        @logger.info "Obtaining the promotions of '#{job_name}'"
+        response_json = @client.api_get_request("/job/#{job_name}/promotion")
+
+        response_json["processes"].each do |promotion|
+          @logger.info "Getting promotion details of '#{promotion['name']}'"
+
+          if promotion['color'] == 'notbuilt'
+            result[promotion['name']] = nil
+          else
+            promo_json = @client.api_get_request("/job/#{job_name}/promotion/latest/#{promotion['name']}")
+            result[promotion['name']] = promo_json['target']['number']
+          end
+        end
+
+        result
+      end
+
       private
 
       # Obtains the threshold params used by jenkins in the XML file