postburner 0.7.2 → 0.9.0.rc.1

data/app/models/postburner/job.rb

@@ -1,26 +1,113 @@
 # frozen_string_literal: true
 
 module Postburner
-  # Must implement a perform method, if an exception is raised the job
-  # doesn't complete.
+  # Base class for all Postburner background jobs using Single Table Inheritance (STI).
   #
-  # Job won't run unless queued_at is set, and is set to a time prior to
-  # the time the job runs.
+  # Postburner::Job provides a PostgreSQL-backed job queue system built on Backburner
+  # and Beanstalkd. Every job is stored as an ActiveRecord model, enabling database
+  # queries, foreign key relationships, and full audit trails.
   #
-  # TODO Mailer uses ActiveJob::Arguments... probably should use that here
-  # as well. Decided how to migrate existing jobs or allow both - Opt to 
-  # allow both: rescue from ActiveJob::DeserializationError and use the
-  # plain hash, probably log it too.
+  # @abstract Subclass and implement {#perform} to define job behavior
   #
-  # Add `cancelled_at` that blocks jobs performing if present.
+  # @example Creating and queueing a job
+  #   class ProcessDonation < Postburner::Job
+  #     queue 'critical'
+  #     queue_priority 0
   #
+  #     def perform(args)
+  #       donation = Donation.find(args['donation_id'])
+  #       # ... process donation ...
+  #       log "Processed donation #{donation.id}"
+  #     end
+  #   end
+  #
+  #   job = ProcessDonation.create!(args: { 'donation_id' => 123 })
+  #   job.queue!(delay: 1.hour)
+  #
+  # @example With callbacks
+  #   class SendEmail < Postburner::Job
+  #     before_enqueue :validate_recipient
+  #     after_processed :track_delivery
+  #
+  #     def perform(args)
+  #       UserMailer.welcome(args['email']).deliver_now
+  #     end
+  #
+  #     private
+  #
+  #     def validate_recipient
+  #       raise "Invalid email" unless args['email'].include?('@')
+  #     end
+  #
+  #     def track_delivery
+  #       Analytics.track('email_sent', email: args['email'])
+  #     end
+  #   end
+  #
+  # @note Job won't run unless queued_at is set and is prior to execution time
+  # @note Subclasses must implement the {#perform} method
+  #
+  # @todo Add support for ActiveJob::Arguments serialization
+  # @todo Add `cancelled_at` field to block job execution if present
+  #
+  # @attr_reader [Integer] id Primary key
+  # @attr_reader [String] type STI type column for job subclass
+  # @attr_reader [String] sid Unique UUID identifier
+  # @attr_reader [Integer] bkid Beanstalkd job ID (nil in test mode)
+  # @attr_reader [Hash] args JSONB arguments passed to perform
+  # @attr_reader [Time] run_at Scheduled execution time (nil for immediate)
+  # @attr_reader [Time] queued_at Time job was queued
+  # @attr_reader [Time] attempting_at Time first attempt started
+  # @attr_reader [Time] processing_at Time current/last processing started
+  # @attr_reader [Time] processed_at Time job completed successfully
+  # @attr_reader [Time] removed_at Time job was removed from queue
+  # @attr_reader [Float] lag Milliseconds between intended_at and attempting_at
+  # @attr_reader [Float] duration Milliseconds between processing_at and processed_at
+  # @attr_reader [Integer] attempt_count Number of execution attempts
+  # @attr_reader [Integer] error_count Number of errors encountered
+  # @attr_reader [Integer] log_count Number of log entries
+  # @attr_reader [Array<Time>] attempts Array of attempt timestamps
+  # @attr_reader [Array<Hash>] errata Array of error details with timestamps
+  # @attr_reader [Array<Hash>] logs Array of log entries with timestamps
+  #
+  # Module to override Backburner::Queue methods to return nil when setting values
+  # This prevents return values from interfering with callback definitions
+  module BackburnerQueueOverrides
+    def queue(name=nil)
+      result = super
+      name.nil? ? result : nil
+    end
+
+    def queue_priority(pri=nil)
+      result = super
+      pri.nil? ? result : nil
+    end
+
+    def queue_respond_timeout(ttr=nil)
+      result = super
+      ttr.nil? ? result : nil
+    end
+
+    def queue_max_job_retries(retries=nil)
+      result = super
+      retries.nil? ? result : nil
+    end
+
+    def queue_retry_delay(delay=nil)
+      result = super
+      delay.nil? ? result : nil
+    end
+
+    def queue_retry_delay_proc(proc=nil)
+      result = super
+      proc.nil? ? result : nil
+    end
+  end
+
   class Job < ApplicationRecord
     include Backburner::Queue
