Merge pull request #198 from travis-ci/cd-v3-parity

v3 Add Build and Job Restart and Cancellation

lib/travis/api/v3/access_control/generic.rb

@@ -51,6 +51,10 @@ module Travis::API::V3
       visible? build.repository
     end
 
+    def build_writable?(build)
+      writable? build.repository
+    end
+
     def branch_visible?(branch)
       visible? branch.repository
     end
@@ -59,6 +63,10 @@ module Travis::API::V3
       visible? job.repository
     end
 
+    def job_writable?(job)
+      writable? job.repository
+    end
+
     def organization_visible?(organization)
       full_access? or public_api?
     end

lib/travis/api/v3/permissions/build.rb

@@ -0,0 +1,13 @@
+require 'travis/api/v3/permissions/generic'
+
+module Travis::API::V3
+  class Permissions::Build < Permissions::Generic
+    def cancel?
+      write?
+    end
+
+    def restart?
+      write?
+    end
+  end
+end

lib/travis/api/v3/permissions/job.rb

@@ -0,0 +1,13 @@
+require 'travis/api/v3/permissions/generic'
+
+module Travis::API::V3
+  class Permissions::Job < Permissions::Generic
+    def cancel?
+      write?
+    end
+
+    def restart?
+      write?
+    end
+  end
+end

lib/travis/api/v3/queries/build.rb

@@ -6,5 +6,17 @@ module Travis::API::V3
       return Models::Build.find_by_id(id) if id
       raise WrongParams, 'missing build.id'.freeze
     end
+
+    def cancel(user)
+      payload = { id: id, user_id: user.id, source: 'api' }
+      perform_async(:build_cancellation, payload)
+      payload
+    end
+
+    def restart(user)
+      payload = { id: id, user_id: user.id, source: 'api' }
+      perform_async(:build_restart, payload)
+      payload
+    end
   end
 end

lib/travis/api/v3/queries/job.rb

@@ -4,7 +4,19 @@ module Travis::API::V3
 
     def find
       return Models::Job.find_by_id(id) if id
-      raise WrongParams, 'missing build.id'.freeze
+      raise WrongParams, 'missing job.id'.freeze
+    end
+
+    def cancel(user)
+      payload = { id: id, user_id: user.id, source: 'api' }
+      perform_async(:job_cancellation, payload)
+      payload
+    end
+
+    def restart(user)
+      payload = { id: id, user_id: user.id, source: 'api' }
+      perform_async(:job_restart, payload)
+      payload
     end
   end
 end

lib/travis/api/v3/routes.rb

@@ -18,14 +18,17 @@ module Travis::API::V3
       route '/build/{build.id}'
       get :find
 
-      # post :cancel, '/cancel'
-      # post :restart, '/restart'
+      post :cancel, '/cancel'
+      post :restart, '/restart'
     end
 
     resource :job do
       capture id: :digit
       route '/job/{job.id}'
       get :find
+
+      post :cancel, '/cancel'
+      post :restart, '/restart'
     end
 
     resource :organization do

lib/travis/api/v3/services/build/cancel.rb

@@ -0,0 +1,13 @@
+module Travis::API::V3
+  class Services::Build::Cancel < Service
+
+    def run
+      raise LoginRequired unless access_control.logged_in? or access_control.full_access?
+      raise NotFound      unless build = find(:build)
+      access_control.permissions(build).cancel!
+
+      query.cancel(access_control.user)
+      accepted(build: build, state_change: :cancel)
+    end
+  end
+end

lib/travis/api/v3/services/build/restart.rb

@@ -0,0 +1,13 @@
+module Travis::API::V3
+  class Services::Build::Restart < Service
+
+    def run
+      raise LoginRequired unless access_control.logged_in? or access_control.full_access?
+      raise NotFound      unless build = find(:build)
+      access_control.permissions(build).restart!
+
+      query.restart(access_control.user)
+      accepted(build: build, state_change: :restart)
+    end
+  end
+end

lib/travis/api/v3/services/job/cancel.rb

