improved_jenkins_client 1.6.0

data/lib/improved_jenkins_client/system.rb

@@ -0,0 +1,134 @@
+#
+# Copyright (c) 2012-2013 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'timeout'
+
+module JenkinsApi
+  class Client
+    # This class is used to communicate with Jenkins and performing some admin
+    # level operations such as restarting and reloading Jenkins.
+    #
+    class System
+
+      # Initializes a new System object.
+      #
+      # @param client [Client] the client object
+      #
+      # @return [System] the system object
+      #
+      def initialize(client)
+        @client = client
+        @logger = @client.logger
+        @timeout = @client.timeout
+      end
+
+      # Returns a string representation of System class.
+      #
+      def to_s
+        "#<JenkinsApi::Client::System>"
+      end
+
+      # Sends a quiet down request to the server.
+      #
+      def quiet_down
+        @logger.info "Performing a quiet down of jenkins..."
+        @client.api_post_request("/quietDown")
+      end
+
+      # Cancels the quiet down request sent to the server.
+      #
+      def cancel_quiet_down
+        @logger.info "Cancelling jenkins form quiet down..."
+        @client.api_post_request("/cancelQuietDown")
+      end
+
+      # Checks if server is in quiet down mode.
+      #
+      def check_quiet_down?
+        @logger.info "Checking if jenkins is in quiet down mode..."
+        @client.root.quieting_down?
+      end
+
+      # Restarts the Jenkins server
+      #
+      # @param [Boolean] force whether to force restart or wait till all
+      #               jobs are completed.
+      #
+      def restart(force = false)
+        if force
+          @logger.info "Performing a force restart of jenkins..."
+          @client.api_post_request("/restart")
+        else
+          @logger.info "Performing a safe restart of jenkins..."
+          @client.api_post_request("/safeRestart")
+        end
+      end
+
+      # Performs a force restart of Jenkins server
+      #
+      def restart!
+        restart(true)
+      end
+
+      # Reload the Jenkins server
+      #
+      def reload
+        @logger.info "Reloading jenkins..."
+        @client.api_post_request("/reload")
+      end
+
+      # List all users known to Jenkins by their Full Name
+      #
+      def list_users
+        warn "DEPRECATION: System#list_users is deprecated. Please use User#list instead"
+        @logger.info "Obtaining the list of users from jenkins"
+        users = @client.api_get_request("/asynchPeople")
+        names = []
+        users['users'].each { |user|
+          names << user['user']['fullName']
+        } unless users.nil?
+        return names
+      end
+
+      # This method waits till the server becomes ready after a start
+      # or restart.
+      #
+      def wait_for_ready
+        Timeout::timeout(@timeout) do
+          while true do
+            response = @client.get_root
+            @logger.info "Waiting for jenkins to restart..."
+            if (response.body =~ /Please wait while Jenkins is restarting/ ||
+              response.body =~ /Please wait while Jenkins is getting ready to work/)
+              sleep 30
+              redo
+            else
+              return true
+            end
+          end
+        end
+        false
+      end
+
+    end
+  end
+end

data/lib/improved_jenkins_client/urihelper.rb

@@ -0,0 +1,18 @@
+require 'uri'
+require 'addressable/uri'
+
+module JenkinsApi
+  module UriHelper
+    # Encode a string for using in the query part of an URL
+    #
+    def form_encode(string)
+      URI.encode_www_form_component string.encode(Encoding::UTF_8)
+    end
+
+    # Encode a string for use in the hiearchical part of an URL
+    #
+    def path_encode(path)
+      Addressable::URI.escape(path.encode(Encoding::UTF_8))
+    end
+  end
+end

data/lib/improved_jenkins_client/user.rb

