postburner 0.8.0 → 1.0.0.pre.1

data/lib/postburner/strategies/test_queue.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Postburner
+  # 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
+  # a job has a future run_at, forcing you to use explicit time travel in tests.
+  #
+  # @note Auto-detected when Rails.env.test? and ActiveJob adapter is :test
+  #
+  # ## When to Use TestQueue
+  #
+  # Choose this strategy for test environments where you want:
+  # - **Explicit time management:** Forces you to use `travel_to` for scheduled jobs
+  # - **Strict testing:** Catches scheduling bugs by failing loudly
+  # - **Synchronous execution:** Jobs run immediately on `queue!` call
+  # - **No Beanstalkd:** Tests run without external dependencies
+  # - **Predictable timing:** Full control over when jobs execute
+  #
+  # This is ideal for unit/integration tests where you want to verify job
+  # scheduling logic and maintain explicit control over time progression.
+  #
+  # ## Strategy Behavior
+  #
+  # - **Execution:** Synchronous/inline (no Beanstalkd required)
+  # - **Testing mode:** Returns true
+  # - **Premature execution:** Raises {Postburner::Job::PrematurePerform} exception
+  # - **Beanstalkd:** Not used (bkid remains nil)
+  # - **Time travel:** Requires explicit `travel_to` for scheduled jobs
+  #
+  # ## Usage
+  #
+  # @example Automatically activated in Rails test environment
+  #   # In test_helper.rb or rails_helper.rb
+  #   # TestQueue is automatically set if Rails.env.test?
+  #   # and ActiveJob.queue_adapter == :test
+  #
+  # @example Explicitly activate TestQueue
+  #   Postburner.inline_test_strategy!
+  #   job = MyJob.create!(args: { user_id: 123 })
+  #   job.queue!
+  #   # Job executes immediately and synchronously
+  #   assert job.reload.processed_at
+  #
+  # @example Scheduled jobs require explicit time travel
+  #   Postburner.inline_test_strategy!
+  #   job = MyJob.create!(args: {})
+  #
+  #   # This will raise PrematurePerform
+  #   # job.queue!(delay: 1.hour)
+  #
+  #   # Use time travel instead
+  #   job.queue!(delay: 1.hour)
+  #   travel_to(job.run_at) do
+  #     # Job executes within the time travel block
+  #   end
+  #
+  # @example Testing with scheduled jobs
+  #   test "processes payment after delay" do
+  #     Postburner.inline_test_strategy!
+  #     job = ProcessPayment.create!(args: { payment_id: 123 })
+  #
+  #     future_time = 2.hours.from_now
+  #     job.queue!(at: future_time)
+  #
+  #     travel_to(future_time) do
+  #       # Job executes here
+  #       assert job.reload.processed_at
+  #     end
+  #   end
+  #
+  # @see ImmediateTestQueue Test strategy with automatic time travel
+  # @see NiceQueue Default production strategy
+  # @see Postburner.inline_test_strategy!
+  #
+  class TestQueue < Queue
+    class << self
+      # Returns whether this strategy is for testing.
+      #
+      # @return [Boolean] Always true for test strategies
+      #
+      def testing
+        true
+      end
+
+      # Executes job inline/synchronously without Beanstalkd.
+      #
+      # Called automatically via after_save_commit hook when {Postburner::Job#queue!}
+      # is invoked. Executes the job immediately in the same process. If the job
+      # has a future run_at, raises {Postburner::Job::PrematurePerform} to force
+      # explicit time management with `travel_to`.
+      #
+      # @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 [Postburner::Job::PrematurePerform] if job has future run_at
+      #
+      # @api private
+      #
+      def insert(job, options = {})
+        # Execute immediately in test mode
+        # Will raise PrematurePerform if run_at is in the future
+        job.perform!(job.args)
+
+        # Return format matching Backburner response (symbol keys)
+        { status: 'INLINE', id: nil }
+      end
+
+      # Handles jobs executed before their scheduled run_at time.
+      #
+      # This strategy raises an exception with a helpful error message,
+      # forcing developers to use explicit `travel_to` calls in tests.
+      #
+      # @param job [Postburner::Job] The job being executed prematurely
+      #
+      # @return [void]
+      #
+      # @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.zone.now) / 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."
+      end
+    end
+  end
+end

