jenkins_api_client 0.13.0 → 0.14.0

data/.gitignore

@@ -17,6 +17,9 @@ doc
 #
 Gemfile.lock
 
+# graphviz dot file
+*.dot
+
 # MacOS:
 .DS_Store
 

data/.travis.yml

@@ -24,6 +24,7 @@ script:
   - travis/setup_crumb.sh
   - bundle exec rake func_tests
 notifications:
+  webhooks: https://www.buildheroes.com/api/projects/588c9dffdc8f0deff4d89d87bf370e8dba8a8a95/builds
   email: false
   irc:
     on_success: change

data/CHANGELOG.md

@@ -4,6 +4,19 @@ CHANGELOG
 upcoming
 --------
 
+v0.14.0  [07-AUG-2013]
+----------------------
+* Fixed a bug where a space was missing in the exec_cli method argument list.
+  Credit: @missedone
+* Refactored create/update jobs by introducing create_or_update methods.
+  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.
+  Credit: dougforpres
+* Added a method `Job#poll` which will poll for SCM changes programatically.
+* Added a shortcut method `System#restart!` for force restart.
+
 v0.13.0  [09-JUL-2013]
 ----------------------
 * Jenkins XSS disable option is now supported. No inputs are required - the

data/Gemfile

@@ -1,14 +1,15 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "nokogiri", "~> 1.5.0"
 gem "thor", ">= 0.16.0"
 gem "json", ">= 0"
 gem "terminal-table", ">= 1.4.0"
-gem "mixlib-shellout", "~> 1.1.0"
+gem "mixlib-shellout", ">= 1.1.0"
 
 group :development do
   gem "bundler", ">= 1.0"
   gem "jeweler", ">= 1.6.4"
+  gem "rspec", "~> 2.13.0"
   gem "simplecov"
-  gem "rspec"
+  gem "yard"
 end

data/README.md