@@ -0,0 +1,13 @@
+module Travis::API::V3
+  class Services::Job::Cancel < Service
+
+    def run
+      raise LoginRequired unless access_control.logged_in? or access_control.full_access?
+      raise NotFound      unless job = find(:job)
+      access_control.permissions(job).cancel!
+
+      query.cancel(access_control.user)
+      accepted(job: job, state_change: :cancel)
+    end
+  end
+end

lib/travis/api/v3/services/job/restart.rb

@@ -0,0 +1,13 @@
+module Travis::API::V3
+  class Services::Job::Restart < Service
+
+    def run
+      raise LoginRequired unless access_control.logged_in? or access_control.full_access?
+      raise NotFound      unless job = find(:job)
+      access_control.permissions(job).restart!
+
+      query.restart(access_control.user)
+      accepted(job: job, state_change: :restart)
+    end
+  end
+end

lib/travis/api/workers/job_restart.rb

@@ -13,7 +13,6 @@ module Travis
         user = User.find(data['user_id'])
         Travis.service(:reset_model, user, job_id: data['id']).run
       end
-
     end
   end
 end

spec/v3/services/build/cancel_spec.rb

@@ -0,0 +1,153 @@
+require 'spec_helper'
+
+describe Travis::API::V3::Services::Build::Cancel do
+  let(:repo) { Travis::API::V3::Models::Repository.where(owner_name: 'svenfuchs', name: 'minimal').first }
+  let(:build) { repo.builds.first }
+  let(:sidekiq_payload) { JSON.load(Sidekiq::Client.last['args'].last.to_json) }
+  let(:sidekiq_params) { Sidekiq::Client.last['args'].last.deep_symbolize_keys }
+
+  before do
+    Travis::Features.stubs(:owner_active?).returns(true)
+    @original_sidekiq = Sidekiq::Client
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = []
+  end
+
+  after do
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = @original_sidekiq
+  end
+
+  describe "not authenticated" do
+    before  { post("/v3/build/#{build.id}/cancel")      }
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "login_required",
+      "error_message" => "login required"
+    }}
+  end
+
+  describe "missing build, authenticated" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/build/9999999999/cancel", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "build not found (or insufficient access)",
+      "resource_type" => "build"
+    }}
+  end
+
+  describe "existing repository, no push access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/build/#{build.id}/cancel", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "error_type",
+      "insufficient_access",
+      "error_message",
+      "operation requires cancel access to build",
+      "resource_type",
+      "build",
+      "permission",
+      "cancel")
+    }
+  end
+
+  describe "private repository, no access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { repo.update_attribute(:private, true)                             }
+    before        { post("/v3/build/#{build.id}/cancel", {}, headers)                 }
+    after         { repo.update_attribute(:private, false)                            }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "build not found (or insufficient access)",
+      "resource_type" => "build"
+    }}
+  end
+
+  describe "existing repository, push access" do
+    let(:params)  {{}}
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1)                          }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                                                 }}
+    before        { Travis::API::V3::Models::Permission.create(repository: repo, user: repo.owner, push: true) }
+    before        { post("/v3/build/#{build.id}/cancel", params, headers)                                      }
+
+    example { expect(last_response.status).to be == 202 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "build",
+      "@href",
+      "@representation",
+      "minimal",
+      "cancel",
+      "id",
+      "state_change")
+    }
+
+    example { expect(sidekiq_payload).to be == {
+      "id"     => "#{build.id}",
+      "user_id"=> repo.owner_id,
+      "source" => "api"}
+    }
+
+    example { expect(Sidekiq::Client.last['queue']).to be == 'build_cancellations'                }
+    example { expect(Sidekiq::Client.last['class']).to be == 'Travis::Sidekiq::BuildCancellation' }
+
+    describe "setting id has no effect" do
+      let(:params) {{ id: 42 }}
+      example { expect(sidekiq_payload).to be == {
+        "id"     => "#{build.id}",
+        "user_id"=> repo.owner_id,
+        "source" => "api"}
+      }
+    end
+  end
+
+  #  TODO decided to discuss further with rkh as this use case doesn't really exist at the moment
+  #  and 'fixing' the query requires modifying workers that v2 uses, thereby running the risk of breaking v2,
+  #  and also because in 6 months or so travis-hub will be able to cancel builds without using travis-core at all.
+  #
+  # describe "existing repository, application with full access" do
+  #   let(:app_name)   { 'travis-example'                                                           }
+  #   let(:app_secret) { '12345678'                                                                 }
+  #   let(:sign_opts)  { "a=#{app_name}"                                                            }
+  #   let(:signature)  { OpenSSL::HMAC.hexdigest('sha256', app_secret, sign_opts)                   }
+  #   let(:headers)    {{ 'HTTP_AUTHORIZATION' => "signature #{sign_opts}:#{signature}"            }}
+  #   before { Travis.config.applications = { app_name => { full_access: true, secret: app_secret }}}
+  #   before { post("/v3/build/#{build.id}/cancel", params, headers)                                }
+  #
+  #   describe 'without setting user' do
+  #     let(:params) {{}}
+  #     example { expect(last_response.status).to be == 400 }
+  #     example { expect(JSON.load(body)).to      be ==     {
+  #       "@type"         => "error",
+  #       "error_type"    => "wrong_params",
+  #       "error_message" => "missing user"
+  #     }}
+  #   end
+  #
+  #   describe 'setting user' do
+  #     let(:params) {{ user: { id: repo.owner.id } }}
+  #     example { expect(last_response.status).to be == 202 }
+  #     example { expect(sidekiq_payload).to be == {
+  #       # repository: { id: repo.id, owner_name: 'svenfuchs', name: 'minimal' },
+  #       # user:       { id: repo.owner.id },
+  #       # message:    nil,
+  #       # branch:     'master',
+  #       # config:     {}
+  #     }}
+  #   end
+  # end
+end

