postburner 1.0.0.pre.12 → 1.0.0.pre.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49bdf9db5c61a4cc37f1ec0b0246b275f7ca825935e1083c98f9caef5ae383d
-  data.tar.gz: 9990e7870348f823d415755d76d0e33b0b10528dd3412c793c2922829a2ab9fd
+  metadata.gz: 61fa262497356b4b08226b9cb7138184c9a0b46958cb7a81d4c4ebd622be5487
+  data.tar.gz: 93bd5ef944fa62392546d96d607d02c076d94a2dc6e7d8f18fc32cfc90cdd4ec
 SHA512:
-  metadata.gz: 7b625d36b312e8eb1b1a4fb6509d87d23518a34943ee0150ccba3d57dd3b6b5970bbf40f5bf283be8c052b3be2b072888fa1fa3d47b9f72264b513ee5db7a05e
-  data.tar.gz: 9fdd52fb338a3a6575042e2af955711128c02b9534074935a5360113391169f0ab53657c6155acf40ca8ee34424a2b01583500a3efb75eb48e9ea467e428c759
+  metadata.gz: e2129e509d590c58c9d46192f6a60ea4576af7e4e56f94fceceb3d39c0d8db8fbda7f4bb1e65f140b294d9b4378ea965ec728088517384034c07881cb186c6fe
+  data.tar.gz: 9807a50fd61a2c24e8fe0620cafbc4fd10d903cde1a7d2b5a21118452c709fd69578e211a152bd10752fef9ab82561524d3d5040ae896394f8bab07c0dbdf6df

data/README.md

