postburner 1.0.0.pre.3 → 1.0.0.pre.4

data/app/concerns/postburner/insertion.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Concern providing queue insertion methods for Postburner jobs.
+  #
+  # Handles enqueuing jobs to Beanstalkd (or test strategies), including
+  # scheduling, re-queueing, and the internal insertion mechanics via
+  # after_save_commit callbacks.
+  #
+  # @example Basic queueing
+  #   class MyJob < Postburner::Job
+  #     def perform(args)
+  #       # ... work ...
+  #     end
+  #   end
+  #
+  #   job = MyJob.create!(args: { foo: 'bar' })
+  #   job.queue!
+  #
+  # @example Scheduled queueing
+  #   job.queue!(delay: 1.hour)
+  #   job.queue!(at: 2.days.from_now)
+  #
+  module Insertion
+    extend ActiveSupport::Concern
+
+    # 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?
+      raise AlreadyProcessed, "Processed at #{self.processed_at}" if self.processed_at
+
+      at = options.delete(:at)
+      now = Time.zone.now
+
+      self.queued_at = now
+      self.run_at = case
+                    when at.present?
+                      # this is rudimentary, add error handling
+                      options[:delay] ||= at.to_i - now.to_i
+                      at
+                    when options[:delay].present?
+                      now + options[:delay].seconds
+                    end
+
+      @_insert_options = options
+
+      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
+
+      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
+
+    private
+
+    # 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?
+      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 = 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
+
+      persist_metadata!(bkid: response[:id])
+
+      self.log("QUEUED: #{response}") if response
+
+      response
+    end
+  end
+end

data/app/concerns/postburner/logging.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Concern providing logging and exception tracking for Postburner jobs.
+  #
+  # Provides methods for adding timestamped log entries and tracking exceptions
+  # in the job's PostgreSQL audit trail. All logs are stored in JSONB arrays
+  # with timestamps, levels, and elapsed time tracking.
+  #
+  # @example Basic logging
+  #   class MyJob < Postburner::Job
+  #     def perform(args)
+  #       log "Starting processing"
+  #       # ... work ...
+  #       log! "Critical checkpoint reached"
+  #     end
+  #   end
+  #
+  # @example Exception tracking
+  #   class MyJob < Postburner::Job
+  #     def perform(args)
+  #       process_data(args)
+  #     rescue => e
+  #       log_exception!(e)
+  #       raise
+  #     end
+  #   end
+  #
+  module Logging
+    extend ActiveSupport::Concern
+
+    included do
+      # Valid log levels in order of severity
+      LOG_LEVELS = [
+        :debug,
+        :info,
+        :warning,
+        :error
+      ].freeze
+    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,
+        {
+          bkid:       self.bkid,
+          class:      exception.class,
+          message:    exception.message,
+          backtrace:  exception.backtrace,
+        }
+      ]
+    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.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])
+
+      self.logs << [
+        Time.zone.now, # time
+        {
+          bkid:     self.bkid,
+          level:    options[:level], # level
+          message:  message, # message
+          elapsed:  self.elapsed_ms, # ms from start
+        }
+      ]
+    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
+
+    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,
+        error_count:  self.errata.length,
+        logs:         self.logs,
+        log_count:    self.logs.length,
+      }.merge(data))
+    end
+  end
+end

data/{lib/postburner/queue_config.rb → app/concerns/postburner/properties.rb}

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 module Postburner
-  # Queue configuration module for Postburner::Job classes.
+  # Queue properties 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.
+  # Defines configurable properties for job queue management.
   #
   # @example Basic usage
   #   class ProcessPayment < Postburner::Job
@@ -19,10 +18,13 @@ module Postburner
   #     end
   #   end
   #
-  module QueueConfig
+  module Properties
     extend ActiveSupport::Concern
 
     included do
+      # Instance-level queue configuration (overrides class-level defaults)
+      attr_writer :priority, :ttr
+
       class_attribute :postburner_queue_name, default: 'default'
       class_attribute :postburner_priority, default: nil
       class_attribute :postburner_ttr, default: nil
@@ -150,5 +152,64 @@ module Postburner
         end
       end
     end
+
+    # 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 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: {}, priority: 1500)
+    #   job.priority  # => 1500
+    #
+    def priority
+      @priority || self.class.priority
+    end
+
+    # Returns the 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: {}, ttr: 600)
+    #   job.ttr  # => 600
+    #
+    def ttr
+      @ttr || self.class.ttr
+    end
+
+    # Returns the full tube name with environment prefix.
+    #
+    # Expands the queue name to include the environment prefix
+    # (e.g., 'critical' becomes 'postburner.development.critical').
+    #
+    # @return [String] Full tube name with environment prefix
+    #
+    # @example
+    #   job.expanded_tube_name  # => 'postburner.development.critical'
+    #
+    def expanded_tube_name
+      Postburner.configuration.expand_tube_name(queue_name)
+    end
   end
 end

data/app/concerns/postburner/statistics.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Concern providing statistics and metrics methods for Postburner jobs.
+  #
+  # Provides methods for calculating timing metrics, retrieving job statistics,
+  # and determining intended execution times for scheduled jobs.
+  #
+  # @example Get job statistics
+  #   job.stats
+  #   # => { id: 5, bkid: 1, queue: "default", ... }
+  #
+  # @example Check elapsed time
+  #   job.elapsed_ms  # => 1234.567
+  #
+  module Statistics
+    extend ActiveSupport::Concern
+
+    # 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.expanded_tube_name)
+
+      {
+        id: self.id,
+        bkid: self.bkid,
+        queue: queue_name,
+        tube: expanded_tube_name,
+        watched: watched,
+        beanstalk: self.bk.stats.to_h.symbolize_keys,
+      }
+    end
+
+    # 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
+
+    # 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
+  end
+end