spec/v3/services/build/find_spec.rb

@@ -26,9 +26,13 @@ describe Travis::API::V3::Services::Build::Find do
     before     { get("/v3/build/#{build.id}") }
     example    { expect(last_response).to be_ok }
     example    { expect(parsed_body).to be == {
-      "@type"              => "build",
-      "@href"              => "/v3/build/#{build.id}",
-      "@representation"    => "standard",
+      "@type"            => "build",
+      "@href"            => "/v3/build/#{build.id}",
+      "@representation"  => "standard",
+      "@permissions"     => {
+        "read"           => true,
+        "cancel"         => false,
+        "restart"        => false},
       "id"               => build.id,
       "number"           => build.number,
       "state"            => build.state,
@@ -99,9 +103,13 @@ describe Travis::API::V3::Services::Build::Find do
     after         { repo.update_attribute(:private, false) }
     example       { expect(last_response).to be_ok  }
     example    { expect(parsed_body).to be == {
-      "@type"              => "build",
-      "@href"              => "/v3/build/#{build.id}",
-      "@representation"    => "standard",
+      "@type"            => "build",
+      "@href"            => "/v3/build/#{build.id}",
+      "@representation"  => "standard",
+      "@permissions"     => {
+        "read"           => true,
+        "cancel"         => false,
+        "restart"        => false},
       "id"               => build.id,
       "number"           => build.number,
       "state"            => build.state,

spec/v3/services/build/restart_spec.rb

@@ -0,0 +1,154 @@
+require 'spec_helper'
+
+describe Travis::API::V3::Services::Build::Restart do
+  let(:repo) { Travis::API::V3::Models::Repository.where(owner_name: 'svenfuchs', name: 'minimal').first }
+  let(:build) { repo.builds.first }
+  let(:sidekiq_payload) { JSON.load(Sidekiq::Client.last['args'].last.to_json) }
+  let(:sidekiq_params) { Sidekiq::Client.last['args'].last.deep_symbolize_keys }
+
+  before do
+    Travis::Features.stubs(:owner_active?).returns(true)
+    @original_sidekiq = Sidekiq::Client
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = []
+  end
+
+  after do
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = @original_sidekiq
+  end
+
+  describe "not authenticated" do
+    before  { post("/v3/build/#{build.id}/restart")      }
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "login_required",
+      "error_message" => "login required"
+    }}
+  end
+
+  describe "missing build, authenticated" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/build/9999999999/restart", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "build not found (or insufficient access)",
+      "resource_type" => "build"
+    }}
+  end
+
+  describe "existing repository, no push access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/build/#{build.id}/restart", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "error_type",
+      "insufficient_access",
+      "error_message",
+      "operation requires restart access to build",
+      "resource_type",
+      "build",
+      "permission",
+      "restart")
+    }
+  end
+
+  describe "private repository, no access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { repo.update_attribute(:private, true)                             }
+    before        { post("/v3/build/#{build.id}/restart", {}, headers)                 }
+    after         { repo.update_attribute(:private, false)                            }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "build not found (or insufficient access)",
+      "resource_type" => "build"
+    }}
+  end
+
+  describe "existing repository, push access" do
+    let(:params)  {{}}
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1)                          }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                                                 }}
+    before        { Travis::API::V3::Models::Permission.create(repository: repo, user: repo.owner, push: true) }
+    before        { post("/v3/build/#{build.id}/restart", params, headers)                                      }
+
+    example { expect(last_response.status).to be == 202 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "pending",
+      "build",
+      "@href",
+      "@representation",
+      "minimal",
+      "restart",
+      "id",
+      "state_change")
+    }
+
+    example { expect(sidekiq_payload).to be == {
+      "id"     => "#{build.id}",
+      "user_id"=> repo.owner_id,
+      "source" => "api"}
+    }
+
+    example { expect(Sidekiq::Client.last['queue']).to be == 'build_restarts'                }
+    example { expect(Sidekiq::Client.last['class']).to be == 'Travis::Sidekiq::BuildRestart' }
+
+    describe "setting id has no effect" do
+      let(:params) {{ id: 42 }}
+      example { expect(sidekiq_payload).to be == {
+        "id"     => "#{build.id}",
+        "user_id"=> repo.owner_id,
+        "source" => "api"}
+      }
+    end
+  end
+
+  #  TODO decided to discuss further with rkh as this use case doesn't really exist at the moment
+  #  and 'fixing' the query requires modifying workers that v2 uses, thereby running the risk of breaking v2,
+  #  and also because in 6 months or so travis-hub will be able to cancel builds without using travis-core at all.
+  #
+  # describe "existing repository, application with full access" do
+  #   let(:app_name)   { 'travis-example'                                                           }
+  #   let(:app_secret) { '12345678'                                                                 }
+  #   let(:sign_opts)  { "a=#{app_name}"                                                            }
+  #   let(:signature)  { OpenSSL::HMAC.hexdigest('sha256', app_secret, sign_opts)                   }
+  #   let(:headers)    {{ 'HTTP_AUTHORIZATION' => "signature #{sign_opts}:#{signature}"            }}
+  #   before { Travis.config.applications = { app_name => { full_access: true, secret: app_secret }}}
+  #   before { post("/v3/build/#{build.id}/restart", params, headers)                                }
+  #
+  #   describe 'without setting user' do
+  #     let(:params) {{}}
+  #     example { expect(last_response.status).to be == 400 }
+  #     example { expect(JSON.load(body)).to      be ==     {
+  #       "@type"         => "error",
+  #       "error_type"    => "wrong_params",
+  #       "error_message" => "missing user"
+  #     }}
+  #   end
+  #
+  #   describe 'setting user' do
+  #     let(:params) {{ user: { id: repo.owner.id } }}
+  #     example { expect(last_response.status).to be == 202 }
+  #     example { expect(sidekiq_payload).to be == {
+  #       # repository: { id: repo.id, owner_name: 'svenfuchs', name: 'minimal' },
+  #       # user:       { id: repo.owner.id },
+  #       # message:    nil,
+  #       # branch:     'master',
+  #       # config:     {}
+  #     }}
+  #   end
+  # end
+end

