postburner 0.8.0 → 1.0.0.pre.1

data/lib/postburner/queue_config.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Queue configuration module for Postburner::Job classes.
+  #
+  # Provides DSL methods for configuring queue behavior (name, priority, TTR, retries).
+  # Replaces Backburner::Queue with cleaner implementation that doesn't interfere
+  # with ActiveSupport::Callbacks.
+  #
+  # @example Basic usage
+  #   class ProcessPayment < Postburner::Job
+  #     queue 'critical'
+  #     queue_priority 0
+  #     queue_ttr 300
+  #     queue_max_job_retries 3
+  #
+  #     def perform(args)
+  #       # ...
+  #     end
+  #   end
+  #
+  module QueueConfig
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :postburner_queue_name, default: 'default'
+      class_attribute :postburner_priority, default: nil
+      class_attribute :postburner_ttr, default: nil
+      class_attribute :postburner_max_retries, default: nil
+      class_attribute :postburner_retry_delay, default: nil
+    end
+
+    class_methods do
+      # Sets or returns the queue name.
+      #
+      # @param name [String, Symbol, nil] Queue name to set, or nil to get current value
+      #
+      # @return [String, nil] Current queue name when getting, nil when setting
+      #
+      # @example Set queue
+      #   queue 'critical'
+      #
+      # @example Get queue
+      #   ProcessPayment.queue  # => 'critical'
+      #
+      def queue(name = nil)
+        if name
+          self.postburner_queue_name = name.to_s
+          nil  # Return nil to avoid callback interference
+        else
+          postburner_queue_name
+        end
+      end
+
+      # Sets or returns the queue priority.
+      #
+      # Lower numbers = higher priority in Beanstalkd.
+      #
+      # @param pri [Integer, nil] Priority to set (0-4294967295), or nil to get current value
+      #
+      # @return [Integer, nil] Current priority when getting, nil when setting
+      #
+      # @example Set priority
+      #   queue_priority 0  # Highest priority
+      #
+      # @example Get priority
+      #   ProcessPayment.queue_priority  # => 0
+      #
+      def queue_priority(pri = nil)
+        if pri
+          self.postburner_priority = pri
+          nil
+        else
+          postburner_priority
+        end
+      end
+
+      # Sets or returns the queue TTR (time-to-run).
+      #
+      # Number of seconds Beanstalkd will wait for job completion before
+      # making it available again.
+      #
+      # @param ttr [Integer, nil] Timeout in seconds, or nil to get current value
+      #
+      # @return [Integer, nil] Current TTR when getting, nil when setting
+      #
+      # @example Set TTR
+      #   queue_ttr 300  # 5 minutes
+      #
+      # @example Get TTR
+      #   ProcessPayment.queue_ttr  # => 300
+      #
+      def queue_ttr(ttr = nil)
+        if ttr
+          self.postburner_ttr = ttr
+          nil
+        else
+          postburner_ttr
+        end
+      end
+
+      # Sets or returns maximum number of job retries.
+      #
+      # @param retries [Integer, nil] Max retries, or nil to get current value
+      #
+      # @return [Integer, nil] Current max retries when getting, nil when setting
+      #
+      # @example Set max retries
+      #   queue_max_job_retries 3
+      #
+      # @example Get max retries
+      #   ProcessPayment.queue_max_job_retries  # => 3
+      #
+      def queue_max_job_retries(retries = nil)
+        if retries
+          self.postburner_max_retries = retries
+          nil
+        else
+          postburner_max_retries
+        end
+      end
+
+      # Sets or returns the retry delay.
+      #
+      # Can accept either a fixed delay (Integer) or a proc for dynamic calculation.
+      # The proc receives the retry count and returns delay in seconds.
+      #
+      # @param delay [Integer, Proc, nil] Delay in seconds, proc, or nil to get current value
+      #
+      # @return [Integer, Proc, nil] Current delay when getting, nil when setting
+      #
+      # @example Set fixed retry delay
+      #   queue_retry_delay 10
+      #
+      # @example Set exponential backoff with proc
+      #   queue_retry_delay ->(retries) { 2 ** retries }
+      #
+      # @example Get retry delay
+      #   ProcessPayment.queue_retry_delay  # => 10 or #<Proc>
+      #
+      def queue_retry_delay(delay = nil)
+        if delay
+          self.postburner_retry_delay = delay
+          nil
+        else
+          postburner_retry_delay
+        end
+      end
+    end
+  end
+end