@@ -111,7 +111,7 @@ bundle exec rake postburner:work WORKER=default
 - [Beanstalkd Integration](#beanstalkd-integration)
 - [Installation](#installation)
 - [Deployment](#deployment)
-- [Web UI](#web-ui)
+- [Web UI - v2 Coming Soon](#web-ui)
 
 ## Why
 
@@ -249,6 +249,30 @@ Jobs without `Postburner::Beanstalkd` use defaults from `config/postburner.yml`:
 - `default_priority: 65536`
 - `default_ttr: 300`
 
+#### Configuring Third-Party Jobs
+
+For jobs you don't control (e.g., `Turbo::Streams::BroadcastJob`, `ActionMailer::MailDeliveryJob`), use the `enqueue_options` hook:
+
+```ruby
+# config/initializers/postburner.rb
+Postburner.configure do |config|
+  config.enqueue_options = ->(job) do
+    case job.class.name
+    when 'Turbo::Streams::BroadcastJob'
+      { priority: 100, ttr: 60 }
+    when 'ActionMailer::MailDeliveryJob'
+      { priority: 500, ttr: 120 }
+    else
+      {}  # Use defaults
+    end
+  end
+end
+```
+
+**Priority cascade:** `job.priority` (from `.set(priority: n)`) > `enqueue_options` hook > class-level > `default_priority`
+
+**TTR cascade:** class-level `ttr` > `enqueue_options` hook > `default_ttr`
+
 ### Tracked Jobs
 
 Tracked jobs store full execution details in PostgreSQL, providing comprehensive audit trails (i.e. logging, timing, errors, retry tracking) for critical operations.

data/app/concerns/postburner/insertion.rb

@@ -53,6 +53,9 @@ module Postburner
     #
     # @example Queue at specific time
     #   job.queue!(at: Time.zone.now + 2.days)
+    #   job.queue!(at: Time.zone.parse('2025-01-15 09:00:00'))
+    #   job.queue!(at: '2025-01-15 09:00:00'.in_time_zone)
+    #   job.queue!(at: Time.parse('2025-01-15 09:00:00 EST'))
     #
     # @example Queue with priority
     #   job.queue!(pri: 0, delay: 30.minutes)

data/app/models/postburner/schedule.rb

@@ -109,6 +109,7 @@ module Postburner
     validates :name, presence: true, uniqueness: true
     validates :job_class, presence: true
     validates :timezone, presence: true
+    validate :validate_timezone_exists!
     validate :validate_scheduling_mode!
     validate :validate_job_class_exists!
     validate :validate_cron_expression!, if: :cron?
@@ -387,6 +388,24 @@ module Postburner
       )
     end
 
+    # Validate that timezone is a recognized ActiveSupport timezone.
+    #
+    # Uses Time.find_zone to check if the timezone string resolves to a valid
+    # ActiveSupport::TimeZone. Invalid timezones would cause nil pointer errors
+    # during schedule calculations.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def validate_timezone_exists!
+      return if timezone.blank?
+
+      if Time.find_zone(timezone).nil?
+        errors.add(:timezone, "is not a recognized timezone")
+      end
+    end
+
     # Validate that exactly one scheduling mode is configured.
     #
     # Ensures either anchor+interval+interval_unit OR cron is set, but not both.

data/lib/postburner/active_job/adapter.rb

@@ -106,6 +106,47 @@ module ActiveJob
         job.class.included_modules.include?(Postburner::Tracked)
       end
 
+      # Resolves Beanstalkd options (priority and TTR) for a job.
+      #
+      # Uses a priority cascade:
+      # 1. job.priority (from .set(priority: n))
+      # 2. enqueue_options hook (for third-party jobs like Turbo)
+      # 3. Class-level configuration (postburner_ttr, priority DSL)
+      # 4. Global defaults from configuration
+      #
+      # @param job [ActiveJob::Base] The job instance
+      #
+      # @return [Hash] Hash with :pri and :ttr keys
+      #
+      def job_options(job)
+        hook_options = resolve_enqueue_options(job)
+
+        # Priority cascade: job.priority > hook > class-level > default
+        pri = job.priority ||
+              hook_options[:priority] ||
+              Postburner.configuration.default_priority
+
+        # TTR cascade: class-level > hook > default
+        ttr = (job.class.respond_to?(:postburner_ttr) && job.class.postburner_ttr) ||
+              hook_options[:ttr] ||
+              Postburner.configuration.default_ttr
+
+        { pri: pri, ttr: ttr }
+      end
+
+      # Calls the enqueue_options hook if configured.
+      #
+      # @param job [ActiveJob::Base] The job instance
+      #
+      # @return [Hash] Options hash with :priority and/or :ttr, or empty hash
+      #
+      def resolve_enqueue_options(job)
+        hook = Postburner.configuration.enqueue_options
+        return {} unless hook.respond_to?(:call)
+
+        hook.call(job) || {}
+      end
+
       # Enqueues a tracked job (with PostgreSQL audit trail).
       #
       # Creates a Postburner::TrackedJob record, then queues minimal payload
@@ -130,18 +171,13 @@ module ActiveJob
         # Queue to Beanstalkd with minimal payload
         Postburner.connected do |conn|
           tube_name = expand_tube_name(job.queue_name)
-
-          # Get priority and TTR
-          # Priority order: job.priority (from .set or class.priority) > default
-          pri = job.priority || Postburner.configuration.default_priority
-          ttr = job.class.respond_to?(:postburner_ttr) && job.class.postburner_ttr ||
-                Postburner.configuration.default_ttr
+          opts = job_options(job)
 
           bkid = conn.tubes[tube_name].put(
             Postburner::ActiveJob::Payload.tracked_payload(job, tracked_job.id),
-            pri: pri,
+            pri: opts[:pri],
             delay: delay,
-            ttr: ttr
+            ttr: opts[:ttr]
           )
 
           # Update tracked_job with Beanstalkd ID
@@ -164,18 +200,13 @@ module ActiveJob
 
         Postburner.connected do |conn|
           tube_name = expand_tube_name(job.queue_name)
-
-          # Get priority and TTR
-          # Priority order: job.priority (from .set or class.priority) > default
-          pri = job.priority || Postburner.configuration.default_priority
-          ttr = job.class.respond_to?(:postburner_ttr) && job.class.postburner_ttr ||
-                Postburner.configuration.default_ttr
+          opts = job_options(job)
 
           conn.tubes[tube_name].put(
             Postburner::ActiveJob::Payload.default_payload(job),
-            pri: pri,
+            pri: opts[:pri],
             delay: delay,
-            ttr: ttr
+            ttr: opts[:ttr]
           )
         end
       end

data/lib/postburner/configuration.rb

@@ -23,6 +23,7 @@ module Postburner
     # Global settings
     attr_accessor :beanstalk_url, :logger, :default_queue, :default_priority, :default_ttr
     attr_accessor :default_scheduler_interval, :default_scheduler_priority
+    attr_accessor :enqueue_options
 
     # Worker-specific settings (loaded for a single worker)
     attr_accessor :worker_config
@@ -35,6 +36,9 @@ module Postburner
     # @option options [Integer] :default_ttr Default time-to-run in seconds (default: 300)
     # @option options [Integer] :default_scheduler_interval Scheduler check interval in seconds (default: 300)
     # @option options [Integer] :default_scheduler_priority Scheduler job priority (default: 100)
+    # @option options [Proc] :enqueue_options Proc that receives job and returns options hash
+    #   with :priority and/or :ttr keys. Called during enqueue to customize job options.
+    #   Priority cascade: job.priority > hook > class-level > default
     # @option options [Hash] :worker_config Worker configuration hash with keys:
     #   - :name [String] Worker name
     #   - :queues [Array<String>] Queue/tube names to process
@@ -52,6 +56,7 @@ module Postburner
       @default_ttr = options[:default_ttr] || 300
       @default_scheduler_interval = options[:default_scheduler_interval] || 300
       @default_scheduler_priority = options[:default_scheduler_priority] || 100
+      @enqueue_options = options[:enqueue_options]
       @worker_config = options[:worker_config] || {
         name: 'default',
         queues: ['default'],

data/lib/postburner/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.12
+  version: 1.0.0.pre.13
 platform: ruby
 authors:
 - Matt Smith