postburner 1.0.0.pre.2 → 1.0.0.pre.4

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

@@ -1,28 +1,30 @@
 # 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
   #     queue 'critical'
-  #     queue_priority 0
-  #     queue_ttr 300
-  #     queue_max_job_retries 3
+  #     priority 0
+  #     ttr 300
+  #     max_retries 3
   #
   #     def perform(args)
   #       # ...
   #     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
@@ -32,6 +34,9 @@ module Postburner
 
     class_methods do
       # Sets or returns the queue name.
+      # 
+      # The queue name expands 'postburner.<environment>.<queue_name>' for the
+      # tube name in Beanstalkd.
       #
       # @param name [String, Symbol, nil] Queue name to set, or nil to get current value
       #
@@ -52,21 +57,21 @@ module Postburner
         end
       end
 
-      # Sets or returns the queue priority.
+      # Sets or returns the priority.
       #
-      # Lower numbers = higher priority in Beanstalkd.
+      # Lower numbers = higher priority in Beanstalkd (0 is highest).
       #
       # @param pri [Integer, nil] Priority to set (0-4294967295), or nil to get current value
       #
       # @return [Integer, nil] Current priority when getting, nil when setting
       #
       # @example Set priority
-      #   queue_priority 0  # Highest priority
+      #   priority 0  # Highest priority
       #
       # @example Get priority
-      #   ProcessPayment.queue_priority  # => 0
+      #   ProcessPayment.priority  # => 0
       #
-      def queue_priority(pri = nil)
+      def priority(pri = nil)
         if pri
           self.postburner_priority = pri
           nil
@@ -75,24 +80,24 @@ module Postburner
         end
       end
 
-      # Sets or returns the queue TTR (time-to-run).
+      # Sets or returns the TTR (time-to-run).
       #
       # Number of seconds Beanstalkd will wait for job completion before
       # making it available again.
       #
-      # @param ttr [Integer, nil] Timeout in seconds, or nil to get current value
+      # @param seconds [Integer, nil] Timeout in seconds, or nil to get current value
       #
       # @return [Integer, nil] Current TTR when getting, nil when setting
       #
       # @example Set TTR
-      #   queue_ttr 300  # 5 minutes
+      #   ttr 300  # 5 minutes
       #
       # @example Get TTR
-      #   ProcessPayment.queue_ttr  # => 300
+      #   ProcessPayment.ttr  # => 300
       #
-      def queue_ttr(ttr = nil)
-        if ttr
-          self.postburner_ttr = ttr
+      def ttr(seconds = nil)
+        if seconds
+          self.postburner_ttr = seconds
           nil
         else
           postburner_ttr
@@ -106,12 +111,12 @@ module Postburner
       # @return [Integer, nil] Current max retries when getting, nil when setting
       #
       # @example Set max retries
-      #   queue_max_job_retries 3
+      #   max_retries 3
       #
       # @example Get max retries
-      #   ProcessPayment.queue_max_job_retries  # => 3
+      #   ProcessPayment.max_retries  # => 3
       #
-      def queue_max_job_retries(retries = nil)
+      def max_retries(retries = nil)
         if retries
           self.postburner_max_retries = retries
           nil
@@ -130,15 +135,15 @@ module Postburner
       # @return [Integer, Proc, nil] Current delay when getting, nil when setting
       #
       # @example Set fixed retry delay
-      #   queue_retry_delay 10
+      #   retry_delay 10
       #
       # @example Set exponential backoff with proc
-      #   queue_retry_delay ->(retries) { 2 ** retries }
+      #   retry_delay ->(retries) { 2 ** retries }
       #
       # @example Get retry delay
-      #   ProcessPayment.queue_retry_delay  # => 10 or #<Proc>
+      #   ProcessPayment.retry_delay  # => 10 or #<Proc>
       #
-      def queue_retry_delay(delay = nil)
+      def retry_delay(delay = nil)
         if delay
           self.postburner_retry_delay = delay
           nil
@@ -147,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