postburner 1.0.0.pre.17 → 1.0.0.pre.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05d87a7d1949eb64ef1918b4bb0f0cdeb24796097c370f90576b3a158d0be5a7
-  data.tar.gz: 857304a0b925574ab66d6ad215e6cbe3bdba8c109ecb9a34e96e8ab0ca40aac3
+  metadata.gz: 4af263bde4adb664e58df7f7045152e0fee7c29c953227aeb962b385b68de21d
+  data.tar.gz: 976c3a47d49bf83c26719e7b8adf17d05c827c0cd982855c5258307d703c4acf
 SHA512:
-  metadata.gz: af92d06c7d796c0db2bb766986bc9b27ad46e9958103e11871538e3224b43a054d80fb50b7bb0b5f8d93de1a11331e10b10d26058c219047e15530f6a36a1b9e
-  data.tar.gz: 351f86f49998e5350b7b705a4f77f68a91c29340995dc5531b964bbdb40b6bb55f3c4202459cdc7453429c7e3b7ceaa4ca934628fc8503305f9630eb9c287142
+  metadata.gz: 30e9379f4c7e05d18659f9864fb58c9e8a0f564575d323a9d3865b352ba3e0d08975bc9a3859d8044602f5c657c16bdd7dd32098944d07b6ad8007124f868a26
+  data.tar.gz: 1c0eb570bf338995bfa385a95c6d8ded11a937fb6155481b199e6a94f5992104d6ebc9524601056397f6251c89841d9148d7d45434e583d2e8f91e1e8f14aa66

data/README.md

@@ -302,6 +302,7 @@ end
 Jobs without `Postburner::Beanstalkd` use defaults from `config/postburner.yml`:
 - `default_priority: 65536`
 - `default_ttr: 300`
+- `default_queue: default` (if not specified, defaults to `'default'`)
 
 #### Configuring Third-Party Jobs
 
@@ -1278,6 +1279,8 @@ production:  # <- environment config
 # config/postburner.yml
 default: &default
   beanstalk_url: <%= ENV['BEANSTALK_URL'] || 'beanstalk://localhost:11300' %>
+  # default_queue: default       # Queue for jobs (defaults to 'default')
+  default_mailer_queue: mailers  # Queue for Postburner::Mailer (defaults to default_queue)
 
 development:  # <- environment config
   <<: *default
@@ -1781,7 +1784,9 @@ Set default priority in `config/postburner.yml`:
 
 ```yaml
 production:
-  default_priority: 65536  # Default without explicit priority set
+  default_queue: default           # Queue for jobs (defaults to 'default')
+  default_mailer_queue: mailers    # Queue for Postburner::Mailer (defaults to default_queue)
+  default_priority: 65536          # Default without explicit priority set
   default_ttr: 300
 ```
 

data/app/concerns/postburner/properties.rb

@@ -202,10 +202,10 @@ module Postburner
     #   job.queue_name  # => 'urgent'
     #
     def queue_name
-      @queue_name || self.class.queue || Postburner.configuration.default_queue_name
+      @queue_name || self.class.queue || Postburner.configuration.default_queue
     end
 
-    # Returns the full tube name with environment prefix.
+    # Returns the full Beanstalkd tube name with environment prefix.
     #
     # Expands the queue name to include the environment prefix
     # (e.g., 'critical' becomes 'postburner.development.critical').
@@ -213,12 +213,18 @@ module Postburner
     # @return [String] Full tube name with environment prefix
     #
     # @example
-    #   job.expanded_tube_name  # => 'postburner.development.critical'
+    #   job.tube_name  # => 'postburner.development.critical'
     #
-    def expanded_tube_name
+    def tube_name
       Postburner.configuration.expand_tube_name(queue_name)
     end
 
+    # @!method expanded_tube_name
+    #   Alias for {#tube_name}.
+    #   @return [String] Full tube name with environment prefix
+    #   @see #tube_name
+    alias_method :expanded_tube_name, :tube_name
+
     # Returns the priority for this job instance.
     #
     # Checks instance-level override first, then falls back to class-level configuration.

data/app/concerns/postburner/statistics.rb

@@ -73,13 +73,13 @@ module Postburner
     #
     def stats
       # Get configured watched tubes (expanded with environment prefix)
