postburner 1.0.0.pre.4 → 1.0.0.pre.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a279e41bee615d867b4392c53c9cfe9535c1652842f166f2f6cd33b3fc6215e2
-  data.tar.gz: f11ad9028e92679bc5c5fc3d62b75d8a3a163394bb130dac4bb9a1bcd33c7cfb
+  metadata.gz: a480ddab26850f1ecacc0f3c1ec75de82d8ac1f0acd2b4b7f0997dc5b3cc044c
+  data.tar.gz: 6d7ed3b8dd92df4d1064750c7eead44b8fa8d3c60887cb5c98771844a14f014d
 SHA512:
-  metadata.gz: 70eeebf1007b699b58713d3a9fc107aabf118fe6c13c39d519e4b800416d9ea185bb96012be1e37a617ef7b4e52896e1387aa2f11e9b45077912bb154071f62f
-  data.tar.gz: 1e34ecbf3dfe03401f7280deca6939e056bceb21ed6d2303e87b4f5c53d5ea23f0d712814acc48a356b471dbd1754505a155e7830c304051bfb1faae2fe4fde1
+  metadata.gz: 92f61d683537fa34a3aec8c7a052eb2313476fa2b647760d909022b28d0171db89b90c572b73af7eef6438bb1fc462f457d4b44bad1d249064993f68269de7e1
+  data.tar.gz: 495c9b4fba775507dd54666ab964bfa4d41fcc6608c3499ab5f4cc24b4f0af9a2cb4265b18331b566d61fce1318b1b1bc6a7ed9bc05d73619c5d5dd5dbc1711b

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:
@@ -1302,6 +1352,91 @@ end
 ```
 
 
+### Tube Statistics and Management
+
+Postburner provides methods to inspect and manage Beanstalkd tubes:
+
+**View tube statistics:**
+
+```ruby
+# View all tubes on the Beanstalkd server
+stats = Postburner.stats
+# => {
+#   tubes: [
+#     { name: "postburner.production.default", ready: 10, delayed: 5, buried: 0, reserved: 2, total: 17 },
+#     { name: "postburner.production.critical", ready: 0, delayed: 0, buried: 0, reserved: 1, total: 1 }
+#   ],
+#   totals: { ready: 10, delayed: 5, buried: 0, reserved: 3, total: 18 }
+# }
+
+# View specific tubes only
+stats = Postburner.stats(['postburner.production.critical'])
+# => { tubes: [...], totals: {...} }
+```
+
+**Clear jobs from tubes:**
+
+For safety, `clear_jobs!` requires you to explicitly specify which tubes to clear. This prevents accidentally clearing tubes from other applications sharing the same Beanstalkd server.
+
+```ruby
+# Collect stats only (no clearing)
+result = Postburner.clear_jobs!
+# => { tubes: [...], totals: {...}, cleared: false }
+
+# Clear specific tubes (must be in config/postburner.yml)
+result = Postburner.clear_jobs!(['postburner.production.default'])
+# => { tubes: [...], totals: {...}, cleared: true }
+
+# Pretty-print JSON output
+Postburner.clear_jobs!(['postburner.production.default'], silent: false)
+# Outputs formatted JSON to stdout
+
+# Silent mode (no output, just return data)
+result = Postburner.clear_jobs!(['postburner.production.default'], silent: true)
+```
+
+**Safety validation:**
+
+Only tubes defined in your loaded configuration can be cleared. This prevents mistakes in multi-tenant Beanstalkd environments:
+
+```ruby
+# Error: trying to clear tube not in config
+Postburner.clear_jobs!(['postburner.production.other-app'])
+# => ArgumentError: Cannot clear tubes not in configuration.
+#    Invalid tubes: postburner.production.other-app
+#    Configured tubes: postburner.production.default, postburner.production.critical
+```
+
+**Shortcut using watched_tube_names:**
+
+Clear all configured tubes at once:
+
+```ruby
+# Get all tubes from current configuration
+watched_tubes = Postburner.watched_tube_names
+# => ["postburner.production.default", "postburner.production.critical", "postburner.production.mailers"]
+
+# Clear all configured tubes
+Postburner.clear_jobs!(watched_tubes, silent: true)
+# or
+Postburner.clear_jobs!(Postburner.watched_tube_names, silent: true)
+```
+
+**Low-level Connection API:**
+
+For programmatic use without output formatting, use `Connection#clear_tubes!`:
+
+```ruby
+Postburner.connected do |conn|
+  # Returns data only (no puts)
+  result = conn.clear_tubes!(Postburner.watched_tube_names)
+  # => { tubes: [...], totals: {...}, cleared: true }
+
+  # Same validation - must be in configuration
+  result = conn.clear_tubes!(['postburner.production.default'])
+end
+```
+
 ## Web UI
 
 Mount the inspection interface:

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.
@@ -155,9 +159,8 @@ module Postburner
       #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}"
