jenkins2 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89372ed31079640dc0d1e310f3cb279c209846f3
-  data.tar.gz: 2ff0f1d37148a71cede4a61ffd9fb9dca76edaa5
+  metadata.gz: d1608986d87d4133655aed40daf7d52e89b27bfb
+  data.tar.gz: 948685475fb6f4bfed364db6d3692ca159c65ad9
 SHA512:
-  metadata.gz: 28f396b6e2f8dbaf2f2e0f8ff6b222677d0e405b264af0f97c01d8ddd4ea34c3b53577ce555a31f5810b10b4ad47444c741a7a77db578caa773f69ed8f896461
-  data.tar.gz: c53ee77163b15abe3cdc5bc14b24d408d6c51faf8d8b768e8e4f5f499b97db7d420c020a6c4c1bd874eed030568b60ffa6c2292a932bffe41a20bc0ee216b810
+  metadata.gz: eb1ea897fbea4233cf2120577532f96170e3e2dfad99bbba3812c8117757b818d1dc0b3aa6f12c8f8d25122f46204e57c80bb7813fdc2bde72f2f4a5960f8578
+  data.tar.gz: 3918162db471507a88b91718acf48460af711a13790a6211f50a8587900d507f7c57cd4d7f68cc44b32c84e93e4d740bc32f66e5b5df984086a1de121f660aba

data/CHANGELOG.md

@@ -1,13 +1,40 @@
 # Change Log
 
+[jenkins]: https://jenkins.io/download/
+[command-launcher]: https://plugins.jenkins.io/command-launcher
+[cloudbees-folder]: https://plugins.jenkins.io/cloudbees-folder
+[plain-credentials]: https://plugins.jenkins.io/plain-credentials
+[role-strategy]: https://plugins.jenkins.io/role-strategy
+[ssh-credentials]: https://plugins.jenkins.io/ssh-credentials
+
+## [v1.1.0](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v1.1.0) (February 26, 2018)
+
+### Tested With
+
+- [Jenkins][jenkins] 2.89.4
+	- [Command Agent Launcher][command-launcher] 1.2
+	- [Folders][cloudbees-folder] 6.3
+	- [Plain Credentials][plain-credentials] 1.4
+	- [Role-based Authorization Strategy][role-strategy] 2.7.0
+	- [SSH Credentials][ssh-credentials] 1.13
+
+### Enhancements
+
+- Can manage folders with [Folders][cloudbees-folder] plugin.
+	- Can create/show/update/delete jobs inside nested folders.
+	- Can create/show/update/delete credentials inside nested folders.
+- Can manage roles/users/permissions in [Role-based Authorization Strategy][role-strategy] plugin.
+	- Can list/create/delete roles.
+	- Can assign/unassign roles to/from users.
+
 ## [v1.0.0](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v1.0.0) (February 19, 2018)
 
 ### Tested With
 
-- Jenkins 2.89.4
-	- ssh-credentials 1.13
-	- plain-credentials 1.4
-	- command-launcher 1.2
+- [Jenkins][jenkins] 2.89.4
+	- [Command Agent Launcher][command-launcher] 1.2
+	- [Plain Credentials][plain-credentials] 1.4
+	- [SSH Credentials][ssh-credentials] 1.13
 
 ### Enhancements
 

data/lib/jenkins2/api.rb

@@ -8,6 +8,7 @@ require_relative 'api/credentials'
 require_relative 'api/computer'
 require_relative 'api/job'
 require_relative 'api/plugins'
+require_relative 'api/role_strategy'
 require_relative 'api/root'
 require_relative 'api/user'
 require_relative 'api/view'
@@ -18,6 +19,7 @@ module Jenkins2
 		include Computer
 		include Job
 		include Plugins
+		include RoleStrategy
 		include Root
 		include User
 		include View

data/lib/jenkins2/api/job.rb

@@ -4,7 +4,14 @@ require_relative 'rud'
 
 module Jenkins2
 	class API
+		# Allows manipulating jobs (projects). Supports cloudbees-folder plugin - i.e. nested jobs.
 		module Job
+			# Step into proxy for managing jobs.
+			# ==== Parameters:
+			# +name+:: Job name
+			# +params+:: Key-value parameters. They will be added as URL parameters to request.
+			# ==== Returns:
+			# A Jenkins2::API::Job::Proxy object
 			def job(name, **params)
 				proxy = Proxy.new connection, 'job', params
 				proxy.id = name