@@ -9,7 +9,7 @@ Copyright © 2012-2013, Kannan Manickam [![endorse](http://api.coderwall.com
 
 Client libraries for communicating with a Jenkins CI server and programatically managing jobs.
 
-IRC Channel: ##jenkins-api-client
+IRC Channel: ##jenkins-api-client (on freenode)
 
 Mailing list: jenkins_api_client@googlegroups.com
 
@@ -67,6 +67,14 @@ file. To use the client without credentials, just leave out the
 <tt>username</tt> and <tt>password</tt> parameters. The <tt>password</tt>
 parameter is only required if <tt>username</tt> is specified.
 
+### Cross-site Scripting (XSS) and Crumb Support
+
+Support for Jenkins crumbs has been added.  These allow an application to
+use the Jenkins API POST methods without requiring the 'Prevent Cross Site
+Request Forgery exploits' to be disabled.  The API will check in with the
+Jenkins server to determine whether crumbs are enabled or not, and use them
+if appropriate.
+
 ### Basic Usage
 
 As discussed earlier, you can either specify all the credentials and server
@@ -174,7 +182,8 @@ puts @client.exec_cli("version")
 ```
 
 * authentication with public/private key file
-remember to upload the public key to http://#{server_ip}:#{server_port}/user/#{my_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',

data/Rakefile

@@ -3,6 +3,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'jenkins_api_client/version'
 require 'rake'
 require 'jeweler'
+require 'yard'
 
 Jeweler::Tasks.new do |gemspec|
   gemspec.name             = 'jenkins_api_client'
@@ -41,4 +42,65 @@ RSpec::Core::RakeTask.new(:test) do |spec|
   spec.rspec_opts = ['--color', '--format documentation']
 end
 
-task :default => [:unit_tests]
+YARD::Config.load_plugin 'thor'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb', 'lib/**/**/*.rb']
+end
+
+namespace :doc do
+  # This task requires that graphviz is installed locally. For more info:
+  # http://www.graphviz.org/
+  desc "Generates the class diagram using the yard generated dot file"
+  task :generate_class_diagram do
+    puts "Generating the dot file..."
+    `yard graph --file jenkins_api_client.dot`
+    puts "Generating class diagram from the dot file..."
+    `dot jenkins_api_client.dot -Tpng -o jenkins_api_client_class_diagram.png`
+  end
+
+  desc "Applies Google Analytics tracking script to all generated html files"
+  task :apply_google_analytics do
+    files = Dir.glob("**/*.html")
+
+    string_to_replace = "</body>"
+    string_to_replace_with = <<-EOF
+      <script type="text/javascript">
+        var _gaq = _gaq || [];
+        _gaq.push(['_setAccount', 'UA-37519629-2']);
+        _gaq.push(['_trackPageview']);
+
+        (function() {
+            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+        })();
+      </script>
+    </body>
+    EOF
+
+    files.each do |html_file|
+      puts "Processing file: #{html_file}"
+      contents = ""
+      # Read the file contents
+      file =  File.open(html_file)
+      file.each { |line| contents << line }
+      file.close
+
+      # If the file already has google analytics tracking info, skip it.
+      if contents.include?(string_to_replace_with)
+        puts "Skipped..."
+        next
+      end
+
+      # Apply google analytics tracking info to the html file
+      contents.gsub!(string_to_replace, string_to_replace_with)
+
+      # Write the contents with the google analytics info to the file
+      file =  File.open(html_file, "w")
+      file.write(contents)
+      file.close
+    end
+  end
+end
+
+task :default => [:unit_tests]

data/jenkins_api_client.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "jenkins_api_client"
-  s.version = "0.13.0"
+  s.version = "0.14.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Kannan Manickam"]
-  s.date = "2013-07-10"
+  s.date = "2013-08-08"
   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"]
@@ -28,6 +28,7 @@ Gem::Specification.new do |s|
     "config/login.yml.example",
     "java_deps/jenkins-cli.jar",
     "jenkins_api_client.gemspec",
+    "jenkins_api_client_class_diagram.png",
     "lib/jenkins_api_client.rb",
     "lib/jenkins_api_client/build_queue.rb",
     "lib/jenkins_api_client/cli/base.rb",
@@ -40,6 +41,7 @@ Gem::Specification.new do |s|
     "lib/jenkins_api_client/job.rb",
     "lib/jenkins_api_client/node.rb",
     "lib/jenkins_api_client/system.rb",
+    "lib/jenkins_api_client/user.rb",
     "lib/jenkins_api_client/version.rb",
     "lib/jenkins_api_client/view.rb",
     "scripts/login_with_irb.rb",
@@ -48,6 +50,7 @@ Gem::Specification.new do |s|
     "spec/func_tests/node_spec.rb",
     "spec/func_tests/spec_helper.rb",
     "spec/func_tests/system_spec.rb",
+    "spec/func_tests/user_spec.rb",
     "spec/func_tests/view_spec.rb",
     "spec/unit_tests/build_queue_spec.rb",
     "spec/unit_tests/client_spec.rb",
@@ -57,6 +60,7 @@ Gem::Specification.new do |s|
     "spec/unit_tests/node_spec.rb",
     "spec/unit_tests/spec_helper.rb",
     "spec/unit_tests/system_spec.rb",
+    "spec/unit_tests/user_spec.rb",
     "spec/unit_tests/view_spec.rb",
     "travis/jenkins_config.xml",
     "travis/jenkins_config_with_crumb.xml",
@@ -78,32 +82,35 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<thor>, [">= 0.16.0"])
       s.add_runtime_dependency(%q<json>, [">= 0"])
       s.add_runtime_dependency(%q<terminal-table>, [">= 1.4.0"])
-      s.add_runtime_dependency(%q<mixlib-shellout>, ["~> 1.1.0"])
+      s.add_runtime_dependency(%q<mixlib-shellout>, [">= 1.1.0"])
       s.add_development_dependency(%q<bundler>, [">= 1.0"])
       s.add_development_dependency(%q<jeweler>, [">= 1.6.4"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.13.0"])
       s.add_development_dependency(%q<simplecov>, [">= 0"])
-      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
     else
       s.add_dependency(%q<nokogiri>, ["~> 1.5.0"])
       s.add_dependency(%q<thor>, [">= 0.16.0"])
       s.add_dependency(%q<json>, [">= 0"])
       s.add_dependency(%q<terminal-table>, [">= 1.4.0"])
-      s.add_dependency(%q<mixlib-shellout>, ["~> 1.1.0"])
+      s.add_dependency(%q<mixlib-shellout>, [">= 1.1.0"])
       s.add_dependency(%q<bundler>, [">= 1.0"])
       s.add_dependency(%q<jeweler>, [">= 1.6.4"])
+      s.add_dependency(%q<rspec>, ["~> 2.13.0"])
       s.add_dependency(%q<simplecov>, [">= 0"])
-      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
     end
   else
     s.add_dependency(%q<nokogiri>, ["~> 1.5.0"])
     s.add_dependency(%q<thor>, [">= 0.16.0"])
     s.add_dependency(%q<json>, [">= 0"])
     s.add_dependency(%q<terminal-table>, [">= 1.4.0"])
-    s.add_dependency(%q<mixlib-shellout>, ["~> 1.1.0"])
+    s.add_dependency(%q<mixlib-shellout>, [">= 1.1.0"])
     s.add_dependency(%q<bundler>, [">= 1.0"])
     s.add_dependency(%q<jeweler>, [">= 1.6.4"])
+    s.add_dependency(%q<rspec>, ["~> 2.13.0"])
     s.add_dependency(%q<simplecov>, [">= 0"])
-    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
   end
 end
 

data/lib/jenkins_api_client.rb

@@ -28,6 +28,7 @@ require 'jenkins_api_client/node'
 require 'jenkins_api_client/system'
 require 'jenkins_api_client/view'
 require 'jenkins_api_client/build_queue'
+require 'jenkins_api_client/user'
 
 require 'jenkins_api_client/cli/helper'
 require 'jenkins_api_client/cli/base'

data/lib/jenkins_api_client/build_queue.rb

@@ -30,7 +30,9 @@ module JenkinsApi
 
       # Initializes a new BuildQueue object.
       #
-      # @param [Object] client a reference to Client
+      # @param client [Client] the client object
+      #
+      # @return [BuildQueue] the build queue object
       #
       def initialize(client)
         @client = client
@@ -208,7 +210,7 @@ module JenkinsApi
       #
       # @param [String] task_name name of the task
       #
-      # @return [TrueClass|FalseClass] buildable or not
+      # @return [Boolean] buildable or not
       #
       def is_buildable?(task_name)
         @logger.info "Checking if task '#{task_name}' from the build queue" +
@@ -225,7 +227,7 @@ module JenkinsApi
       #
       # @param [String] task_name name of the task
       #
-      # @return [TrueClass|FalseClass] blocked or not
+      # @return [Boolean] blocked or not
       #
       def is_blocked?(task_name)
         @logger.info "Checking if task '#{task_name}' from the build queue" +
@@ -242,7 +244,7 @@ module JenkinsApi
       #
       # @param [String] task_name name of the task
       #
-      # @return [TrueClass|FalseClass] stuck or not
+      # @return [Boolean] stuck or not
       #
       def is_stuck?(task_name)
         @logger.info "Checking if task '#{task_name}' from the build queue" +

data/lib/jenkins_api_client/client.rb

@@ -83,23 +83,25 @@ module JenkinsApi
     # @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
+    #   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
+    # @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] :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
-    #   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
+    # @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)
@@ -210,6 +212,14 @@ module JenkinsApi
       JenkinsApi::Client::BuildQueue.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
+    #
+    def user
+      JenkinsApi::Client::User.new(self)
+    end
+
     # Returns a string representing the class name
     #
     # @return [String] string representation of class name
@@ -323,9 +333,7 @@ module JenkinsApi
     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?
+        refresh_crumbs
 
         # Added form_data default {} instead of nil to help with proxies
         # that barf with empty post
@@ -343,13 +351,22 @@ module JenkinsApi
         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
+      rescue Exceptions::ForbiddenException => e
+        refresh_crumbs(true)
+
+        if @crumbs_enabled
+          @logger.info "Retrying: #{@crumb_max_retries - retries + 1} out of" +
+            " #{@crumb_max_retries} times..."
+          retries -= 1
+
+          if retries > 0
+            retry
+          else
+            raise Exceptions::ForbiddenWithCrumb.new(@logger, e.message)
+          end
+        else
+          raise
+        end
       end
     end
 
@@ -377,9 +394,7 @@ module JenkinsApi
     def post_config(url_prefix, xml)
       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?
+        refresh_crumbs
 
         url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
         request = Net::HTTP::Post.new("#{url_prefix}")
@@ -391,13 +406,22 @@ module JenkinsApi
         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
+      rescue Exceptions::ForbiddenException => e
+        refresh_crumbs(true)
+
+        if @crumbs_enabled
+          @logger.info "Retrying: #{@crumb_max_retries - retries + 1} out of" +
+            " #{@crumb_max_retries} times..."
+          retries -= 1
+
+          if retries > 0
+            retry
+          else
+            raise Exceptions::ForbiddenWithCrumb.new(@logger, e.message)
+          end
+        else
+          raise
+        end
       end
     end
 
@@ -463,7 +487,8 @@ module JenkinsApi
       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 << " --username #{@username} --password #{@password}" if @identity_file.nil? || @identity_file.empty?
+      cmd << ' '
       cmd << args.join(' ')
       java_cmd = Mixlib::ShellOut.new(cmd)
 
@@ -506,6 +531,46 @@ module JenkinsApi
       end
     end
 
+    # Used to determine whether crumbs are enabled, and populate/clear our
+    # local crumb accordingly.
+    #
+    # @param force_refresh [Boolean] determines whether the check is
+    #   cursory or deeper.  The default is cursory - i.e. if crumbs
+    #   enabled is 'nil' then figure out what to do, otherwise skip
+    #   If 'true' the method will check to see if the crumbs require-
+    #   ment has changed (by querying Jenkins), and updating crumb
+    #   (refresh, delete, create) as appropriate.
+    #
+    def refresh_crumbs(force_refresh = false)
+      # Quick check to see if someone has changed XSS settings and not
+      # restarted us
+      if force_refresh || @crumbs_enabled.nil?
+        old_crumbs_setting = @crumbs_enabled
+        new_crumbs_setting = use_crumbs?
+
+        if old_crumbs_setting != new_crumbs_setting
+          @crumbs_enabled = new_crumbs_setting
+        end
+
+        # Get or clear crumbs setting appropriately
+        # Works as refresh if crumbs still enabled
+        if @crumbs_enabled
+          if old_crumbs_setting
+            @logger.info "Crumb expired.  Refetching from the server."
+          else
+            @logger.info "Crumbs turned on.  Fetching from the server."
+          end
+
+          @crumb = get_crumb if force_refresh || !old_crumbs_setting
+        else
+          if old_crumbs_setting
+            @logger.info "Crumbs turned off.  Clearing crumb."
+            @crumb.clear
+          end
+        end
+      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.