postburner 0.8.0 → 1.0.0.pre.1

data/app/models/postburner/job.rb

@@ -1,26 +1,81 @@
 # 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
   #
   class Job < ApplicationRecord
-    include Backburner::Queue
+    include QueueConfig
+    include Callbacks
 
-    define_model_callbacks :insert
-    define_model_callbacks :attempt
-    define_model_callbacks :processing
-    define_model_callbacks :processed, only: :after
+    # Instance-level queue configuration (overrides class-level defaults)
+    attr_writer :queue_priority, :queue_ttr
 
     LOG_LEVELS = [
       :debug,
@@ -35,6 +90,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 +201,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 +235,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 +286,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 +353,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 +376,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 +396,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 +429,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,13 +458,50 @@ 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
 
-    def beanstalk_job
+    # 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.bk
+    #   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 bk
       return unless self.bkid.present?
       return @_beanstalk_job if @_beanstalk_job
 
@@ -195,11 +510,197 @@ module Postburner
       @_beanstalk_job
     end
 
-    def beanstalk_job!
+    alias_method :beanstalk_job, :bk
+
+    # 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 bk!
       @_beanstalk_job = nil
       self.beanstalk_job
     end
 
+    alias_method :beanstalk_job!, :bk!
+
+    # Returns job statistics including Beanstalkd job state.
+    #
+    # Fetches current job state from Beanstalkd and returns combined statistics
+    # about the job's PostgreSQL record and its current Beanstalkd status.
+    #
+    # @return [Hash] Statistics hash with the following keys:
+    #   - id: PostgreSQL job ID
+    #   - bkid: Beanstalkd job ID
+    #   - queue: Queue name configured for this job class (e.g., 'sleep-jobs')
+    #   - tube: Derived tube name with environment prefix (e.g., 'postburner.development.sleep-jobs')
+    #   - watched: Boolean indicating if tube is in configured watch list
+    #   - beanstalk: Hash of Beanstalkd job statistics:
+    #     - id: Beanstalkd job ID
+    #     - tube: Tube name where job resides
+    #     - state: Job state (ready, reserved, delayed, buried)
+    #     - pri: Priority (0 = highest, 4294967295 = lowest)
+    #     - age: Seconds since job was created
+    #     - delay: Seconds remaining before job becomes ready (0 if ready now)
+    #     - ttr: Time-to-run in seconds (time allowed for job processing)
+    #     - time_left: Seconds remaining before job times out (0 if not reserved)
+    #     - file: Binlog file number containing job
+    #     - reserves: Number of times job has been reserved
+    #     - timeouts: Number of times job has timed out during processing
+    #     - releases: Number of times job has been released back to ready
+    #     - buries: Number of times job has been buried
+    #     - kicks: Number of times job has been kicked from buried/delayed
+    #
+    # @raise [Beaneater::NotFoundError] if job no longer exists in Beanstalkd
+    #
+    # @example
+    #   job.stats
+    #   # => {
+    #   #   id: 5,
+    #   #   bkid: 1,
+    #   #   queue: "sleep-jobs",
+    #   #   tube: "postburner.development.sleep-jobs",
+    #   #   watched: false,
+    #   #   beanstalk: {
+    #   #     id: 1,
+    #   #     tube: "postburner.development.sleep-jobs",
+    #   #     state: "ready",
+    #   #     pri: 50,
+    #   #     age: 1391,
+    #   #     delay: 0,
+    #   #     ttr: 120,
+    #   #     time_left: 0,
+    #   #     file: 0,
+    #   #     reserves: 0,
+    #   #     timeouts: 0,
+    #   #     releases: 0,
+    #   #     buries: 0,
+    #   #     kicks: 0
+    #   #   }
+    #   # }
+    #
+    def stats
+      # Get configured watched tubes (expanded with environment prefix)
+      watched = Postburner.watched_tube_names.include?(self.tube_name)
+
+      {
+        id: self.id,
+        bkid: self.bkid,
+        queue: queue_name,
+        tube: tube_name,
+        watched: watched,
+        beanstalk: self.bk.stats.to_h.symbolize_keys,
+      }
+    end
+
+    alias_method :beanstalk_job_stats, :stats
+
+    # Returns the queue name for this job instance.
+    #
+    # Checks instance-level override first, then falls back to class-level configuration.
+    #
+    # @return [String] Queue name
+    #
+    # @example Class-level configuration
+    #   class MyJob < Postburner::Job
+    #     queue 'critical'
+    #   end
+    #   job = MyJob.create!(args: {})
+    #   job.queue_name  # => 'critical'
+    #
+    def queue_name
+      self.class.queue
+    end
+
+    # Returns the queue priority for this job instance.
+    #
+    # Checks instance-level override first, then falls back to class-level configuration.
+    #
+    # @return [Integer, nil] Priority (lower = higher priority)
+    #
+    # @example Instance-level override
+    #   job = MyJob.create!(args: {}, queue_priority: 1500)
+    #   job.queue_priority  # => 1500
+    #
+    def queue_priority
+      @queue_priority || self.class.queue_priority
+    end
+
+    # Returns the queue TTR (time-to-run) for this job instance.
+    #
+    # Checks instance-level override first, then falls back to class-level configuration.
+    #
+    # @return [Integer, nil] TTR in seconds
+    #
+    # @example Instance-level override
+    #   job = MyJob.create!(args: {}, queue_ttr: 600)
+    #   job.queue_ttr  # => 600
+    #
+    def queue_ttr
+      @queue_ttr || self.class.queue_ttr
+    end
+
+    def tube_name
+      Postburner.configuration.expand_tube_name(queue_name)
+    end
+
+    # Extends the job's time-to-run (TTR) in Beanstalkd.
+    #
+    # 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]
+    #
+    # @note Does nothing if job has no bkid (e.g., in test mode)
+    #
+    # @example Process large file line by line
+    #   def perform(args)
+    #     file = File.find(args['file_id'])
+    #     file.each_line do |line|
+    #       # ... process line ...
+    #       extend!  # Extend TTR to prevent timeout
+    #     end
+    #   end
+    #
+    # @see #bk
+    #
+    def extend!
+      return unless self.bk
+      begin
+        self.bk.touch
+      rescue Beaneater::NotConnected => e
+        self.bk!.touch
+      end
+    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 +713,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 +775,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 +909,59 @@ 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!
+      #debugger
       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(
-            self.class,
-            self.id,
-            options
-          )
-
-          persist_metadata!(
-            bkid: response[:id],
-          )
-        end
+      response = Postburner.queue_strategy.insert(self, options)
+      #debugger
+
+      # 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 +970,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