@@ -0,0 +1,131 @@
+#
+# Copyright (c) 2012-2013 Douglas Henderson <dougforpres@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'timeout'
+require 'improved_jenkins_client/urihelper'
+
+module JenkinsApi
+  class Client
+    # This class is used to communicate with Jenkins and performing some user
+    # level operations - currently limited to fetching user info, but can
+    # be extended to support updating user fields
+    #
+    # @since 0.14.0
+    #
+    class User
+      include JenkinsApi::UriHelper
+
+      # Initializes a new User object.
+      #
+      # @param client [Client] the client object
+      #
+      # @return [User] the user object
+      #
+      def initialize(client)
+        @client = client
+        @logger = @client.logger
+        @timeout = @client.timeout
+      end
+
+      # Returns a string representation of User class.
+      #
+      def to_s
+        "#<JenkinsApi::Client::User>"
+      end
+
+      # Get a list of users
+      # Response will include same as is available from
+      # http://jenkins/user/#{username}
+      # userid, display name, and email-address
+      #
+      # @return [Hash] of [Hash], keyed by Jenkins user id
+      #   * +fullName+ The jenkins user idoutput+ Console output of the job
+      #   * +properties+ Size of the text. This ca
+      #
+      def list
+        @logger.info "Obtaining the list of users from jenkins"
+        # First we need to get the list of users.
+        # This is the same as "System.list_users", but since I didn't want to
+        # depend on that class I reproduced the request here.
+        userlist = @client.api_get_request("/asynchPeople")
+        users = {}
+
+        userlist['users'].each { |user|
+          # Jenkins seems ok to fetch by full-name, as long as perfect match
+          # since the name *came* from Jenkins this seems reasonably safe
+          user = get(user['user']['fullName'])
+          users[user['id']] = user if user
+        } unless userlist.nil?
+
+        return users
+      end
+
+      # Get a single user
+      #
+      # @param user_id [String] User ID or Full Name
+      #
+      # @return [Hash]
+      #   * +id+ Jenkins user id
+      #   * +fullName+ Full name of user (or user id if not set)
+      #   * other fields populated by Jenkins - this may vary based on version/plugins
+      #
+      # @example Example JSON for user info
+      #   {
+      #     "absoluteUrl" : "https://myjenkins.example.com/jenkins/user/fred",
+      #     "description" : "",
+      #     "fullName" : "Fred Flintstone",
+      #     "id" : "fred",
+      #     "property" : [
+      #       {
+      #       },
+      #       {
+      #       },
+      #       {
+      #         "address" : "fred@slaterockandgravel.com"
+      #       },
+      #       {
+      #       },
+      #       {
+      #       },
+      #       {
+      #         "insensitiveSearch" : false
+      #       }
+      #     ]
+      #   }
+      #
+      def get(user_id)
+        @client.api_get_request("/user/#{path_encode user_id}")
+      end
+
+      def get_api_token(user_id)
+        response = @client.api_get_request("/user/#{path_encode user_id}/configure", nil, '')
+        html = Nokogiri::HTML(response)
+        attr = html.xpath('//input[@id="apiToken"]/@value').first
+        if attr.nil?
+          raise Exceptions::ApiException.new(@logger, "Failed to get api token")
+        end
+        attr.value
+      end
+
+    end
+  end
+end

data/lib/improved_jenkins_client/version.rb

@@ -0,0 +1,36 @@
+#
+# Copyright (c) 2012-2013 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+module JenkinsApi
+  class Client
+    # Major version of the gem
+    MAJOR   = 1
+    # Minor version of the gem
+    MINOR   = 6
+    # Tiny version of the gem used for patches
+    TINY    = 0
+    # Used for pre-releases
+    PRE     = nil
+    # Version String of Jenkins API Client.
+    VERSION = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+  end
+end

data/lib/improved_jenkins_client/view.rb