@@ -15,24 +22,45 @@ module Jenkins2
 				attr_accessor :id
 				include ::Jenkins2::API::RUD
 
+				# Create a new job from config.xml.
+				# ==== Parameters:
+				# +config_xml+:: config.xml of new job as string.
+				# ==== Returns:
+				# True on success
 				def create(config_xml)
-					connection.post('createItem', config_xml, name: id) do |req|
+					path = ::File.join(::File.dirname(@path), 'createItem')
+					connection.post(path, config_xml, name: id) do |req|
 						req['Content-Type'] = 'text/xml'
 					end.code == '200'
 				end
 
+				# Create a new job by copying another one.
+				# ==== Parameters:
+				# +from+:: Job name to copy new job from.
+				# ==== Returns:
+				# True on success.
 				def copy(from)
-					connection.post('createItem', nil, name: id, from: from, mode: 'copy').code == '302'
+					path = ::File.join(::File.dirname(@path), 'createItem')
+					connection.post(path, nil, name: id, from: from, mode: 'copy').code == '302'
 				end
 
+				# Disable a job, restrict all builds of the job from now on.
+				# ==== Returns:
+				# True on success.
 				def disable
 					connection.post(build_path('disable')).code == '302'
 				end
 
+				# Enable job, allow building the job. Cancels previously issued "disable".
+				# ==== Returns:
+				# True on success.
 				def enable
 					connection.post(build_path('enable')).code == '302'
 				end
 
+				# Schedule a job build. Allows to pass build parameters, if required.
+				# ==== Returns:
+				# True on success.
 				def build(build_parameters={})
 					if build_parameters.empty?
 						connection.post(build_path('build'))
@@ -44,6 +72,29 @@ module Jenkins2
 				def polling
 					connection.post(build_path('polling')).code == '302'
 				end
+
+				# cloudbees-folder plugin provides special type of job - folder. So now we can have
+				# nested jobs. This methods allows to go 1 job deeper.
+				# ==== Parameters:
+				# +name+:: Job name
+				# +params+:: Key-value parameters. They will be added as URL parameters to request.
+				# ==== Returns:
+				# A new Jenkins2::API::Job::Proxy object
+				def job(name, **params)
+					proxy = Proxy.new connection, build_path('job'), params
+					proxy.id = name
+					proxy
+				end
+
+				# cloudbees-folder plugin provides special type of job - folder. You can now create
+				# credentials inside particular folder.
+				# ==== Parameters:
+				# +params+:: Key-value parameters. They will be added as URL parameters to request.
+				# ==== Returns:
+				# A new Jenkins2::API::Credentials::Proxy object
+				def credentials(params={})
+					::Jenkins2::API::Credentials::Proxy.new connection, build_path('credentials'), params
+				end
 			end
 		end
 	end

