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

data/.gitignore

@@ -33,3 +33,6 @@ Gemfile.lock
 *.tmproj
 tmtags
 *.swp
+
+# Skip the log file
+jenkins_api_client.log

data/CHANGELOG.md

@@ -6,14 +6,14 @@ upcoming
 
 v0.14.1  [18-AUG-2013]
 ----------------------
-* Fixed a bug in Job#create_or_update method. Credit: @bobbrez
+* Fixed a bug in Job#create_or_update method. Credit: [@bobbrez][]
 
 v0.14.0  [07-AUG-2013]
 ----------------------
 * Fixed a bug where a space was missing in the exec_cli method argument list.
-  Credit: @missedone
+  Credit: [@missedone][]
 * Refactored create/update jobs by introducing create_or_update methods.
-  Credit: @riywo
+  Credit: [@riywo][]
 * Enhancement to crumb processing - auto detect the change of crumb setting and
   do proper exception handling. Credit: dougforpress
 * Added a `User` class which will handle jenkins users related functions.
@@ -37,38 +37,37 @@ v0.13.0  [09-JUL-2013]
   queue for longer than the 'timeout' parameter. This timeout parameter can be
   set during the client initialization.
 * Improved documentation
-* Support for enabling/disabling jobs. Credit: @dieterdemeyer
-* Added functionality for copying jobs. Credit: @dieterdemeyer
+* Support for enabling/disabling jobs. Credit: [@dieterdemeyer][]
+* Added functionality for copying jobs. Credit: [@dieterdemeyer][]
 * Added functionality for wiping out the workspace of a job.
-  Credit: @dieterdemeyer
-* Added functionality for listing jenkins users. Credit: @dieterdemeyer
+  Credit: [@dieterdemeyer][]
+* Added functionality for listing jenkins users. Credit: [@dieterdemeyer][]
 * Fixed a bug where the exceptions where not thrown when using the
   `get_console_output` method.
 * Fixed a bug where the jenkins_path attribute was ignored when the server_url
-  input argument is given. Credit: @woodbusy
+  input argument is given. Credit: [@woodbusy][]
 * support public/private key pair authentication for Jenkins CLI.
-  Credit: @missedone
+  Credit: [@missedone][]
 
 
 v0.12.1  [25-JUN-2013]
 ----------------------
 * Fixed a bug where the SSL support was not working properly with Ruby