data/lib/postburner/time_helpers.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Provides time travel utilities for testing without requiring test context.
+  #
+  # This module wraps ActiveSupport::Testing::TimeHelpers to enable time travel
+  # from non-test contexts (like class methods or service objects). It creates
+  # a helper object extended with Rails' TimeHelpers and delegates time travel
+  # operations to it.
+  #
+  # @note Requires ActiveSupport::Testing::TimeHelpers (Rails testing framework)
+  # @note Time travel affects global time via Time.stub - use only in test environments
+  #
+  # ## Usage
+  #
+  # @example Basic time travel
+  #   include Postburner::TimeHelpers
+  #
+  #   travel_to(2.days.from_now) do
+  #     # Code here executes as if it's 2 days in the future
+  #     Time.zone.now  # => 2 days from now
+  #   end
+  #
+  # @example In a class method
+  #   class MyService
+  #     extend Postburner::TimeHelpers
+  #
+  #     def self.process_scheduled_task(time)
+  #       travel_to(time) do
+  #         # Execute task at specified time
+  #       end
+  #     end
+  #   end
+  #
+  # @see ActiveSupport::Testing::TimeHelpers
+  #
+  module TimeHelpers
+    # Travels to specified time for block execution using Rails time helpers.
+    #
+    # Creates a helper object extended with ActiveSupport::Testing::TimeHelpers
+    # and uses it to stub global time. This is necessary for time travel outside
+    # of test method contexts where TimeHelpers aren't available directly.
+    #
+    # The travel_to call stubs Time globally (using Time.stub), so all time-based
+    # operations within the block execute as if they're happening at the specified
+    # time. After the block completes, time returns to normal.
+    #
+    # @param time [Time, DateTime, ActiveSupport::TimeWithZone] The time to travel to
+    # @param block [Proc] Block to execute at the specified time
+    #
+    # @return [Object] The return value of the block
+    #
+    # @raise [RuntimeError] if ActiveSupport::Testing::TimeHelpers not available
+    #
+    # @example Travel to specific time
+    #   travel_to(Time.zone.parse('2025-12-25 00:00:00')) do
+    #     puts Time.zone.now  # => 2025-12-25 00:00:00
+    #   end
+    #
+    # @example Travel relative to now
+    #   travel_to(1.hour.from_now) do
+    #     # Execute code as if 1 hour has passed
+    #   end
+    #
+    def travel_to(time, &block)
+      unless defined?(ActiveSupport::Testing::TimeHelpers)
+        raise "ActiveSupport::Testing::TimeHelpers not available. " \
+              "Postburner::TimeHelpers requires Rails testing helpers for time travel."
+      end
+
+      helper = Object.new.extend(ActiveSupport::Testing::TimeHelpers)
+      helper.travel_to(time, &block)
+    end
+  end
+end