data/lib/jenkins2/api/role_strategy.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Jenkins2
+	class API
+		# Provides support for role-strategy plugin.
+		# Allows creating, deleting, assigning, unassigning and listing roles.
+		module RoleStrategy
+			module RoleType
+				GLOBAL = 'globalRoles'
+				PROJECT = 'projectRoles'
+				SLAVE = 'slaveRoles'
+			end
+
+			# Step into proxy for managing roles in role-strategy.
+			# ==== Returns:
+			# A proxy object that enables different operations on roles.
+			def roles
+				Proxy.new connection, 'role-strategy/strategy'
+			end
+
+			class Proxy < ::Jenkins2::ResourceProxy
+				# Get existing roles and users assigned to them.
+				# *Returns*:: Hash where keys are roles, and values are arrays of users assigned to role.
+				def list
+					::JSON.parse(connection.get(build_path('getAllRoles')).body,
+						object_class: ::OpenStruct).to_h
+				end
+
+				# Create a role in role-strategy
+				# ==== Parameters:
+				# +role+:: Role name.
+				# +type+:: Role type. Use RoleType enum values.
+				# +permissions+:: Array of permission ids. Default is - no permissions.
+				# +pattern+:: Slave or project pattern. Ignored for global roles.
+				# ==== Returns:
+				# True on success
+				def create(role:, type:, permissions: [], pattern: nil)
+					connection.post(build_path('addRole'), nil, roleName: role, type: type,
+						permissionIds: (permissions || []).join(','), pattern: pattern, overwrite: false).
+						code == '200'
+				end
+
+				# Delete role(s) in role-strategy
+				# ==== Parameters:
+				# +role+:: Role name or array of role names.
+				# +type+:: Role type. Use RoleType enum values.
+				# ==== Returns:
+				# True on success
+				def delete(role:, type:)
+					connection.post(build_path('removeRoles'), nil, roleNames: [role].flatten.join(','),
+						type: type).code == '200'
+				end
+
+				# Assign role to user in role-strategy
+				# ==== Parameters:
+				# +role+:: Role name.
+				# +type+:: Role type. Use RoleType enum values.
+				# +rsuser+:: Username.
+				# ==== Returns:
+				# True on success
+				def assign(role:, type:, rsuser:)
+					connection.post(build_path('assignRole'), nil, roleName: role, type: type, sid: rsuser).
+						code == '200'
+				end
+
+				# Unassign role from user in role-strategy
+				# ==== Parameters:
+				# +role+:: Role name.
+				# +type+:: Role type. Use RoleType enum values.
+				# +rsuser+:: Username.
+				# ==== Returns:
+				# True on success
+				def unassign(role:, type:, rsuser:)
+					connection.post(build_path('unassignRole'), nil, roleName: role, type: type, sid: rsuser).
+						code == '200'
+				end
+
+				# Unassign all roles from user in role-strategy
+				# ==== Parameters:
+				# +type+:: Role type. Use RoleType enum values.
+				# +rsuser+:: Username.
+				# ==== Returns:
+				# True on success
+				def unassign_all(type:, rsuser:)
+					connection.post(build_path('deleteSid'), nil, type: type, sid: rsuser).code == '200'
+				end
+			end
+		end
+	end
+end

data/lib/jenkins2/cli.rb

@@ -5,7 +5,9 @@ require 'yaml'
 
 require_relative 'version'
 require_relative 'cli/credentials'
+require_relative 'cli/job'
 require_relative 'cli/nodes'
+require_relative 'cli/role_strategy'
 require_relative 'cli/root'
 require_relative 'cli/plugins'
 require_relative 'cli/user'

data/lib/jenkins2/cli/credentials.rb

@@ -153,7 +153,7 @@ module Jenkins2
 
 		class ListCredentials < CLI
 			def self.description
-				'Lists credentials in a specific store.'
+				'List credentials in a specific store.'
 			end
 
 			def add_options

data/lib/jenkins2/cli/job.rb

@@ -2,46 +2,190 @@
 
 module Jenkins2
 	class CLI
-		class ListJobs < CLI
+		# class Build < CLI
+		# 	# TODO: implement
+		# end
+
+		class CopyJob < CLI
 			def self.description
-				'Lists all jobs in a specific view or item group.'
+				'Copy a job.'
 			end
 
 			private
 
 			def add_options
-				parser.separator 'Optional arguments:'
-				parser.on '-n', '--name NAME', 'Name of the view. Default - all' do |n|
+				parser.separator 'Mandatory arguments:'
+				parser.on '-f', '--from NAME', 'Name of the job to copy from.' do |f|
+					options[:from] = f
+				end
+				parser.on '-n', '--name NAME', 'Name of the new job.' do |n|
 					options[:name] = n
 				end
 			end
 
-			def run; end
+			def mandatory_arguments
+				super + %i[name from]
+			end
+
+			def run
+				jc.job(options[:name]).copy(options[:from])
+			end
 		end
 
-		class CopyJob < CLI
+		class CreateJob < CLI
 			def self.description
-				'Copies a job.'
+				'Create a new job by reading stdin as an XML configuration.'
 			end
 
 			private
 
 			def add_options
 				parser.separator 'Mandatory arguments:'
-				parser.on '-f', '--from NAME', 'Name of the job to copy.' do |f|
-					options[:from] = f
+				parser.on '-n', '--name NAME', 'Name of the new job.' do |n|
+					options[:name] = n
 				end
-				parser.on '-n', '--name NAME', 'Name of the new job, to be created.' do |n|
+			end
+
+			def mandatory_arguments
+				super + %i[name]
+			end
+
+			def run
+				jc.job(options[:name]).create($stdin.read)
+			end
+		end
+
+		class DeleteJob < CLI
+			def self.description
+				'Delete a job.'
+			end
+
+			private
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '-n', '--name NAME', 'Name of the job.' do |n|
 					options[:name] = n
 				end
 			end
 
 			def mandatory_arguments