-
-    define_model_callbacks :insert
-    define_model_callbacks :attempt
-    define_model_callbacks :processing
-    define_model_callbacks :processed, only: :after
+    singleton_class.prepend BackburnerQueueOverrides
+    include Callbacks
 
     LOG_LEVELS = [
       :debug,
@@ -35,6 +122,97 @@ module Postburner
 
     validates :sid, presence: {strict: true}
 
+    # Abstract method to be implemented by subclasses.
+    #
+    # This method contains the actual work logic for the job. It is called
+    # by {#perform!} within the processing callbacks. Any exceptions raised
+    # will be logged and re-raised, causing the job to fail.
+    #
+    # @abstract Subclasses must implement this method
+    #
+    # @param args [Hash] Job arguments from the args JSONB column
+    #
+    # @return [void]
+    #
+    # @raise [NotImplementedError] if subclass does not implement this method
+    #
+    # @example
+    #   class ProcessPayment < Postburner::Job
+    #     def perform(args)
+    #       payment = Payment.find(args['payment_id'])
+    #       payment.process!
+    #       log "Payment #{payment.id} processed successfully"
+    #     end
+    #   end
+    #
+    # @note Use {#log} or {#log!} within perform to add entries to the job's audit trail
+    # @note Exceptions will be caught, logged to errata, and re-raised
+    #
+    # @see #perform!
+    # @see #log
+    # @see #log_exception
+    #
+    def perform(args)
+      raise NotImplementedError, "Subclasses must implement the perform method"
+    end
+
+    # @!method destroy
+    #   Destroys the job record and removes it from Beanstalkd queue.
+    #
+    #   Uses before_destroy callback to call {#delete!} which removes the job
+    #   from Beanstalkd before destroying the ActiveRecord model.
+    #
+    #   @return [self] the destroyed job object
+    #   @raise [Beaneater::NotConnected] if Beanstalkd connection fails
+    #   @see #delete!
+    #   @see #remove!
+    #   @note This is a standard Rails method with Beanstalkd integration via callback
+
+    # @!method destroy!
+    #   Destroys the job record and removes it from Beanstalkd queue, raising on failure.
+    #
+    #   Uses before_destroy callback to call {#delete!} which removes the job
+    #   from Beanstalkd before destroying the ActiveRecord model.
+    #
+    #   @return [self] the destroyed job object
+    #   @raise [ActiveRecord::RecordNotDestroyed] if validations prevent destruction
+    #   @raise [Beaneater::NotConnected] if Beanstalkd connection fails
+    #   @see #delete!
+    #   @see #remove!
+    #   @note This is a standard Rails method with Beanstalkd integration via callback
+
+    # Enqueues the job to Beanstalkd for processing.
+    #
+    # Sets queued_at timestamp and optionally run_at for scheduled execution.
+    # Triggers enqueue callbacks and inserts job into Beanstalkd via after_save_commit hook.
+    # In test mode, executes immediately instead of queueing to Beanstalkd.
+    #
+    # @param options [Hash] Queue options
+    # @option options [Time, ActiveSupport::Duration] :at Absolute time to run the job
+    # @option options [Integer, ActiveSupport::Duration] :delay Seconds to delay execution
+    # @option options [Integer] :pri Beanstalkd priority (lower = higher priority)
+    # @option options [Integer] :ttr Time-to-run in seconds before job times out
+    #
+    # @return [void]
+    #
+    # @raise [ActiveRecord::RecordInvalid] if job is not valid
+    # @raise [AlreadyProcessed] if job was already processed
+    #
+    # @example Queue immediately
+    #   job.queue!
+    #
+    # @example Queue with delay
+    #   job.queue!(delay: 1.hour)
+    #
+    # @example Queue at specific time
+    #   job.queue!(at: Time.zone.now + 2.days)
+    #
+    # @example Queue with priority
+    #   job.queue!(pri: 0, delay: 30.minutes)
+    #
+    # @see #requeue!
+    # @see Postburner.queue_strategy
+    #
     def queue!(options={})
       return if self.queued_at.present? && self.bkid.present?
       raise ActiveRecord::RecordInvalid, "Can't queue unless valid." unless self.valid?
@@ -55,9 +233,33 @@ module Postburner
 
       @_insert_options = options
 
-      self.save!
+      run_callbacks :enqueue do
+        self.save!
+      end
     end
 
+    # Re-queues an existing job by removing it from Beanstalkd and queueing again.
+    #
+    # Calls {#delete!} to remove from Beanstalkd, resets queuing metadata,
+    # then calls {#queue!} with new options.
+    #
+    # @param options [Hash] Queue options (same as {#queue!})
+    # @option options [Time, ActiveSupport::Duration] :at Absolute time to run the job
+    # @option options [Integer, ActiveSupport::Duration] :delay Seconds to delay execution
+    # @option options [Integer] :pri Beanstalkd priority
+    # @option options [Integer] :ttr Time-to-run in seconds
+    #
+    # @return [void]
+    #
+    # @raise [ActiveRecord::RecordInvalid] if job is not valid
+    # @raise [Beaneater::NotConnected] if Beanstalkd connection fails
+    #
+    # @example Requeue with different delay
+    #   job.requeue!(delay: 5.minutes)
+    #
+    # @see #queue!
+    # @see #delete!
+    #
     def requeue!(options={})
       self.delete!
       self.bkid, self.queued_at = nil, nil
@@ -65,11 +267,47 @@ module Postburner
       self.queue! options
     end
 
+    # Checks if job is flagged for insertion into Beanstalkd.
+    #
+    # Set internally by {#queue!} to trigger insertion via after_save_commit hook.
+    #
+    # @return [Boolean] true if job will be inserted on save
+    # @api private
+    #
     def will_insert?
       @_insert_options.is_a? Hash
     end
 
-    # tube: backburner.worker.queue.backburner-jobs
+    # Executes a job by ID, delegating to the current queue strategy.
+    #
+    # Loads the job from database by ID and delegates execution to the current
+    # queue strategy's {handle_perform!} method. This provides a unified API
+    # for job execution regardless of strategy (async, test, or null).
+    #
+    # Called automatically by Backburner workers in production. Can also be
+    # called manually for test/null strategies to trigger execution.
+    #
+    # @param id [Integer] Job ID to execute
+    # @param _ [Hash] Unused Backburner metadata parameter
+    #
+    # @return [void]
+    #
+    # @example Backburner automatic execution (production)
+    #   # Jobs execute in tube: backburner.worker.queue.backburner-jobs
+    #   # Backburner calls: Postburner::Job.perform(job_id)
+    #
+    # @example Manual execution with NullQueue
+    #   Postburner.null_strategy!
+    #   job = MyJob.create!(args: {})
+    #   job.queue!(delay: 1.hour)
+    #   Postburner::Job.perform(job.id)  # Time travels and executes
+    #
+    # @note Strategy-aware: delegates to Postburner.queue_strategy.handle_perform!
+    # @note For NullQueue, automatically handles time travel for scheduled jobs
+    #
+    # @see #perform!
+    # @see Queue.handle_perform!
+    # @see NullQueue.handle_perform!
     #
     def self.perform(id, _={})
       job = nil
@@ -80,12 +318,41 @@ module Postburner
 [Postburner::Job] [#{id}] Not Found.
         MSG
       end
-      #job&.perform!(job.args)
-      job.perform!(job.args)
+      #job.perform!(job.args)
+      Postburner.queue_strategy.handle_perform!(job)
     end
 
+    # Executes the job with full lifecycle management and error handling.
+    #
+    # This is the main execution method called by Backburner workers or test strategies.
+    # Performs validation checks, executes callbacks, calls the subclass {#perform} method,
+    # tracks timing and statistics, and handles errors.
+    #
+    # Execution flow:
+    # 1. Runs attempt callbacks (fires on every retry)
+    # 2. Updates attempting metadata (attempting_at, attempts, lag)
+    # 3. Validates job state (queued, not processed, not removed, not premature)
+    # 4. Runs processing callbacks
+    # 5. Calls subclass {#perform} method
+    # 6. Runs processed callbacks (only on success)
+    # 7. Updates completion metadata (processed_at, duration)
+    # 8. Logs and tracks any exceptions
+    #
+    # @param args [Hash] Arguments to pass to {#perform} method
+    #
+    # @return [void]
+    #
+    # @raise [Exception] Any exception raised by {#perform} is logged and re-raised
+    #
+    # @note Does not execute if queued_at is nil, in the future, already processed, or removed
+    # @note Premature execution (before run_at) is delegated to queue strategy
+    #
+    # @see #perform
+    # @see Postburner.queue_strategy
+    # @see Callbacks
+    #
     def perform!(args={})
-      _run_attempt_callbacks do
+      run_callbacks :attempt do
         self.attempting
 
         self.update_columns(
@@ -118,15 +385,14 @@ module Postburner
             return
           end
 
-          if self.run_at && self.run_at > Time.zone.now
-            response = self.insert! delay: self.run_at - Time.zone.now
-            self.log! "PREMATURE; RE-INSERTED: #{response}"
+          if self.run_at && self.run_at.to_i > Time.zone.now.to_i
+            Postburner.queue_strategy.handle_premature_perform(self)
             return
           end
 
           self.log!("START (bkid #{self.bkid})")
 
-          _run_processing_callbacks do
+          run_callbacks :processing do
             begin
               self.perform(args)
             rescue Exception => exception
@@ -142,7 +408,7 @@ module Postburner
             now = Time.zone.now
             _duration =  (now - self.processing_at) * 1000 rescue nil
 
-            _run_processed_callbacks do
+            run_callbacks :processed do
               persist_metadata!(
                 processed_at: now,
                 duration:     _duration,
@@ -162,6 +428,30 @@ module Postburner
 
     end
 
+    # Deletes the job from the Beanstalkd queue.
+    #
+    # This is a Beanstalkd operation that removes the job from the queue but
+    # does NOT destroy the ActiveRecord model. Use {#destroy} or {#remove!} to
+    # also update the database record.
+    #
+    # Automatically retries with fresh connection if Beanstalkd connection is stale.
+    # Called automatically by before_destroy callback when using {#destroy}.
+    #
+    # @return [void]
+    #
+    # @raise [Beaneater::NotConnected] if Beanstalkd connection fails after retry
+    #
+    # @note Does nothing if job has no bkid (e.g., in test mode)
+    # @note Does not modify ActiveRecord model - only affects Beanstalkd
+    #
+    # @example
+    #   job.delete!  # Removes from Beanstalkd queue only
+    #   job.reload   # Job still exists in database
+    #
+    # @see #remove!
+    # @see #destroy
+    # @see #beanstalk_job
+    #
     def delete!
       return unless self.beanstalk_job
       begin
@@ -171,6 +461,26 @@ module Postburner
       end
     end
 
+    # Kicks a buried job back into the ready queue in Beanstalkd.
+    #
+    # This is a Beanstalkd operation used to retry jobs that were buried due to
+    # repeated failures or explicit burial. Does not modify the ActiveRecord model.
+    #
+    # Automatically retries with fresh connection if Beanstalkd connection is stale.
+    #
+    # @return [void]
+    #
+    # @raise [Beaneater::NotConnected] if Beanstalkd connection fails after retry
+    #
+    # @note Does nothing if job has no bkid (e.g., in test mode)
+    # @note Only works on buried jobs - see Beanstalkd documentation
+    #
+    # @example
+    #   job.kick!  # Moves buried job back to ready queue
+    #
+    # @see #delete!
+    # @see #beanstalk_job
+    #
     def kick!
       return unless self.beanstalk_job
       begin
@@ -180,12 +490,49 @@ module Postburner
       end
     end
 
+    # Soft-deletes the job by removing from Beanstalkd and setting removed_at timestamp.
+    #
+    # Unlike {#destroy}, this preserves the job record in the database for audit trails
+    # while removing it from the Beanstalkd queue and marking it as removed.
+    #
+    # @return [void]
+    #
+    # @raise [Beaneater::NotConnected] if Beanstalkd connection fails
+    #
+    # @note Idempotent - does nothing if already removed
+    # @note Does not destroy ActiveRecord model - only soft deletes
+    #
+    # @example
+    #   job.remove!
+    #   job.removed_at  # => 2025-10-31 12:34:56 UTC
+    #   job.persisted?  # => true (still in database)
+    #
+    # @see #delete!
+    # @see #destroy
+    #
     def remove!
       return if self.removed_at
       self.delete!
       self.update_column(:removed_at, Time.zone.now)
     end
 
+    # Returns the Beanstalkd job object for direct queue operations.
+    #
+    # Provides access to the underlying Beaneater job object for advanced
+    # Beanstalkd operations. Caches the job object in an instance variable.
+    #
+    # @return [Beaneater::Job, nil] Beanstalkd job object or nil if no bkid
+    #
+    # @example Direct Beanstalkd operations
+    #   bk_job = job.beanstalk_job
+    #   bk_job.stats           # Get job statistics
+    #   bk_job.bury            # Bury the job
+    #   bk_job.release(pri: 0) # Release with priority
+    #
+    # @see #beanstalk_job!
+    # @see #delete!
+    # @see #kick!
+    #
     def beanstalk_job
       return unless self.bkid.present?
       return @_beanstalk_job if @_beanstalk_job
@@ -195,11 +542,43 @@ module Postburner
       @_beanstalk_job
     end
 
+    # Returns the Beanstalkd job object with cache invalidation.
+    #
+    # Same as {#beanstalk_job} but clears the cached instance variable first,
+    # forcing a fresh lookup from Beanstalkd. Use when job state may have changed.
+    #
+    # @return [Beaneater::Job, nil] Beanstalkd job object or nil if no bkid
+    #
+    # @example
+    #   job.beanstalk_job!  # Forces fresh lookup
+    #
+    # @see #beanstalk_job
+    #
     def beanstalk_job!
       @_beanstalk_job = nil
       self.beanstalk_job
     end
 
+    # Tracks an exception in the job's errata array.
+    #
+    # Appends exception details to the in-memory errata array with timestamp,
+    # class, message, and backtrace. Does NOT persist to database immediately.
+    # Use {#log_exception!} to persist immediately.
+    #
+    # @param exception [Exception] The exception to track
+    #
+    # @return [Array<Array>] Updated errata array
+    #
+    # @example
+    #   begin
+    #     # ... risky operation ...
+    #   rescue => e
+    #     log_exception(e)
+    #     raise
+    #   end
+    #
+    # @see #log_exception!
+    #
     def log_exception(exception)
       self.errata << [
         Time.zone.now,
@@ -212,11 +591,53 @@ module Postburner
       ]
     end
 
+    # Tracks an exception and immediately persists to database.
+    #
+    # Calls {#log_exception} to append exception details, then persists
+    # both errata and error_count to database via {#persist_metadata!}.
+    #
+    # @param exception [Exception] The exception to track
+    #
+    # @return [void]
+    #
+    # @example
+    #   begin
+    #     # ... risky operation ...
+    #   rescue => e
+    #     log_exception!(e)
+    #     raise
+    #   end
+    #
+    # @see #log_exception
+    #
     def log_exception!(exception)
       self.log_exception(exception)
-      self.update_column :errata, self.errata
+      self.persist_metadata!
     end
 
+    # Appends a log message to the job's logs array.
+    #
+    # Adds timestamped log entry to in-memory logs array with bkid, level,
+    # message, and elapsed time. Does NOT persist to database immediately.
+    # Use {#log!} to persist immediately.
+    #
+    # @param message [String] Log message to append
+    # @param options [Hash] Log options
+    # @option options [Symbol] :level Log level (:debug, :info, :warning, :error) - defaults to :info
+    #
+    # @return [Array<Array>] Updated logs array
+    #
+    # @note Invalid log levels are coerced to :error
+    #
+    # @example
+    #   log "Processing started"
+    #   log "Warning: rate limit approaching", level: :warning
+    #   log "Critical error occurred", level: :error
+    #
+    # @see #log!
+    # @see #elapsed_ms
+    # @see LOG_LEVELS
+    #
     def log(message, options={})
       options[:level] ||= :info
       options[:level] = :error unless LOG_LEVELS.member?(options[:level])
@@ -232,26 +653,131 @@ module Postburner
       ]
     end
 
-    # ms from attempting_at
+    # Returns elapsed time in milliseconds since job execution started.
+    #
+    # Calculates milliseconds between attempting_at and current time.
+    # Used to track how long a job has been executing.
+    #
+    # @return [Float, nil] Milliseconds since attempting_at, or nil if not yet attempting
+    #
+    # @example
+    #   elapsed_ms  # => 1234.567 (job has been running for ~1.2 seconds)
+    #
+    # @see #log
     #
     def elapsed_ms
       return unless self.attempting_at
       (Time.zone.now - self.attempting_at) * 1000
     end
 
+    # Appends a log message and immediately persists to database.
+    #
+    # Calls {#log} to append message, then persists logs array to database.
+    # Use this for important log messages that should be saved immediately.
+    #
+    # @param message [String] Log message to append
+    # @param options [Hash] Log options
+    # @option options [Symbol] :level Log level (:debug, :info, :warning, :error)
+    #
+    # @return [void]
+    #
+    # @example
+    #   log! "Job started"
+    #   log! "Payment processed successfully", level: :info
+    #   log! "Retrying failed request", level: :warning
+    #
+    # @see #log
+    #
     def log!(message, options={})
       self.log(message, options)
       self.update_column :logs, self.logs
     end
 
+    # Returns the intended execution time for the job.
+    #
+    # Returns run_at if scheduled, otherwise returns queued_at.
+    # Used for calculating lag (delay between intended and actual execution).
+    #
+    # @return [Time] Intended execution timestamp
+    #
+    # @example
+    #   job.queue!(delay: 1.hour)
+    #   job.intended_at  # => 1 hour from now (run_at)
+    #
+    #   job.queue!
+    #   job.intended_at  # => now (queued_at)
+    #
+    # @see #lag
+    #
     def intended_at
       self.run_at ? self.run_at : self.queued_at
     end
 
+    # Exception raised when attempting to queue a job that has already been processed.
+    #
+    # @example
+    #   job.queue!
+    #   # ... job completes ...
+    #   job.queue!  # => raises AlreadyProcessed
+    #
     class AlreadyProcessed < StandardError; end
 
+    # Exception raised when a job is executed before its scheduled run_at time.
+    #
+    # In production (Queue/NiceQueue), this is handled by re-inserting with delay.
+    # In test mode (TestQueue), this exception is raised to force explicit time management.
+    #
+    # @example
+    #   Postburner.inline_test_strategy!
+    #   job.queue!(delay: 1.hour)
+    #   # => raises PrematurePerform: "Job scheduled for ..."
+    #
+    # @see Postburner::TestQueue
+    # @see Postburner::ImmediateTestQueue
+    #
+    class PrematurePerform < StandardError; end
+
+    # Exception raised when a queue strategy returns an invalid response format.
+    #
+    # Queue strategies must return a Hash with an `:id` key when inserting jobs.
+    # The `:id` value represents the Beanstalkd job ID (can be nil for test strategies).
+    # This exception is raised in {#insert!} when a strategy returns a malformed response.
+    #
+    # @example Valid response formats
+    #   { id: 12345, status: "INSERTED" }  # Production with Beanstalkd ID
+    #   { id: nil, status: "INLINE" }      # Test strategy without Beanstalkd
+    #
+    # @example Invalid response (raises MalformedResponse)
+    #   "success"                          # Not a Hash
+    #   { status: "INSERTED" }             # Missing :id key
+    #   { "id" => 12345 }                  # String key instead of symbol
+    #
+    # @example Handling in custom strategy
+    #   class MyStrategy
+    #     def self.insert(job, options = {})
+    #       # Must return Hash with :id key (symbol)
+    #       { id: nil, status: "QUEUED" }
+    #     end
+    #   end
+    #
+    # @see #insert!
+    # @see Postburner.queue_strategy
+    #
+    class MalformedResponse < StandardError; end
+
     private
 
+    # Persists job metadata (errata, logs, and counts) to database.
+    #
+    # Updates errata, error_count, logs, and log_count columns, plus any
+    # additional data passed in. Used internally for atomic metadata updates.
+    #
+    # @param data [Hash] Additional columns to update
+    #
+    # @return [void]
+    #
+    # @api private
+    #
     def persist_metadata!(data={})
       self.update_columns({
         errata:       self.errata,
@@ -261,35 +787,57 @@ module Postburner
       }.merge(data))
     end
 
+    # After-save-commit callback that inserts job into queue if flagged.
+    #
+    # Checks {#will_insert?} and calls {#insert!} if true. Triggered by
+    # after_save_commit callback after {#queue!} saves the record.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
     def insert_if_queued!
       return unless self.will_insert?
-      backburner_response = insert!(@_insert_options)
-      Rails.logger.info "[Postburner] Backburner::Worker#enqueue for #{self.id}: #{backburner_response}"
-      true
+      insert!(@_insert_options)
     end
 
+    # Inserts job into queue via current queue strategy.
+    #
+    # Delegates to Postburner.queue_strategy.insert which handles actual
+    # queueing (Beanstalkd in production, inline execution in test mode).
+    # Updates bkid if the strategy returns a Beanstalkd job ID.
+    #
+    # @param options [Hash] Queue options (delay, pri, ttr, etc.)
+    #
+    # @return [Hash, nil] Queue strategy response
+    #
+    # @api private
+    #
     def insert!(options={})
-      response = nil
-
-      _run_insert_callbacks do
-        Job.transaction do
-          response = Backburner::Worker.enqueue(
-            Postburner::Job,
-            self.id,
-            options
-          )
-
-          persist_metadata!(
-            bkid: response[:id],
-          )
-        end
+      response = Postburner.queue_strategy.insert(self, options)
+
+      # Response must be a hash with an :id key (value can be nil)
+      # Backburner returns symbol keys
+      unless response.is_a?(Hash) && response.key?(:id)
+        raise MalformedResponse, "Missing :id key in response: #{response.inspect}"
       end
 
-      self.log("QUEUED: #{response}")
+      persist_metadata!(bkid: response[:id])
+
+      self.log("QUEUED: #{response}") if response
 
       response
     end
 
+    # Records an attempt and calculates execution lag.
+    #
+    # Appends current time to attempts array, sets attempting_at on first attempt,
+    # and calculates lag (delay between intended and actual execution time).
+    #
+    # @return [Time] Current timestamp
+    #
+    # @api private
+    #
     def attempting
       now = Time.zone.now
       self.attempts << now
@@ -298,10 +846,27 @@ module Postburner
       now
     end
 
+    # Before-validation callback that ensures job has a unique sid.
+    #
+    # Generates a UUID for sid if not already set. Used for job identification
+    # independent of database ID.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
     def ensure_sid!
       self.sid ||= SecureRandom.uuid
     end
 
+    # Backburner message format for the job.
+    #
+    # Returns a simple string representation used by Backburner.
+    #
+    # @return [String] Message format
+    #
+    # @api private
+    #
     def message
       "Job: #{self.id}"
     end