data/lib/postburner/tracked.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Concern for ActiveJob classes to opt-in to PostgreSQL tracking.
+  #
+  # Simply include this module in your ActiveJob class to enable full audit
+  # trail persistence in PostgreSQL. Without this, jobs execute as "default" jobs
+  # (Beanstalkd only, no PostgreSQL overhead).
+  #
+  # @example Opt-in to tracking
+  #   class ProcessPayment < ApplicationJob
+  #     include Postburner::Tracked  # ← Enables PostgreSQL audit trail
+  #
+  #     def perform(payment_id)
+  #       log "Processing payment #{payment_id}"
+  #       # ... work ...
+  #       log! "Payment processed successfully"
+  #     end
+  #   end
+  #
+  # @example Without tracking (default mode)
+  #   class SendEmail < ApplicationJob
+  #     # No Postburner::Tracked - executes as default job
+  #
+  #     def perform(email)
+  #       # Fast execution, no PostgreSQL overhead
+  #     end
+  #   end
+  #
+  module Tracked
+    extend ActiveSupport::Concern
+
+    included do
+      # Include Beanstalkd configuration DSL automatically
+      include Postburner::Beanstalkd
+
+      # Reference to Postburner::Job during execution (set by worker)
+      attr_accessor :postburner_job
+    end
+
+    # Appends a log message to the job's audit trail.
+    #
+    # Only available for tracked jobs. Logs are stored in the
+    # Postburner::Job record's `logs` JSONB array.
+    #
+    # @param message [String] Log message
+    # @param level [Symbol] Log level (:debug, :info, :warning, :error)
+    #
+    # @return [void]
+    #
+    # @example
+    #   def perform(user_id)
+    #     log "Starting user processing"
+    #     # ... work ...
+    #     log "Completed successfully", level: :info
+    #   end
+    #
+    def log(message, level: :info)
+      postburner_job&.log(message, level: level)
+    end
+
+    # Appends a log message and immediately persists to database.
+    #
+    # Use this for important log messages that should be saved immediately
+    # rather than batched with other updates.
+    #
+    # @param message [String] Log message
+    # @param level [Symbol] Log level (:debug, :info, :warning, :error)
+    #
+    # @return [void]
+    #
+    # @example
+    #   def perform(payment_id)
+    #     log! "Critical: Processing high-value payment #{payment_id}"
+    #   end
+    #
+    def log!(message, level: :info)
+      postburner_job&.log!(message, level: level)
+    end
+
+    # Tracks an exception in the job's errata array.
+    #
+    # Appends exception details (class, message, backtrace) to the
+    # in-memory errata array. Does NOT persist immediately.
+    #
+    # @param exception [Exception] The exception to track
+    #
+    # @return [void]
+    #
+    # @example
+    #   def perform(user_id)
+    #     process_user(user_id)
+    #   rescue => e
+    #     log_exception(e)
+    #     raise
+    #   end
+    #
+    def log_exception(exception)
+      postburner_job&.log_exception(exception)
+    end
+
+    # Tracks an exception and immediately persists to database.
+    #
+    # @param exception [Exception] The exception to track
+    #
+    # @return [void]
+    #
+    # @example
+    #   def perform(user_id)
+    #     process_user(user_id)
+    #   rescue CriticalError => e
+    #     log_exception!(e)
+    #     raise
+    #   end
+    #
+    def log_exception!(exception)
+      postburner_job&.log_exception!(exception)
+    end
+
+    # Returns the Beanstalkd job object for direct queue operations.
+    #
+    # Provides access to the underlying Beaneater job object through the
+    # TrackedJob wrapper. Use this to perform Beanstalkd operations like
+    # touch, bury, release, etc.
+    #
+    # @return [Beaneater::Job, nil] Beanstalkd job object or nil if not available
+    #
+    # @example Extend TTR during long operation
+    #   def perform(file_id)
+    #     file = File.find(file_id)
+    #     file.each_line do |line|
+    #       # ... process line ...
+    #       bk&.touch  # Extend TTR
+    #     end
+    #   end
+    #
+    # @example Other Beanstalkd operations
+    #   bk&.bury              # Bury the job
+    #   bk&.release(pri: 0)   # Release with priority
+    #   bk&.stats             # Get job statistics
+    #
+    # @see #extend!
+    #
+    def bk
+      postburner_job&.bk
+    end
+
+    # Extends the job's time-to-run (TTR) in Beanstalkd.
+    #
+    # Convenience method that calls touch on the Beanstalkd job, extending
+    # the TTR by the original TTR value. Use this during long-running operations
+    # to prevent the job from timing out.
+    #
+    # @return [void]
+    #
+    # @example Process large file line by line
+    #   def perform(file_id)
+    #     file = File.find(file_id)
+    #     file.each_line do |line|
+    #       # ... process line ...
+    #       extend!  # Extend TTR to prevent timeout
+    #     end
+    #   end
+    #
+    # @see #bk
+    #
+    def extend!
+      postburner_job&.extend!
+    end
+  end
+end

data/lib/postburner/version.rb

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

