Merge branch '24295-freeze-period-API-changes' into 'master'

Freeze Period API changes

See merge request gitlab-org/gitlab!29382

app/finders/freeze_periods_finder.rb

+# frozen_string_literal: true
+
+class FreezePeriodsFinder
+  def initialize(project, current_user = nil)
+    @project = project
+    @current_user = current_user
+  end
+
+  def execute
+    return Ci::FreezePeriod.none unless Ability.allowed?(@current_user, :read_freeze_period, @project)
+
+    @project.freeze_periods
+  end
+end

app/models/ci/freeze_period.rb

@@ -5,6 +5,8 @@ module Ci
     include StripAttribute
     self.table_name = 'ci_freeze_periods'
 
+    default_scope { order(created_at: :asc) }
+
     belongs_to :project, inverse_of: :freeze_periods
 
     strip_attributes :freeze_start, :freeze_end

app/policies/ci/freeze_period_policy.rb

+# frozen_string_literal: true
+
+module Ci
+  class FreezePeriodPolicy < BasePolicy
+    delegate { @subject.resource_parent }
+  end
+end

app/policies/project_policy.rb

@@ -362,6 +362,10 @@ class ProjectPolicy < BasePolicy
     enable :destroy_deploy_token
     enable :read_prometheus_alerts
     enable :admin_terraform_state
+    enable :create_freeze_period
+    enable :read_freeze_period
+    enable :update_freeze_period
+    enable :destroy_freeze_period
   end
 
   rule { public_project & metrics_dashboard_allowed }.policy do

changelogs/unreleased/24295-freeze-period-API-changes.yml

+---
+title: Expose Freeze Periods in REST API
+merge_request: 29382
+author:
+type: added

lib/api/api.rb

@@ -141,6 +141,7 @@ module API
       mount ::API::Events
       mount ::API::Features
       mount ::API::Files
+      mount ::API::FreezePeriods
       mount ::API::GroupBoards
       mount ::API::GroupClusters
       mount ::API::GroupExport

lib/api/entities/freeze_period.rb

+# frozen_string_literal: true
+
+module API
+  module Entities
+    class FreezePeriod < Grape::Entity
+      expose :id
+      expose :freeze_start, :freeze_end, :cron_timezone
+      expose :created_at, :updated_at
+    end
+  end
+end

lib/api/freeze_periods.rb

