(#860) Track time of envelope download job enqueuing

Author: excelsior

app/api/entities/envelope_download.rb

@@ -5,6 +5,18 @@ class EnvelopeDownload < Grape::Entity
       expose :display_status, as: :status,
                               documentation: { type: 'string', desc: 'Status of download' }
 
+      expose :enqueued_at,
+             documentation: { type: 'string', desc: 'When the download was enqueued' },
+             if: ->(object) { object.pending? }
+
+      expose :finished_at,
+             documentation: { type: 'string', desc: 'When the download finished' },
+             if: ->(object) { object.finished? }
+
+      expose :started_at,
+             documentation: { type: 'string', desc: 'When the download started' },
+             if: ->(object) { object.in_progress? }
+
       expose :url,
              documentation: { type: 'string', desc: 'AWS S3 URL' },
              if: ->(object) { object.finished? }

app/api/v1/envelopes.rb

@@ -84,7 +84,11 @@ class Envelopes < MountableAPI
 
             desc 'Starts an envelope download'
             post do
-              @envelope_download.update_column(:status, :pending)
+              @envelope_download.update!(
+                enqueued_at: Time.current,
+                status: :pending
+              )
+
               DownloadEnvelopesJob.perform_later(@envelope_download.id)
               present @envelope_download, with: API::Entities::EnvelopeDownload
             end

db/migrate/20250925025616_add_enqueued_at_to_envelope_downloads.rb

@@ -0,0 +1,5 @@
+class AddEnqueuedAtToEnvelopeDownloads < ActiveRecord::Migration[8.0]
+  def change
+    add_column :envelope_downloads, :enqueued_at, :datetime
+  end
+end

db/structure.sql

@@ -325,7 +325,8 @@ CREATE TABLE public.envelope_downloads (
     url character varying,
     created_at timestamp(6) without time zone NOT NULL,
     updated_at timestamp(6) without time zone NOT NULL,
-    status character varying DEFAULT 'pending'::character varying NOT NULL
+    status character varying DEFAULT 'pending'::character varying NOT NULL,
+    enqueued_at timestamp(6) without time zone
 );
 
 
@@ -1888,6 +1889,7 @@ ALTER TABLE ONLY public.envelopes
 SET search_path TO "$user", public;
 
 INSERT INTO "schema_migrations" (version) VALUES
+('20250925025616'),
 ('20250922224518'),
 ('20250921174021'),
 ('20250902034147'),

spec/api/v1/envelopes_spec.rb

@@ -180,13 +180,17 @@
           envelope_download = EnvelopeDownload.last
           expect(envelope_download.envelope_community).to eq(envelope_community)
           expect(envelope_download.status).to eq('pending')
+
+          expect_json_sizes(2)
+          expect_json('enqueued_at', nil)
+          expect_json('status', 'pending')
         end
       end
 
       # rubocop:todo RSpec/NestedGroups
       context 'with envelope download' do # rubocop:todo RSpec/MultipleMemoizedHelpers, RSpec/NestedGroups
         # rubocop:enable RSpec/NestedGroups
-        before do
+        let!(:envelope_download) do
           create(
             :envelope_download,
             envelope_community:,
@@ -207,6 +211,8 @@
           it 'returns `in progress`' do
             expect { perform_request }.not_to change(EnvelopeDownload, :count)
             expect_status(:ok)
+            expect_json_sizes(2)
+            expect_json('started_at', envelope_download.started_at.as_json)
             expect_json('status', 'in_progress')
           end
         end
@@ -216,13 +222,17 @@
         # rubocop:todo RSpec/NestedGroups
         context 'failed' do # rubocop:todo RSpec/ContextWording, RSpec/MultipleMemoizedHelpers, RSpec/NestedGroups
           # rubocop:enable RSpec/NestedGroups
-          let(:status) { :finished }
           let(:internal_error_message) { Faker::Lorem.sentence }
+          let(:status) { :finished }
+          let(:url) { Faker::Internet.url }
 
           it 'returns `failed`' do
             expect { perform_request }.not_to change(EnvelopeDownload, :count)
             expect_status(:ok)
+            expect_json_sizes(3)
+            expect_json('finished_at', envelope_download.finished_at.as_json)
             expect_json('status', 'failed')
+            expect_json('url', url)
           end
         end
         # rubocop:enable RSpec/MultipleMemoizedHelpers
@@ -238,6 +248,8 @@
           it 'returns `finished` and URL' do
             expect { perform_request }.not_to change(EnvelopeDownload, :count)
             expect_status(:ok)
+            expect_json_sizes(3)
+            expect_json('finished_at', envelope_download.finished_at.as_json)
             expect_json('status', 'finished')
             expect_json('url', url)
           end
@@ -280,17 +292,26 @@
     end
 
     context 'with valid token' do
+      let(:now) { Time.current.change(usec: 0) }
+
       context 'without envelope download' do # rubocop:todo RSpec/NestedGroups
         # rubocop:todo RSpec/MultipleExpectations
-        it 'creates new pending download and enqueues job' do
+        it 'creates new pending download and enqueues job' do # rubocop:todo RSpec/ExampleLength
           # rubocop:enable RSpec/MultipleExpectations
-          expect { perform_request }.to change(EnvelopeDownload, :count).by(1)
+          travel_to now do
+            expect { perform_request }.to change(EnvelopeDownload, :count).by(1)
+          end
+
           expect_status(:created)
 
           envelope_download = EnvelopeDownload.last
           expect(envelope_download.envelope_community).to eq(envelope_community)
           expect(envelope_download.status).to eq('pending')
 
+          expect_json_sizes(2)
+          expect_json('enqueued_at', now.as_json)
+          expect_json('status', 'pending')
+
           expect(ActiveJob::Base.queue_adapter.enqueued_jobs.size).to eq(1)
 
           job = ActiveJob::Base.queue_adapter.enqueued_jobs.first
@@ -299,18 +320,27 @@
         end
       end
 
+      # rubocop:todo RSpec/MultipleMemoizedHelpers
       context 'with envelope download' do # rubocop:todo RSpec/NestedGroups
         let!(:envelope_download) do
           create(:envelope_download, :finished, envelope_community:)
         end
 
         it 'enqueues job for existing download' do
-          expect { perform_request }.to not_change(EnvelopeDownload, :count)
-            .and enqueue_job(DownloadEnvelopesJob).with(envelope_download.id)
+          travel_to now do
+            expect { perform_request }.to not_change(EnvelopeDownload, :count)
+              .and enqueue_job(DownloadEnvelopesJob).with(envelope_download.id)
+          end
+
           expect_status(:created)
           expect(envelope_download.reload.status).to eq('pending')
+
+          expect_json_sizes(2)
+          expect_json('enqueued_at', now.as_json)
+          expect_json('status', 'pending')
         end
       end
+      # rubocop:enable RSpec/MultipleMemoizedHelpers
     end
   end
 end

spec/factories/envelope_downloads.rb

@@ -1,24 +1,25 @@
 FactoryBot.define do
   factory :envelope_download do
+    enqueued_at { Time.current.change(usec: 0) }
     # rubocop:todo FactoryBot/FactoryAssociationWithStrategy
     envelope_community { create(:envelope_community, :with_random_name) }
     # rubocop:enable FactoryBot/FactoryAssociationWithStrategy
 
     trait :failed do
-      finished_at { Time.current }
+      finished_at { Time.current.change(usec: 0) }
       internal_error_message { Faker::Lorem.sentence }
-      started_at { Time.current }
+      started_at { Time.current.change(usec: 0) }
       status { :finished }
     end
 
     trait :finished do
-      finished_at { Time.current }
-      started_at { Time.current }
+      finished_at { Time.current.change(usec: 0) }
+      started_at { Time.current.change(usec: 0) }
       status { :finished }
     end
 
     trait :in_progress do
-      started_at { Time.current }
+      started_at { Time.current.change(usec: 0) }
       status { :in_progress }
     end
   end