data/lib/postburner/strategies/immediate_test_queue.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+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
+  # 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
+  #
+  # 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}
+  #
+  # 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}.
+  #
+  # ## Strategy Behavior
+  #
+  # - **Execution:** Synchronous/inline (no Beanstalkd required)
+  # - **Testing mode:** Returns true
+  # - **Premature execution:** Automatically travels to run_at and executes
+  # - **Beanstalkd:** Not used (bkid remains nil)
+  # - **Time travel:** Automatic using ActiveSupport::Testing::TimeHelpers
+  # - **Execution order:** Jobs may execute out of intended chronological order
+  #
+  # ## How Time Travel Works
+  #
+  # When a job with future run_at is queued:
+  # 1. Detects job.run_at > Time.zone.now
+  # 2. Calls `travel_to(job.run_at)` to stub global time
+  # 3. Executes job at the scheduled time (Time.zone.now == job.run_at)
+  # 4. Returns to present time after execution
+  # 5. Job timestamps reflect the scheduled time, not actual time
+  #
+  # @note Time is stubbed globally during execution - side effects may occur
+  # @note Multiple scheduled jobs execute in queue order, not scheduled order
+  #
+  # ## Usage
+  #
+  # @example Explicitly activate ImmediateTestQueue
+  #   Postburner.inline_immediate_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!
+  #   job = SendReminderEmail.create!(args: { user_id: 123 })
+  #
+  #   # Job executes immediately despite 2-day delay
+  #   job.queue!(delay: 2.days)
+  #
+  #   # Timestamps reflect the scheduled time
+  #   assert_equal 2.days.from_now.to_i, job.reload.run_at.to_i
+  #   assert_not_nil job.processed_at
+  #
+  # @example Multiple jobs execute in queue order, not schedule order
+  #   Postburner.inline_immediate_test_strategy!
+  #
+  #   job1 = MyJob.create!(args: { id: 1 })
+  #   job2 = MyJob.create!(args: { id: 2 })
+  #
+  #   job1.queue!(delay: 2.days)  # Executes first (queued first)
+  #   job2.queue!(delay: 1.hour)  # Executes second (queued second)
+  #
+  #   # Both are processed, but job1 executed before job2
+  #   # despite job2 having an earlier scheduled time
+  #
+  # @example Testing feature with scheduled job
+  #   test "sends reminder email after 24 hours" do
+  #     Postburner.inline_immediate_test_strategy!
+  #
+  #     user = users(:john)
+  #     reminder = ReminderJob.create!(args: { user_id: user.id })
+  #     reminder.queue!(delay: 24.hours)
+  #
+  #     # Job executes immediately at scheduled time
+  #     assert reminder.reload.processed_at
+  #     assert_emails 1
+  #   end
+  #
+  # @see TestQueue Test strategy requiring explicit time travel
+  # @see NiceQueue Default production strategy
+  # @see Postburner.inline_immediate_test_strategy!
+  #
+  class ImmediateTestQueue < TestQueue
+    class << self
+      include TimeHelpers
+
+      # Executes job inline with automatic time travel for scheduled jobs.
+      #
+      # Called automatically via after_save_commit hook when {Postburner::Job#queue!}
+      # is invoked. If the job has a future run_at, travels to that time before
+      # execution. Otherwise executes immediately.
+      #
+      # @param job [Postburner::Job] The job to execute
+      # @param options [Hash] Unused in test mode
+      #
+      # @return [Hash] Status hash with :status => 'INLINE', :id => nil
+      #
+      # @raise [RuntimeError] if ActiveSupport::Testing::TimeHelpers not available
+      #
+      # @api private
+      #
+      def insert(job, options = {})
+        # If job has a future run_at, travel to that time for execution
+        if job.run_at && job.run_at > Time.zone.now
+          travel_to(job.run_at) do
+            job.perform!(job.args)
+          end
+        else
+          # No future run_at, execute normally
+          job.perform!(job.args)
+        end
+
+        # Return format matching Backburner response (symbol keys)
+        { status: 'INLINE', id: nil }
+      end
+    end
+  end
+end