data/lib/postburner/workers/base.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Postburner
+  module Workers
+    # Base worker class with shared functionality for all worker types.
+    #
+    # Provides common methods for signal handling, job execution, error handling,
+    # and retry logic. Subclasses implement the specific execution strategy
+    # (simple, forking, threads_on_fork).
+    #
+    class Base
+      attr_reader :config, :logger
+
+      # @param config [Postburner::Configuration] Worker configuration
+      #
+      def initialize(config)
+        @config = config
+        @logger = config.logger
+        @shutdown = false
+        setup_signal_handlers
+      end
+
+      # Starts the worker loop.
+      #
+      # Subclasses must implement this method to define their execution strategy.
+      #
+      # @return [void]
+      #
+      # @raise [NotImplementedError] if not implemented by subclass
+      #
+      def start
+        raise NotImplementedError, "Subclasses must implement #start"
+      end
+
+      # Initiates graceful shutdown.
+      #
+      # Sets shutdown flag to stop processing new jobs. Current jobs
+      # are allowed to finish.
+      #
+      # @return [void]
+      #
+      def shutdown
+        @shutdown = true
+      end
+
+      # Checks if shutdown has been requested.
+      #
+      # @return [Boolean] true if shutdown requested, false otherwise
+      #
+      def shutdown?
+        @shutdown
+      end
+
+      protected
+
+      # Sets up signal handlers for graceful shutdown.
+      #
+      # TERM and INT signals trigger graceful shutdown.
+      #
+      # @return [void]
+      #
+      def setup_signal_handlers
+        Signal.trap('TERM') { shutdown }
+        Signal.trap('INT') { shutdown }
+      end
+
+      # Expands queue name to full tube name with environment prefix.
+      #
+      # Delegates to Postburner::Configuration#expand_tube_name.
+      #
+      # @param queue_name [String] Base queue name
+      #
+      # @return [String] Full tube name (e.g., 'postburner.production.critical')
+      #
+      def expand_tube_name(queue_name)
+        config.expand_tube_name(queue_name)
+      end
+
+      # Executes a job from Beanstalkd.
+      #
+      # Delegates to Postburner::ActiveJob::Execution to handle default,
+      # tracked, and legacy job formats.
+      #
+      # @param beanstalk_job [Beaneater::Job] Job from Beanstalkd
+      #
+      # @return [void]
+      #
+      def execute_job(beanstalk_job)
+        logger.info "[Postburner] Executing #{beanstalk_job.class.name} #{beanstalk_job.id}"
+        Postburner::ActiveJob::Execution.execute(beanstalk_job.body)
+        logger.info "[Postburner] Deleting #{beanstalk_job.class.name} #{beanstalk_job.id} (success)"
+        beanstalk_job.delete
+      rescue => e
+        handle_error(beanstalk_job, e)
+      end
+
+      # Handles job execution errors with retry logic.
+      #
+      # Implements retry strategy:
+      # - Parses payload to determine job type
+      # - For default jobs: manages retry count, re-queues with backoff
+      # - For tracked jobs: buries job (Postburner::Job handles retries)
+      # - For legacy jobs: buries job
+      #
+      # @param beanstalk_job [Beaneater::Job] Job from Beanstalkd
+      # @param error [Exception] The exception that was raised
+      #
+      # @return [void]
+      #
+      def handle_error(beanstalk_job, error)
+        logger.error "[Postburner] Job failed: #{error.class} - #{error.message}"
+        logger.error error.backtrace.join("\n")
+
+        begin
+          payload = JSON.parse(beanstalk_job.body)
+
+          if payload['tracked'] || Postburner::ActiveJob::Payload.legacy_format?(payload)
+            # Tracked and legacy jobs: bury for inspection
+            # (Postburner::Job has its own retry logic)
+            logger.info "[Postburner] Burying tracked/legacy job for inspection"
+            beanstalk_job.bury
+          else
+            # Default job: handle retry logic
+            handle_default_retry(beanstalk_job, payload, error)
+          end
+        rescue => retry_error
+          logger.error "[Postburner] Error handling failure: #{retry_error.message}"
+          beanstalk_job.bury rescue nil
+        end
+      end
+
+      # Handles retry logic for default jobs.
+      #
+      # Checks ActiveJob's retry_on configuration, increments retry count,
+      # and re-queues with exponential backoff if retries remaining.
+      #
+      # @param beanstalk_job [Beaneater::Job] Job from Beanstalkd
+      # @param payload [Hash] Parsed job payload
+      # @param error [Exception] The exception that was raised
+      #
+      # @return [void]
+      #
+      def handle_default_retry(beanstalk_job, payload, error)
+        retry_count = payload['retry_count'] || 0
+        job_class = payload['job_class'].constantize
+
+        # Check if job class wants to retry this error
+        # (This is simplified - full implementation would check retry_on config)
+        max_retries = 5  # Default max retries
+
+        if retry_count < max_retries
+          # Increment retry count
+          payload['retry_count'] = retry_count + 1
+          payload['executions'] = (payload['executions'] || 0) + 1
+
+          # Calculate backoff delay (exponential: 1s, 2s, 4s, 8s, 16s...)
+          delay = calculate_backoff(retry_count)
+
+          # Delete old job and insert new one with updated payload
+          beanstalk_job.delete
+
+          Postburner.connected do |conn|
+            tube_name = expand_tube_name(payload['queue_name'])
+            conn.tubes[tube_name].put(
+              JSON.generate(payload),
+              pri: payload['priority'] || 0,
+              delay: delay,
+              ttr: 120
+            )
+          end
+
+          logger.info "[Postburner] Retrying default job #{payload['job_id']}, attempt #{retry_count + 1} in #{delay}s"
+        else
+          # Max retries exceeded
+          logger.error "[Postburner] Discarding default job #{payload['job_id']} after #{retry_count} retries"
+          beanstalk_job.delete
+          # TODO: Call after_discard callback if configured
+        end
+      end
+
+      # Calculates exponential backoff delay for retries.
+      #
+      # @param retry_count [Integer] Number of retries so far
+      #
+      # @return [Integer] Delay in seconds (capped at 1 hour)
+      #
+      def calculate_backoff(retry_count)
+        # Exponential backoff: 2^retry_count, capped at 3600 seconds (1 hour)
+        [2 ** retry_count, 3600].min
+      end
+
+      # Watches the configured queues in Beanstalkd.
+      #
+      # @param connection [Postburner::Connection] Beanstalkd connection
+      # @param queue_name [String, nil] Optional specific queue name to watch (watches all if nil)
+      #
+      # @return [void]
+      #
+      def watch_queues(connection, queue_name = nil)
+        if queue_name
+          tube_name = config.expand_tube_name(queue_name)
+          connection.beanstalk.tubes.watch!(tube_name)
+        else
+          tube_names = config.expanded_tube_names
+          connection.beanstalk.tubes.watch!(*tube_names)
+        end
+      end
+    end
+  end
+end