postburner 1.0.0.pre.13 → 1.0.0.pre.14

data/lib/postburner/strategies/{nice_queue.rb → default_queue.rb}

@@ -4,13 +4,13 @@ module Postburner
   # Default production queue strategy with graceful handling of premature execution.
   #
   # This is the recommended production strategy and the default for Postburner.
-  # Unlike the strict {Queue} strategy, NiceQueue automatically re-inserts jobs
+  # Unlike the strict {StrictQueue} strategy, DefaultQueue automatically re-inserts jobs
   # that are executed before their scheduled run_at time, ensuring they run at
   # the correct time without raising exceptions.
   #
   # @note This is the DEFAULT strategy set on Postburner initialization
   #
-  # ## When to Use NiceQueue
+  # ## When to Use DefaultQueue
   #
   # Choose this strategy for production environments:
   # - **Default choice:** This should be your go-to production strategy
@@ -42,12 +42,12 @@ module Postburner
   # ## Usage
   #
   # @example Default behavior (automatically set)
-  #   # No configuration needed - NiceQueue is the default
+  #   # No configuration needed - DefaultQueue is the default
   #   job = MyJob.create!(args: { user_id: 123 })
   #   job.queue!(delay: 1.hour)
   #
-  # @example Explicitly activate NiceQueue
-  #   Postburner.nice_async_strategy!
+  # @example Explicitly activate DefaultQueue
+  #   Postburner.default_strategy!
   #   job = MyJob.create!(args: {})
   #   job.queue!(at: Time.zone.now + 2.days)
   #
@@ -58,15 +58,15 @@ module Postburner
   #   # Job is automatically re-inserted with 55-minute delay
   #   # "PREMATURE; RE-INSERTED" logged to job.logs
   #
-  # @see Queue Strict production strategy that raises on premature execution
-  # @see TestQueue Test strategy with inline execution
-  # @see Postburner.nice_async_strategy!
+  # @see StrictQueue Strict production strategy that raises on premature execution
+  # @see InlineTestQueue Test strategy with inline execution
+  # @see Postburner.default_strategy!
   #
-  class NiceQueue < Queue
+  class DefaultQueue < StrictQueue
     class << self
       # Handles jobs executed before their scheduled run_at time.
       #
-      # Unlike the parent {Queue} strategy, NiceQueue gracefully handles premature
+      # Unlike the parent {StrictQueue} strategy, DefaultQueue gracefully handles premature
       # execution by re-inserting the job with the appropriate delay instead of
       # raising an exception.
       #