data/lib/postburner/strategies/nice_queue.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+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
+  # 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
+  #
+  # Choose this strategy for production environments:
+  # - **Default choice:** This should be your go-to production strategy
+  # - **Graceful recovery:** Automatically handles scheduling edge cases
+  # - **Worker restarts:** Handles jobs picked up during worker restarts
+  # - **Clock drift:** Tolerates minor time synchronization issues
+  # - **Robust operation:** Prevents job failures due to timing issues
+  #
+  # This strategy provides the most forgiving and robust behavior for production
+  # systems where you want scheduled jobs to execute correctly even if workers
+  # pick them up slightly early.
+  #
+  # ## Strategy Behavior
+  #
+  # - **Execution:** Asynchronous via Beanstalkd workers
+  # - **Testing mode:** Returns false
+  # - **Premature execution:** Re-inserts job with calculated delay, logs the event
+  # - **Beanstalkd:** Required and used for all job queueing
+  #
+  # ## How Premature Execution Works
+  #
+  # When a job is executed before its run_at time:
+  # 1. Calculates remaining delay: `job.run_at - Time.zone.now`
+  # 2. Re-inserts job to Beanstalkd with calculated delay
+  # 3. Logs "PREMATURE; RE-INSERTED" message to job logs
+  # 4. Returns without executing the job
+  # 5. Job executes normally when picked up at the correct time
+  #
+  # ## Usage
+  #
+  # @example Default behavior (automatically set)
+  #   # No configuration needed - NiceQueue is the default
+  #   job = MyJob.create!(args: { user_id: 123 })
+  #   job.queue!(delay: 1.hour)
+  #
+  # @example Explicitly activate NiceQueue
+  #   Postburner.nice_async_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(at: Time.zone.now + 2.days)
+  #
+  # @example Premature execution is handled gracefully
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(delay: 1.hour)
+  #   # Worker picks up job 5 minutes early...
+  #   # 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!
+  #
+  class NiceQueue < Queue
+    class << self
+      # Handles jobs executed before their scheduled run_at time.
+      #
+      # Unlike the parent {Queue} strategy, NiceQueue gracefully handles premature
+      # execution by re-inserting the job with the appropriate delay instead of
+      # raising an exception.
+      #
+      # @param job [Postburner::Job] The job being executed prematurely
+      #
+      # @return [void]
+      #
+      # @note Logs "PREMATURE; RE-INSERTED" message to job's audit trail
+      #
+      def handle_premature_perform(job)
+        response = job.insert! delay: job.run_at - Time.zone.now
+        job.log! "PREMATURE; RE-INSERTED: #{response}"
+      end
+    end
+  end
+end