spec/v3/services/builds/find_spec.rb

@@ -52,6 +52,10 @@ describe Travis::API::V3::Services::Builds::Find do
         "@type"            => "build",
         "@href"            => "/v3/build/#{build.id}",
         "@representation"  => "standard",
+        "@permissions"     => {
+          "read"           => true,
+          "cancel"         => false,
+          "restart"        => false },
         "id"               => build.id,
         "number"           => "3",
         "state"            => "configured",
@@ -149,6 +153,10 @@ describe Travis::API::V3::Services::Builds::Find do
         "@type"            => "build",
         "@href"            => "/v3/build/#{build.id}",
         "@representation"  => "standard",
+        "@permissions"     => {
+          "read"           => true,
+          "cancel"         => false,
+          "restart"        => false },
         "id"               => build.id,
         "number"           => "3",
         "state"            => "configured",

spec/v3/services/job/cancel_spec.rb

@@ -0,0 +1,154 @@
+require 'spec_helper'
+
+describe Travis::API::V3::Services::Job::Cancel do
+  let(:repo)  { Travis::API::V3::Models::Repository.where(owner_name: 'svenfuchs', name: 'minimal').first }
+  let(:build) { repo.builds.first }
+  let(:job)   { build.jobs.first}
+  let(:sidekiq_payload) { JSON.load(Sidekiq::Client.last['args'].last.to_json) }
+  let(:sidekiq_params)  { Sidekiq::Client.last['args'].last.deep_symbolize_keys }
+
+  before do
+    Travis::Features.stubs(:owner_active?).returns(true)
+    @original_sidekiq = Sidekiq::Client
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = []
+  end
+
+  after do
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = @original_sidekiq
+  end
+
+  describe "not authenticated" do
+    before  { post("/v3/job/#{job.id}/cancel")      }
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "login_required",
+      "error_message" => "login required"
+    }}
+  end
+
+  describe "missing build, authenticated" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/job/9999999999/cancel", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "job not found (or insufficient access)",
+      "resource_type" => "job"
+    }}
+  end
+
+  describe "existing repository, no push access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/job/#{job.id}/cancel", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "error_type",
+      "insufficient_access",
+      "error_message",
+      "operation requires cancel access to job",
+      "resource_type",
+      "job",
+      "permission",
+      "cancel")
+    }
+  end
+
+  describe "private repository, no access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { repo.update_attribute(:private, true)                             }
+    before        { post("/v3/job/#{job.id}/cancel", {}, headers)                 }
+    after         { repo.update_attribute(:private, false)                            }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "job not found (or insufficient access)",
+      "resource_type" => "job"
+    }}
+  end
+
+  describe "existing repository, push access" do
+    let(:params)  {{}}
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1)                          }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                                                 }}
+    before        { Travis::API::V3::Models::Permission.create(repository: repo, user: repo.owner, push: true) }
+    before        { post("/v3/job/#{job.id}/cancel", params, headers)                                      }
+
+    example { expect(last_response.status).to be == 202 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "job",
+      "@href",
+      "@representation",
+      "minimal",
+      "cancel",
+      "id",
+      "state_change")
+    }
+
+    example { expect(sidekiq_payload).to be == {
+      "id"     => "#{job.id}",
+      "user_id"=> repo.owner_id,
+      "source" => "api"}
+    }
+
+    example { expect(Sidekiq::Client.last['queue']).to be == 'job_cancellations'                }
+    example { expect(Sidekiq::Client.last['class']).to be == 'Travis::Sidekiq::JobCancellation' }
+
+    describe "setting id has no effect" do
+      let(:params) {{ id: 42 }}
+      example { expect(sidekiq_payload).to be == {
+        "id"     => "#{job.id}",
+        "user_id"=> repo.owner_id,
+        "source" => "api"}
+      }
+    end
+  end
+
+  #  TODO decided to discuss further with rkh as this use case doesn't really exist at the moment
+  #  and 'fixing' the query requires modifying workers that v2 uses, thereby running the risk of breaking v2,
+  #  and also because in 6 months or so travis-hub will be able to cancel builds without using travis-core at all.
+  #
+  # describe "existing repository, application with full access" do
+  #   let(:app_name)   { 'travis-example'                                                           }
+  #   let(:app_secret) { '12345678'                                                                 }
+  #   let(:sign_opts)  { "a=#{app_name}"                                                            }
+  #   let(:signature)  { OpenSSL::HMAC.hexdigest('sha256', app_secret, sign_opts)                   }
+  #   let(:headers)    {{ 'HTTP_AUTHORIZATION' => "signature #{sign_opts}:#{signature}"            }}
+  #   before { Travis.config.applications = { app_name => { full_access: true, secret: app_secret }}}
+  #   before { post("/v3/job/#{job.id}/cancel", params, headers)                                }
+  #
+  #   describe 'without setting user' do
+  #     let(:params) {{}}
+  #     example { expect(last_response.status).to be == 400 }
+  #     example { expect(JSON.load(body)).to      be ==     {
+  #       "@type"         => "error",
+  #       "error_type"    => "wrong_params",
+  #       "error_message" => "missing user"
+  #     }}
+  #   end
+  #
+  #   describe 'setting user' do
+  #     let(:params) {{ user: { id: repo.owner.id } }}
+  #     example { expect(last_response.status).to be == 202 }
+  #     example { expect(sidekiq_payload).to be == {
+  #       # repository: { id: repo.id, owner_name: 'svenfuchs', name: 'minimal' },
+  #       # user:       { id: repo.owner.id },
+  #       # message:    nil,
+  #       # branch:     'master',
+  #       # config:     {}
+  #     }}
+  #   end
+  # end
+end

