shoryuken 7.0.0.alpha2 → 7.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 962cd757e952228ae34b93d4fa479c623a2cc60e84aa15bbd40645546bb58a59
-  data.tar.gz: 2313131f61b7299be011498977450cd8eb06392fa176d095111a7195a86eb033
+  metadata.gz: 44ec6add623605d696f0a4151aab96d37331250fa66a6b804edea13b06a2b816
+  data.tar.gz: efe2733bb86113a83b7788041262421c84ee4c50a47718b32ef8bdb505fa15fe
 SHA512:
-  metadata.gz: ffc81ebcf932be68803e4745bdd0070c67f65bfd1a638ef455cb4339d3f5dc3803b11ff11de9bb2892f3205ec7cff81ce2f807700fa3f0869a683ffc9255541e
-  data.tar.gz: d4881cd3e103f290bbfefa48e4d20d8537e4d4aa32d269567bf18b1a77545fc188cc4fe90876a7053c29c527ff94d614d46713e504f7f0f6d117ee25d0a6e779
+  metadata.gz: 84daafb107ff842e74cdb3872885b6c01ea34d95a5eaf6cf2efeeb3398bc835e570ea5b7f93b9451e4e5841d1d27b53ea35db677a4ddd78cdd75c13b417eebae
+  data.tar.gz: ad0dcb19240b8179c62bb6b74e23b1801d1f0d671a0f72a5b26d74a0bbd1f47158abd57a6cee091d88fe903ea91ce09afd34702f9086cb4b2cf14a9a17397509

data/.github/workflows/specs.yml

@@ -45,20 +45,17 @@ jobs:
     name: Rails Specs
     strategy:
       matrix:
-        rails: ['7.0', '7.1', '7.2', '8.0']
+        rails: ['7.2', '8.0', '8.1']
         include:
-          - rails: '7.0'
-            ruby: '3.1'
-            gemfile: gemfiles/rails_7_0.gemfile
-          - rails: '7.1'
-            ruby: '3.2'
-            gemfile: gemfiles/rails_7_1.gemfile
           - rails: '7.2'
-            ruby: '3.3'
+            ruby: '3.2'
             gemfile: gemfiles/rails_7_2.gemfile
           - rails: '8.0'
-            ruby: '3.4'
+            ruby: '3.3'
             gemfile: gemfiles/rails_8_0.gemfile
+          - rails: '8.1'
+            ruby: '3.4'
+            gemfile: gemfiles/rails_8_1.gemfile
     runs-on: ubuntu-latest
     env:
       BUNDLE_GEMFILE: ${{ matrix.gemfile }}
@@ -73,3 +70,19 @@ jobs:
 
       - name: Run Rails specs
         run: bundle exec rake spec:rails
+
+  ci-success:
+    name: CI Success
+    runs-on: ubuntu-latest
+    if: always()
+    needs:
+      - all_specs
+      - rails_specs
+    steps:
+      - name: Check all jobs passed
+        if: |
+          contains(needs.*.result, 'failure') ||
+          contains(needs.*.result, 'cancelled') ||
+          contains(needs.*.result, 'skipped')
+        run: exit 1
+      - run: echo "All CI checks passed!"

data/Appraisals

@@ -1,15 +1,3 @@
-appraise 'rails_7_0' do
-  group :test do
-    gem 'activejob', '~> 7.0'
-  end
-end
-
-appraise 'rails_7_1' do
-  group :test do
-    gem 'activejob', '~> 7.1'
-  end
-end
-
 appraise 'rails_7_2' do
   group :test do
     gem 'activejob', '~> 7.2'
@@ -21,3 +9,9 @@ appraise 'rails_8_0' do
     gem 'activejob', '~> 8.0'
   end
 end
+
+appraise 'rails_8_1' do
+  group :test do
+    gem 'activejob', '~> 8.1'
+  end
+end

data/CHANGELOG.md

@@ -1,4 +1,18 @@
 ## [7.0.0] - Unreleased