data/lib/postburner/strategies/null_queue.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative '../time_helpers'
+
+module Postburner
+  # Null queue strategy for creating jobs without queueing to Beanstalkd.
+  #
+  # This strategy creates job records in the database but does NOT queue them
+  # to Beanstalkd. Jobs can be manually executed later using {.handle_perform!},
+  # which includes automatic time travel for scheduled jobs.
+  #
+  # @note This is a test-mode strategy (returns true for testing)
+  #
+  # ## When to Use NullQueue
+  #
+  # Choose this strategy when you want:
+  # - **Deferred batch processing:** Create many jobs upfront, execute them manually later
+  # - **Conditional execution:** Queue jobs that may or may not execute based on runtime conditions
+  # - **Testing/debugging:** Inspect jobs before execution without auto-execution
+  # - **Manual control:** Explicitly control when jobs execute
+  # - **No Beanstalkd:** Create jobs without requiring Beanstalkd server
+  #
+  # ## Strategy Behavior
+  #
+  # - **Execution:** Manual via {.handle_perform!} call
+  # - **Testing mode:** Returns true
+  # - **Queueing:** Jobs created in database but NOT sent to Beanstalkd
+  # - **Beanstalkd:** Not used (bkid remains nil)
+  # - **Time travel:** Automatic for scheduled jobs during manual execution
+  #
+  # ## Usage
+  #
+  # @example Create jobs without queueing
+  #   Postburner.null_strategy!
+  #   job1 = MyJob.create!(args: { id: 1 })
+  #   job2 = MyJob.create!(args: { id: 2 })
+  #
+  #   job1.queue!
+  #   job2.queue!(delay: 1.hour)
+  #
+  #   # Jobs created but NOT queued to Beanstalkd
+  #   job1.bkid  # => nil
+  #   job2.bkid  # => nil
+  #
+  # @example Manually execute jobs later
+  #   # Later, execute manually
+  #   Postburner::Job.perform(job1.id)  # Executes immediately
+  #   Postburner::Job.perform(job2.id)  # Time travels to scheduled time
+  #
+  #   job1.reload.processed_at  # => present
+  #   job2.reload.processed_at  # => present
+  #
+  # @example Batch processing pattern
+  #   Postburner.null_strategy!
+  #
+  #   # Create 1000 jobs
+  #   jobs = 1000.times.map do |i|
+  #     job = ProcessRecord.create!(args: { record_id: i })
+  #     job.queue!
+  #     job
+  #   end
+  #
+  #   # Execute in batches
+  #   jobs.each_slice(100) do |batch|
+  #     batch.each { |job| Postburner::Job.perform(job.id) }
+  #     sleep 1  # Rate limiting
+  #   end
+  #
+  # @see TestQueue Parent strategy class
+  # @see Postburner.null_strategy!
+  # @see TimeHelpers
+  #
+  class NullQueue < TestQueue
+    class << self
+      include TimeHelpers
+
+      # Does NOT insert job into Beanstalkd queue.
+      #
+      # Called automatically via after_save_commit hook when {Postburner::Job#queue!}
+      # is invoked. Unlike other strategies, this does NOT queue to Beanstalkd - it
+      # only creates the job record in the database.
+      #
+      # @param job [Postburner::Job] The job (not queued)
+      # @param options [Hash] Unused in null mode
+      #
+      # @return [Hash] Status hash with :status => 'NULL', :id => nil
+      #
+      # @api private
+      #
+      def insert(job, options = {})
+        # Return format matching Backburner response (symbol keys)
+        { status: 'NULL', id: nil }
+      end
+
+      # Executes a job with automatic time travel for scheduled jobs.
+      #
+      # Called by {Postburner::Job.perform} when NullQueue strategy is active.
+      # If the job has a future run_at, it automatically travels to that time
+      # before execution. Otherwise executes immediately.
+      #
+      # Users should call {Postburner::Job.perform} instead of this method directly.
+      #
+      # @param job [Postburner::Job] The job to execute
+      #
+      # @return [void]
+      #
+      # @raise [RuntimeError] if ActiveSupport::Testing::TimeHelpers not available
+      #
+      # @example Execute via Job.perform (recommended)
+      #   Postburner.null_strategy!
+      #   job = MyJob.create!(args: {})
+      #   job.queue!(delay: 1.hour)
+      #   Postburner::Job.perform(job.id)  # Delegates to this method
+      #   job.reload.processed_at  # => present
+      #
+      # @see Postburner::Job.perform
+      # @see TimeHelpers#travel_to
+      # @api private
+      #
+      def handle_perform!(job)
+        if job.run_at && job.run_at > Time.zone.now
+          travel_to(job.run_at) do
+            job.perform!(job.args)
+          end
+        else
+          # No future run_at, execute normally
+          job.perform!(job.args)
+        end
+      end
+    end
+  end
+end