data/lib/postburner/strategies/{test_queue.rb → inline_test_queue.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Postburner
-  # Test queue strategy with strict scheduling enforcement.
+  # Inline test queue strategy with strict scheduling enforcement.
   #
   # This strategy executes jobs inline/synchronously without Beanstalkd, making
   # tests fast and predictable. It raises {Postburner::Job::PrematurePerform} if
@@ -9,7 +9,7 @@ module Postburner
   #
   # @note Auto-detected when Rails.env.test? and ActiveJob adapter is :test
   #
-  # ## When to Use TestQueue
+  # ## When to Use InlineTestQueue
   #
   # Choose this strategy for test environments where you want:
   # - **Explicit time management:** Forces you to use `travel_to` for scheduled jobs
@@ -33,10 +33,10 @@ module Postburner
   #
   # @example Automatically activated in Rails test environment
   #   # In test_helper.rb or rails_helper.rb
-  #   # TestQueue is automatically set if Rails.env.test?
+  #   # InlineTestQueue is automatically set if Rails.env.test?
   #   # and ActiveJob.queue_adapter == :test
   #
-  # @example Explicitly activate TestQueue
+  # @example Explicitly activate InlineTestQueue
   #   Postburner.inline_test_strategy!
   #   job = MyJob.create!(args: { user_id: 123 })
   #   job.queue!
@@ -70,11 +70,11 @@ module Postburner
   #     end
   #   end
   #
-  # @see ImmediateTestQueue Test strategy with automatic time travel
+  # @see ImmediateInlineTestQueue Test strategy with automatic time travel
   # @see NiceQueue Default production strategy
   # @see Postburner.inline_test_strategy!
   #
-  class TestQueue < Queue
+  class InlineTestQueue < Queue
     class << self
       # Returns whether this strategy is for testing.
       #
@@ -121,8 +121,11 @@ module Postburner
       # @raise [Postburner::Job::PrematurePerform] Always raises with helpful message
       #
       def handle_premature_perform(job)
-        raise Postburner::Job::PrematurePerform, "Job scheduled for #{job.run_at} (#{((job.run_at - Time.current) / 60).round(1)} minutes from now). Use `travel_to(job.run_at)` in your test, or set `Postburner.inline_immediate_test_strategy!` to execute scheduled jobs immediately."
+        raise Postburner::Job::PrematurePerform, "Job scheduled for #{job.run_at} (#{((job.run_at - Time.current) / 60).round(1)} minutes from now). Use `travel_to(job.run_at)` in your test, or set `Postburner.time_travel_test_strategy!` i.e. `Postburner::TimeTravelTestQueue` to execute scheduled jobs immediately."
       end
     end
   end
+
+  # Backward compatibility alias
+  TestQueue = InlineTestQueue
 end

data/lib/postburner/strategies/{queue.rb → strict_queue.rb}

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 module Postburner
-  # Base production queue strategy that queues jobs to Beanstalkd asynchronously.
+  # Strict production queue strategy that queues jobs to Beanstalkd asynchronously.
   #
   # This is the strict production strategy that raises an exception if a job
-  # is executed before its scheduled run_at time. Unlike {NiceQueue}, it does
+  # is executed before its scheduled run_at time. Unlike {DefaultQueue}, it does
   # not automatically re-insert premature jobs.
   #
-  # @note This is NOT the default strategy - use {NiceQueue} for production
+  # @note This is NOT the default strategy - use {DefaultQueue} for production
   #
-  # ## When to Use Queue
+  # ## When to Use StrictQueue
   #
   # Choose this strategy when you want strict enforcement of job scheduling:
   # - You want jobs to fail loudly if executed prematurely
   # - You're debugging scheduling issues
   # - You want to catch configuration errors in production
   #
-  # For most production use cases, use {NiceQueue} instead, which handles
+  # For most production use cases, use {DefaultQueue} instead, which handles
   # premature execution gracefully by re-inserting with appropriate delay.
   #
   # ## Strategy Behavior
@@ -28,23 +28,23 @@ module Postburner
   #
   # ## Usage
   #
-  # @example Activate Queue strategy
-  #   Postburner.async_strategy!
+  # @example Activate StrictQueue strategy
+  #   Postburner.strict_strategy!
   #   job = MyJob.create!(args: { user_id: 123 })
   #   job.queue!(delay: 1.hour)
   #
   # @example Premature execution raises exception
-  #   Postburner.async_strategy!
+  #   Postburner.strict_strategy!
   #   job = MyJob.create!(args: {})
   #   job.queue!(delay: 1.hour)
   #   # Worker picks up job too early...
   #   # => raises PrematurePerform: "Job has future run_at: ..."
   #
-  # @see NiceQueue Default production strategy with graceful premature handling
-  # @see TestQueue Test strategy with inline execution
-  # @see Postburner.async_strategy!
+  # @see DefaultQueue Default production strategy with graceful premature handling
+  # @see InlineTestQueue Test strategy with inline execution
+  # @see Postburner.strict_strategy!
   #
-  class Queue
+  class StrictQueue
     class << self
       # Returns whether this strategy is for testing.
       #

data/lib/postburner/strategies/{immediate_test_queue.rb → time_travel_test_queue.rb}

@@ -5,25 +5,25 @@ require_relative '../time_helpers'
 module Postburner
   # Test queue strategy with automatic time travel for scheduled jobs.
   #
-  # This strategy executes jobs inline/synchronously like {TestQueue}, but
+  # This strategy executes jobs inline/synchronously like {InlineTestQueue}, but
   # automatically uses time travel for scheduled jobs instead of raising
   # exceptions. When a job has a future run_at, it travels to that time,
   # executes the job, then returns to the present.
   #
   # @note Requires ActiveSupport::Testing::TimeHelpers (Rails testing framework)
   #
-  # ## When to Use ImmediateTestQueue
+  # ## When to Use TimeTravelTestQueue
   #
   # Choose this strategy for test environments where you want:
   # - **Automatic time management:** No need to manually call `travel_to`
   # - **Simple scheduled job testing:** Test delayed/scheduled jobs without boilerplate
   # - **Fast tests:** Jobs execute immediately regardless of schedule
   # - **No Beanstalkd:** Tests run without external dependencies
-  # - **Convenience over control:** Less explicit but easier to use than {TestQueue}
+  # - **Convenience over control:** Less explicit but easier to use than {InlineTestQueue}
   #
   # This is ideal for integration/feature tests where you want to verify that
   # scheduled jobs execute correctly without managing time travel yourself. The
-  # tradeoff is less explicit control over timing compared to {TestQueue}.
+  # tradeoff is less explicit control over timing compared to {InlineTestQueue}.
   #
   # ## Strategy Behavior
   #
@@ -48,15 +48,15 @@ module Postburner
   #
   # ## Usage
   #
-  # @example Explicitly activate ImmediateTestQueue
-  #   Postburner.inline_immediate_test_strategy!
+  # @example Explicitly activate TimeTravelTestQueue
+  #   Postburner.time_travel_test_strategy!
   #   job = MyJob.create!(args: { user_id: 123 })
   #   job.queue!(delay: 1.hour)
   #   # Job executes immediately at scheduled time
   #   assert job.reload.processed_at
   #
   # @example Scheduled jobs execute automatically
-  #   Postburner.inline_immediate_test_strategy!
+  #   Postburner.time_travel_test_strategy!
   #   job = SendReminderEmail.create!(args: { user_id: 123 })
   #
   #   # Job executes immediately despite 2-day delay
@@ -67,7 +67,7 @@ module Postburner
   #   assert_not_nil job.processed_at
   #
   # @example Multiple jobs execute in queue order, not schedule order
-  #   Postburner.inline_immediate_test_strategy!
+  #   Postburner.time_travel_test_strategy!
   #
   #   job1 = MyJob.create!(args: { id: 1 })
   #   job2 = MyJob.create!(args: { id: 2 })
@@ -80,7 +80,7 @@ module Postburner
   #
   # @example Testing feature with scheduled job
   #   test "sends reminder email after 24 hours" do
-  #     Postburner.inline_immediate_test_strategy!
+  #     Postburner.time_travel_test_strategy!
   #
   #     user = users(:john)
   #     reminder = ReminderJob.create!(args: { user_id: user.id })
@@ -91,11 +91,11 @@ module Postburner
   #     assert_emails 1
   #   end
   #
-  # @see TestQueue Test strategy requiring explicit time travel
+  # @see InlineTestQueue Test strategy requiring explicit time travel
   # @see NiceQueue Default production strategy
-  # @see Postburner.inline_immediate_test_strategy!
+  # @see Postburner.time_travel_test_strategy!
   #
-  class ImmediateTestQueue < TestQueue
+  class TimeTravelTestQueue < InlineTestQueue
     class << self
       include TimeHelpers
 
@@ -147,4 +147,7 @@ module Postburner
       end
     end
   end
+
+  # Backward compatibility alias
+  ImmediateTestQueue = TimeTravelTestQueue
 end

data/lib/postburner/test_helpers.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Test helper methods for switching queue strategies in tests.
+  #
+  # Provides instance methods for managing queue strategies in a test-safe,
+  # thread-safe manner. Use these methods to switch between strategies for
+  # individual tests or groups of tests.
+  #
+  # @example Using in setup/teardown
+  #   class MyTest < ActiveSupport::TestCase
+  #     include Postburner::TestHelpers
+  #
+  #     def setup
+  #       switch_queue_strategy!(:time_travel_test)
+  #     end
+  #
+  #     def teardown
+  #       restore_queue_strategy!
+  #     end
+  #
+  #     def test_something
+  #       job = MyJob.create!(args: {})
+  #       job.queue!(delay: 1.hour)
+  #       assert job.reload.processed_at
+  #     end
+  #   end
+  #
+  # @example Using block form
+  #   class MyTest < ActiveSupport::TestCase
+  #     include Postburner::TestHelpers
+  #
+  #     def test_something
+  #       use_queue_strategy(:time_travel_test) do
+  #         job = MyJob.create!(args: {})
+  #         job.queue!(delay: 1.hour)
+  #         assert job.reload.processed_at
+  #       end
+  #     end
+  #   end
+  #
+  module TestHelpers
+    # Switch to a different queue strategy for testing.
+    #
+    # Stashes the current strategy in a thread-local variable so it can be
+    # restored later with {#restore_queue_strategy!}. This is thread-safe
+    # for parallel test execution.
+    #
+    # @param strategy [Class, Symbol] Strategy class or symbol name
+    #   Symbols: :inline_test, :time_travel_test, :strict, :default, :null
+    #
+    # @return [Class] The newly activated strategy class
+    #
+    # @raise [ArgumentError] if strategy is invalid type or unknown symbol
+    #
+    # @example With class constant
+    #   switch_queue_strategy!(Postburner::TimeTravelTestQueue)
+    #
+    # @example With symbol
+    #   switch_queue_strategy!(:time_travel_test)
+    #
+    def switch_queue_strategy!(strategy)
+      Thread.current[:postburner_original_strategy] = Postburner.queue_strategy
+
+      Postburner.queue_strategy = case strategy
+      when Symbol
+        strategy_method = "#{strategy}_strategy!".to_sym
+        if Postburner.respond_to?(strategy_method, true)
+          Postburner.send(strategy_method)
+          Postburner.queue_strategy
+        else
+          raise ArgumentError, "Unknown strategy: #{strategy}. Available: inline_test, time_travel_test, strict, default, null"
+        end
+      when Class
+        strategy
+      else
+        raise ArgumentError, "Expected Class or Symbol, got #{strategy.class}"
+      end
+    end
+
+    # Restore the previously stashed queue strategy.
+    #
+    # Restores the strategy that was active when {#switch_queue_strategy!}
+    # was called. Clears the thread-local stash after restoring.
+    #
+    # @return [Class] The restored strategy class
+    #
+    # @raise [RuntimeError] if no strategy was stashed
+    #
+    # @example Typical usage in teardown
+    #   def teardown
+    #     restore_queue_strategy!
+    #   end
+    #
+    def restore_queue_strategy!
+      original = Thread.current[:postburner_original_strategy]
+      if original.nil?
+        raise "No strategy to restore. Did you call switch_queue_strategy! first?"
+      end
+
+      Postburner.queue_strategy = original
+      Thread.current[:postburner_original_strategy] = nil
+    end
+
+    # Execute a block with a temporary queue strategy.
+    #
+    # Automatically switches to the specified strategy before the block
+    # and restores the original strategy after, even if an exception occurs.
+    #
+    # @param strategy [Class, Symbol] Strategy class or symbol name
+    #   Symbols: :inline_test, :time_travel_test, :strict, :default, :null
+    #
+    # @yield Block to execute with the temporary strategy
+    #
+    # @return [Object] The return value of the block
+    #
+    # @raise [ArgumentError] if strategy is invalid type or unknown symbol
+    #
+    # @example
+    #   use_queue_strategy(:time_travel_test) do
+    #     job = MyJob.create!(args: {})
+    #     job.queue!(delay: 1.hour)
+    #     assert job.reload.processed_at
+    #   end
+    #
+    def use_queue_strategy(strategy, &block)
+      switch_queue_strategy!(strategy)
+      yield
+    ensure
+      restore_queue_strategy!
+    end
+  end
+end

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.13'
+  VERSION = '1.0.0.pre.14'
 end

data/lib/postburner/worker.rb

@@ -501,8 +501,8 @@ module Postburner
     # from Beanstalkd after successful completion.
     #
     # Instruments with ActiveSupport::Notifications:
-    # - perform_start.postburner: Before job execution
-    # - perform.postburner: Around job execution (includes duration)
+    # - perform_start.job.postburner: Before job execution
+    # - perform.job.postburner: Around job execution (includes duration)
     #
     # @param beanstalk_job [Beaneater::Job] Reserved job from Beanstalkd
     # @param payload [Hash] Parsed job body
@@ -511,13 +511,14 @@ module Postburner
     # @api private
     def execute_regular_job(beanstalk_job, payload)
       job_description = format_job_description(payload)
-      instrument_payload = { payload: payload, beanstalk_job_id: beanstalk_job.id }
+      job_payload = Postburner::Instrumentation.job_payload_from_hash(payload, beanstalk_job_id: beanstalk_job.id)
+      instrument_payload = { job: job_payload, beanstalk_job_id: beanstalk_job.id }
 
       logger.info "[Postburner] Executing #{job_description} (bkid: #{beanstalk_job.id})"
 
-      ActiveSupport::Notifications.instrument('perform_start.postburner', instrument_payload)
+      ActiveSupport::Notifications.instrument('perform_start.job.postburner', instrument_payload)
 
-      ActiveSupport::Notifications.instrument('perform.postburner', instrument_payload) do
+      ActiveSupport::Notifications.instrument('perform.job.postburner', instrument_payload) do
         Postburner::ActiveJob::Execution.execute(beanstalk_job.body)
       end
 
@@ -547,9 +548,13 @@ module Postburner
 
     # Handles job execution errors with retry logic.
     #
-    # For tracked jobs and legacy Postburner::Job: Buries the job for inspection.
+    # For tracked jobs and legacy Postburner::Job: Buries the job for inspection
+    # and emits retry_stopped.job.postburner event.
     # For default ActiveJob: Applies exponential backoff retry with max 5 attempts.
     #
+    # Instruments with ActiveSupport::Notifications:
+    # - retry_stopped.job.postburner: When tracked job is buried after failure
+    #
     # @param beanstalk_job [Beaneater::Job] Failed job
     # @param error [Exception] The error that caused the failure
     # @return [void]
@@ -563,6 +568,14 @@ module Postburner
 
         if payload['tracked'] || Postburner::ActiveJob::Payload.legacy_format?(payload)
           logger.info "[Postburner] Burying tracked/legacy job for inspection"
+
+          job_payload = Postburner::Instrumentation.job_payload_from_hash(payload, beanstalk_job_id: beanstalk_job.id)
+          ActiveSupport::Notifications.instrument('retry_stopped.job.postburner', {
+            job: job_payload,
+            beanstalk_job_id: beanstalk_job.id,
+            error: error
+          })
+
           beanstalk_job.bury
         else
           handle_default_retry(beanstalk_job, payload, error)
@@ -579,8 +592,8 @@ module Postburner
     # After 5 failed attempts, discards the job permanently.
     #
     # Instruments with ActiveSupport::Notifications:
-    # - retry.postburner: When job is retried
-    # - discard.postburner: When job is discarded after max retries
+    # - retry.job.postburner: When job is retried
+    # - discard.job.postburner: When job is discarded after max retries
     #
     # @param beanstalk_job [Beaneater::Job] Failed job to retry
     # @param payload [Hash] Parsed job body (modified with retry_count)
@@ -590,6 +603,7 @@ module Postburner
     def handle_default_retry(beanstalk_job, payload, error)
       retry_count = payload['retry_count'] || 0
       max_retries = 5
+      job_payload = Postburner::Instrumentation.job_payload_from_hash(payload, beanstalk_job_id: beanstalk_job.id)
 
       if retry_count < max_retries
         payload['retry_count'] = retry_count + 1
@@ -609,8 +623,8 @@ module Postburner
           )
         end
 
-        ActiveSupport::Notifications.instrument('retry.postburner', {
-          payload: payload,
+        ActiveSupport::Notifications.instrument('retry.job.postburner', {
+          job: job_payload,
           beanstalk_job_id: beanstalk_job.id,
           error: error,
           wait: delay,
@@ -619,8 +633,8 @@ module Postburner
 
         logger.info "[Postburner] Retrying default job #{payload['job_id']}, attempt #{retry_count + 1} in #{delay}s"
       else
-        ActiveSupport::Notifications.instrument('discard.postburner', {
-          payload: payload,
+        ActiveSupport::Notifications.instrument('discard.job.postburner', {
+          job: job_payload,
           beanstalk_job_id: beanstalk_job.id,
           error: error
         })