+- Enhancement: Add ActiveJob Continuations support (Rails 8.1+)
+  - Implements `stopping?` method in ActiveJob adapters to signal graceful shutdown
+  - Enables jobs to checkpoint progress and resume after interruption
+  - Handles past timestamps correctly (SQS treats negative delays as immediate delivery)
+  - Tracks shutdown state in Launcher via `stopping?` flag
+  - Leverages existing Shoryuken shutdown lifecycle (stop/stop! methods)
+  - Includes comprehensive integration tests with continuable jobs
+  - See Rails PR #55127 for more details on ActiveJob Continuations
+
+- Breaking: Remove support for Rails versions older than 7.2
+  - Rails 7.0 and 7.1 have reached end-of-life and are no longer supported
+  - Supported versions: Rails 7.2, 8.0, and 8.1
+  - Users on older Rails versions should upgrade or remain on Shoryuken 6.x
+
 - Enhancement: Replace Concurrent::AtomicFixnum with pure Ruby AtomicCounter
   - Removes external dependency on concurrent-ruby for atomic fixnum operations
   - Introduces Shoryuken::Helpers::AtomicCounter as a thread-safe alternative using Mutex

data/bin/cli/sqs.rb

@@ -13,7 +13,7 @@ module Shoryuken
       no_commands do
         def normalize_dump_message(message)
           # symbolize_keys is needed for keeping it compatible with `requeue`
-          attributes = message[:attributes].symbolize_keys
+          attributes = message[:attributes].transform_keys(&:to_sym)
 
           # See https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_MessageAttributeValue.html
           # The `string_list_values` and `binary_list_values` are not implemented. Reserved for future use.

data/bin/shoryuken

@@ -29,7 +29,7 @@ module Shoryuken
       method_option :delay,       aliases: '-D', type: :numeric,
                                   desc: 'Number of seconds to pause fetching from an empty queue'
       def start
-        opts = options.to_h.symbolize_keys
+        opts = options.to_h.transform_keys(&:to_sym)
 
         say '[DEPRECATED] Please use --config instead of --config-file', :yellow if opts[:config_file]
 

data/gemfiles/rails_7_2.gemfile

@@ -1,19 +1,19 @@
 # This file was generated by Appraisal
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 group :test do
-  gem 'activejob', '~> 7.2'
-  gem 'httparty'
-  gem 'multi_xml'
-  gem 'simplecov'
-  gem 'warning'
+  gem "activejob", "~> 7.2"
+  gem "httparty"
+  gem "multi_xml"
+  gem "simplecov"
+  gem "warning"
 end
 
 group :development do
-  gem 'appraisal', git: 'https://github.com/thoughtbot/appraisal.git'
-  gem 'pry-byebug'
-  gem 'rubocop'
+  gem "appraisal", git: "https://github.com/thoughtbot/appraisal.git"
+  gem "pry-byebug"
+  gem "rubocop"
 end
 
-gemspec path: '../'
+gemspec path: "../"

data/gemfiles/rails_8_0.gemfile

@@ -1,19 +1,19 @@
 # This file was generated by Appraisal
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 group :test do
-  gem 'activejob', '~> 8.0'
-  gem 'httparty'
-  gem 'multi_xml'
-  gem 'simplecov'
-  gem 'warning'
+  gem "activejob", "~> 8.0"
+  gem "httparty"
+  gem "multi_xml"
+  gem "simplecov"
+  gem "warning"
 end
 
 group :development do
-  gem 'appraisal', git: 'https://github.com/thoughtbot/appraisal.git'
-  gem 'pry-byebug'
-  gem 'rubocop'
+  gem "appraisal", git: "https://github.com/thoughtbot/appraisal.git"
+  gem "pry-byebug"
+  gem "rubocop"
 end
 
-gemspec path: '../'
+gemspec path: "../"

data/gemfiles/rails_8_1.gemfile

@@ -0,0 +1,19 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+group :test do
+  gem "activejob", "~> 8.1"
+  gem "httparty"
+  gem "multi_xml"
+  gem "simplecov"
+  gem "warning"
+end
+
+group :development do
+  gem "appraisal", git: "https://github.com/thoughtbot/appraisal.git"
+  gem "pry-byebug"
+  gem "rubocop"
+end
+
+gemspec path: "../"

data/lib/shoryuken/extensions/active_job_adapter.rb

@@ -37,6 +37,19 @@ module ActiveJob
         true
       end
 
