postburner 1.0.0.pre.4 → 1.0.0.pre.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a279e41bee615d867b4392c53c9cfe9535c1652842f166f2f6cd33b3fc6215e2
-  data.tar.gz: f11ad9028e92679bc5c5fc3d62b75d8a3a163394bb130dac4bb9a1bcd33c7cfb
+  metadata.gz: 38e2982c4478f99aa0d19c58ac7455cdf82ff1c3707a154d1dbd0c3a1546ceb8
+  data.tar.gz: 0d17bb9da882d8e1cf2cce7c1cddd508ddbc7531c037dd56b7e0c6d34bd40f5b
 SHA512:
-  metadata.gz: 70eeebf1007b699b58713d3a9fc107aabf118fe6c13c39d519e4b800416d9ea185bb96012be1e37a617ef7b4e52896e1387aa2f11e9b45077912bb154071f62f
-  data.tar.gz: 1e34ecbf3dfe03401f7280deca6939e056bceb21ed6d2303e87b4f5c53d5ea23f0d712814acc48a356b471dbd1754505a155e7830c304051bfb1faae2fe4fde1
+  metadata.gz: 28421eb19f5e288e43e9d455364906dabe0ee3ab024a230efb9aca19842ac3677c4b602788d8f0f7c67253f64e1b382d12a4f23756ff01ef2e43a5b51d478d55
+  data.tar.gz: f13d5452e5394c3e6d8b9468d8863344f35049972fbe5eac6c20cbede12ddc7e9eb2a17538bccb626a7a00a744c567d33e59558f5e7309ab3ecf775bea3db5b9

data/README.md

@@ -48,8 +48,11 @@ class ProcessPayment < ApplicationJob
   end
 end
 
-# Run worker
+# Run worker (bin/postburner)
 bundle exec postburner --worker default
+
+# Or with rake task
+bundle exec rake postburner:work WORKER=default
 ```
 
 ## Why
@@ -124,7 +127,8 @@ beanstalkd -l 127.0.0.1 -p 11300 # Start beanstalkd
 bundle exec rails generate postburner:install
 bundle exec rails db:migrate
 
-bundle exec postburner # start
+bundle exec postburner           # start with bin/postburner
+bundle exec rake postburner:work # or with rake task
 ```
 
 ## Table of Contents