+        raise Postburner::Job::MalformedResponse, "Missing :id key in response: #{response.inspect}"
       end
 
       persist_metadata!(bkid: response[:id])

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/configuration.rb

@@ -99,11 +99,18 @@ module Postburner
         if workers.size == 1
           worker_name = workers.keys.first
         else
-          raise ArgumentError, "Configuration has multiple workers, but --worker not specified\nAvailable workers: #{workers.keys.join(', ')}\nUsage: bin/postburner --worker <name>"
+          raise ArgumentError, <<~ERROR
+            Configuration has multiple workers, but --worker not specified
+            Available workers: #{workers.keys.join(', ')}
+            Usage: bin/postburner --worker <name>
+          ERROR
         end
       else
         unless workers.key?(worker_name)
-          raise ArgumentError, "Worker '#{worker_name}' not found in #{path}\nAvailable workers: #{workers.keys.join(', ')}"
+          raise ArgumentError, <<~ERROR
+            Worker '#{worker_name}' not found in #{path}
+            Available workers: #{workers.keys.join(', ')}
+          ERROR
         end
       end
 

data/lib/postburner/connection.rb

@@ -88,6 +88,68 @@ module Postburner
       @pool = nil
     end
 
+    # Clears jobs from specified tubes or collects stats for all tubes.
+    #
+    # Low-level method that returns data only (no output to stdout).
+    # Delegates to Postburner.stats for collecting statistics.
+    # For user-facing output, use Postburner.clear_jobs! instead.
+    #
+    # SAFETY: Only allows clearing tubes that are defined in the loaded
+    # configuration (watched_tube_names). This prevents accidentally clearing
+    # tubes from other applications or environments.
+    #
+    # @param tube_names [Array<String>, nil] Array of tube names to clear, or nil to only collect stats
+    #
+    # @return [Hash] Statistics and results with keys:
+    #   - tubes: Array of hashes with per-tube stats
+    #   - totals: Hash with aggregated counts across all tubes
+    #   - cleared: Boolean indicating if tubes were actually cleared
+    #
+    # @raise [ArgumentError] if tube_names contains tubes not in watched_tube_names
+    #
+    # @example Collect stats only (no clearing)
+    #   result = conn.clear_tubes!
+    #   result[:totals][:total]  # => 42
+    #
+    # @example Clear configured tubes only
+    #   result = conn.clear_tubes!(Postburner.watched_tube_names)
+    #   result[:cleared]  # => true
+    #
+    # @example Invalid tube raises error
+    #   conn.clear_tubes!(['random-tube'])
+    #   # => ArgumentError: Cannot clear tubes not in configuration
+    #
+    def clear_tubes!(tube_names = nil)
+      ensure_connected!
+
+      # Validate that tubes to clear are in the loaded configuration
+      if tube_names&.any?
+        watched = Postburner.watched_tube_names
+        invalid_tubes = tube_names - watched
+
+        if invalid_tubes.any?
+          raise ArgumentError, <<~ERROR
+            Cannot clear tubes not in configuration.
+            Invalid tubes: #{invalid_tubes.join(', ')}
+            Configured tubes: #{watched.join(', ')}
+          ERROR
+        end
+      end
+
+      # Get stats using Postburner.stats
+      result = Postburner.stats(tube_names)
+      result[:cleared] = tube_names&.any? ? true : false
+
+      # Actually clear if tube names were provided and validated
+      if tube_names&.any?
+        tube_names.each do |tube_name|
+          tubes[tube_name].clear
+        end
+      end
+
+      result
+    end
+
     private
 
     # Establishes connection to Beanstalkd.

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/time_helpers.rb