-				super + %i[name from]
+				super + %i[name]
 			end
 
 			def run
-				jc.job(options[:name]).copy(options[:from])
+				jc.job(options[:name]).delete
+			end
+		end
+
+		class DisableJob < CLI
+			def self.description
+				'Disable a job, restrict all builds of the job from now on.'
+			end
+
+			private
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '-n', '--name NAME', 'Name of the job.' do |n|
+					options[:name] = n
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[name]
+			end
+
+			def run
+				jc.job(options[:name]).disable
+			end
+		end
+
+		class EnableJob < CLI
+			def self.description
+				'Enable job, allow building the job. Cancels previously issued "disable-job".'
+			end
+
+			private
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '-n', '--name NAME', 'Name of the job.' do |n|
+					options[:name] = n
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[name]
+			end
+
+			def run
+				jc.job(options[:name]).enable
+			end
+		end
+
+		class GetJob < CLI
+			def self.description
+				'Dump the job definition XML to stdout.'
+			end
+
+			private
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '-n', '--name NAME', 'Name of the job.' do |n|
+					options[:name] = n
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[name]
+			end
+
+			def run
+				jc.job(options[:name]).config_xml
+			end
+		end
+
+		class ListJobs < CLI
+			def self.description
+				'List all jobs in a specific view or item group.'
+			end
+
+			private
+
+			def add_options
+				parser.separator 'Optional arguments:'
+				parser.on '--view VIEW', 'Name of the view. Default - All.' do |v|
+					options[:view] = v
+				end
+			end
+
+			def run
+				jc.view(options[:view] || 'All').jobs.collect(&:name).join("\n")
+			end
+		end
+
+		class UpdateJob < CLI
+			def self.description
+				'Update the job definition XML from stdin. The opposite of the "get-job" command.'
+			end
+
+			private
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '-n', '--name NAME', 'Name of the job.' do |n|
+					options[:name] = n
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[name]
+			end
+
+			def run
+				jc.job(options[:name]).update($stdin.read)
 			end
 		end
 	end

data/lib/jenkins2/cli/nodes.rb

@@ -24,7 +24,7 @@ module Jenkins2
 
 		class CreateNode < CLI
 			def self.description
-				'Creates a new node by reading stdin for an XML configuration.'
+				'Create a new node by reading stdin for an XML configuration.'
 			end
 
 			def add_options
@@ -42,7 +42,7 @@ module Jenkins2
 
 		class DeleteNode < CLI
 			def self.description
-				'Deletes node(s).'
+				'Delete node(s).'
 			end
 
 			def add_options
@@ -61,7 +61,7 @@ module Jenkins2
 
 		class DisconnectNode < CLI
 			def self.description
-				'Disconnects node(s).'
+				'Disconnect node(s).'
 			end
 
 			def add_options
@@ -86,7 +86,7 @@ module Jenkins2
 
 		class GetNode < CLI
 			def self.description
-				'Dumps the node definition XML to stdout.'
+				'Dump the node definition XML to stdout.'
 			end
 
 			def add_options
@@ -103,7 +103,7 @@ module Jenkins2
 
 		class ListNode < CLI
 			def self.description
-				'Outputs the node list.'
+				'Output the node list.'
 			end
 
 			def run
@@ -113,7 +113,7 @@ module Jenkins2
 
 		class ListOnlineNode < CLI
 			def self.description
-				'Outputs the online node list.'
+				'Output the online node list.'
 			end
 
 			def run
@@ -167,7 +167,7 @@ module Jenkins2
 
 		class UpdateNode < CLI
 			def self.description
-				'Updates the node definition XML from stdin. The opposite of the get-node command.'
+				'Update the node definition XML from stdin. The opposite of the get-node command.'
 			end
 
 			def add_options

data/lib/jenkins2/cli/plugins.rb

@@ -6,7 +6,7 @@ module Jenkins2
 	class CLI
 		class InstallPlugin < CLI
 			def self.description
-				'Installs a plugin either from a file, an URL, standard input or from update center.'
+				'Install a plugin either from a file, an URL, standard input or from update center.'
 			end
 
 			private
