Class: JenkinsApi::Client
- Inherits:
-
Object
- Object
- JenkinsApi::Client
- Defined in:
- lib/jenkins_api_client/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
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
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", "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
0
- 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_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
101 102 103 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 |
# File 'lib/jenkins_api_client/client.rb', line 101 def initialize(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 @log_location = STDOUT unless @log_location @log_level = Logger::INFO unless @log_level @logger = Logger.new(@log_location) @logger.level = @log_level # 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
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 |
# File 'lib/jenkins_api_client/client.rb', line 321 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.info "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
347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 |
# File 'lib/jenkins_api_client/client.rb', line 347 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.info "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
527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 |
# File 'lib/jenkins_api_client/client.rb', line 527 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
511 512 513 514 515 516 517 518 519 520 521 |
# File 'lib/jenkins_api_client/client.rb', line 511 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
574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 |
# File 'lib/jenkins_api_client/client.rb', line 574 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
559 560 561 562 |
# File 'lib/jenkins_api_client/client.rb', line 559 def exec_script(script_text) response = api_post_request('/scriptText', {'script' => script_text}, true) response.body end |
#get_config(url_prefix) ⇒ String
Obtains the configuration of a component from the Jenkins CI server
391 392 393 394 395 396 |
# File 'lib/jenkins_api_client/client.rb', line 391 def get_config(url_prefix) 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") 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
502 503 504 505 |
# File 'lib/jenkins_api_client/client.rb', line 502 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
490 491 492 493 |
# File 'lib/jenkins_api_client/client.rb', line 490 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
305 306 307 308 309 |
# File 'lib/jenkins_api_client/client.rb', line 305 def get_root @logger.info "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
548 549 550 551 |
# File 'lib/jenkins_api_client/client.rb', line 548 def get_server_date response = get_root response["Date"] end |
#init_update_center ⇒ Object
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 |
# File 'lib/jenkins_api_client/client.rb', line 446 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.
239 240 241 242 243 244 245 246 247 248 249 250 |
# File 'lib/jenkins_api_client/client.rb', line 239 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
174 175 176 |
# File 'lib/jenkins_api_client/client.rb', line 174 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
190 191 192 |
# File 'lib/jenkins_api_client/client.rb', line 190 def node JenkinsApi::Client::Node.new(self) end |
#plugin ⇒ JenkinsApi::Client::PluginManager
Creates an instance to the PluginManager by passing a reference to self
215 216 217 |
# File 'lib/jenkins_api_client/client.rb', line 215 def plugin JenkinsApi::Client::PluginManager.new(self) end |
#post_config(url_prefix, xml) ⇒ String
Posts the given xml configuration to the url given
405 406 407 |
# File 'lib/jenkins_api_client/client.rb', line 405 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
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 |
# File 'lib/jenkins_api_client/client.rb', line 413 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.info "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
409 410 411 |
# File 'lib/jenkins_api_client/client.rb', line 409 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
206 207 208 |
# File 'lib/jenkins_api_client/client.rb', line 206 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
182 183 184 |
# File 'lib/jenkins_api_client/client.rb', line 182 def system JenkinsApi::Client::System.new(self) end |
#to_s ⇒ String
Returns a string representing the class name
231 232 233 |
# File 'lib/jenkins_api_client/client.rb', line 231 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
469 470 471 472 |
# File 'lib/jenkins_api_client/client.rb', line 469 def use_crumbs? response = api_get_request("") response["useCrumbs"] end |
#use_security? ⇒ Boolean
Checks if Jenkins uses security
478 479 480 481 |
# File 'lib/jenkins_api_client/client.rb', line 478 def use_security? response = api_get_request("") response["useSecurity"] end |
#user ⇒ JenkinsApi::Client::User
Creates an instance of the User class by passing a reference to self
223 224 225 |
# File 'lib/jenkins_api_client/client.rb', line 223 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
198 199 200 |
# File 'lib/jenkins_api_client/client.rb', line 198 def view JenkinsApi::Client::View.new(self) end |