aws-activejob-sqs 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 733e9f1e9e56f0bf7052035f5b983890a9a29ddc67d668b5a83e609411151375
-  data.tar.gz: cb5c4d63e714b6abbf79c947a39c2f2176fd1be5631baf775383ac2d3f01e7f8
+  metadata.gz: 87f80b0bcacdf1a7121b918c0e126427f98ff530492ba1b086886e04de4e58e3
+  data.tar.gz: 29c3445f74019e920a6b3aa8999f756ea728bc5a2200fd56927e31eca2ed51dc
 SHA512:
-  metadata.gz: 789be54e545ee534377e3e2129911a35a789df7f5b6de0791f075e21beb8f5fcbc804430f2f4b98518ea97559939453594d8f8f47724c0f6f475410456f1d247
-  data.tar.gz: ebb107e7a92d5ec1643f709b6d913ea8a47ee712e70981760ab87517e28c0c9673a4aa5d79f4d99b229e3799a12825744d846388e6fcddb721b96a57d395c052
+  metadata.gz: 5f6f6856fbf896f9af13fa6c03e24d0de80f18ef4fe0edf757e8e952b334ed71e14130a6a340025114380049ff5d605678168d207cbf367bee74d250d933542e
+  data.tar.gz: d3efaa6e454968548d296ab448ad5e18c0940ce95b2969cafa9ced9703b91dbf040534bcc07591ba52961d4732b7ed3777c35eebdd24cd6835e9a76e9b32e712

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+1.2.0 (2026-08-17)
+------------------
+
+* Feature - Report a dropped job to the Rails error reporter and add an optional `permanent_failure_handler` so apps can keep unresolvable jobs on the queue for redelivery instead of losing them (#39).
+
+* Issue - `perform_all_later` no longer partially enqueues a batch before raising when one of the jobs has a delay on a FIFO queue (#40).
+
 1.1.1 (2026-08-12)
 ------------------
 

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

data/lib/active_job/queue_adapters/sqs_adapter.rb

@@ -26,6 +26,12 @@ module ActiveJob
       end
 
       def enqueue_all(jobs)
+        jobs.each do |job|
+          next unless job.scheduled_at
+
+          validate_fifo_delay!(job, Params.assured_delay_seconds(job.scheduled_at))
+        end
+
         enqueued_count = 0
         jobs.group_by(&:queue_name).each do |queue_name, same_queue_jobs|
           enqueued_count += enqueue_batches(queue_name, same_queue_jobs)
@@ -58,11 +64,7 @@ module ActiveJob
       def batch_entry(job)
         entry = Params.new(job, nil).entry
         entry[:id] = job.job_id
-        if job.scheduled_at
-          delay = Params.assured_delay_seconds(job.scheduled_at)
-          validate_fifo_delay!(job, delay)
-          entry[:delay_seconds] = delay
-        end
+        entry[:delay_seconds] = Params.assured_delay_seconds(job.scheduled_at) if job.scheduled_at
         entry
       end
 

data/lib/aws/active_job/sqs/configuration.rb

@@ -48,7 +48,7 @@ module Aws
       # {GLOBAL_ENV_CONFIGS}.  For supported queue specific ENV configurations
       # see: {QUEUE_ENV_CONFIGS}.
       #
-      class Configuration
+      class Configuration # rubocop:disable Metrics/ClassLength
         # Default configuration options
         # @api private
         DEFAULTS = {
@@ -125,6 +125,16 @@ module Aws
         #   receive settings). Retries provided by this mechanism are
         #   after any retries configured on the job with `retry_on`.
         #
+        # @option options [Callable] :permanent_failure_handler a handler called
+        #   as `(error, sqs_message)` just before the poller deletes a
+        #   permanently-failed message (unparseable body or an
+        #   {InvalidJobClassError}). Return normally to delete and report the
+        #   drop; `throw :skip_delete` to keep the message on the queue for
+        #   redelivery and skip the report. Intended for recovering a
+        #   {JobClassNotDefinedError} raised mid rolling-deploy; throwing for
+        #   other causes will pin an unprocessable message on the queue. Poller
+        #   only; the Lambda handler ignores it. See the README for details.
+        #
         # @option options [ActiveSupport::Logger] :logger Logger to use
         #   for the poller.
         #
@@ -177,7 +187,7 @@ module Aws
 
         # @api private
         attr_writer :max_messages, :message_group_id, :visibility_timeout,
-                    :poller_error_handler, :client
+                    :poller_error_handler, :permanent_failure_handler, :client
 
         def excluded_deduplication_keys=(keys)
           @excluded_deduplication_keys = keys.map(&:to_s) | ['job_id']
@@ -188,6 +198,11 @@ module Aws
           @poller_error_handler
         end
 
+        def permanent_failure_handler(&block)
+          @permanent_failure_handler = block if block_given?
+          @permanent_failure_handler
+        end
+
         def client
           @client ||= begin
             client = Aws::SQS::Client.new

data/lib/aws/active_job/sqs/executor.rb

@@ -85,7 +85,7 @@ module Aws
           end
         end
 
-        def execute_task(message)
+        def execute_task(message) # rubocop:disable Metrics/MethodLength
           job = JobRunner.new(message)
           @logger.info("Running job: #{job.id}[#{job.class_name}]")
           job.run
@@ -94,25 +94,62 @@ module Aws
           # An unparseable body is a permanent failure: the message content is
           # immutable, so re-parsing it on redelivery can never succeed. Log and
           # delete it so it does not redeliver indefinitely.
-          drop_permanent_failure(message, "Unable to parse message body: #{message.data.body}. Error: #{e}.")
+          parser_msg = "Unable to parse message body: #{message.data.body}. Error: #{e}."
+          drop_permanent_failure(message, e, parser_msg)
         rescue InvalidJobClassError => e
           # A bad job class is a permanent failure: redelivering it can never
           # succeed and, on the default config, would crash-loop the poller.
           # Log the forensic detail (the message can't be inspected in a DLQ
           # once deleted) and delete it so it does not redeliver.
-          drop_permanent_failure(message, "Rejecting message #{message.message_id}: #{e}. " \
-                                          "Body: #{message.data.body}. Deleting so it does not redeliver.")
+          invalid_msg =
+            "Rejecting message #{message.message_id}: #{e}. " \
+            "Body: #{message.data.body}. Deleting so it does not redeliver."
+          drop_permanent_failure(message, e, invalid_msg)
         rescue StandardError => e
           handle_standard_error(e, job, message)
         ensure
           @task_complete.set
         end
 
-        # Log a permanently-failed message and delete it so SQS does not
-        # redeliver it (which, on the default config, would crash-loop the poller).
-        def drop_permanent_failure(message, log_message)
+        # Handle a permanently-failed message (unparseable body or invalid job
+        # class). Always logged. A dropped message is also reported to the
+        # error tracker so the loss is visible beyond the logs, then deleted so
+        # SQS won't redeliver. A configured +permanent_failure_handler+ can
+        # +throw :skip_delete+ to keep the message on the queue for redelivery
+        # instead, in which case it is neither reported nor deleted.
+        def drop_permanent_failure(message, error, log_message)
           @logger.error log_message
-          message.delete
+
+          handler = Aws::ActiveJob::SQS.config.permanent_failure_handler
+          unless handler
+            report_permanent_failure(error, message)
+            return message.delete
+          end
+
+          catch(:skip_delete) do
+            begin
+              handler.call(error, message)
+            rescue StandardError => e
+              @logger.error "permanent_failure_handler raised: #{e}"
+            end
+            report_permanent_failure(error, message)
+            message.delete
+          end
+        end
+
+        # Report a permanently-dropped job to the application's error tracker
+        # via Rails' error reporter (Rails 7+), if available, so the loss
+        # surfaces in whatever tracker the app uses. A no-op outside Rails.
+        # Only called when the message is actually deleted, so a message kept
+        # for redelivery via +:skip_delete+ is not reported as dropped.
+        def report_permanent_failure(error, message)
+          return unless defined?(::Rails) && ::Rails.respond_to?(:error)
+
+          ::Rails.error.report(
+            error,
+            handled: true,
+            context: { message_id: message.message_id, body: message.data.body }
+          )
         end
 
         def handle_standard_error(error, job, message)

data/lib/aws/active_job/sqs/job_runner.rb

@@ -11,6 +11,16 @@ module Aws
       # deletes it rather than letting it redeliver.
       class InvalidJobClassError < StandardError; end
 
+      # Raised when a message names a class not defined in this process.
+      #
+      # Recoverable in a way other {InvalidJobClassError} causes (malformed
+      # name, disallowed class, non-job class) aren't: during a rolling deploy,
+      # redelivering to a newer worker that has the class may succeed. Subclasses
+      # {InvalidJobClassError} so existing rescues still catch it; a
+      # +permanent_failure_handler+ can single it out and keep the message on
+      # the queue for redelivery.
+      class JobClassNotDefinedError < InvalidJobClassError; end
+
       # @api private
       class JobRunner
         # A job class name is an (optionally namespaced) constant path and
@@ -65,12 +75,14 @@ module Aws
         # segment must be defined directly on the preceding one: a name such
         # as 'SomeJob::Foo' cannot resolve Foo from SomeJob's ancestors when
         # SomeJob itself does not define it. NameError is treated as a
-        # rejection rather than propagated: an unknown class is the same
-        # permanent failure as a disallowed one.
+        # rejection rather than propagated, but as the recoverable
+        # {JobClassNotDefinedError} subclass: an undefined class may just be
+        # missing from this process (e.g. mid rolling-deploy), unlike a
+        # malformed or disallowed name.
         def constantize_job_class(name)
           Object.const_get(name, false)
         rescue NameError
-          raise InvalidJobClassError, "#{name} is not defined"
+          raise JobClassNotDefinedError, "Job Class: #{name} is not defined"
         end
 
         # The allowlist may be configured as an Array of Class values (in code),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aws-activejob-sqs
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Amazon Web Services