@@ -39,7 +39,7 @@ module Jenkins2
 
 		class ListPlugins < CLI
 			def self.description
-				'Lists all installed plugins.'
+				'List all installed plugins.'
 			end
 
 			private
@@ -53,7 +53,7 @@ module Jenkins2
 
 		class UninstallPlugin < CLI
 			def self.description
-				'Uninstalls a plugin.'
+				'Uninstall a plugin.'
 			end
 
 			private

data/lib/jenkins2/cli/role_strategy.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Jenkins2
+	class CLI
+		# Provides list-roles command in CLI. Requires role-strategy plugin enabled.
+		class ListRoles < CLI
+			def self.description
+				'List all global roles in role-strategy plugin.'
+			end
+
+			def run
+				jc.roles.list.collect do |role, users|
+					"#{role}: #{users.join(',')}"
+				end.join("\n")
+			end
+		end
+
+		# Provides create-role command in CLI. Requires role-strategy plugin enabled.
+		class CreateRole < CLI
+			def self.description
+				'Create a role in role-strategy plugin.'
+			end
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '--role ROLE', 'Role name.' do |r|
+					options[:role] = r
+				end
+				parser.on '--type TYPE', 'Role type. One of: globalRoles, projectRoles, slaveRoles.' do |t|
+					options[:type] = t
+				end
+				parser.separator 'Optional arguments:'
+				parser.on '--permissions X,Y,..', Array, 'Comma-separated list of permissions.' do |p|
+					options[:permissions] = p
+				end
+				parser.on '--pattern PATTERN', 'Slave or project pattern. Ignored for global roles.' do |p|
+					options[:pattern] = p
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[role type]
+			end
+
+			def run
+				jc.roles.create(role: options[:role], type: options[:type],
+					permissions: options[:permissions], pattern: options[:pattern])
+			end
+		end
+
+		# Provides delete-role command in CLI. Requires role-strategy plugin enabled.
+		class DeleteRoles < CLI
+			def self.description
+				'Delete role(s) in role-strategy plugin.'
+			end
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '--role X,Y,..', Array, 'Role names.' do |r|
+					options[:role] = r
+				end
+				parser.on '--type TYPE', 'Role type. One of: globalRoles, projectRoles, slaveRoles.' do |t|
+					options[:type] = t
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[role type]
+			end
+
+			def run
+				jc.roles.delete(role: options[:role], type: options[:type])
+			end
+		end
+
+		# Provides assign-role command in CLI. Requires role-strategy plugin enabled.
+		class AssignRole < CLI
+			def self.description
+				'Assign role to user in role-strategy plugin.'
+			end
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '--role ROLE', 'Role name.' do |r|
+					options[:role] = r
+				end
+				parser.on '--type TYPE', 'Role type. One of: globalRoles, projectRoles, slaveRoles.' do |t|
+					options[:type] = t
+				end
+				parser.on '--rsuser USER', 'Username.' do |u|
+					options[:rsuser] = u
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[role type rsuser]
+			end
+
+			def run
+				jc.roles.assign(role: options[:role], type: options[:type], rsuser: options[:rsuser])
+			end
+		end
+
+		# Provides unassign-role command in CLI. Requires role-strategy plugin enabled.
+		class UnassignRole < CLI
+			def self.description
+				'Unassign role from user in role-strategy plugin.'
+			end
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '--role ROLE', 'Role name.' do |r|
+					options[:role] = r
+				end
+				parser.on '--type TYPE', 'Role type. One of: globalRoles, projectRoles, slaveRoles.' do |t|
+					options[:type] = t
+				end
+				parser.on '--rsuser USER', 'Username.' do |u|
+					options[:rsuser] = u
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[role type rsuser]
+			end
+
+			def run
+				jc.roles.unassign(role: options[:role], type: options[:type], rsuser: options[:rsuser])
+			end
+		end
+
+		# Provides unassign-all-roles command in CLI. Requires role-strategy plugin enabled.
+		class UnassignAllRoles < CLI
+			def self.description
+				'Unassign all roles from user in role-strategy plugin.'
+			end
+
+			def add_options
+				parser.separator 'Mandatory arguments:'
+				parser.on '--type TYPE', 'Role type. One of: globalRoles, projectRoles, slaveRoles.' do |t|
+					options[:type] = t
+				end
+				parser.on '--rsuser USER', 'Username.' do |u|
+					options[:rsuser] = u
+				end
+			end
+
+			def mandatory_arguments
+				super + %i[type rsuser]
+			end
+
+			def run
+				jc.roles.unassign_all(type: options[:type], rsuser: options[:rsuser])
+			end
+		end
+	end
+end