@@ -849,6 +853,52 @@ bin/postburner --worker general    # Run the 'general' worker
 bin/postburner --worker general --queues default,mailers  # Only process specific queues
 ```
 
+**Rake task:**
+```bash
+bundle exec rake postburner:work                          # Auto-select worker
+bundle exec rake postburner:work WORKER=general           # Specific worker
+bundle exec rake postburner:work WORKER=general QUEUES=default,mailers  # Filter queues
+bundle exec rake postburner:work CONFIG=config/custom.yml # Custom config
+```
+
+### Programmatic Worker Control
+
+Use `Postburner::Runner` to start workers programmatically from Ruby code:
+
+```ruby
+# Basic usage
+runner = Postburner::Runner.new(
+  config: 'config/postburner.yml',
+  env: 'production',
+  worker: 'default'
+)
+runner.run
+
+# With queue filtering
+runner = Postburner::Runner.new(
+  worker: 'general',
+  queues: ['default', 'mailers']
+)
+runner.run
+
+# From environment variables (Rake task pattern)
+runner = Postburner::Runner.new(
+  config: ENV['CONFIG'] || 'config/postburner.yml',
+  env: Rails.env,
+  worker: ENV['WORKER'],
+  queues: ENV['QUEUES']&.split(',')
+)
+runner.run
+```
+
+**Options:**
+- `:config` - Path to YAML configuration file (default: `'config/postburner.yml'`)
+- `:env` - Environment name (default: `RAILS_ENV` or `'development'`)
+- `:worker` - Worker name from config (required if multiple workers defined)
+- `:queues` - Array of queue names to filter (overrides config queues)
+
+This provides a unified interface used by both `bin/postburner` and `rake postburner:work`, making it easy to integrate Postburner workers into custom deployment scripts or process managers.
+
 ### Running Workers in Separate Processes
 
 For production deployments, run different workers in separate OS processes for isolation and resource allocation:

data/app/concerns/postburner/insertion.rb

@@ -24,6 +24,10 @@ module Postburner
   module Insertion
     extend ActiveSupport::Concern
 
+    included do
+      after_save_commit :insert_if_queued!
+    end
+
     # Enqueues the job to Beanstalkd for processing.
     #
     # Sets queued_at timestamp and optionally run_at for scheduled execution.

data/app/concerns/postburner/properties.rb

@@ -170,6 +170,20 @@ module Postburner
       self.class.queue
     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
+
     # Returns the priority for this job instance.
     #
     # Checks instance-level override first, then falls back to class-level configuration.
@@ -184,6 +198,11 @@ module Postburner
       @priority || self.class.priority
     end
 
+    # Alias for {#priority}.
+    #
+    # @see #priority
+    alias_method :pri, :priority
+
     # Returns the TTR (time-to-run) for this job instance.
     #
     # Checks instance-level override first, then falls back to class-level configuration.
@@ -198,18 +217,5 @@ module Postburner
       @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/models/postburner/job.rb

@@ -81,7 +81,6 @@ module Postburner
 
     before_validation :ensure_sid!
     before_destroy :delete!
-    after_save_commit :insert_if_queued!
 
     validates :sid, presence: {strict: true}
 
@@ -237,6 +236,40 @@ module Postburner
     #
     class MalformedResponse < StandardError; end
 
+    # Exception raised when Beanstalkd rejects a job with BAD_FORMAT error.
+    #
+    # Beanstalkd returns BAD_FORMAT when job parameters are invalid, such as:
+    # - Negative delay values
+    # - Invalid priority (outside 0-4294967295 range)
+    # - Invalid TTR (time-to-run)
+    # - Malformed job data
+    #
+    # This exception wraps the original Beaneater::BadFormatError and includes
+    # detailed debugging information about the parameters that caused the error.
+    # The original exception is preserved via the `cause` chain.
+    #
+    # @example Common causes
+    #   # Negative delay (now prevented by fix in queue.rb)
+    #   job.queue!(at: 1.hour.ago)  # Previously caused BAD_FORMAT
+    #
+    #   # Invalid priority
+    #   job.queue!(pri: -1)  # Outside valid range
+    #
+    # @example Accessing detailed error information
+    #   begin
+    #     job.queue!(at: past_time)
+    #   rescue Postburner::Job::BadFormat => e
+    #     puts e.message  # Includes tube, data, pri, delay, ttr
+    #     puts e.cause    # Original Beaneater::BadFormatError
+    #   end
+    #
+    # @note The error message includes full job parameters for debugging
+    # @note Access original Beanstalkd error via exception.cause
+    #
+    # @see Postburner::Queue#insert
+    #
+    class BadFormat < StandardError; end
+
     private
 
 

data/bin/postburner

@@ -55,37 +55,6 @@ require File.expand_path('config/environment', Dir.pwd)
 
 # Postburner is loaded automatically via the Rails engine when the gem is in your Gemfile
 
-# Load configuration
-config_path = File.expand_path(options[:config], Dir.pwd)
-
-begin
-  config = Postburner::Configuration.load_yaml(config_path, options[:env], options[:worker])
-rescue ArgumentError => e
-  Rails.logger.error "[Postburner] ERROR: #{e.message}"
-  exit 1
-end
-
-# Filter queues if --queues option provided
-if options[:queues]
-  # Validate that all specified queues exist in config
-  invalid_queues = options[:queues] - config.queue_names
-  unless invalid_queues.empty?
-    config.logger.error "[Postburner] ERROR: Unknown queue(s): #{invalid_queues.join(', ')}"
-    config.logger.error "[Postburner] Available queues: #{config.queue_names.join(', ')}"
-    exit 1
-  end
-
-  # Filter config to only include specified queues
-  filtered_queues = config.queues.select { |name, _| options[:queues].include?(name.to_s) }
-  config.queues = filtered_queues
-end
-
-config.logger.info "[Postburner] Configuration: #{config_path}"
-config.logger.info "[Postburner] Environment: #{options[:env]}"
-config.logger.info "[Postburner] Worker: #{options[:worker] || '(auto-selected)'}" if options[:worker] || options[:queues].nil?
-config.logger.info "[Postburner] Queues: #{config.queue_names.join(', ')}"
-config.logger.info "[Postburner] Defaults: forks=#{config.default_forks}, threads=#{config.default_threads}, gc_limit=#{config.default_gc_limit || 'none'}"
-
-# Create and start worker
-worker = Postburner::Workers::Worker.new(config)
-worker.start
+# Create and run worker
+runner = Postburner::Runner.new(options)
+runner.run

data/lib/postburner/runner.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Shared runner logic for bin/postburner and rake tasks.
+  #
+  # Provides a unified interface for starting Postburner workers from
+  # both the command-line executable and Rake tasks. Handles configuration
+  # loading, queue filtering, logging, and worker startup.
+  #
+  # @example Using from bin/postburner
+  #   options = { config: 'config/postburner.yml', env: 'production', worker: 'default' }
+  #   runner = Postburner::Runner.new(options)
+  #   runner.run
+  #
+  # @example Using from Rake task
+  #   options = { worker: ENV['WORKER'], queues: ENV['QUEUES']&.split(',') }
+  #   runner = Postburner::Runner.new(options)
+  #   runner.run
+  #
+  class Runner
+    attr_reader :options
+
+    # Initialize runner with options.
+    #
+    # @param options [Hash] Runner options
+    # @option options [String] :config Path to YAML configuration file (default: 'config/postburner.yml')
+    # @option options [String] :env Environment name (default: RAILS_ENV or 'development')
+    # @option options [String, nil] :worker Worker name from config (required if multiple workers defined)
+    # @option options [Array<String>, nil] :queues List of queue names to filter (overrides config)
+    def initialize(options = {})
+      @options = {
+        config: 'config/postburner.yml',
+        env: ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development',
+        worker: nil,
+        queues: nil
+      }.merge(options)
+    end
+
+    # Load configuration, filter queues, and start worker.
+    #
+    # @return [void]
+    def run
+      config = load_configuration
+      filter_queues(config) if options[:queues]
+      log_configuration(config)
+      start_worker(config)
+    end
+
+    private
+
+    # Load configuration from YAML file.
+    #
+    # @return [Postburner::Configuration]
+    def load_configuration
+      config_path = File.expand_path(options[:config], root_directory)
+      Postburner::Configuration.load_yaml(config_path, options[:env], options[:worker])
+    rescue ArgumentError => e
+      logger.error "[Postburner] ERROR: #{e.message}"
+      exit 1
+    end
+
+    # Filter configuration to only include specified queues.
+    #
+    # @param config [Postburner::Configuration]
+    # @return [void]
+    def filter_queues(config)
+      # Validate that all specified queues exist in config
+      invalid_queues = options[:queues] - config.queue_names
+      unless invalid_queues.empty?
+        config.logger.error "[Postburner] ERROR: Unknown queue(s): #{invalid_queues.join(', ')}"
+        config.logger.error "[Postburner] Available queues: #{config.queue_names.join(', ')}"
+        exit 1
+      end
+
+      # Filter config to only include specified queues
+      filtered_queues = config.queues.select { |name, _| options[:queues].include?(name.to_s) }
+      config.queues = filtered_queues
+    end
+
+    # Log configuration details.
+    #
+    # @param config [Postburner::Configuration]
+    # @return [void]
+    def log_configuration(config)
+      config_path = File.expand_path(options[:config], root_directory)
+      config.logger.info "[Postburner] Configuration: #{config_path}"
+      config.logger.info "[Postburner] Environment: #{options[:env]}"
+      config.logger.info "[Postburner] Worker: #{options[:worker] || '(auto-selected)'}" if options[:worker] || options[:queues].nil?
+      config.logger.info "[Postburner] Queues: #{config.queue_names.join(', ')}"
+      config.logger.info "[Postburner] Defaults: forks=#{config.default_forks}, threads=#{config.default_threads}, gc_limit=#{config.default_gc_limit || 'none'}"
+    end
+
+    # Returns root directory for config file resolution.
+    #
+    # Uses Rails.root when Rails is defined, otherwise falls back to current directory.
+    #
+    # @return [String] Root directory path
+    def root_directory
+      if defined?(Rails) && Rails.respond_to?(:root)
+        Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    end
+
+    # Create and start worker.
+    #
+    # @param config [Postburner::Configuration]
+    # @return [void]
+    def start_worker(config)
+      worker = Postburner::Workers::Worker.new(config)
+      worker.start
+    end
+
+    # Returns logger for error reporting during initialization.
+    #
+    # @return [Logger]
+    def logger
+      if defined?(Rails)
+        Rails.logger
+      else
+        Logger.new($stderr)
+      end
+    end
+  end
+end

data/lib/postburner/strategies/queue.rb

@@ -81,24 +81,21 @@ module Postburner
 
             # Get priority, TTR from job instance (respects instance overrides) or options
             pri = options[:pri] || job.priority || Postburner.configuration.default_priority
-            delay = options[:delay] || 0
+            delay = options[:delay].present? ? [0, options[:delay].to_i].max : 0
             ttr = options[:ttr] || job.ttr || Postburner.configuration.default_ttr
+            payload = JSON.generate(data)
 
             begin
               response = conn.tubes[tube_name].put(
-                JSON.generate(data),
+                payload,
                 pri: pri,
                 delay: delay,
                 ttr: ttr
               )
             rescue Beaneater::BadFormatError => e
-              Rails.logger.error "Beanstalkd BAD_FORMAT error from:"
-              Rails.logger.error "  tube: #{tube_name}"
-              Rails.logger.error "  data: #{JSON.generate(data)}"
-              Rails.logger.error "  pri: #{pri.inspect} (#{pri.class})"
-              Rails.logger.error "  delay: #{delay.inspect} (#{delay.class})"
-              Rails.logger.error "  ttr: #{ttr.inspect} (#{ttr.class})"
-              raise
+              raise Postburner::Job::BadFormat.new(
+                "Beanstalkd BAD_FORMAT: tube=#{tube_name} payload=#{payload} pri=#{pri.inspect} delay=#{delay.inspect} ttr=#{ttr.inspect}"
+              ), cause: e
             end
 
             response

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.4'
+  VERSION = '1.0.0.pre.5'
 end

data/lib/postburner.rb

@@ -8,6 +8,7 @@ require "postburner/active_job/execution"
 require "postburner/active_job/adapter"
 require "postburner/workers/base"
 require "postburner/workers/worker"
+require "postburner/runner"
 require "postburner/engine"
 require "postburner/strategies/queue"
 require "postburner/strategies/nice_queue"
@@ -449,7 +450,6 @@ module Postburner
   #
   def self.stats
     connected do |conn|
-
       {
         watched_tubes: self.watched_tubes,
         # Get all tube instances that exist on Beanstalkd

data/lib/tasks/postburner.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+namespace :postburner do
+  desc "Start Postburner worker (ENV: WORKER=name, QUEUES=queue1,queue2, CONFIG=path)"
+  task work: :environment do
+    # Parse options from environment variables
+    options = {
+      config: ENV['CONFIG'] || 'config/postburner.yml',
+      env: Rails.env,
+      worker: ENV['WORKER'],
+      queues: ENV['QUEUES']&.split(',')&.map(&:strip)
+    }
+
+    # Create and run worker
+    runner = Postburner::Runner.new(options)
+    runner.run
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.4
+  version: 1.0.0.pre.5
 platform: ruby
 authors:
 - Matt Smith
@@ -104,7 +104,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
 - README.md
 - Rakefile
 - app/assets/config/postburner_manifest.js
@@ -147,6 +146,7 @@ files:
 - lib/postburner/configuration.rb
 - lib/postburner/connection.rb
 - lib/postburner/engine.rb
+- lib/postburner/runner.rb
 - lib/postburner/strategies/immediate_test_queue.rb
 - lib/postburner/strategies/nice_queue.rb
 - lib/postburner/strategies/null_queue.rb
@@ -157,6 +157,7 @@ files:
 - lib/postburner/version.rb
 - lib/postburner/workers/base.rb
 - lib/postburner/workers/worker.rb
+- lib/tasks/postburner.rake
 - lib/tasks/postburner_tasks.rake
 homepage: https://gitlab.nearapogee.com/opensource/postburner
 licenses:

data/MIT-LICENSE

@@ -1,20 +0,0 @@
-Copyright 2021 Matt Smith
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.