+      # Indicates whether Shoryuken is in the process of shutting down.
+      #
+      # This method is required for ActiveJob Continuations support (Rails 8.1+).
+      # When true, it signals to jobs that they should checkpoint their progress
+      # and gracefully interrupt execution to allow for resumption after restart.
+      #
+      # @return [Boolean] true if Shoryuken is shutting down, false otherwise
+      # @see https://github.com/rails/rails/pull/55127 Rails ActiveJob Continuations
+      def stopping?
+        launcher = Shoryuken::Runner.instance.launcher
+        launcher&.stopping? || false
+      end
+
       def enqueue(job, options = {}) # :nodoc:
         register_worker!(job)
 

data/lib/shoryuken/helpers/timer_task.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Helpers
+    # A thread-safe timer task implementation.
+    # Drop-in replacement for Concurrent::TimerTask without external dependencies.
+    class TimerTask
+      def initialize(execution_interval:, &task)
+        raise ArgumentError, 'A block must be provided' unless block_given?
+
+        @execution_interval = Float(execution_interval)
+        raise ArgumentError, 'execution_interval must be positive' if @execution_interval <= 0
+
+        @task = task
+        @mutex = Mutex.new
+        @thread = nil
+        @running = false
+        @killed = false
+      end
+
+      # Start the timer task execution
+      def execute
+        @mutex.synchronize do
+          return self if @running || @killed
+
+          @running = true
+          @thread = Thread.new { run_timer_loop }
+        end
+        self
+      end
+
+      # Stop and kill the timer task
+      def kill
+        @mutex.synchronize do
+          return false if @killed
+
+          @killed = true
+          @running = false
+
+          @thread.kill if @thread&.alive?
+        end
+        true
+      end
+
+      private
+
+      def run_timer_loop
+        until @killed
+          sleep(@execution_interval)
+          break if @killed
+
+          begin
+            @task.call
+          rescue => e
+            # Log the error but continue running
+            # This matches the behavior of Concurrent::TimerTask
+            warn "TimerTask execution error: #{e.message}"
+            warn e.backtrace.join("\n") if e.backtrace
+          end
+        end
+      ensure
+        @mutex.synchronize { @running = false }
+      end
+    end
+  end
+end

data/lib/shoryuken/launcher.rb

@@ -6,6 +6,18 @@ module Shoryuken
 
     def initialize
       @managers = create_managers
+      @stopping = false
+    end
+
+    # Indicates whether the launcher is in the process of stopping.
+    #
+    # This flag is set to true when either {#stop} or {#stop!} is called,
+    # and is used by ActiveJob adapters to signal jobs that they should
+    # checkpoint and prepare for graceful shutdown.
+    #
+    # @return [Boolean] true if stopping, false otherwise
+    def stopping?
+      @stopping
     end
 
     def start
@@ -16,6 +28,7 @@ module Shoryuken
     end
 
     def stop!
+      @stopping = true
       initiate_stop
 
       # Don't await here so the timeout below is not delayed
@@ -28,6 +41,7 @@ module Shoryuken
     end
 
     def stop
+      @stopping = true
       fire_event(:quiet, true)
 
       initiate_stop

data/lib/shoryuken/logging/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Logging
+    # Base formatter class that provides common functionality for Shoryuken log formatters.
+    # Provides thread ID generation and context management.
+    class Base < ::Logger::Formatter
+      # Generates a thread ID for the current thread.
+      # Uses a combination of thread object_id and process ID to create a unique identifier.
+      #
+      # @return [String] A base36-encoded thread identifier
+      def tid
+        Thread.current['shoryuken_tid'] ||= (Thread.current.object_id ^ ::Process.pid).to_s(36)
+      end
+
+      # Returns the current logging context as a formatted string.
+      # Context is set using {Shoryuken::Logging.with_context}.
+      #
+      # @return [String] Formatted context string or empty string if no context
+      def context
+        c = Thread.current[:shoryuken_context]
+        c ? " #{c}" : ''
+      end
+    end
+  end
+end