@@ -0,0 +1,313 @@
+#
+# Copyright (c) 2012-2013 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'improved_jenkins_client/urihelper'
+
+module JenkinsApi
+  class Client
+    # This class communicates with Jenkins "/view" API and used to create,
+    # delete, update, and various other operations permitted on the Jenkins
+    # API.
+    #
+    class View
+      include JenkinsApi::UriHelper
+
+      # Initializes a new view object
+      #
+      # @param client [Client] the client object
+      #
+      # @return [View] the client object
+      #
+      def initialize(client)
+        @client = client
+        @logger = @client.logger
+      end
+
+      # Return a string representation of the object
+      #
+      def to_s
+        "#<JenkinsApi::Client::View>"
+      end
+
+      # Creates a new empty view of the given type
+      #
+      # @param [String] view_name Name of the view to be created
+      # @param [String] type Type of view to be created. Valid options:
+      # listview, myview. Default: listview
+      #
+      def create(view_name, type = "listview")
+        @logger.info "Creating a view '#{view_name}' of type '#{type}'"
+        mode = case type
+        when "listview"
+          "hudson.model.ListView"
+        when "myview"
+          "hudson.model.MyView"
+        else
+          raise "Type #{type} is not supported by Jenkins."
+        end
+        initial_post_params = {
+          "name" => view_name,
+          "mode" => mode,
+          "json" => {
+            "name" => view_name,
+            "mode" => mode
+          }.to_json
+        }
+        @client.api_post_request("/createView", initial_post_params)
+      end
+
+      # Creates a listview by accepting the given parameters hash
+      #
+      # @param [Hash] params options to create the new view
+      # @option params [String] :name Name of the view
+      # @option params [String] :description Description of the view
+      # @option params [String] :status_filter Filter jobs based on the status.
+      #         Valid options: all_selected_jobs, enabled_jobs_only,
+      #         disabled_jobs_only. Default: all_selected_jobs
+      # @option params [Boolean] :filter_queue true or false
+      # @option params [Boolean] :filter_executors true or false
+      # @option params [String] :regex Regular expression to filter jobs that
+      #         are to be added to the view
+      #
+      # @raise [ArgumentError] if the required parameter +:name+ is not
+      #   specified
+      #
+      def create_list_view(params)
+        # Name is a required parameter. Raise an error if not specified
+        raise ArgumentError, "Name is required for creating view" \
+          unless params.is_a?(Hash) && params[:name]
+        create(params[:name], "listview")
+        @logger.debug "Creating a list view with params: #{params.inspect}"
+        status_filter = case params[:status_filter]
+        when "all_selected_jobs"
+          ""
+        when "enabled_jobs_only"
+          "1"
+        when "disabled_jobs_only"
+          "2"
+        else
+          ""
+        end
+        post_params = {
+          "name" => params[:name],
+          "mode" => "hudson.model.ListView",
+          "description" => params[:description],
+          "statusFilter" => status_filter,
+          "json" => {
+            "name" => params[:name],
+            "description" => params[:description],
+            "mode" => "hudson.model.ListView",
+            "statusFilter" => "",
+            "columns" => [
+              {
+                "stapler-class" => "hudson.views.StatusColumn",
+                "kind"=> "hudson.views.StatusColumn"
+              },
+              {
+                "stapler-class" => "hudson.views.WeatherColumn",
+                "kind" => "hudson.views.WeatherColumn"
+              },
+              {
+                "stapler-class" => "hudson.views.JobColumn",
+                "kind" => "hudson.views.JobColumn"
+              },
+              {
+                "stapler-class" => "hudson.views.LastSuccessColumn",
+                "kind" => "hudson.views.LastSuccessColumn"
+              },
+              {
+                "stapler-class" => "hudson.views.LastFailureColumn",
+                "kind" => "hudson.views.LastFailureColumn"
+              },
+              {
+                "stapler-class" => "hudson.views.LastDurationColumn",
+                "kind" => "hudson.views.LastDurationColumn"
+              },
+              {
+                "stapler-class" => "hudson.views.BuildButtonColumn",
+                "kind" => "hudson.views.BuildButtonColumn"
+              }
+            ]
+          }.to_json
+        }
+        post_params.merge!("filterQueue" => "on") if params[:filter_queue]
+        post_params.merge!("filterExecutors" => "on") if params[:filter_executors]
+        post_params.merge!("useincluderegex" => "on",
+                           "includeRegex" => params[:regex]) if params[:regex]
+        @client.api_post_request("/view/#{path_encode params[:name]}/configSubmit",
+                                 post_params)
+      end
+
+      # Delete a view
+      #
+      # @param [String] view_name
+      #
+      def delete(view_name)
+        @logger.info "Deleting view '#{view_name}'"
+        @client.api_post_request("/view/#{path_encode view_name}/doDelete")
+      end
+
+      # Deletes all views (except the All view) in Jenkins.
+      #
+      # @note This method deletes all views (except the All view) available
+      #       in Jenkins. Please use with caution.
+      #
+      def delete_all!
+        @logger.info "Deleting all views from jenkins"
+        list.each { |view| delete(view) unless view == "All"}
+      end
+
+      # This method lists all views
+      #
+      # @param [String] filter a regex to filter view names
+      # @param [Bool] ignorecase whether to be case sensitive or not
+      #
+      def list(filter = "", ignorecase = true)
+        @logger.info "Obtaining views based on filter '#{filter}'"
+        view_names = []
+        response_json = @client.api_get_request("", "tree=views[name]")
+        response_json["views"].each { |view|
+          if ignorecase
+            view_names << view["name"] if view["name"] =~ /#{filter}/i
+          else
+            view_names << view["name"] if view["name"] =~ /#{filter}/
+          end
+        }
+        view_names
+      end
+
+      # Checks if the given view exists in Jenkins
+      #
+      # @param [String] view_name
+      #
+      def exists?(view_name)
+        list(view_name).include?(view_name)
+      end
+
+      # List jobs in a view
+      #
+      # @param [String] view_name
+      #
+      # @return [Array] job_names list of jobs in the specified view
+      #
+      def list_jobs(view_name)
+        @logger.info "Obtaining the jobs present in view '#{view_name}'"
+        job_names = []
+        raise "The view #{view_name} doesn't exists on the server"\
+          unless exists?(view_name)
+        response_json = @client.api_get_request("/view/#{path_encode view_name}")
+        response_json["jobs"].each do |job|
+          job_names << job["name"]
+        end
+        job_names
+      end
+
+      # List jobs in view along with their details
+      #
+      # @param [String] view_name
+      #
+      # @return [Array<Hash>] the details of jobs in the specified view
+      #
+      def list_jobs_with_details(view_name)
+        @logger.info "Obtaining the jobs present in view '#{view_name}'"
+        raise "The view #{view_name} doesn't exists on the server"\
+          unless exists?(view_name)
+        response_json = @client.api_get_request("/view/#{path_encode view_name}")
+        response_json["jobs"]
+      end
+
+      # Add a job to view
+      #
+      # @param [String] view_name
+      # @param [String] job_name
+      #
+      def add_job(view_name, job_name)
+        @logger.info "Adding job '#{job_name}' to view '#{view_name}'"
+        post_msg = "/view/#{path_encode view_name}/addJobToView?name=#{form_encode job_name}"
+        @client.api_post_request(post_msg)
+      end
+
+      # Remove a job from view
+      #
+      # @param [String] view_name
+      # @param [String] job_name
+      #
+      def remove_job(view_name, job_name)
+        @logger.info "Removing job '#{job_name}' from view '#{view_name}'"
+        post_msg = "/view/#{path_encode view_name}/removeJobFromView?name=#{form_encode job_name}"
+        @client.api_post_request(post_msg)
+      end
+
+      # List (sub-)views in a view
+      #
+      # @param [String] view_name
+      #
+      # @return [Array] view_names list of (sub-)views in the specified view
+      #
+      def list_views(view_name)
+        @logger.info "Obtaining the views present in view '#{view_name}'"
+        view_names = []
+        raise "The view #{view_name} doesn't exists on the server"\
+          unless exists?(view_name)
+        response_json = @client.api_get_request("/view/#{path_encode view_name}")
+        response_json["views"].each do |view|
+          view_names << view["name"]
+        end
+        view_names
+      end
+
+      # List (sub-)views in view along with their details
+      #
+      # @param [String] view_name
+      #
+      # @return [Array<Hash>] the details of (sub-)views in the specified view
+      #
+      def list_views_with_details(view_name)
+        @logger.info "Obtaining the views present in view '#{view_name}'"
+        raise "The view #{view_name} doesn't exists on the server"\
+          unless exists?(view_name)
+        response_json = @client.api_get_request("/view/#{path_encode view_name}")
+        response_json["views"]
+      end
+
+      # Obtain the configuration stored in config.xml of a specific view
+      #
+      # @param [String] view_name
+      #
+      def get_config(view_name)
+        @logger.info "Obtaining the configuration of view '#{view_name}'"
+        @client.get_config("/view/#{path_encode view_name}")
+      end
+
+      # Post the configuration of a view given the view name and the config.xml
+      #
+      # @param [String] view_name
+      # @param [String] xml
+      #
+      def post_config(view_name, xml)
+        @logger.info "Posting the configuration of view '#{view_name}'"
+        @client.post_config("/view/#{path_encode view_name}/config.xml", xml)
+      end
+
+    end
+  end
+end