-      watched = Postburner.watched_tube_names.include?(self.expanded_tube_name)
+      watched = Postburner.watched_tube_names.include?(self.tube_name)
 
       {
         id: self.id,
         bkid: self.bkid,
         queue: queue_name,
-        tube: expanded_tube_name,
+        tube: tube_name,
         watched: watched,
         beanstalk: self.bk.stats.to_h.symbolize_keys,
       }

data/app/models/postburner/mailer.rb

@@ -1,12 +1,90 @@
 module Postburner
-  # Send a mailer, tracked.
+  # A tracked job for sending ActionMailer emails via Beanstalkd.
   #
-  # Postburner::Mailer.deliver(UserMailer, :welcome).with(user_id: 1)
-  # Postburner::Mailer.deliver(UserMailer, :welcome).with(user_id: 1).queue! at: Time.current + 1.day
-  # Postburner::Mailer.deliver(UserMailer, :welcome).with(user_id: 1).queue! delay: 5.minutes
+  # Provides a chainable API similar to ActionMailer for building and
+  # queueing email deliveries with full audit trail support.
+  #
+  # == Queue Configuration
+  #
+  # By default, mailer jobs use the +default_queue+ (typically 'default').
+  # You can route mailers to a dedicated queue using several approaches:
+  #
+  # === Via configuration (recommended)
+  #
+  # Set +default_mailer_queue+ in your postburner.yml or configuration:
+  #
+  #   # config/postburner.yml
+  #   production:
+  #     default_mailer_queue: mailers
+  #
+  #   # Or programmatically
+  #   Postburner.configure do |config|
+  #     config.default_mailer_queue = 'mailers'
+  #   end
+  #
+  # === Via queue! option (per-job override)
+  #
+  # Override the queue when queueing a specific job:
+  #
+  #   Postburner::Mailer.delivery(UserMailer, :welcome)
+  #     .with(user_id: 1)
+  #     .queue!(queue: 'priority_mailers')
+  #
+  # === Via instance setter (per-job override)
+  #
+  # Set the queue on the job instance before queueing:
+  #
+  #   job = Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1)
+  #   job.queue_name = 'priority_mailers'
+  #   job.queue!
+  #
+  # @example Basic delivery (queued immediately)
+  #   Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!
+  #
+  # @example Scheduled delivery at a specific time
+  #   Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(at: Time.current + 1.day)
+  #
+  # @example Delayed delivery
+  #   Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(delay: 5.minutes)
+  #
+  # @example Queue to specific queue
+  #   Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(queue: 'bulk_mailers')
+  #
+  # @see Postburner::Job Base class for tracked jobs
+  # @see Postburner::Configuration#default_mailer_queue Configuration option
   class Mailer < Job
-    #queue 'mailers'
 
