Class: JenkinsApi::Client
- Inherits:
-
Object
- Object
- JenkinsApi::Client
- Defined in:
- lib/jenkins_api_client/client.rb,
lib/jenkins_api_client.rb,
lib/jenkins_api_client/job.rb,
lib/jenkins_api_client/node.rb,
lib/jenkins_api_client/user.rb,
lib/jenkins_api_client/view.rb,
lib/jenkins_api_client/system.rb,
lib/jenkins_api_client/version.rb,
lib/jenkins_api_client/build_queue.rb,
lib/jenkins_api_client/plugin_manager.rb,
lib/jenkins_api_client/plugin_settings/base.rb,
lib/jenkins_api_client/plugin_settings/hipchat.rb,
lib/jenkins_api_client/plugin_settings/collection.rb,
lib/jenkins_api_client/plugin_settings/workspace_cleanup.rb
Overview
This is the client class that acts as the bridge between the subclasses and Jenkins. This class contains methods that performs GET and POST requests for various operations.
Defined Under Namespace
Modules: PluginSettings Classes: BuildQueue, Job, Node, PluginManager, System, User, View
Constant Summary collapse
- DEFAULT_SERVER_PORT =
Default port to be used to connect to Jenkins
8080
- DEFAULT_TIMEOUT =
Default timeout in seconds to be used while performing operations
120
- DEFAULT_HTTP_OPEN_TIMEOUT =
10
- DEFAULT_HTTP_READ_TIMEOUT =
120
- VALID_PARAMS =
Parameters that are permitted as options while initializing the client
[ "server_url", "server_ip", "server_port", "proxy_ip", "proxy_port", "jenkins_path", "username", "password", "password_base64", "logger", "log_location", "log_level", "timeout", "http_open_timeout", "http_read_timeout", "ssl", "follow_redirects", "identity_file", "cookies" ].freeze
- MAJOR =
Major version of the gem
1
- MINOR =
Minor version of the gem
4
- TINY =
Tiny version of the gem used for patches
1
- PRE =
Used for pre-releases
nil
- VERSION =
Version String of Jenkins API Client.
[MAJOR, MINOR, TINY, PRE].compact.join('.')
Instance Attribute Summary collapse
-
#logger ⇒ Object
Returns the value of attribute logger.
-
#timeout ⇒ Object
Returns the value of attribute timeout.
Instance Method Summary collapse
-
#api_get_request(url_prefix, tree = nil, url_suffix = "/api/json", raw_response = false) ⇒ String, Hash
Sends a GET request to the Jenkins CI server with the specified URL.
-
#api_post_request(url_prefix, form_data = {}, raw_response = false) ⇒ String
Sends a POST message to the Jenkins CI server with the specified URL.
-
#compare_versions(version_a, version_b) ⇒ Object
Compare two version strings (A and B) if A == B, returns 0 if A > B, returns 1 if A < B, returns -1.
-
#deconstruct_version_string(version) ⇒ Object
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.
-
#exec_cli(command, args = []) ⇒ String
Execute the Jenkins CLI.
-
#exec_script(script_text) ⇒ String
Executes the provided groovy script on the Jenkins CI server.
-
#get_artifact(job_name, filename) ⇒ Object
Connects to the server and downloads artifacts to a specified location.
-
#get_config(url_prefix) ⇒ String
Obtains the configuration of a component from the Jenkins CI server.
-
#get_hudson_version ⇒ String
Obtain the Hudson version of the CI server Only queries Hudson/Jenkins if the version is not already stored.
-
#get_jenkins_version ⇒ String
Obtains the jenkins version from the API Only queries Jenkins if the version is not already stored.
-
#get_root ⇒ Net::HTTP::Response
Obtains the root of Jenkins server.
-
#get_server_date ⇒ String
Obtain the date of the Jenkins server.
- #init_update_center ⇒ Object
-
#initialize(args) ⇒ JenkinsApi::Client
constructor
Initialize a Client object with Jenkins CI server credentials.
-
#inspect ⇒ Object
Overrides the inspect method to get rid of the credentials being shown in the in interactive IRB sessions and also when the ‘inspect` method is called.
-
#job ⇒ JenkinsApi::Client::Job
Creates an instance to the Job class by passing a reference to self.
-
#node ⇒ JenkinsApi::Client::Node
Creates an instance to the Node class by passing a reference to self.
-
#plugin ⇒ JenkinsApi::Client::PluginManager
Creates an instance to the PluginManager by passing a reference to self.
-
#post_config(url_prefix, xml) ⇒ String
Posts the given xml configuration to the url given.
- #post_data(url_prefix, data, content_type) ⇒ Object
- #post_json(url_prefix, json) ⇒ Object
-
#queue ⇒ JenkinsApi::Client::BuildQueue
Creates an instance to the BuildQueue by passing a reference to self.
-
#system ⇒ JenkinsApi::Client::System
Creates an instance to the System class by passing a reference to self.
-
#to_s ⇒ String
Returns a string representing the class name.
-
#use_crumbs? ⇒ Boolean
Checks if Jenkins uses crumbs (i.e) the XSS disable option is checked in Jenkins’ security settings.
-
#use_security? ⇒ Boolean
Checks if Jenkins uses security.
-
#user ⇒ JenkinsApi::Client::User
Creates an instance of the User class by passing a reference to self.
-
#view ⇒ JenkinsApi::Client::View
Creates an instance to the View class by passing a reference to self.
Constructor Details
#initialize(args) ⇒ JenkinsApi::Client
Initialize a Client object with Jenkins CI server credentials
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 |
# File 'lib/jenkins_api_client/client.rb', line 104 def initialize(args) args = symbolize_keys(args) args.each do |key, value| if value && VALID_PARAMS.include?(key.to_s) instance_variable_set("@#{key}", value) end end if args.is_a? Hash # 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) raise ArgumentError, "If username is provided, password is required" end if @proxy_ip.nil? ^ @proxy_port.nil? raise ArgumentError, "Proxy IP and port must both be specified or" + " both left nil" 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 if @logger raise ArgumentError, "logger parameter must be a Logger object" unless @logger.is_a?(Logger) raise ArgumentError, "log_level should not be set if using custom logger" if @log_level raise ArgumentError, "log_location should not be set if using custom logger" if @log_location else @log_location = STDOUT unless @log_location @log_level = Logger::INFO unless @log_level @logger = Logger.new(@log_location) @logger.level = @log_level end # Base64 decode inserts a newline character at the end. As a workaround # added chomp to remove newline characters. I hope nobody uses newline # characters at the end of their passwords :) @password = Base64.decode64(@password_base64).chomp if @password_base64 # No connections are made to the Jenkins server during initialize to # allow the unit tests to behave normally as mocking is simpler this way. # If this variable is nil, the first POST request will query the API and # populate this variable. @crumbs_enabled = nil # The crumbs hash. Store it so that we don't have to obtain the crumb for # every POST request. It appears that the crumb doesn't change often. @crumb = {} # This is the number of times to refetch the crumb if it ever expires. @crumb_max_retries = 3 end |
Instance Attribute Details
#logger ⇒ Object
Returns the value of attribute logger.
42 43 44 |
# File 'lib/jenkins_api_client/client.rb', line 42 def logger @logger end |
#timeout ⇒ Object
Returns the value of attribute timeout.
42 43 44 |
# File 'lib/jenkins_api_client/client.rb', line 42 def timeout @timeout end |
Instance Method Details
#api_get_request(url_prefix, tree = nil, url_suffix = "/api/json", raw_response = false) ⇒ String, Hash
Sends a GET request to the Jenkins CI server with the specified URL
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 |
# File 'lib/jenkins_api_client/client.rb', line 351 def api_get_request(url_prefix, tree = nil, url_suffix ="/api/json", raw_response = false) url_prefix = "#{@jenkins_path}#{url_prefix}" to_get = "" if tree to_get = "#{url_prefix}#{url_suffix}?#{tree}" else to_get = "#{url_prefix}#{url_suffix}" end request = Net::HTTP::Get.new(to_get) @logger.debug "GET #{to_get}" response = make_http_request(request) if raw_response handle_exception(response, "raw") else handle_exception(response, "body", url_suffix =~ /json/) end end |
#api_post_request(url_prefix, form_data = {}, raw_response = false) ⇒ String
Sends a POST message to the Jenkins CI server with the specified URL
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 |
# File 'lib/jenkins_api_client/client.rb', line 379 def api_post_request(url_prefix, form_data = {}, raw_response = false) retries = @crumb_max_retries begin refresh_crumbs # Added form_data default {} instead of nil to help with proxies # that barf with empty post request = Net::HTTP::Post.new("#{@jenkins_path}#{url_prefix}") @logger.debug "POST #{url_prefix}" if @crumbs_enabled request[@crumb["crumbRequestField"]] = @crumb["crumb"] end request.set_form_data(form_data) response = make_http_request(request) if raw_response handle_exception(response, "raw") else handle_exception(response) end 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.) end else raise end end end |
#compare_versions(version_a, version_b) ⇒ Object
Compare two version strings (A and B) if A == B, returns 0 if A > B, returns 1 if A < B, returns -1
559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 |
# File 'lib/jenkins_api_client/client.rb', line 559 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 |
#deconstruct_version_string(version) ⇒ Object
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
543 544 545 546 547 548 549 550 551 552 553 |
# File 'lib/jenkins_api_client/client.rb', line 543 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 |
#exec_cli(command, args = []) ⇒ String
Execute the Jenkins CLI
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 |
# File 'lib/jenkins_api_client/client.rb', line 606 def exec_cli(command, args = []) base_dir = File.dirname(__FILE__) server_url = "http://#{@server_ip}:#{@server_port}/#{@jenkins_path}" 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 << ' ' cmd << args.join(' ') java_cmd = Mixlib::ShellOut.new(cmd) # Run the command java_cmd.run_command if java_cmd.stderr.empty? java_cmd.stdout.chomp else # The stderr has a stack trace of the Java program. We'll already have # a stack trace for Ruby. So just display a descriptive message for the # error thrown by the CLI. raise Exceptions::CLIException.new( @logger, java_cmd.stderr.split("\n").first ) end end |
#exec_script(script_text) ⇒ String
Executes the provided groovy script on the Jenkins CI server
591 592 593 594 |
# File 'lib/jenkins_api_client/client.rb', line 591 def exec_script(script_text) response = api_post_request('/scriptText', {'script' => script_text}, true) response.body end |
#get_artifact(job_name, filename) ⇒ Object
Connects to the server and downloads artifacts to a specified location
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 |
# File 'lib/jenkins_api_client/client.rb', line 266 def get_artifact(job_name,filename) @artifact = job.find_artifact(job_name) uri = URI.parse(@artifact) http = Net::HTTP.new(uri.host, uri.port) http.verify_mode = OpenSSL::SSL::VERIFY_NONE http.use_ssl = @ssl request = Net::HTTP::Get.new(uri.request_uri) request.basic_auth(@username, @password) response = http.request(request) if response.code == "200" File.write(File.(filename), response.body) else raise "Couldn't get the artifact" end end |
#get_config(url_prefix) ⇒ String
Obtains the configuration of a component from the Jenkins CI server
423 424 425 426 427 428 |
# File 'lib/jenkins_api_client/client.rb', line 423 def get_config(url_prefix) request = Net::HTTP::Get.new("#{@jenkins_path}#{url_prefix}/config.xml") @logger.debug "GET #{url_prefix}/config.xml" response = make_http_request(request) handle_exception(response, "body") end |
#get_hudson_version ⇒ String
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
534 535 536 537 |
# File 'lib/jenkins_api_client/client.rb', line 534 def get_hudson_version get_root if @hudson_version.nil? @hudson_version end |
#get_jenkins_version ⇒ String
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
522 523 524 525 |
# File 'lib/jenkins_api_client/client.rb', line 522 def get_jenkins_version get_root if @jenkins_version.nil? @jenkins_version end |
#get_root ⇒ Net::HTTP::Response
Obtains the root of Jenkins server. This function is used to see if Jenkins is running
335 336 337 338 339 |
# File 'lib/jenkins_api_client/client.rb', line 335 def get_root @logger.debug "GET #{@jenkins_path}/" request = Net::HTTP::Get.new("#{@jenkins_path}/") make_http_request(request) end |
#get_server_date ⇒ String
Obtain the date of the Jenkins server
580 581 582 583 |
# File 'lib/jenkins_api_client/client.rb', line 580 def get_server_date response = get_root response["Date"] end |
#init_update_center ⇒ Object
478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 |
# File 'lib/jenkins_api_client/client.rb', line 478 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 |
#inspect ⇒ Object
Overrides the inspect method to get rid of the credentials being shown in the in interactive IRB sessions and also when the ‘inspect` method is called. Just print the important variables.
248 249 250 251 252 253 254 255 256 257 258 259 |
# File 'lib/jenkins_api_client/client.rb', line 248 def inspect "#<JenkinsApi::Client:0x#{(self.__id__ * 2).to_s(16)}" + " @ssl=#{@ssl.inspect}," + " @log_location=#{@log_location.inspect}," + " @log_level=#{@log_level.inspect}," + " @crumbs_enabled=#{@crumbs_enabled.inspect}," + " @follow_redirects=#{@follow_redirects.inspect}," + " @jenkins_path=#{@jenkins_path.inspect}," + " @timeout=#{@timeout.inspect}>," + " @http_open_timeout=#{@http_open_timeout.inspect}>," + " @http_read_timeout=#{@http_read_timeout.inspect}>" end |
#job ⇒ JenkinsApi::Client::Job
Creates an instance to the Job class by passing a reference to self
183 184 185 |
# File 'lib/jenkins_api_client/client.rb', line 183 def job JenkinsApi::Client::Job.new(self) end |
#node ⇒ JenkinsApi::Client::Node
Creates an instance to the Node class by passing a reference to self
199 200 201 |
# File 'lib/jenkins_api_client/client.rb', line 199 def node JenkinsApi::Client::Node.new(self) end |
#plugin ⇒ JenkinsApi::Client::PluginManager
Creates an instance to the PluginManager by passing a reference to self
224 225 226 |
# File 'lib/jenkins_api_client/client.rb', line 224 def plugin JenkinsApi::Client::PluginManager.new(self) end |
#post_config(url_prefix, xml) ⇒ String
Posts the given xml configuration to the url given
437 438 439 |
# File 'lib/jenkins_api_client/client.rb', line 437 def post_config(url_prefix, xml) post_data(url_prefix, xml, 'application/xml;charset=UTF-8') end |
#post_data(url_prefix, data, content_type) ⇒ Object
445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 |
# File 'lib/jenkins_api_client/client.rb', line 445 def post_data(url_prefix, data, content_type) retries = @crumb_max_retries begin refresh_crumbs request = Net::HTTP::Post.new("#{@jenkins_path}#{url_prefix}") @logger.debug "POST #{url_prefix}" request.body = data request.content_type = content_type if @crumbs_enabled request[@crumb["crumbRequestField"]] = @crumb["crumb"] end response = make_http_request(request) handle_exception(response) 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.) end else raise end end end |
#post_json(url_prefix, json) ⇒ Object
441 442 443 |
# File 'lib/jenkins_api_client/client.rb', line 441 def post_json(url_prefix, json) post_data(url_prefix, json, 'application/json;charset=UTF-8') end |
#queue ⇒ JenkinsApi::Client::BuildQueue
Creates an instance to the BuildQueue by passing a reference to self
215 216 217 |
# File 'lib/jenkins_api_client/client.rb', line 215 def queue JenkinsApi::Client::BuildQueue.new(self) end |
#system ⇒ JenkinsApi::Client::System
Creates an instance to the System class by passing a reference to self
191 192 193 |
# File 'lib/jenkins_api_client/client.rb', line 191 def system JenkinsApi::Client::System.new(self) end |
#to_s ⇒ String
Returns a string representing the class name
240 241 242 |
# File 'lib/jenkins_api_client/client.rb', line 240 def to_s "#<JenkinsApi::Client>" end |
#use_crumbs? ⇒ Boolean
Checks if Jenkins uses crumbs (i.e) the XSS disable option is checked in Jenkins’ security settings
501 502 503 504 |
# File 'lib/jenkins_api_client/client.rb', line 501 def use_crumbs? response = api_get_request("", "tree=useCrumbs") response["useCrumbs"] end |
#use_security? ⇒ Boolean
Checks if Jenkins uses security
510 511 512 513 |
# File 'lib/jenkins_api_client/client.rb', line 510 def use_security? response = api_get_request("", "tree=useSecurity") response["useSecurity"] end |
#user ⇒ JenkinsApi::Client::User
Creates an instance of the User class by passing a reference to self
232 233 234 |
# File 'lib/jenkins_api_client/client.rb', line 232 def user JenkinsApi::Client::User.new(self) end |
#view ⇒ JenkinsApi::Client::View
Creates an instance to the View class by passing a reference to self
207 208 209 |
# File 'lib/jenkins_api_client/client.rb', line 207 def view JenkinsApi::Client::View.new(self) end |