spec/v3/services/job/find_spec.rb

@@ -20,6 +20,10 @@ describe Travis::API::V3::Services::Job::Find do
       "@type"             => "job",
       "@href"             => "/v3/job/#{job.id}",
       "@representation"   => "standard",
+      "@permissions"      => {
+        "read"            => true,
+        "cancel"          => false,
+        "restart"         => false },
       "id"                => job.id,
       "number"            => job.number,
       "state"             => job.state,
@@ -140,6 +144,10 @@ describe Travis::API::V3::Services::Job::Find do
       "@type"             => "job",
       "@href"             => "/v3/job/#{job.id}",
       "@representation"   => "standard",
+      "@permissions"      => {
+        "read"            => true,
+        "cancel"          => false,
+        "restart"         => false },
       "id"                => job.id,
       "number"            => job.number,
       "state"             => job.state,

spec/v3/services/job/restart_spec.rb

@@ -0,0 +1,155 @@
+require 'spec_helper'
+
+describe Travis::API::V3::Services::Job::Restart do
+  let(:repo)  { Travis::API::V3::Models::Repository.where(owner_name: 'svenfuchs', name: 'minimal').first }
+  let(:build) { repo.builds.first }
+  let(:job)   { build.jobs.first }
+  let(:sidekiq_payload) { JSON.load(Sidekiq::Client.last['args'].last.to_json) }
+  let(:sidekiq_params)  { Sidekiq::Client.last['args'].last.deep_symbolize_keys }
+
+  before do
+    Travis::Features.stubs(:owner_active?).returns(true)
+    @original_sidekiq = Sidekiq::Client
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = []
+  end
+
+  after do
+    Sidekiq.send(:remove_const, :Client) # to avoid a warning
+    Sidekiq::Client = @original_sidekiq
+  end
+
+  describe "not authenticated" do
+    before  { post("/v3/job/#{job.id}/restart")      }
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "login_required",
+      "error_message" => "login required"
+    }}
+  end
+
+  describe "missing build, authenticated" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/job/9999999999/restart", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "job not found (or insufficient access)",
+      "resource_type" => "job"
+    }}
+  end
+
+  describe "existing repository, no push access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { post("/v3/job/#{job.id}/restart", {}, headers)                 }
+
+    example { expect(last_response.status).to be == 403 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "error_type",
+      "insufficient_access",
+      "error_message",
+      "operation requires restart access to job",
+      "resource_type",
+      "job",
+      "permission",
+      "restart")
+    }
+  end
+
+  describe "private repository, no access" do
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1) }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                        }}
+    before        { repo.update_attribute(:private, true)                             }
+    before        { post("/v3/job/#{job.id}/restart", {}, headers)                 }
+    after         { repo.update_attribute(:private, false)                            }
+
+    example { expect(last_response.status).to be == 404 }
+    example { expect(JSON.load(body)).to      be ==     {
+      "@type"         => "error",
+      "error_type"    => "not_found",
+      "error_message" => "job not found (or insufficient access)",
+      "resource_type" => "job"
+    }}
+  end
+
+  describe "existing repository, push access" do
+    let(:params)  {{}}
+    let(:token)   { Travis::Api::App::AccessToken.create(user: repo.owner, app_id: 1)                          }
+    let(:headers) {{ 'HTTP_AUTHORIZATION' => "token #{token}"                                                 }}
+    before        { Travis::API::V3::Models::Permission.create(repository: repo, user: repo.owner, push: true) }
+    before        { post("/v3/job/#{job.id}/restart", params, headers)                                      }
+
+    example { expect(last_response.status).to be == 202 }
+    example { expect(JSON.load(body).to_s).to include(
+      "@type",
+      "pending",
+      "job",
+      "@href",
+      "@representation",
+      "minimal",
+      "restart",
+      "id",
+      "state_change")
+    }
+
+    example { expect(sidekiq_payload).to be == {
+      "id"     => "#{job.id}",
+      "user_id"=> repo.owner_id,
+      "source" => "api"}
+    }
+
+    example { expect(Sidekiq::Client.last['queue']).to be == 'job_restarts'                }
+    example { expect(Sidekiq::Client.last['class']).to be == 'Travis::Sidekiq::JobRestart' }
+
+    describe "setting id has no effect" do
+      let(:params) {{ id: 42 }}
+      example { expect(sidekiq_payload).to be == {
+        "id"     => "#{job.id}",
+        "user_id"=> repo.owner_id,
+        "source" => "api"}
+      }
+    end
+  end
+
+  #  TODO decided to discuss further with rkh as this use case doesn't really exist at the moment
+  #  and 'fixing' the query requires modifying workers that v2 uses, thereby running the risk of breaking v2,
+  #  and also because in 6 months or so travis-hub will be able to cancel builds without using travis-core at all.
+  #
+  # describe "existing repository, application with full access" do
+  #   let(:app_name)   { 'travis-example'                                                           }
+  #   let(:app_secret) { '12345678'                                                                 }
+  #   let(:sign_opts)  { "a=#{app_name}"                                                            }
+  #   let(:signature)  { OpenSSL::HMAC.hexdigest('sha256', app_secret, sign_opts)                   }
+  #   let(:headers)    {{ 'HTTP_AUTHORIZATION' => "signature #{sign_opts}:#{signature}"            }}
+  #   before { Travis.config.applications = { app_name => { full_access: true, secret: app_secret }}}
+  #   before { post("/v3/job/#{job.id}/restart", params, headers)                                }
+  #
+  #   describe 'without setting user' do
+  #     let(:params) {{}}
+  #     example { expect(last_response.status).to be == 400 }
+  #     example { expect(JSON.load(body)).to      be ==     {
+  #       "@type"         => "error",
+  #       "error_type"    => "wrong_params",
+  #       "error_message" => "missing user"
+  #     }}
+  #   end
+  #
+  #   describe 'setting user' do
+  #     let(:params) {{ user: { id: repo.owner.id } }}
+  #     example { expect(last_response.status).to be == 202 }
+  #     example { expect(sidekiq_payload).to be == {
+  #       # repository: { id: repo.id, owner_name: 'svenfuchs', name: 'minimal' },
+  #       # user:       { id: repo.owner.id },
+  #       # message:    nil,
+  #       # branch:     'master',
+  #       # config:     {}
+  #     }}
+  #   end
+  # end
+end