data/lib/postburner/strategies/queue.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Base 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
+  # not automatically re-insert premature jobs.
+  #
+  # @note This is NOT the default strategy - use {NiceQueue} for production
+  #
+  # ## When to Use Queue
+  #
+  # 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
+  # premature execution gracefully by re-inserting with appropriate delay.
+  #
+  # ## Strategy Behavior
+  #
+  # - **Execution:** Asynchronous via Beanstalkd workers
+  # - **Testing mode:** Returns false
+  # - **Premature execution:** Raises {Postburner::Job::PrematurePerform} exception
+  # - **Beanstalkd:** Required and used for all job queueing
+  #
+  # ## Usage
+  #
+  # @example Activate Queue strategy
+  #   Postburner.async_strategy!
+  #   job = MyJob.create!(args: { user_id: 123 })
+  #   job.queue!(delay: 1.hour)
+  #
+  # @example Premature execution raises exception
+  #   Postburner.async_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!
+  #
+  class Queue
+    class << self
+      # Returns whether this strategy is for testing.
+      #
+      # @return [Boolean] Always false for production strategies
+      #
+      def testing
+        false
+      end
+
+      # Inserts job into Beanstalkd queue asynchronously.
+      #
+      # Called automatically via after_save_commit hook when {Postburner::Job#queue!}
+      # is invoked. Enqueues the job to Beanstalkd and returns the response.
+      # The bkid is updated by {Postburner::Job#insert!} after this returns.
+      #
+      # @param job [Postburner::Job] The job to insert
+      # @param options [Hash] Beanstalkd options
+      # @option options [Integer] :delay Seconds to delay execution
+      # @option options [Integer] :pri Priority (lower = higher priority)
+      # @option options [Integer] :ttr Time-to-run before job times out
+      #
+      # @return [Hash] Response with :id (beanstalkd job id) and :status
+      #
+      # @raise [Beaneater::NotConnected] if Beanstalkd connection fails
+      #
+      # @api private
+      #
+      def insert(job, options = {})
+        #debugger
+        Postburner::Job.transaction do
+          Postburner.connected do |conn|
+            tube_name = job.tube_name
+            data = { class: job.class.name, args: [job.id] }
+
+            # Get priority, TTR from job instance (respects instance overrides) or options
+            pri = options[:pri] || job.queue_priority || Postburner.configuration.default_priority
+            delay = options[:delay] || 0
+            ttr = options[:ttr] || job.queue_ttr || Postburner.configuration.default_ttr
+
+            response = conn.tubes[tube_name].put(
+              JSON.generate(data),
+              pri: pri,
+              delay: delay,
+              ttr: ttr
+            )
+
+            response
+          end
+        end
+      end
+
+      def handle_perform!(job)
+        job.perform!(job.args)
+      end
+
+      # Handles jobs executed before their scheduled run_at time.
+      #
+      # This strategy raises an exception to fail loudly on premature execution.
+      # Override in subclasses (like {NiceQueue}) to handle differently.
+      #
+      # @param job [Postburner::Job] The job being executed prematurely
+      #
+      # @return [void]
+      #
+      # @raise [Postburner::Job::PrematurePerform] Always raises for this strategy
+      #
+      def handle_premature_perform(job)
+        raise Postburner::Job::PrematurePerform, "Job has future run_at: #{job.run_at}"
+      end
+    end
+  end
+end