Updating the runners API (#582)

* Updating the runners API

* Fixing rubocop offences

lib/gitlab/client/runners.rb

@@ -9,11 +9,13 @@ module Runners
     #
     # @example
     #   Gitlab.runners
-    #   Gitlab.runners(:active)
-    #   Gitlab.runners(:paused)
+    #   Gitlab.runners(type: 'instance_type', status: 'active')
+    #   Gitlab.runners(tag_list: 'tag1,tag2')
     #
     # @param  [Hash] options A customizable set of options.
-    # @option options [String] :scope The scope of specific runners to show, one of: active, paused, online; showing all runners if none provided
+    # @option options [String] :type(optional) The type of runners to show, one of: instance_type, group_type, project_type
+    # @option options [String] :status(optional) The status of runners to show, one of: active, paused, online, offline
+    # @option options [String] :tag_list(optional) List of the runners tags (separated by comma)
     # @return [Array<Gitlab::ObjectifiedHash>]
     def runners(options = {})
       get('/runners', query: options)
@@ -24,9 +26,13 @@ def runners(options = {})
     #
     # @example
     #   Gitlab.all_runners
+    #   Gitlab.all_runners(type: 'instance_type', status: 'active')
+    #   Gitlab.all_runners(tag_list: 'tag1,tag2')
     #
     # @param  [Hash] options A customizable set of options.
-    # @option options [String] :scope The scope of runners to show, one of: specific, shared, active, paused, online; showing all runners if none provided
+    # @option options [String] :type(optional) The type of runners to show, one of: instance_type, group_type, project_type
+    # @option options [String] :status(optional) The status of runners to show, one of: active, paused, online, offline
+    # @option options [String] :tag_list(optional) List of the runners tags (separated by comma)
     # @return [Array<Gitlab::ObjectifiedHash>]
     def all_runners(options = {})
       get('/runners/all', query: options)
@@ -50,15 +56,19 @@ def runner(id)
     # @example
     #   Gitlab.update_runner(42, { description: 'Awesome runner' })
     #   Gitlab.update_runner(42, { active: false })
-    #   Gitlab.update_runner(42, { tag_list: [ 'awesome', 'runner' ] })
     #
     # @param  [Integer, String] id The ID of a runner
     # @param  [Hash] options A customizable set of options.
-    # @option options [String] :active The state of a runner; can be set to true or false.
-    # @option options [String] :tag_list The list of tags for a runner; put array of tags, that should be finally assigned to a runner
+    # @option options [String] :description(optional) The description of a runner
+    # @option options [Boolean] :active(optional) The state of a runner; can be set to true or false
+    # @option options [String] :tag_list(optional) The list of tags for a runner; put array of tags, that should be finally assigned to a runner(separated by comma)
+    # @option options [Boolean] :run_untagged(optional) Flag indicating the runner can execute untagged jobs
+    # @option options [Boolean] :locked(optional) Flag indicating the runner is locked
+    # @option options [String] :access_level(optional) The access_level of the runner; not_protected or ref_protected
+    # @option options [Integer] :maximum_timeout(optional) Maximum timeout set when this runner will handle the job
     # @return <Gitlab::ObjectifiedHash>
     def update_runner(id, options = {})
-      put("/runners/#{id}", query: options)
+      put("/runners/#{id}", body: options)
     end
 
     # Remove a runner.
@@ -68,19 +78,23 @@ def update_runner(id, options = {})
     #   Gitlab.delete_runner(42)
     #
     # @param  [Integer, String] id The ID of a runner
-    # @return <Gitlab::ObjectifiedHash>
+    # @return [nil] This API call returns an empty response body.
     def delete_runner(id)
       delete("/runners/#{id}")
     end
 
-    # Gets a list of Jobs for a Runner
+    # List jobs that are being processed or were processed by specified runner.
     #
     # @example
     #   Gitlab.runner_jobs(1)
+    #   Gitlab.runner_jobs(1, status: 'success')
+    #   Gitlab.runner_jobs(1, sort: 'desc')
     #
     # @param  [Integer] id The ID of a runner.
     # @param  [Hash] options A customizable set of options.
-    # @option options [String] :status Status of the job; one of: running, success, failed, canceled
+    # @option options [String] :status(optional) Status of the job; one of: running, success, failed, canceled
+    # @option options [String] :order_by(optional) Order jobs by id.
+    # @option options [String] :sort(optional) Sort jobs in asc or desc order (default: desc)
     # @return [Array<Gitlab::ObjectifiedHash>]
     def runner_jobs(runner_id, options = {})
       get("/runners/#{url_encode runner_id}/jobs", query: options)
@@ -91,11 +105,17 @@ def runner_jobs(runner_id, options = {})
     #
     # @example
     #   Gitlab.project_runners(42)
+    #   Gitlab.project_runners(42, type: 'instance_type', status: 'active')
+    #   Gitlab.project_runners(42, tag_list: 'tag1,tag2')
     #
     # @param  [Integer, String] id The ID or name of a project.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :type(optional) The type of runners to show, one of: instance_type, group_type, project_type
+    # @option options [String] :status(optional) The status of runners to show, one of: active, paused, online, offline
+    # @option options [String] :tag_list(optional) List of the runners tags (separated by comma)
     # @return [Array<Gitlab::ObjectifiedHash>]
-    def project_runners(project_id)
-      get("/projects/#{url_encode project_id}/runners")
+    def project_runners(project_id, options = {})
+      get("/projects/#{url_encode project_id}/runners", query: options)
     end
 
     # Enable an available specific runner in the project.
@@ -125,21 +145,39 @@ def project_disable_runner(id, runner_id)
       delete("/projects/#{url_encode id}/runners/#{runner_id}")
     end
 
+    # List all runners (specific and shared) available in the group as well its ancestor groups. Shared runners are listed if at least one shared runner is defined.
+    # @see https://docs.gitlab.com/ee/api/runners.html#list-groups-runners
+    #
+    # @example
+    #   Gitlab.group_runners(9)
+    #   Gitlab.group_runners(9, type: 'instance_type', status: 'active')
+    #   Gitlab.group_runners(9, tag_list: 'tag1,tag2')
+    #
+    # @param  [Integer, String] id The ID or name of a project.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :type(optional) The type of runners to show, one of: instance_type, group_type, project_type
+    # @option options [String] :status(optional) The status of runners to show, one of: active, paused, online, offline
+    # @option options [String] :tag_list(optional) List of the runners tags (separated by comma)
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def group_runners(group, options = {})
+      get("/groups/#{url_encode group}/runners", query: options)
+    end
+
     # Register a new Runner for the instance.
     #
     # @example
     #   Gitlab.register_runner('9142c16ea169eaaea3d752313a434a6e')
     #   Gitlab.register_runner('9142c16ea169eaaea3d752313a434a6e', description: 'Some Description', active: true, locked: false)
     #
-    # @param  [String] token Registration token.
+    # @param  [String] token(required) Registration token.
     # @param  [Hash] options A customizable set of options.
-    # @option options [String] :description Runner description.
-    # @option options [Hash] :info Runner metadata.
-    # @option options [Boolean] :active Whether the Runner is active.
-    # @option options [Boolean] :locked Whether the Runner should be locked for current project.
-    # @option options [Boolean] :run_untagged Whether the Runner should handle untagged jobs.
-    # @option options [Array<String>] :tag_list List of Runner tags.
-    # @option options [Integer] :maximum_timeout Maximum timeout set when this Runner will handle the job.
+    # @option options [String] :description(optional) Runner description.
+    # @option options [Hash] :info(optional) Runner metadata.
+    # @option options [Boolean] :active(optional) Whether the Runner is active.
+    # @option options [Boolean] :locked(optional) Whether the Runner should be locked for current project.
+    # @option options [Boolean] :run_untagged(optional) Whether the Runner should handle untagged jobs.
+    # @option options [Array<String>] :tag_list(optional) List of Runner tags.
+    # @option options [Integer] :maximum_timeout(optional) Maximum timeout set when this Runner will handle the job.
     # @return <Gitlab::ObjectifiedHash> Response against runner registration
     def register_runner(token, options = {})
       body = { token: token }.merge(options)

lib/gitlab/help.rb

@@ -74,14 +74,14 @@ def actions_table(topic = nil)
     # Returns full namespace of a command (e.g. Gitlab::Client::Branches.cmd)
     def namespace(cmd)
       method_owners.select { |method| method[:name] == cmd }
-                   .map { |method| method[:owner] + '.' + method[:name] }
+                   .map { |method| "#{method[:owner]}.#{method[:name]}" }
                    .shift
     end
 
     # Massage output from 'ri'.
     def change_help_output!(cmd, output_str)
       output_str = +output_str
-      output_str.gsub!(/#{cmd}\((.*?)\)/m, cmd + ' \1')
+      output_str.gsub!(/#{cmd}\((.*?)\)/m, "#{cmd} \1")
       output_str.gsub!(/,\s*/, ' ')
 
       # Ensure @option descriptions are on a single line

spec/fixtures/group_runners.json

@@ -0,0 +1,32 @@
+[
+  {
+    "id": 3,
+    "description": "Shared",
+    "ip_address": "127.0.0.1",
+    "active": true,
+    "is_shared": true,
+    "name": "gitlab-runner",
+    "online": null,
+    "status": "not_connected"
+  },
+  {
+    "id": 6,
+    "description": "Test",
+    "ip_address": "127.0.0.1",
+    "active": true,
+    "is_shared": true,
+    "name": "gitlab-runner",
+    "online": false,
+    "status": "offline"
+  },
+  {
+    "id": 8,
+    "description": "Test 2",
+    "ip_address": "127.0.0.1",
+    "active": true,
+    "is_shared": false,
+    "name": "gitlab-runner",
+    "online": null,
+    "status": "not_connected"
+  }
+]

spec/gitlab/cli_spec.rb

@@ -99,7 +99,7 @@
       end
 
       it 'renders output as json' do
-        expect(JSON.parse(@output)['result']).to eq(JSON.parse(File.read(File.dirname(__FILE__) + '/../fixtures/user.json')))
+        expect(JSON.parse(@output)['result']).to eq(JSON.parse(File.read("#{File.dirname(__FILE__)}/../fixtures/user.json")))
         expect(JSON.parse(@output)['cmd']).to eq('Gitlab.user')
       end
     end

spec/gitlab/client/runners_spec.rb

@@ -8,7 +8,7 @@
       stub_get('/runners', 'runners')
     end
 
-    context 'without scope' do
+    context 'without extra queries' do
       before do
         @runner = Gitlab.runners
       end
@@ -24,14 +24,14 @@
       end
     end
 
-    context 'with scope' do
+    context 'with queries' do
       before do
-        stub_get('/runners?scope=online', 'runners')
-        @runner = Gitlab.runners(scope: :online)
+        stub_get('/runners?type=instance_type', 'runners')
+        @runner = Gitlab.runners(type: :instance_type)
       end
 
       it 'gets the correct resource' do
-        expect(a_get('/runners').with(query: { scope: :online })).to have_been_made
+        expect(a_get('/runners').with(query: { type: :instance_type })).to have_been_made
       end
 
       it 'returns a paginated response of runners' do
@@ -47,7 +47,7 @@
       stub_get('/runners/all', 'runners')
     end
 
-    context 'without scope' do
+    context 'without extra queries' do
       before do
         @runner = Gitlab.all_runners
       end
@@ -63,14 +63,14 @@
       end
     end
 
-    context 'with scope' do
+    context 'with queries' do
       before do
-        stub_get('/runners/all?scope=online', 'runners')
-        @runner = Gitlab.all_runners(scope: :online)
+        stub_get('/runners/all?type=instance_type', 'runners')
+        @runner = Gitlab.all_runners(type: :instance_type)
       end
 
       it 'gets the correct resource' do
-        expect(a_get('/runners/all').with(query: { scope: :online })).to have_been_made
+        expect(a_get('/runners/all').with(query: { type: :instance_type })).to have_been_made
       end
 
       it 'returns a paginated response of runners' do
@@ -100,12 +100,12 @@
 
   describe '.update_runner' do
     before do
-      stub_put('/runners/6', 'runner_edit').with(query: { description: 'abcefg' })
+      stub_put('/runners/6', 'runner_edit').with(body: { description: 'abcefg' })
       @runner = Gitlab.update_runner(6, description: 'abcefg')
     end
 
     it 'gets the correct resource' do
-      expect(a_put('/runners/6').with(query: { description: 'abcefg' })).to have_been_made
+      expect(a_put('/runners/6').with(body: { description: 'abcefg' })).to have_been_made
     end
 
     it 'returns an updated response of a runner' do
@@ -192,6 +192,41 @@
     end
   end
 
+  describe '.group_runners' do
+    before do
+      stub_get('/groups/9/runners', 'group_runners')
+    end
+
+    context 'without extra queries' do
+      before do
+        @runners = Gitlab.group_runners(9)
+      end
+
+      it 'gets the correct resource' do
+        expect(a_get('/groups/9/runners')).to have_been_made
+      end
+
+      it 'returns a paginated response of runners' do
+        expect(@runners).to be_a Gitlab::PaginatedResponse
+      end
+    end
+
+    context 'with queries' do
+      before do
+        stub_get('/groups/9/runners?type=instance_type', 'group_runners')
+        @runner = Gitlab.group_runners(9, type: :instance_type)
+      end
+
+      it 'gets the correct resource' do
+        expect(a_get('/groups/9/runners').with(query: { type: :instance_type })).to have_been_made
+      end
+
+      it 'returns a paginated response of runners' do
+        expect(@runner).to be_a Gitlab::PaginatedResponse
+      end
+    end
+  end
+
   describe '.register_runner' do
     before do
       stub_post('/runners', 'register_runner_response').with(body: { token: '6337ff461c94fd3fa32ba3b1ff4125', description: 'Some Description', active: true, locked: false })

spec/gitlab/objectified_hash_spec.rb

@@ -13,8 +13,8 @@
     let(:oh) { described_class.new(hash) }
 
     it 'allows to call Hash methods' do
-      expect(oh.dig('foo')).to eq('bar')
-      expect(oh.merge(key: :value)).to eq({ 'foo' => 'bar', key: :value })
+      expect(oh['foo']).to eq('bar')
+      expect(oh.merge(key: :value)).to eq('foo' => 'bar', key: :value)
     end
 
     it 'warns about calling Hash methods' do