-  1.8.7/JRuby 1.6. Credit: @brettporter (For more info:
-  https://github.com/arangamani/jenkins_api_client/pull/85)
+  1.8.7/JRuby 1.6. (Pull [#85][]) Credit: [@brettporter][]
 
 v0.12.0  [18-JUN-2013]
 ----------------------
 * Authentication is now optional as not all Jenkins instances have
-  authentication enabled by default. Credit: @dougforpres
+  authentication enabled by default. Credit: [@dougforpres][]
 * Ability to retrieve build details so that more than just (`lamp color`) is
-  available. Credit: @dougforpres
+  available. Credit: [@dougforpres][]
 * Ability to retrieve build test-results for those builds that have them.
-  Credit: @dougforpres
+  Credit: [@dougforpres][]
 * Option to follow any 301/302 responses. This allows POST to build to follow
-  the redirect and end up with a 200 response. Credit: @dougforpres
+  the redirect and end up with a 200 response. Credit: [@dougforpres][]
 * Minor change to the POST requests handling where jenkins instances with a
   proxy returns 411 if no form data is specified. Fixed by sending an empty
-  hash. Credit: @dougforpres
+  hash. Credit: [@dougforpres][]
 * As of Jenkins release 1.519, the job build returns a 201 code instead of 302.
   This was resulting in an exception and the exception handling is modified to
   handle this condition.
@@ -78,17 +77,17 @@ v0.12.0  [18-JUN-2013]
 v0.11.0  [09-JUN-2013]
 ----------------------
 * A new input argument `server_url` is supported which accepts the jenkins URL
-  instead of IP address and Port. Credit: @dieterdemeyer
-* When renaming the job, preserve the job history. Credit: @rubytester
-* Various exception handling improvements. Credit: @drnic
+  instead of IP address and Port. Credit: [@dieterdemeyer][]
+* When renaming the job, preserve the job history. Credit: [@rubytester][]
+* Various exception handling improvements. Credit: [@drnic][]
 
 v0.10.0  [24-APR-2013]
 ----------------------
-* new function to execute jenkins CLI `cli_exec`. Credit: @missedone
-* Add ability to use http proxy. Credit: @woodbusy
-* prompt the user for credentials when using irb login script. @woodbusy
-* bugfix for job.console_output. Credit: @drnic
-* add ssl support. Credit: @madisp
+* new function to execute jenkins CLI `cli_exec`. Credit: [@missedone][]
+* Add ability to use http proxy. Credit: [@woodbusy][]
+* prompt the user for credentials when using irb login script. [@woodbusy][]
+* bugfix for job.console_output. Credit: [@drnic][]
+* add ssl support. Credit: [@madisp][]
 
 v0.9.1  [01-APR-2013]
 ---------------------
@@ -101,18 +100,18 @@ v0.9.0  [10-MAR-2013]
 * Removed warnings from client.rb
 * Refactored and improved exception handling
 * A bug is fixed in client which allows only the valid params as options.
-  Credit: @Niarfe
+  Credit: [@Niarfe][]
 * Added a timeout parameter for waiting for jenkins to become ready.
-  Credit: @Niarfe
-* Added function to reload jenkins. Credit: @missedone
+  Credit: [@Niarfe][]
+* Added function to reload jenkins. Credit: [@missedone][]
 * Fixed a bug where jenkins_path was missing in get_config and post_config.
-  Credit: @cylol
+  Credit: [@cylol][]
 * Added capability to obtain jenkins version and other useful information
 * Added new tests for various cases, and other code improvements
 
 v0.8.1  [15-FEB-2013]
 ---------------------
-* Fixed a bug in creating view. Issue #42
+* Fixed a bug in creating view. Issue [#42][]
 
 v0.8.0  [14-FEB-2013]
 ---------------------
@@ -120,16 +119,16 @@ v0.8.0  [14-FEB-2013]
 * Added rename feature for jobs
 * Added support for sending skype notification in job creation and on existing
   jobs
-* Added support for sending Jenkins root URL configuration. Credit: @kevinhcross
+* Added support for sending Jenkins root URL configuration. Credit: [@kevinhcross][]
 * Added `delete_all!` methods for Job, View, and Node.
 * `get_eta` in BuildQueue will return "N/A" if the ETA is not given by Jenkins
 * Creating view accepts params Hash and more configuration through the API
-* Spaces are allowed in Job, Node, and View names. Credit: @kevinhcross
-* Support has been added to build a job with parameters. Credit: @tjhanley
+* Spaces are allowed in Job, Node, and View names. Credit: [@kevinhcross][]
+* Support has been added to build a job with parameters. Credit: [@tjhanley][]
 
 v0.7.3  [05-FEB-2013]
 ---------------------
-* Fixed #27 with a bug in create_view including extra character in the end of
+* Fixed [#27][] with a bug in create_view including extra character in the end of
   the name
 
 v0.7.2  [02-FEB-2013]
@@ -138,7 +137,7 @@ v0.7.2  [02-FEB-2013]
 
 v0.7.1  [30-JAN-2013]
 ---------------------
-* Fixed a bug (Issue #23) to remove the usage of "\" in Job.
+* Fixed a bug (Issue [#23][]) to remove the usage of "\" in Job.
 
 v0.7.0  [27-JAN-2013]
 ---------------------
@@ -149,7 +148,7 @@ v0.7.0  [27-JAN-2013]
 * Added support for notification_email option when setting up a job
 * Added support for CVS provider in SCM
 * Added `create_dump_slave` and `delete` methods in Node API
-* Added BuildQueue class which is accessible by `@client.queue` method
+* Added BuildQueue class which is accessible by `[@client][].queue` method
 * Improvements in all over the code for performance and error handling
 
 v0.6.2  [13-JAN-2013]
@@ -220,3 +219,25 @@ v0.0.2  [16-OCT-2012]
 v0.0.1  [15-OCT-2012]
 ---------------------
 * Initial Release
+
+
+<!--- The following link definition list is generated by PimpMyChangelog --->
+[#23]: https://github.com/arangamani/jenkins_api_client/issues/23
+[#27]: https://github.com/arangamani/jenkins_api_client/issues/27
+[#42]: https://github.com/arangamani/jenkins_api_client/issues/42
+[#85]: https://github.com/arangamani/jenkins_api_client/issues/85
+[@Niarfe]: https://github.com/Niarfe
+[@bobbrez]: https://github.com/bobbrez
+[@brettporter]: https://github.com/brettporter
+[@client]: https://github.com/client
+[@cylol]: https://github.com/cylol
+[@dieterdemeyer]: https://github.com/dieterdemeyer
+[@dougforpres]: https://github.com/dougforpres
+[@drnic]: https://github.com/drnic
+[@kevinhcross]: https://github.com/kevinhcross
+[@madisp]: https://github.com/madisp
+[@missedone]: https://github.com/missedone
+[@riywo]: https://github.com/riywo
+[@rubytester]: https://github.com/rubytester
+[@tjhanley]: https://github.com/tjhanley
+[@woodbusy]: https://github.com/woodbusy

data/CONTRIBUTORS.md

@@ -1,15 +1,3 @@
 Thank you very much to all who contributed to this project.
 
-* [Niarfe](https://github.com/Niarfe)
-* [dieterdemeyer](https://github.com/dieterdemeyer)
-* [kevinhcross](https://github.com/kevinhcross)
-* [drnic](https://github.com/drnic)
-* [woodbusy](https://github.com/woodbusy)
-* [missedone](https://github.com/missedone)
-* [cylol](https://github.com/cylol)
-* [madisp](https://github.com/madisp)
-* [rubytester](https://github.com/rubytester)
-* [dougforpres](https://github.com/dougforpres)
-* [brettporter](https://github.com/brettporter)
-* [riywo](https://github.com/riywo)
-* [bobbrez](https://github.com/bobbrez)
+Please visit the [Contributors](https://github.com/arangamani/jenkins_api_client/graphs/contributors) page on Github.

data/README.md

@@ -177,6 +177,87 @@ initial_jobs.each do |job|
 end
 ```
 
+### Waiting for a build to start/Getting the build number
+Newer versions of Jenkins (starting with the 1.519 build) make it easier for
+an application to determine the build number for a 'build' request. (previously
+there would be a degree of guesswork involved).  The new version actually
+returns information allowing the jenkins_api_client to check the build queue
+for the job and see if it has started yet (once it has started, the build-
+number is available.
+
+If you wish to take advantage of this hands-off approach, the build method
+supports an additional 'opts' hash that lets you specify how long you wish to
+wait for the build to start.
+
+#### Old Jenkins vs New Jenkins (1.519+)
+
+##### Old (v < 1.519)
+The 'opts' parameter will work with older versions of Jenkins with the following
+caveats:
+* The 'cancel_on_build_start_timeout' option has no effect
+* The build_number is calculated by calling 'current_build_number' and adding
+  1 before the build is started.  This might break if there are multiple
+  entities running builds on the same job, or there are queued builds.
+
+##### New (v >= 1.519)
+* All options work, and build number is accurately determined from queue
+  info.
+
+#### Initiating a build and returning the build_number
+
+##### Minimum required
+```ruby
+# Minimum options required
+opts = {'build_start_timeout' => 30}
+@client.job.build(job_name, job_params || {}, opts)
+```
+This method will block for up to 30 seconds, while waiting for the build to
+start.  Instead of returning an http-status code, it will return the
+build_number, or if the build has not started will raise 'Timeout::Error'
+Note: to maintain legacy compatibility, passing 'true' will set the timeout
+to the default timeout specified when creating the @client.
+
+##### Auto cancel the queued-build on timeout
+```ruby
+# Wait for up to 30 seconds, attempt to cancel queued build
+opts = {'build_start_timeout' => 30,
+        'cancel_on_build_start_timeout' => true}
+@client.job.build(job_name, job_params || {}, opts)
+```
+This method will block for up to 30 seconds, while waiting for the build to
+start.  Instead of returning an http-status code, it will return the
+build_number, or if the build has not started will raise 'Timeout::Error'.
+Prior to raising the Timeout::Error, it will attempt to cancel the queued
+build - thus preventing it from starting.
+
+##### Getting some feedback while you're waiting
+The opts parameter supports two values that can be assigned proc objects
+(which will be 'call'ed).  Both are optional, and will only be called if
+specified in opts.
+These are initially intended to assist with logging progress.
+
+* 'progress_proc' - called when job is initially queued, and periodically
+  thereafter.
+  * max_wait - the value of 'build_start_timeout'
+  * current_wait - how long we've been waiting so far
+  * poll_count - how many times we've polled the queue
+* 'completion_proc' - called just prior to return/Timeout::Error
+  * build_number - the build number assigned (or nil if timeout)
+  * cancelled - whether the build was cancelled (true if 'new' Jenkins
+    and it was able to cancel the build, false otherwise)
+
+To use a class method, just specify 'instance.method(:method_name)', or
+use a proc or lambda
+
+```ruby
+# Wait for up to 30 seconds, attempt to cancel queued build, progress
+opts = {'build_start_timeout' => 30,
+        'cancel_on_build_start_timeout' => true,
+        'poll_interval' => 2,      # 2 is actually the default :)
+        'progress_proc' => lambda {|max,curr,count| ... },
+        'completion_proc' => lambda {|build_number,cancelled| ... }}
+@client.job.build(job_name, job_params || {}, opts)
+```
 ### Running Jenkins CLI
 To running [Jenkins CLI](https://wiki.jenkins-ci.org/display/JENKINS/Jenkins+CLI)
 
@@ -190,8 +271,9 @@ puts @client.exec_cli("version")
 ```
 
 * authentication with public/private key file
-remember to upload the public key to
-http://<Server IP>:<Server Port>/user/<Username>/configure
+remember to upload the public key to:
+
+    `http://#{Server IP}:#{Server Port}/user/#{Username}/configure`
 
 ```ruby
 @client = JenkinsApi::Client.new(:server_ip => '127.0.0.1',
@@ -278,3 +360,7 @@ FEATURE REQUEST:
 If you use this gem for your project and you think it would be nice to have a
 particular feature that is presently not implemented, I would love to hear that
 and consider working on it. Just open an issue in Github as a feature request.
+
+
+[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/arangamani/jenkins_api_client/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
+

data/jenkins_api_client.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "jenkins_api_client"
-  s.version = "1.0.0.alpha.2"
+  s.version = "1.0.0.beta.1"
 
   s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
   s.authors = ["Kannan Manickam"]
-  s.date = "2013-10-25"
+  s.date = "2013-11-17"
   s.description = "\nThis is a simple and easy-to-use Jenkins Api client with features focused on\nautomating Job configuration programaticaly and so forth"
   s.email = ["arangamani.kannan@gmail.com"]
   s.executables = ["jenkinscli"]
@@ -42,13 +42,14 @@ Gem::Specification.new do |s|
     "lib/jenkins_api_client/node.rb",
     "lib/jenkins_api_client/plugin_manager.rb",
     "lib/jenkins_api_client/system.rb",
+    "lib/jenkins_api_client/urihelper.rb",
     "lib/jenkins_api_client/user.rb",
     "lib/jenkins_api_client/version.rb",
     "lib/jenkins_api_client/view.rb",
     "scripts/login_with_irb.rb",
     "spec/func_tests/client_spec.rb",
     "spec/func_tests/job_spec.rb",
-    "spec/func_tests/node_spec.rb",
+    "spec/func_tests/node_spec.rb.pending",
     "spec/func_tests/plugin_spec.rb",
     "spec/func_tests/spec_helper.rb",
     "spec/func_tests/system_spec.rb",
@@ -56,6 +57,7 @@ Gem::Specification.new do |s|
     "spec/func_tests/view_spec.rb",
     "spec/unit_tests/build_queue_spec.rb",
     "spec/unit_tests/client_spec.rb",
+    "spec/unit_tests/fake_http_response.rb",
     "spec/unit_tests/fixtures/files/available_plugins.json",
     "spec/unit_tests/fixtures/files/computer_sample.xml",
     "spec/unit_tests/fixtures/files/installed_plugins.json",

data/lib/jenkins_api_client/client.rb

@@ -287,6 +287,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
@@ -321,7 +326,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)
@@ -346,8 +350,7 @@ 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
@@ -386,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")
@@ -413,8 +415,7 @@ module JenkinsApi
       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 = data
         request.content_type = content_type
@@ -480,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