+# frozen_string_literal: true
+
+module API
+  class FreezePeriods < Grape::API
+    include PaginationParams
+
+    before { authenticate! }
+
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
+
+    resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
+      desc 'Get project freeze periods' do
+        detail 'This feature was introduced in GitLab 13.0.'
+        success Entities::FreezePeriod
+      end
+      params do
+        use :pagination
+      end
+
+      get ":id/freeze_periods" do
+        authorize! :read_freeze_period, user_project
+
+        freeze_periods = ::FreezePeriodsFinder.new(user_project, current_user).execute
+
+        present paginate(freeze_periods), with: Entities::FreezePeriod, current_user: current_user
+      end
+
+      desc 'Get a single freeze period' do
+        detail 'This feature was introduced in GitLab 13.0.'
+        success Entities::FreezePeriod
+      end
+      params do
+        requires :freeze_period_id, type: Integer, desc: 'The ID of a project freeze period'
+      end
+      get ":id/freeze_periods/:freeze_period_id" do
+        authorize! :read_freeze_period, user_project
+
+        present freeze_period, with: Entities::FreezePeriod, current_user: current_user
+      end
+
+      desc 'Create a new freeze period' do
+        detail 'This feature was introduced in GitLab 13.0.'
+        success Entities::FreezePeriod
+      end
+      params do
+        requires :freeze_start, type: String, desc: 'Freeze Period start'
+        requires :freeze_end, type: String, desc: 'Freeze Period end'
+        optional :cron_timezone, type: String, desc: 'Timezone'
+      end
+      post ':id/freeze_periods' do
+        authorize! :create_freeze_period, user_project
+
+        freeze_period_params = declared(params, include_parent_namespaces: false)
+
+        freeze_period = user_project.freeze_periods.create(freeze_period_params)
+
+        if freeze_period.persisted?
+          present freeze_period, with: Entities::FreezePeriod
+        else
+          render_validation_error!(freeze_period)
+        end
+      end
+
+      desc 'Update a freeze period' do
+        detail 'This feature was introduced in GitLab 13.0.'
+        success Entities::FreezePeriod
+      end
+      params do
+        optional :freeze_start, type: String, desc: 'Freeze Period start'
+        optional :freeze_end, type: String, desc: 'Freeze Period end'
+        optional :cron_timezone, type: String, desc: 'Freeze Period Timezone'
+      end
+      put ':id/freeze_periods/:freeze_period_id' do
+        authorize! :update_freeze_period, user_project
+
+        freeze_period_params = declared(params, include_parent_namespaces: false, include_missing: false)
+
+        if freeze_period.update(freeze_period_params)
+          present freeze_period, with: Entities::FreezePeriod
+        else
+          render_validation_error!(freeze_period)
+        end
+      end
+
+      desc 'Delete a freeze period' do
+        detail 'This feature was introduced in GitLab 13.0.'
+        success Entities::FreezePeriod
+      end
+      params do
+        requires :freeze_period_id, type: Integer, desc: 'Freeze Period ID'
+      end
+      delete ':id/freeze_periods/:freeze_period_id' do
+        authorize! :destroy_freeze_period, user_project
+
+        destroy_conditionally!(freeze_period)
+      end
+    end
+
+    helpers do
+      def freeze_period
+        @freeze_period ||= user_project.freeze_periods.find(params[:freeze_period_id])
+      end
+    end
+  end
+end

spec/finders/freeze_periods_finder_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe FreezePeriodsFinder do
+  subject(:finder) { described_class.new(project, user).execute }
+
+  let(:project) { create(:project, :private) }
+  let(:user) { create(:user) }
+  let!(:freeze_period_1) { create(:ci_freeze_period, project: project, created_at: 2.days.ago) }
+  let!(:freeze_period_2) { create(:ci_freeze_period, project: project, created_at: 1.day.ago) }
+
+  shared_examples_for 'returns nothing' do
+    specify do
+      is_expected.to be_empty
+    end
+  end
+
+  shared_examples_for 'returns freeze_periods ordered by created_at asc' do
+    it 'returns freeze_periods ordered by created_at' do
+      expect(subject.count).to eq(2)
+      expect(subject.pluck('id')).to eq([freeze_period_1.id, freeze_period_2.id])
+    end
+  end
+
+  context 'when user is a maintainer' do
+    before do
+      project.add_maintainer(user)
+    end
+
+    it_behaves_like 'returns freeze_periods ordered by created_at asc'
+  end
+
+  context 'when user is a guest' do
+    before do
+      project.add_guest(user)
+    end
+
+    it_behaves_like 'returns nothing'
+  end
+
+  context 'when user is a developer' do
+    before do
+      project.add_developer(user)
+    end
+
+    it_behaves_like 'returns nothing'
+  end
+
+  context 'when user is not a project member' do
+    it_behaves_like 'returns nothing'
+
+    context 'when project is public' do
+      let(:project) { create(:project, :public) }
+
+      it_behaves_like 'returns nothing'
+    end
+  end
+end

spec/fixtures/api/schemas/public_api/v4/freeze_period.json

+{
+  "type": "object",
+  "required": [
+    "id",
+    "freeze_start",
+    "freeze_end",
+    "cron_timezone",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "id": { "type": "integer" },
+    "freeze_start": { "type": "string" },
+    "freeze_end": { "type": "string"},
+    "cron_timezone": { "type": "string" },
+    "created_at": { "type": "string" },
+    "updated_at": { "type": "string" }
+  },
+  "additionalProperties": false
+}

spec/fixtures/api/schemas/public_api/v4/freeze_periods.json

+{
+  "type": "array",
+  "items": { "$ref": "freeze_period.json" }
+}
+