data/lib/shoryuken/logging/pretty.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Logging
+    # A pretty log formatter that includes timestamps, process ID, thread ID,
+    # context information, and severity in a human-readable format.
+    #
+    # Output format: "TIMESTAMP PID TID-THREAD_ID CONTEXT SEVERITY: MESSAGE"
+    #
+    # @example Output
+    #   2023-08-15T10:30:45Z 12345 TID-abc123 MyWorker/queue1/msg-456 INFO: Processing message
+    class Pretty < Base
+      # Formats a log message with timestamp and full context information.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param _program_name [String] Program name (unused)
+      # @param message [String] The log message
+      # @return [String] Formatted log entry with newline
+      def call(severity, time, _program_name, message)
+        "#{time.utc.iso8601} #{Process.pid} TID-#{tid}#{context} #{severity}: #{message}\n"
+      end
+    end
+  end
+end

data/lib/shoryuken/logging/without_timestamp.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Logging
+    # A log formatter that excludes timestamps from output.
+    # Useful for environments where timestamps are added by external logging systems.
+    #
+    # Output format: "pid=PID tid=THREAD_ID CONTEXT SEVERITY: MESSAGE"
+    #
+    # @example Output
+    #   pid=12345 tid=abc123 MyWorker/queue1/msg-456 INFO: Processing message
+    class WithoutTimestamp < Base
+      # Formats a log message without timestamp information.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param _time [Time] Timestamp (unused)
+      # @param _program_name [String] Program name (unused)
+      # @param message [String] The log message
+      # @return [String] Formatted log entry with newline
+      def call(severity, _time, _program_name, message)
+        "pid=#{Process.pid} tid=#{tid}#{context} #{severity}: #{message}\n"
+      end
+    end
+  end
+end

data/lib/shoryuken/logging.rb

@@ -2,32 +2,12 @@
 
 require 'time'
 require 'logger'
+require_relative 'logging/base'
+require_relative 'logging/pretty'
+require_relative 'logging/without_timestamp'
 
 module Shoryuken
   module Logging
-    class Base < ::Logger::Formatter
-      def tid
-        Thread.current['shoryuken_tid'] ||= (Thread.current.object_id ^ ::Process.pid).to_s(36)
-      end
-
-      def context
-        c = Thread.current[:shoryuken_context]
-        c ? " #{c}" : ''
-      end
-    end
-
-    class Pretty < Base
-      # Provide a call() method that returns the formatted message.
-      def call(severity, time, _program_name, message)
-        "#{time.utc.iso8601} #{Process.pid} TID-#{tid}#{context} #{severity}: #{message}\n"
-      end
-    end
-
-    class WithoutTimestamp < Base
-      def call(severity, _time, _program_name, message)
-        "pid=#{Process.pid} tid=#{tid}#{context} #{severity}: #{message}\n"
-      end
-    end
 
     def self.with_context(msg)
       Thread.current[:shoryuken_context] = msg

data/lib/shoryuken/message.rb

@@ -1,9 +1,70 @@
 # frozen_string_literal: true
 
 module Shoryuken
+  # Represents an SQS message received by a Shoryuken worker.
+  # This class wraps the raw AWS SQS message data and provides convenient methods
+  # for interacting with the message, including deletion and visibility timeout management.
+  #
+  # Message instances are automatically created by Shoryuken and passed to your
+  # worker's `perform` method as the first argument.
+  #
+  # @example Basic worker with message handling
+  #   class MyWorker
+  #     include Shoryuken::Worker
+  #     shoryuken_options queue: 'my_queue'
+  #
+  #     def perform(sqs_msg, body)
+  #       puts "Processing message #{sqs_msg.message_id}"
+  #       puts "Message body: #{body}"
+  #       puts "Queue: #{sqs_msg.queue_name}"
+  #
+  #       # Process the message...
+  #
+  #       # Delete the message when done (if auto_delete is false)
+  #       sqs_msg.delete unless auto_delete?
+  #     end
+  #   end
+  #
+  # @example Working with message attributes
+  #   def perform(sqs_msg, body)
+  #     # Access standard SQS attributes
+  #     sender_id = sqs_msg.attributes['SenderId']
+  #     sent_timestamp = sqs_msg.attributes['SentTimestamp']
+  #
+  #     # Access custom message attributes
+  #     priority = sqs_msg.message_attributes['Priority']&.[]('StringValue')
+  #     user_id = sqs_msg.message_attributes['UserId']&.[]('StringValue')
+  #   end
   class Message
     extend Forwardable
 