@@ -64,8 +64,10 @@ module Postburner
     #
     def travel_to(time, &block)
       unless defined?(ActiveSupport::Testing::TimeHelpers)
-        raise "ActiveSupport::Testing::TimeHelpers not available. " \
-              "Postburner::TimeHelpers requires Rails testing helpers for time travel."
+        raise <<~ERROR
+          ActiveSupport::Testing::TimeHelpers not available.
+          Postburner::TimeHelpers requires Rails testing helpers for time travel.
+        ERROR
       end
 
       helper = Object.new.extend(ActiveSupport::Testing::TimeHelpers)

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.4'
+  VERSION = '1.0.0.pre.6'
 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"
@@ -374,25 +375,50 @@ module Postburner
     end
   end
 
-  # Removes all jobs from all tubes (not yet implemented).
+  # Clears jobs from specified tubes or shows stats for all tubes.
   #
-  # This is a destructive operation intended for development/testing cleanup.
-  # Requires confirmation string "CONFIRM" to prevent accidental execution.
+  # High-level method with formatted output. Delegates to Connection#clear_tubes!
+  # for the actual work, then pretty-prints the results.
   #
-  # @param confirm [String] Must be exactly "CONFIRM" to execute
+  # SAFETY: Only allows clearing tubes that are defined in the loaded
+  # configuration. This prevents accidentally clearing tubes from other
+  # applications or environments sharing the same Beanstalkd server.
   #
-  # @return [void]
+  # @param tube_names [Array<String>, nil] Array of tube names to clear, or nil to only show stats
+  # @param silent [Boolean] If true, suppress output to stdout (default: false)
   #
-  # @example
-  #   Postburner.remove_all!("CONFIRM")
+  # @return [Hash] Statistics and results (see Connection#clear_tubes!)
+  #
+  # @raise [ArgumentError] if tube_names contains tubes not in watched_tube_names
+  #
+  # @example Show stats only (no clearing) - SAFE
+  #   Postburner.clear_jobs!
+  #   # Shows stats for ALL tubes on Beanstalkd, but doesn't clear anything
+  #
+  # @example Clear watched tubes only - SAFE
+  #   Postburner.clear_jobs!(Postburner.watched_tube_names)
+  #   # Only clears tubes defined in your config
   #
-  # @note Currently a no-op - implementation pending
-  # @todo Implement job removal from all tubes
+  # @example Trying to clear unconfigured tube - RAISES ERROR
+  #   Postburner.clear_jobs!(['some-other-app-tube'])
+  #   # => ArgumentError: Cannot clear tubes not in configuration
   #
-  def self.remove_all!(confirm)
-    return unless confirm == "CONFIRM"
+  # @example Silent mode (programmatic use)
+  #   result = Postburner.clear_jobs!(Postburner.watched_tube_names, silent: true)
+  #   result[:totals][:total]  # => 42
+  #
+  # @see Connection#clear_tubes!
+  #
+  def self.clear_jobs!(tube_names = nil, silent: false)
+    require 'json'
+
+    result = connection.clear_tubes!(tube_names)
+
+    unless silent
+      puts JSON.pretty_generate(result)
+    end
 
-    # TODO
+    result
   end
 
   # Returns array of watched tube names with environment prefix.
@@ -422,39 +448,82 @@ module Postburner
     @__watched_tubes ||= watched_tube_names.map { |tube_name| connection.tubes[tube_name] }
   end
 
-  # Returns statistics and introspection data about Beanstalkd and configured queues.
+  # Returns detailed statistics about Beanstalkd tubes.
   #
