Form 526 Document Upload - Lighthouse status polling system

app/models/lighthouse526_document_upload.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class Lighthouse526DocumentUpload < ApplicationRecord
+  include AASM
+
+  VETERAN_UPLOAD_DOCUMENT_TYPE = 'Veteran Upload'
+  BDD_INSTRUCTIONS_DOCUMENT_TYPE = 'BDD Instructions'
+  FORM_0781_DOCUMENT_TYPE = 'Form 0781'
+  FORM_0781A_DOCUMENT_TYPE = 'Form 0781a'
+
+  VALID_DOCUMENT_TYPES = [
+    BDD_INSTRUCTIONS_DOCUMENT_TYPE,
+    FORM_0781_DOCUMENT_TYPE,
+    FORM_0781A_DOCUMENT_TYPE,
+    VETERAN_UPLOAD_DOCUMENT_TYPE
+  ].freeze
+
+  belongs_to :form526_submission
+  belongs_to :form_attachment, optional: true
+
+  validates :lighthouse_document_request_id, presence: true
+  validates :document_type, presence: true, inclusion: { in: VALID_DOCUMENT_TYPES }
+
+  # Veteran Uploads must reference a FormAttachment record as that is where we store a Veteran-submitted file's
+  # metadata, including S3 URL
+  validates :form_attachment, presence: true, if: :veteran_upload?
+
+  # Window for polling Lighthouse for the status of an upload
+  scope :status_update_required, -> { where('status_last_polled_at < ?', 1.day.ago.utc).or(where(status_last_polled_at: nil)) }
+
+  aasm do
+    state :pending, initial: true
+    state :completed, :failed
+
+    event :complete do
+      transitions from: :pending, to: :completed, guard: :end_time_saved?
+    end
+
+    event :fail do
+      transitions from: :pending, to: :failed, guard: %i[end_time_saved? error_message_saved?]
+    end
+  end
+
+  private
+
+  def veteran_upload?
+    document_type == VETERAN_UPLOAD_DOCUMENT_TYPE
+  end
+
+  def end_time_saved?
+    lighthouse_processing_ended_at != nil
+  end
+
+  def error_message_saved?
+    error_message != nil
+  end
+end

app/sidekiq/lighthouse/form_526_document_upload_polling_job.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'lighthouse/benefits_documents/form526/documents_status_polling_service'
+require 'lighthouse/benefits_documents/form526/update_documents_status_service'
+
+module Lighthouse
+  class Form526DocumentUploadPollingJob
+    include Sidekiq::Job
+    # This job runs every 24 hours
+    # Only retry within that window to avoid polling the same documents twice
+    # 13 retries = retry for ~17 hours
+    # See Sidekiq documentation for retry algorithm
+    # https://github.com/sidekiq/sidekiq/wiki/Error-Handling#automatic-job-retry
+    sidekiq_options retry: 13
+
+    POLLED_BATCH_DOCUMENT_COUNT = 100
+    STATSD_KEY_PREFIX = 'worker.lighthouse.poll_form_526_document_uploads'
+
+    sidekiq_retries_exhausted do |msg, _ex|
+      StatsD.increment("#{STATSD_KEY_PREFIX}.exhausted")
+
+      Rails.logger.warn(
+        'Lighthouse::Form526DocumentUploadPollingJob retries exhausted',
+        {
+          job_id: msg['jid'],
+          error_class: msg['error_class'],
+          error_message: msg['error_message'],
+          timestamp: Time.now.utc
+        }
+      )
+    end
+
+    def perform
+      Lighthouse526DocumentUpload.pending.status_update_required.in_batches(
+        of: POLLED_BATCH_DOCUMENT_COUNT
+      ) do |document_batch|
+        lighthouse_document_request_ids = document_batch.pluck(:lighthouse_document_request_id)
+        response = BenefitsDocuments::Form526::DocumentsStatusPollingService.call(lighthouse_document_request_ids)
+
+        if response.status == 200
+          BenefitsDocuments::Form526::UpdateDocumentsStatusService.call(document_batch, response.body)
+        else
+          StatsD.increment("#{STATSD_KEY_PREFIX}.polling_error")
+
+          Rails.logger.warn(
+            'Lighthouse::Form526DocumentUploadPollingJob status endpoint failure',
+            {
+              response_status: response.status,
+              response_body: response.body,
+              lighthouse_document_request_ids:,
+              timestamp: Time.now.utc
+            }
+          )
+        end
+      end
+    end
+  end
+end

db/migrate/20240304203337_create_lighthouse526_document_uploads.rb

@@ -0,0 +1,18 @@
+class CreateLighthouse526DocumentUploads < ActiveRecord::Migration[7.0]
+  def change
+    create_table :lighthouse526_document_uploads do |t|
+      t.references :form526_submission, foreign_key: true, null: false
+      t.references :form_attachment, foreign_key: true
+      t.string :lighthouse_document_request_id, null: false
+      t.string :aasm_state, index: true
+      t.string :document_type
+      t.datetime :lighthouse_processing_started_at
+      t.datetime :lighthouse_processing_ended_at
+      t.datetime :status_last_polled_at, index: true
+      t.jsonb :error_message
+      t.jsonb :last_status_response
+
+      t.timestamps
+    end
+  end
+end