data/lib/jenkins2/cli/user.rb

@@ -4,7 +4,7 @@ module Jenkins2
 	class CLI
 		class WhoAmI < CLI
 			def self.description
-				'Reports your credentials.'
+				'Report your credentials.'
 			end
 
 			def run

data/lib/jenkins2/cli/view.rb

@@ -4,7 +4,7 @@ module Jenkins2
 	class CLI
 		class CreateView < CLI
 			def self.description
-				'Creates a new view by reading stdin as a XML configuration.'
+				'Create a new view by reading stdin as an XML configuration.'
 			end
 
 			private
@@ -52,7 +52,7 @@ module Jenkins2
 
 		class GetView < CLI
 			def self.description
-				'Dumps the view definition XML to stdout.'
+				'Dump the view definition XML to stdout.'
 			end
 
 			private
@@ -75,7 +75,7 @@ module Jenkins2
 
 		class UpdateView < CLI
 			def self.description
-				'Updates the view definition XML from stdin. The opposite of the get-view command.'
+				'Update the view definition XML from stdin. The opposite of the get-view command.'
 			end
 
 			private
@@ -98,7 +98,7 @@ module Jenkins2
 
 		class AddJobToView < CLI
 			def self.description
-				'Adds jobs to view.'
+				'Add jobs to view.'
 			end
 
 			private
@@ -126,7 +126,7 @@ module Jenkins2
 
 		class RemoveJobFromView < CLI
 			def self.description
-				'Removes jobs from view.'
+				'Remove jobs from view.'
 			end
 
 			private

data/lib/jenkins2/connection.rb

@@ -5,17 +5,17 @@ require 'openssl'
 require 'json'
 
 module Jenkins2
+	# Creates a "connection" to Jenkins and makes all the HTTP requests.
 	class Connection
-		# Creates a "connection" to Jenkins.
-		# Parameter:
+		# ==== Parameters:
 		# +server+:: Jenkins Server URL.
-		def initialize(url)
-			@server = url
+		def initialize(server)
+			@server = server
 			@crumb = nil
 		end
 
 		# Add basic auth to existing connection. Returns self.
-		# Parameters:
+		# ==== Parameters:
 		# +user+:: Jenkins API user.
 		# +key+:: Jenkins API key.
 		def basic_auth(user, key)
@@ -23,23 +23,58 @@ module Jenkins2
 			self
 		end
 
+		# Appends api/json to passed +path+ and makes GET request. Yields request, if block given.
+		# ==== Parameters:
+		# +path+:: Path to make request to. "api/json" will be appened to the end.
+		# +params+:: Parameter hash. It will be converted to URL parameters.
+		# +&block+:: Yields Net::HTTP::Get request.
+		# ==== Returns:
+		# Net::HTTP::Response
 		def get_json(path, params={}, &block)
 			get(::File.join(path, 'api/json'), params, &block)
 		end
 
+		# Makes GET request. Yields request, if block given.
+		# ==== Parameters:
+		# +path+:: Path to make request to.
+		# +params+:: Parameter hash. It will be converted to URL parameters.
+		# +&block+:: Yields Net::HTTP::Get request.
+		# ==== Returns:
+		# Net::HTTP::Response
 		def get(path, params={}, &block)
 			api_request(Net::HTTP::Get, build_uri(path, params), &block)
 		end
 
+		# Makes HEAD request. Yields request, if block given.
+		# ==== Parameters:
+		# +path+:: Path to make request to.
+		# +params+:: Parameter hash. It will be converted to URL parameters.
+		# +&block+:: Yields Net::HTTP::Head request.
+		# ==== Returns:
+		# Net::HTTP::Response
 		def head(path, params={}, &block)
 			api_request(Net::HTTP::Head, build_uri(path, params), &block)
 		end
 