-  # Provides Beaneater tube instances for configured tubes and all tubes that exist
-  # on the Beanstalkd server. Tube instances support introspection methods:
+  # Collects job counts (ready, delayed, buried, reserved) for each tube
+  # and provides aggregate totals across all tubes.
   #
-  # - tube.name - Tube name
-  # - tube.stats - Tube statistics hash (current-jobs-ready, current-jobs-buried, etc.)
-  # - tube.peek_ready - Next ready job
-  # - tube.peek_delayed - Next delayed job
-  # - tube.peek_buried - Next buried job
-  # - tube.kick(n) - Kick n buried jobs back to ready
-  # - tube.pause(delay) - Pause tube for delay seconds
-  # - tube.clear - Delete all jobs in tube
+  # @param tube_names [Array<String>, nil] Specific tube names to inspect, or nil for all tubes
   #
-  # @return [Hash] Statistics hash with the following keys:
-  #   - watched_tubes: Array of configured/watched Beaneater::Tube instances
-  #   - tubes: Array of all Beaneater::Tube instances on the server
+  # @return [Hash] Statistics hash with keys:
+  #   - tubes: Array of hashes with per-tube stats (name, ready, delayed, buried, reserved, total)
+  #   - totals: Hash with aggregated counts across all tubes
   #
   # @raise [Beaneater::NotConnected] if connection to Beanstalkd fails
   #
-  # @example
+  # @example Get stats for all tubes
   #   stats = Postburner.stats
-  #   stats[:watched_tubes].each { |tube| puts "#{tube.name}: #{tube.stats}" }
-  #   stats[:tubes].first.peek_ready
+  #   stats[:totals][:total]  # => 42
+  #   stats[:tubes].first[:name]  # => "default"
+  #
+  # @example Get stats for specific tubes
+  #   stats = Postburner.stats(Postburner.watched_tube_names)
+  #   stats[:tubes].size  # => 3
   #
-  def self.stats
+  def self.stats(tube_names = nil)
     connected do |conn|
+      # Get tubes to inspect
+      tubes_to_inspect = if tube_names&.any?
+        tube_names.map { |name| conn.tubes[name] }
+      else
+        conn.beanstalk.tubes.all
+      end
 
-      {
-        watched_tubes: self.watched_tubes,
-        # Get all tube instances that exist on Beanstalkd
-        tubes: conn.beanstalk.tubes.all
+      result = {
+        tubes: [],
+        totals: {
+          ready: 0,
+          delayed: 0,
+          buried: 0,
+          reserved: 0,
+          total: 0
+        }
       }
+
+      # Collect stats from each tube
+      tubes_to_inspect.each do |tube|
+        begin
+          stats = tube.stats
+          # Beaneater returns a StatStruct; access the underlying hash
+          stats_hash = stats.instance_variable_get(:@hash) || {}
+
+          tube_data = {
+            name: tube.name,
+            ready: stats_hash['current-jobs-ready'] || 0,
+            delayed: stats_hash['current-jobs-delayed'] || 0,
+            buried: stats_hash['current-jobs-buried'] || 0,
+            reserved: stats_hash['current-jobs-reserved'] || 0,
+            total: (stats_hash['current-jobs-ready'] || 0) +
+                   (stats_hash['current-jobs-delayed'] || 0) +
+                   (stats_hash['current-jobs-buried'] || 0) +
+                   (stats_hash['current-jobs-reserved'] || 0)
+          }
+        rescue Beaneater::NotFoundError
+          # Tube doesn't exist yet, skip it
+          next
+        end
+
+        result[:tubes] << tube_data
+
+        # Aggregate totals
+        result[:totals][:ready] += tube_data[:ready]
+        result[:totals][:delayed] += tube_data[:delayed]
+        result[:totals][:buried] += tube_data[:buried]
+        result[:totals][:reserved] += tube_data[:reserved]
+        result[:totals][:total] += tube_data[:total]
+      end
+
+      result
     end
   end
 end

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.6
 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.