data/lib/improved_jenkins_client.rb

@@ -0,0 +1,52 @@
+#
+# Copyright (c) 2012 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'improved_jenkins_client/version'
+require 'improved_jenkins_client/exceptions'
+require 'improved_jenkins_client/client'
+require 'improved_jenkins_client/job'
+require 'improved_jenkins_client/node'
+require 'improved_jenkins_client/system'
+require 'improved_jenkins_client/view'
+require 'improved_jenkins_client/build_queue'
+require 'improved_jenkins_client/plugin_manager'
+require 'improved_jenkins_client/user'
+require 'improved_jenkins_client/root'
+
+require 'improved_jenkins_client/cli/helper'
+require 'improved_jenkins_client/cli/base'
+require 'improved_jenkins_client/cli/job'
+require 'improved_jenkins_client/cli/node'
+require 'improved_jenkins_client/cli/system'
+
+module JenkinsApi
+  class Client
+    module PluginSettings
+      class InvalidType < Exception; end
+
+      autoload :Base, 'improved_jenkins_client/plugin_settings/base'
+      autoload :Hipchat, 'improved_jenkins_client/plugin_settings/hipchat'
+      autoload :WorkspaceCleanup, 'improved_jenkins_client/plugin_settings/workspace_cleanup'
+      autoload :Collection, 'improved_jenkins_client/plugin_settings/collection'
+    end
+  end
+end