spec/models/ci/freeze_period_spec.rb

@@ -5,6 +5,8 @@ require 'spec_helper'
 RSpec.describe Ci::FreezePeriod, type: :model do
   subject { build(:ci_freeze_period) }
 
+  let(:invalid_cron) { '0 0 0 * *' }
+
   it { is_expected.to belong_to(:project) }
 
   it { is_expected.to respond_to(:freeze_start) }
@@ -13,13 +15,19 @@ RSpec.describe Ci::FreezePeriod, type: :model do
 
   describe 'cron validations' do
     it 'allows valid cron patterns' do
-      freeze_period = build(:ci_freeze_period, freeze_start: '0 23 * * 5')
+      freeze_period = build(:ci_freeze_period)
 
       expect(freeze_period).to be_valid
     end
 
-    it 'does not allow invalid cron patterns' do
-      freeze_period = build(:ci_freeze_period, freeze_start: '0 0 0 * *')
+    it 'does not allow invalid cron patterns on freeze_start' do
+      freeze_period = build(:ci_freeze_period, freeze_start: invalid_cron)
+
+      expect(freeze_period).not_to be_valid
+    end
+
+    it 'does not allow invalid cron patterns on freeze_end' do
+      freeze_period = build(:ci_freeze_period, freeze_end: invalid_cron)
 
       expect(freeze_period).not_to be_valid
     end