+    # Returns the queue name for this mailer job.
+    #
+    # Checks in order: instance override, +default_mailer_queue+ config,
+    # then falls back to +default_queue+.
+    #
+    # @return [String] Queue name
+    #
+    # @example Default behavior (uses default_mailer_queue or default_queue)
+    #   job = Postburner::Mailer.delivery(UserMailer, :welcome)
+    #   job.queue_name  # => 'mailers' (if configured) or 'default'
+    #
+    # @example Instance override
+    #   job = Postburner::Mailer.delivery(UserMailer, :welcome)
+    #   job.queue_name = 'priority_mailers'
+    #   job.queue_name  # => 'priority_mailers'
+    def queue_name
+      @queue_name ||
+        self.class.queue ||
+        Postburner.configuration.default_mailer_queue ||
+        Postburner.configuration.default_queue
+    end
+
+    # Build a new mailer job without persisting.
+    #
+    # @param mailer [Class] The ActionMailer class (e.g., UserMailer)
+    # @param action [Symbol, String] The mailer action/method name (e.g., :welcome)
+    # @return [Postburner::Mailer] An unsaved mailer job instance
+    #
+    # @example
+    #   job = Postburner::Mailer.delivery(UserMailer, :welcome)
+    #   job.with(user_id: 1).queue!
     def self.delivery(mailer, action)
       job = self.new(
         args: {
@@ -17,14 +95,33 @@ module Postburner
       job
     end
 
+    # Build and persist a new mailer job.
+    #
+    # @param mailer [Class] The ActionMailer class (e.g., UserMailer)
+    # @param action [Symbol, String] The mailer action/method name (e.g., :welcome)
+    # @return [Postburner::Mailer] A persisted mailer job instance
+    #
+    # @example
+    #   job = Postburner::Mailer.delivery!(UserMailer, :password_reset)
+    #   job.with!(token: reset_token)
     def self.delivery!(mailer, action)
       job = self.delivery(mailer, action)
       job.save!
       job
     end
 
-    # Similar to ActionMailer #with - set the parameters
+    # Set the mailer parameters without persisting.
+    #
+    # Similar to ActionMailer's +#with+ method for parameterized mailers.
+    # Parameters are serialized using ActiveJob::Arguments for safe storage.
+    #
+    # @param params [Hash] Parameters to pass to the mailer
+    # @return [self] Returns self for method chaining
     #
+    # @example
+    #   Postburner::Mailer.delivery(UserMailer, :welcome)
+    #     .with(user_id: 1, locale: :en)
+    #     .queue!
     def with(params={})
       self.args.merge!(
         'params' => ::ActiveJob::Arguments.serialize(params)
@@ -32,16 +129,31 @@ module Postburner
       self
     end
 
+    # Set the mailer parameters and persist immediately.
+    #
+    # @param params [Hash] Parameters to pass to the mailer
+    # @return [self] Returns self for method chaining
+    #
+    # @example
+    #   job = Postburner::Mailer.delivery!(OrderMailer, :confirmation)
+    #   job.with!(order_id: order.id)
     def with!(params={})
       self.with(params)
       self.save!
       self
     end
 
-    # Build the mail but don't send.
+    # Build the Mail::Message without sending.
+    #
+    # Useful for testing or inspecting the email before delivery.
     #
-    # Optional `args` argument for testing convenience.
+    # @return [Mail::Message] The assembled email message
     #
+    # @example Inspect email before sending
+    #   job = Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1)
+    #   mail = job.assemble
+    #   puts mail.subject  # => "Welcome!"
+    #   puts mail.to       # => ["user@example.com"]
     def assemble
       mail = self.mailer.with(self.params).send(self.action)
       mail
@@ -49,22 +161,43 @@ module Postburner
 
     # Get the mailer class.
     #
+    # @return [Class] The ActionMailer class
+    #
+    # @example
+    #   job.mailer  # => UserMailer
     def mailer
       self.args['mailer'].constantize
     end
 
-    # Get the mailer action as a symbol.
+    # Get the mailer action name.
+    #
+    # @return [Symbol, nil] The mailer action as a symbol
     #
+    # @example
+    #   job.action  # => :welcome
     def action
       self.args['action']&.to_sym
     end
 
-    # Get the deserialized params.
+    # Get the deserialized mailer parameters.
     #
+    # @return [Hash] The parameters passed via {#with}
+    #
+    # @example
+    #   job.params  # => { user_id: 1, locale: :en }
     def params
       ::ActiveJob::Arguments.deserialize(self.args['params']).to_h
     end
 
+    # Execute the mailer job.
+    #
+    # Called by the Postburner worker. Assembles and delivers the email,
+    # logging progress at each step.
+    #
+    # @param args [Hash] Job arguments (unused, params stored in {#args})
+    # @return [void]
+    #
+    # @api private
     def perform(args)
       self.log! "Building"
       mail = self.assemble

data/lib/postburner/configuration.rb

@@ -22,7 +22,7 @@ module Postburner
   class Configuration
     # Global settings
     attr_accessor :beanstalk_url, :logger, :default_priority, :default_ttr
-    attr_accessor :default_queue_name, :default_max_retries, :default_retry_delay
+    attr_accessor :default_queue, :default_mailer_queue, :default_max_retries, :default_retry_delay
     attr_accessor :default_scheduler_interval, :default_scheduler_priority
     attr_accessor :enqueue_options
 
@@ -34,6 +34,7 @@ module Postburner
     # @option options [Logger] :logger Logger instance (default: Rails.logger)
     # @option options [Integer] :default_priority Default job priority (default: 65536, lower = higher priority)
     # @option options [Integer] :default_ttr Default time-to-run in seconds (default: 300)
+    # @option options [String] :default_mailer_queue Queue name for Postburner::Mailer jobs (default: nil, uses default_queue)
     # @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
@@ -53,7 +54,8 @@ module Postburner
       @logger = options[:logger] || (defined?(Rails) ? Rails.logger : Logger.new(STDOUT))
       @default_priority = options[:default_priority] || 65536
       @default_ttr = options[:default_ttr] || 300
-      @default_queue_name = options[:default_queue_name] || 'default'
+      @default_queue = options[:default_queue] || 'default'
+      @default_mailer_queue = options[:default_mailer_queue]
       @default_max_retries = options[:default_max_retries] || 0
       @default_retry_delay = options[:default_retry_delay] || ->(n) { 2 ** n }
       @default_scheduler_interval = options[:default_scheduler_interval] || 300
@@ -97,6 +99,7 @@ module Postburner
     #   default: &default
     #     beanstalk_url: <%= ENV.fetch('BEANSTALK_URL', 'beanstalk://localhost:11300') %>
     #     default_priority: 131072 # change default priority from 65536 to 131072
+    #     default_mailer_queue: mailers  # optional: route Postburner::Mailer to separate queue
     #
     #   production: # <- environment config, i.e. defaults
     #     <<: *default
@@ -166,6 +169,8 @@ module Postburner
         beanstalk_url: env_config['beanstalk_url'],
         default_priority: env_config['default_priority'],
         default_ttr: env_config['default_ttr'],
+        default_queue: env_config['default_queue'],
+        default_mailer_queue: env_config['default_mailer_queue'],
         default_scheduler_interval: env_config['scheduler_interval'],
         default_scheduler_priority: env_config['scheduler_priority'],
         worker_config: worker_config

data/lib/postburner/strategies/strict_queue.rb

@@ -76,7 +76,7 @@ module Postburner
         #debugger
         Postburner::Job.transaction do
           Postburner.connected do |conn|
-            tube_name = job.expanded_tube_name
+            tube_name = job.tube_name
             data = { class: job.class.name, args: [job.id] }
 
             # Get priority, TTR from job instance (respects instance overrides) or options

data/lib/postburner/tube.rb

@@ -1,35 +1,96 @@
 module Postburner
+  # A wrapper around Beaneater tubes for inspecting Beanstalkd queues.
+  #
+  # Provides methods to enumerate tubes and paginate through jobs,
+  # primarily used by the Postburner web UI for job inspection.
+  #
+  # @note Beanstalkd is not designed for job enumeration or searching.
+  #   It is optimized for fast job reservation, not inspection. This class
+  #   iterates through job IDs sequentially which is inherently inefficient.
+  #   Use this only for debugging and development purposes, not for
+  #   production workloads or high-volume introspection of queues.
+  #
+  # @example List all tubes
+  #   tubes = Postburner::Tube.all
+  #   tubes.each { |tube| puts tube.peek_ids }
+  #
+  # @example Paginate through jobs in a tube
+  #   tube = Postburner::Tube.all.first
+  #   first_page = tube.jobs(20)
+  #   second_page = tube.jobs(20, after: first_page.last.id)
+  #
+  # @see Postburner.connection For accessing the Beaneater connection
   class Tube
+    # Initialize a new Tube wrapper.
+    #
+    # @param tube [Beaneater::Tube] The underlying Beaneater tube object
     def initialize(tube)
       @tube = tube
     end
 
     # Get all tubes as Postburner::Tube instances.
     #
+    # @return [Array<Postburner::Tube>] All tubes from the Beanstalkd server
+    #
+    # @example
+    #   Postburner::Tube.all
+    #   # => [#<Postburner::Tube>, #<Postburner::Tube>, ...]
     def self.all
       Postburner.connection.tubes.all.map { |tube| self.new(tube) }
     end
 
-    # Get all peeked ids across all known tubes.
+    # Get all peeked job IDs across all known tubes.
+    #
+    # Useful for finding the minimum known job ID when starting pagination.
+    #
+    # @return [Array<Integer>] Sorted array of job IDs from all tubes
     #
+    # @example
+    #   Postburner::Tube.peek_ids
+    #   # => [1, 5, 12, 47, 89, 102]
     def self.peek_ids
       self.all.map(&:peek_ids).flatten.sort
     end
 
-    # Get all peeked ids.
+    # Get peeked job IDs from this tube.
     #
+    # Peeks at buried, ready, and delayed states to find known job IDs.
+    #
+    # @return [Array<Integer>] Job IDs visible via peek operations
+    #
+    # @example
+    #   tube = Postburner::Tube.all.first
+    #   ids = tube.peek_ids  # => [1, 5, 12]
     def peek_ids
       [ :buried, :ready, :delayed ].map { |type| @tube.peek(type) }.
         reject(&:nil?).map(&:id).map(&:to_i)
     end
 
-    # Get paginated array of jobs.
+    # Get a paginated array of jobs from this tube.
+    #
+    # Efficiently retrieves jobs by starting from known IDs and iterating
+    # until the requested count is fulfilled. Supports cursor-based pagination
+    # via the +after+ parameter.
+    #
+    # @param count [Integer] Number of jobs to return (default: 20)
+    # @param limit [Integer] Maximum ID range to scan (default: 1000)
+    # @param after [Integer, nil] Return jobs after this ID for pagination
+    # @return [Array<Beaneater::Job>] Jobs from this tube
     #
-    # Attempts to do this efficiently as possible, by peeking at known
-    # ids and exiting when count has been fulfilled.
+    # @example Get first page of jobs
+    #   tube.jobs(20)
+    #   # => [#<Beaneater::Job id=1>, #<Beaneater::Job id=5>, ...]
     #
-    # Just pass the last known id to after for the next batch.
+    # @example Access job properties
+    #   jobs = tube.jobs(5)
+    #   jobs.first.id      # => 1
+    #   jobs.first.body    # => "{\"job_class\":\"MyJob\",...}"
+    #   jobs.first.stats   # => {"tube"=>"default", "state"=>"ready", ...}
     #
+    # @example Paginate through jobs
+    #   page1 = tube.jobs(20)
+    #   page2 = tube.jobs(20, after: page1.last.id)
+    #   # => [#<Beaneater::Job id=25>, #<Beaneater::Job id=26>, ...]
     def jobs(count=20, limit: 1000, after: nil)
       # Note: beaneater transforms hyphenated beanstalkd stats to underscores
       stats = @tube.stats

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.17'
+  VERSION = '1.0.0.pre.18'
 end

data/lib/postburner.rb

@@ -405,6 +405,11 @@ module Postburner
   #   Postburner.clear_jobs!(Postburner.scheduler_tube_name)
   #   # Clears the scheduler watchdog tube
   #
+  # @example Clear watched tubes AND scheduler tube
+  #   Postburner.clear_jobs!(Postburner.watched_tube_names + [Postburner.scheduler_tube_name])
+  #   # Or use the convenience method:
+  #   Postburner.clear_all!
+  #
   # @example Trying to clear unconfigured tube - RAISES ERROR
   #   Postburner.clear_jobs!(['some-other-app-tube'])
   #   # => ArgumentError: Cannot clear tubes not in configuration
@@ -413,6 +418,7 @@ module Postburner
   #   result = Postburner.clear_jobs!(Postburner.watched_tube_names, silent: true)
   #   result[:totals][:total]  # => 42
   #
+  # @see #clear_all!
   # @see Connection#clear_tubes!
   #
   def self.clear_jobs!(tube_names = nil, silent: false)
@@ -431,21 +437,25 @@ module Postburner
   # Clears all configured tubes including scheduler.
   #
   # Convenience method that clears all watched tubes plus the scheduler tube
-  # in a single call. This is the equivalent of:
+  # in a single call. Use this to completely reset Postburner's Beanstalkd state,
+  # such as during test setup or when recovering from a stuck state.
   #
+  # Equivalent to:
   #   Postburner.clear_jobs!(Postburner.watched_tube_names + [Postburner.scheduler_tube_name])
   #
   # @param silent [Boolean] If true, suppress output to stdout (default: false)
   #
   # @return [Hash] Statistics and results (see Connection#clear_tubes!)
   #
-  # @example Clear everything
+  # @example Clear everything (interactive/console use)
   #   Postburner.clear_all!
   #
-  # @example Silent mode
-  #   result = Postburner.clear_all!(silent: true)
+  # @example Silent mode (test setup or programmatic use)
+  #   Postburner.clear_all!(silent: true)
   #
   # @see #clear_jobs!
+  # @see #watched_tube_names
+  # @see #scheduler_tube_name
   #
   def self.clear_all!(silent: false)
     all_tubes = watched_tube_names + [scheduler_tube_name]

metadata

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