+		# Makes POST request. Yields request, if block given.
+		# ==== Parameters:
+		# +path+:: Path to make request to.
+		# +body+:: Post request body.
+		# +params+:: Parameter hash. It will be converted to URL parameters.
+		# +&block+:: Yields Net::HTTP::Post request.
+		# ==== Returns:
+		# Net::HTTP::Response
 		def post(path, body=nil, params={}, &block)
 			headers = { 'Content-Type' => 'application/x-www-form-urlencoded' }
 			api_request(Net::HTTP::Post, build_uri(path, params), body, headers, &block)
 		end
 
+		# Builds URI. Appends parameters.
+		# ==== Parameters:
+		# +relative_or_absolute+:: Absolute URI or URI path. If path, Jenkins server will be prepended.
+		# +params+:: Parameter hash. It will be converted to URL parameters.
+		# ==== Returns:
+		# Absolute URI with parameters
 		def build_uri(relative_or_absolute, params={})
 			result = ::URI.parse relative_or_absolute
 			result = ::URI.parse ::File.join(@server.to_s, relative_or_absolute) unless result.absolute?
@@ -47,6 +82,15 @@ module Jenkins2
 			result
 		end
 
+		# Makes request, using +method+ provided. Yields request, if block given. Retries request with
+		# updated crumbs, if "No valid crumbs" error received.
+		# ==== Parameters:
+		# +method+:: Net:HTTP class to instantiate (e.g. Net::HTTP::Post, Net::HTTP::Get)
+		# +url+:: Absolute URI to make request to.
+		# +body+:: Request body if applicable.
+		# +headers+:: Request headers.
+		# ==== Returns:
+		# Net::HTTP::Response
 		def api_request(method, uri, body=nil, headers=nil)
 			req = method.new(URI(uri), headers)
 			req.basic_auth @user, @key if @user and @key
@@ -67,10 +111,19 @@ module Jenkins2
 			end
 		end
 
+		# Updates crumbs for current connection. These crumbs will be submitted with all requests.
+		# ==== Returns:
+		# Crumbs as hash
 		def update_crumbs
 			@crumb = JSON.parse(get_json('/crumbIssuer').body)
 		end
 
+		# Handles Jenkins response. Tries parsing error messages in some cases, then reraises
+		# exception from Jenkins2 namespace.
+		# ==== Returns:
+		# HTTPResponse
+		# ==== Raises:
+		# Different Net::HTTP and Jenkins2 errors.
 		def handle_response(response)
 			Log.debug{ "Response: #{response.code}, #{response.body}" }
 			case response
@@ -80,6 +133,8 @@ module Jenkins2
 				raise Jenkins2::BadRequestError, response
 			when Net::HTTPServiceUnavailable
 				raise Jenkins2::ServiceUnavailableError, response
+			when Net::HTTPInternalServerError
+				raise Jenkins2::InternalServerError, response
 			when Net::HTTPClientError, Net::HTTPServerError # 4XX, 5XX
 				response.value
 			else

data/lib/jenkins2/errors.rb

@@ -29,6 +29,17 @@ module Jenkins2
 		end
 	end
 
+	class InternalServerError < Net::HTTPError
+		def initialize(res)
+			case res.body
+			when %r{<div id="error-description">(.+)</div>}m
+				super(Regexp.last_match(1), res)
+			else
+				res.value
+			end
+		end
+	end
+
 	class NoValidCrumbMatcher
 		def self.===(exception)
 			exception.message == '403 "No valid crumb was included in the request"'

data/lib/jenkins2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jenkins2
-	VERSION = '1.0.0'
+	VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jenkins2
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Juri Timošin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-19 00:00:00.000000000 Z
+date: 2018-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ci_reporter_minitest
@@ -98,6 +98,7 @@ files:
 - lib/jenkins2/api/credentials.rb
 - lib/jenkins2/api/job.rb
 - lib/jenkins2/api/plugins.rb
+- lib/jenkins2/api/role_strategy.rb
 - lib/jenkins2/api/root.rb
 - lib/jenkins2/api/rud.rb
 - lib/jenkins2/api/user.rb
@@ -107,6 +108,7 @@ files:
 - lib/jenkins2/cli/job.rb
 - lib/jenkins2/cli/nodes.rb
 - lib/jenkins2/cli/plugins.rb
+- lib/jenkins2/cli/role_strategy.rb
 - lib/jenkins2/cli/root.rb
 - lib/jenkins2/cli/user.rb
 - lib/jenkins2/cli/view.rb