spec/requests/api/freeze_periods_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe API::FreezePeriods do
+  let_it_be(:project) { create(:project, :repository, :private) }
+  let_it_be(:user) { create(:user) }
+  let_it_be(:admin) { create(:admin) }
+  let(:api_user) { user }
+  let(:invalid_cron) { '0 0 0 * *' }
+  let(:last_freeze_period) { project.freeze_periods.last }
+
+  describe 'GET /projects/:id/freeze_periods' do
+    context 'when the user is the admin' do
+      let!(:freeze_period) { create(:ci_freeze_period, project: project, created_at: 2.days.ago) }
+
+      it 'returns 200 HTTP status' do
+        get api("/projects/#{project.id}/freeze_periods", admin)
+
+        expect(response).to have_gitlab_http_status(:ok)
+      end
+    end
+
+    context 'when the user is the maintainer' do
+      before do
+        project.add_maintainer(user)
+      end
+
+      context 'when there are two freeze_periods' do
+        let!(:freeze_period_1) { create(:ci_freeze_period, project: project, created_at: 2.days.ago) }
+        let!(:freeze_period_2) { create(:ci_freeze_period, project: project, created_at: 1.day.ago) }
+
+        it 'returns 200 HTTP status' do
+          get api("/projects/#{project.id}/freeze_periods", user)
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+
+        it 'returns freeze_periods ordered by created_at ascending' do
+          get api("/projects/#{project.id}/freeze_periods", user)
+
+          expect(json_response.count).to eq(2)
+          expect(freeze_period_ids).to eq([freeze_period_1.id, freeze_period_2.id])
+        end
+
+        it 'matches response schema' do
+          get api("/projects/#{project.id}/freeze_periods", user)
+
+          expect(response).to match_response_schema('public_api/v4/freeze_periods')
+        end
+      end
+
+      context 'when there are no freeze_periods' do
+        it 'returns 200 HTTP status' do
+          get api("/projects/#{project.id}/freeze_periods", user)
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+
+        it 'returns an empty response' do
+          get api("/projects/#{project.id}/freeze_periods", user)
+
+          expect(json_response).to be_empty
+        end
+      end
+    end
+
+    context 'when user is a guest' do
+      before do
+        project.add_guest(user)
+      end
+
+      let!(:freeze_period) do
+        create(:ci_freeze_period, project: project)
+      end
+
+      it 'responds 403 Forbidden' do
+        get api("/projects/#{project.id}/freeze_periods", user)
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+
+    context 'when user is not a project member' do
+      it 'responds 404 Not Found' do
+        get api("/projects/#{project.id}/freeze_periods", user)
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+
+      context 'when project is public' do
+        let(:project) { create(:project, :public) }
+
+        it 'responds 403 Forbidden' do
+          get api("/projects/#{project.id}/freeze_periods", user)
+
+          expect(response).to have_gitlab_http_status(:forbidden)
+        end
+      end
+    end
+  end
+
+  describe 'GET /projects/:id/freeze_periods/:freeze_period_id' do
+    context 'when there is a freeze period' do
+      let!(:freeze_period) do
+        create(:ci_freeze_period, project: project)
+      end
+
+      context 'when the user is the admin' do
+        let!(:freeze_period) { create(:ci_freeze_period, project: project, created_at: 2.days.ago) }
+
+        it 'responds 200 OK' do
+          get api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", admin)
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+      end
+
+      context 'when the user is the maintainer' do
+        before do
+          project.add_maintainer(user)
+        end
+
+        it 'responds 200 OK' do
+          get api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", user)
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+
+        it 'returns a freeze period' do
+          get api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", user)
+
+          expect(json_response).to include(
+            'id' => freeze_period.id,
+            'freeze_start' => freeze_period.freeze_start,
+            'freeze_end' => freeze_period.freeze_end,
+            'cron_timezone' => freeze_period.cron_timezone)
+        end
+
+        it 'matches response schema' do
+          get api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", user)
+
+          expect(response).to match_response_schema('public_api/v4/freeze_period')
+        end
+      end
+
+      context 'when user is a guest' do
+        before do
+          project.add_guest(user)
+        end
+
+        it 'responds 403 Forbidden' do
+          get api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", user)
+
+          expect(response).to have_gitlab_http_status(:forbidden)
+        end
+
+        context 'when project is public' do
+          let(:project) { create(:project, :public) }
+
+          context 'when freeze_period exists' do
+            it 'responds 403 Forbidden' do
+              get api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", user)
+
+              expect(response).to have_gitlab_http_status(:forbidden)
+            end
+          end
+
+          context 'when freeze_period does not exist' do
+            it 'responds 403 Forbidden' do
+              get api("/projects/#{project.id}/freeze_periods/0", user)
+
+              expect(response).to have_gitlab_http_status(:forbidden)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  describe 'POST /projects/:id/freeze_periods' do
+    let(:params) do
+      {
+        freeze_start: '0 23 * * 5',
+        freeze_end: '0 7 * * 1',
+        cron_timezone: 'UTC'
+      }
+    end
+
+    subject { post api("/projects/#{project.id}/freeze_periods", api_user), params: params }
+
+    context 'when the user is the admin' do
+      let(:api_user) { admin }
+
+      it 'accepts the request' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:created)
+      end
+    end
+
+    context 'when user is the maintainer' do
+      before do
+        project.add_maintainer(user)
+      end
+
+      context 'with valid params' do
+        it 'accepts the request' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:created)
+        end
+
+        it 'creates a new freeze period' do
+          expect do
+            subject
+          end.to change { Ci::FreezePeriod.count }.by(1)
+
+          expect(last_freeze_period.freeze_start).to eq('0 23 * * 5')
+          expect(last_freeze_period.freeze_end).to eq('0 7 * * 1')
+          expect(last_freeze_period.cron_timezone).to eq('UTC')
+        end
+
+        it 'matches response schema' do
+          subject
+
+          expect(response).to match_response_schema('public_api/v4/freeze_period')
+        end
+      end
+
+      context 'with incomplete params' do
+        let(:params) do
+          {
+            freeze_start: '0 23 * * 5',
+            cron_timezone: 'UTC'
+          }
+        end
+
+        it 'responds 400 Bad Request' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:bad_request)
+          expect(json_response['error']).to eq("freeze_end is missing")
+        end
+      end
+
+      context 'with invalid params' do
+        let(:params) do
+          {
+            freeze_start: '0 23 * * 5',
+            freeze_end: invalid_cron,
+            cron_timezone: 'UTC'
+          }
+        end
+
+        it 'responds 400 Bad Request' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:bad_request)
+          expect(json_response['message']['freeze_end']).to eq([" is invalid syntax"])
+        end
+      end
+    end
+
+    context 'when user is a developer' do
+      before do
+        project.add_developer(user)
+      end
+
+      it 'responds 403 Forbidden' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+
+    context 'when user is a reporter' do
+      before do
+        project.add_reporter(user)
+      end
+
+      it 'responds 403 Forbidden' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+
+    context 'when user is not a project member' do
+      it 'responds 403 Forbidden' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+
+      context 'when project is public' do
+        let(:project) { create(:project, :public) }
+
+        it 'responds 403 Forbidden' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:forbidden)
+        end
+      end
+    end
+  end
+
+  describe 'PUT /projects/:id/freeze_periods/:freeze_period_id' do
+    let(:params) { { freeze_start: '0 22 * * 5', freeze_end: '5 4 * * sun' } }
+    let!(:freeze_period) { create :ci_freeze_period, project: project }
+
+    subject { put api("/projects/#{project.id}/freeze_periods/#{freeze_period.id}", api_user), params: params }
+
+    context 'when user is the admin' do
+      let(:api_user) { admin }
+
+      it 'accepts the request' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:ok)
+      end
+    end
+
+    context 'when user is the maintainer' do
+      before do
+        project.add_maintainer(user)
+      end
+
+      context 'with valid params' do
+        it 'accepts the request' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+
+        it 'performs the update' do
+          subject
+
+          freeze_period.reload
+
+          expect(freeze_period.freeze_start).to eq(params[:freeze_start])
+          expect(freeze_period.freeze_end).to eq(params[:freeze_end])
+        end
+
+        it 'matches response schema' do
+          subject
+
+          expect(response).to match_response_schema('public_api/v4/freeze_period')
+        end
+      end
+
+      context 'with invalid params' do
+        let(:params) { { freeze_start: invalid_cron } }
+
+        it 'responds 400 Bad Request' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:bad_request)
+          expect(json_response['message']['freeze_start']).to eq([" is invalid syntax"])
+        end
+      end
+    end
+
+    context 'when user is a reporter' do
+      before do
+        project.add_reporter(user)
+      end
+
+      it 'responds 403 Forbidden' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+
+    context 'when user is not a project member' do
+      it 'responds 404 Not Found' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+
+      context 'when project is public' do
+        let(:project) { create(:project, :public) }
+
+        it 'responds 403 Forbidden' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:forbidden)
+        end
+      end
+    end
+  end
+
+  describe 'DELETE /projects/:id/freeze_periods/:freeze_period_id' do
+    let!(:freeze_period) { create :ci_freeze_period, project: project }
+    let(:freeze_period_id) { freeze_period.id }
+
+    subject { delete api("/projects/#{project.id}/freeze_periods/#{freeze_period_id}", api_user) }
+
+    context 'when user is the admin' do
+      let(:api_user) { admin }
+
+      it 'accepts the request' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:no_content)
+      end
+    end
+
+    context 'when user is the maintainer' do
+      before do
+        project.add_maintainer(user)
+      end
+
+      it 'accepts the request' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:no_content)
+      end
+
+      it 'destroys the freeze period' do
+        expect do
+          subject
+        end.to change { Ci::FreezePeriod.count }.by(-1)
+      end
+
+      context 'when it is a non-existing freeze period id' do
+        let(:freeze_period_id) { 0 }
+
+        it '404' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:not_found)
+        end
+      end
+    end
+
+    context 'when user is a reporter' do
+      before do
+        project.add_reporter(user)
+      end
+
+      it 'responds 403 Forbidden' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+
+    context 'when user is not a project member' do
+      it 'responds 404 Not Found' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+
+      context 'when project is public' do
+        let(:project) { create(:project, :public) }
+
+        it 'responds 403 Forbidden' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:forbidden)
+        end
+      end
+    end
+  end
+
+  def freeze_period_ids
+    json_response.map do |freeze_period_hash|
+      freeze_period_hash.fetch('id')&.to_i
+    end
+  end
+end