+    # @!method message_id
+    #   Returns the unique SQS message ID.
+    #   @return [String] The message ID assigned by SQS
+    #
+    # @!method receipt_handle
+    #   Returns the receipt handle needed for deleting or modifying the message.
+    #   @return [String] The receipt handle for this message
+    #
+    # @!method md5_of_body
+    #   Returns the MD5 hash of the message body.
+    #   @return [String] MD5 hash of the message body
+    #
+    # @!method body
+    #   Returns the raw message body as received from SQS.
+    #   @return [String] The raw message body
+    #
+    # @!method attributes
+    #   Returns the SQS message attributes (system attributes).
+    #   @return [Hash] System attributes like SenderId, SentTimestamp, etc.
+    #
+    # @!method md5_of_message_attributes
+    #   Returns the MD5 hash of the message attributes.
+    #   @return [String] MD5 hash of message attributes
+    #
+    # @!method message_attributes
+    #   Returns custom message attributes set by the sender.
+    #   @return [Hash] Custom message attributes with typed values
     def_delegators(:data,
                    :message_id,
                    :receipt_handle,
@@ -13,8 +74,24 @@ module Shoryuken
                    :md5_of_message_attributes,
                    :message_attributes)
 
-    attr_accessor :client, :queue_url, :queue_name, :data
+    # @return [Aws::SQS::Client] The SQS client used for message operations
+    attr_accessor :client
 
+    # @return [String] The URL of the SQS queue this message came from
+    attr_accessor :queue_url
+
+    # @return [String] The name of the queue this message came from
+    attr_accessor :queue_name
+
+    # @return [Aws::SQS::Types::Message] The raw SQS message data
+    attr_accessor :data
+
+    # Creates a new Message instance wrapping SQS message data.
+    #
+    # @param client [Aws::SQS::Client] The SQS client for message operations
+    # @param queue [Shoryuken::Queue] The queue this message came from
+    # @param data [Aws::SQS::Types::Message] The raw SQS message data
+    # @api private
     def initialize(client, queue, data)
       self.client     = client
       self.data       = data
@@ -22,6 +99,12 @@ module Shoryuken
       self.queue_name = queue.name
     end
 
+    # Deletes this message from the SQS queue.
+    # Once deleted, the message will not be redelivered and cannot be retrieved again.
+    # This is typically called after successful message processing when auto_delete is disabled.
+    #
+    # @return [Aws::SQS::Types::DeleteMessageResult] The deletion result
+    # @raise [Aws::SQS::Errors::ServiceError] If the deletion fails
     def delete
       client.delete_message(
         queue_url: queue_url,
@@ -29,12 +112,42 @@ module Shoryuken
       )
     end
 
+    # Changes the visibility timeout of this message with additional options.
+    # This allows you to hide the message from other consumers for a longer or shorter period.
+    #
+    # @param options [Hash] Options to pass to change_message_visibility
+    # @option options [Integer] :visibility_timeout New visibility timeout in seconds
+    # @return [Aws::SQS::Types::ChangeMessageVisibilityResult] The change result
+    # @raise [Aws::SQS::Errors::ServiceError] If the change fails
+    #
+    # @example Extending visibility with additional options
+    #   sqs_msg.change_visibility(visibility_timeout: 300)
+    #
+    # @see #visibility_timeout= For a simpler interface
     def change_visibility(options)
       client.change_message_visibility(
         options.merge(queue_url: queue_url, receipt_handle: data.receipt_handle)
       )
     end
 
+    # Sets the visibility timeout for this message.
+    # This is a convenience method for changing only the visibility timeout.
+    #
+    # @param timeout [Integer] New visibility timeout in seconds (0-43200)
+    # @return [Aws::SQS::Types::ChangeMessageVisibilityResult] The change result
+    # @raise [Aws::SQS::Errors::ServiceError] If the change fails
+    #
+    # @example Extending processing time
+    #   def perform(sqs_msg, body)
+    #     if complex_processing_needed?(body)
+    #       sqs_msg.visibility_timeout = 1800  # 30 minutes
+    #     end
+    #
+    #     process_message(body)
+    #   end
+    #
+    # @example Making message immediately visible again
+    #   sqs_msg.visibility_timeout = 0  # Make visible immediately
     def visibility_timeout=(timeout)
       client.change_message_visibility(
         queue_url: queue_url,