postburner 1.0.0.pre.6 → 1.0.0.pre.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a480ddab26850f1ecacc0f3c1ec75de82d8ac1f0acd2b4b7f0997dc5b3cc044c
-  data.tar.gz: 6d7ed3b8dd92df4d1064750c7eead44b8fa8d3c60887cb5c98771844a14f014d
+  metadata.gz: 38a691a9f1e5d99c0d6f19cbe7c4c605bd1e570787d1cb7c8b5ee862b3efa84c
+  data.tar.gz: 962f60d03662ee7dc119503f190d5f6376cd7be35a14b52c140d75141a837b0c
 SHA512:
-  metadata.gz: 92f61d683537fa34a3aec8c7a052eb2313476fa2b647760d909022b28d0171db89b90c572b73af7eef6438bb1fc462f457d4b44bad1d249064993f68269de7e1
-  data.tar.gz: 495c9b4fba775507dd54666ab964bfa4d41fcc6608c3499ab5f4cc24b4f0af9a2cb4265b18331b566d61fce1318b1b1bc6a7ed9bc05d73619c5d5dd5dbc1711b
+  metadata.gz: e4a3bdd33be9342b9e521ef806baff7e27375891f73487daba929aefc9abf1ac888dd037bf764b46c839b8f904e9b766558f1705d2eebbab612a9b27d1562577
+  data.tar.gz: 69e36547fbc73cab99f8d9991a62825019f4d201e041fdf7cfb508fd885c0ce3dc6b6801f6e1897fe4037877b0649718b7089566b42a68d5e622302797a4c3ac

data/README.md

@@ -127,6 +127,13 @@ beanstalkd -l 127.0.0.1 -p 11300 # Start beanstalkd
 bundle exec rails generate postburner:install
 bundle exec rails db:migrate
 
+# application.rb
+config.active_job.queue_adapter = :postburner
+# Note: Postburner auto-prefixes queue names with "postburner.{env}." similar to:
+#config.active_job.queue_name_prefix = Postburner.tube_prefix(Rails.env) # i.e. "postburner.#{Rails.env}"
+config.action_mailer.deliver_later_queue_name = 'mailers' # gets prefixed by config.active_job.queue_name_prefix
+
+
 bundle exec postburner           # start with bin/postburner
 bundle exec rake postburner:work # or with rake task
 ```
@@ -1084,6 +1091,42 @@ production:  # <- environment config, i.e. defaults
         - mailers
 ```
 
+### Queue Names
+
+Postburner automatically prefixes all queue names with `postburner.{env}.` to create Beanstalkd tube names. This namespacing prevents collisions when multiple applications share the same Beanstalkd server.
+
+**The same base queue name is used everywhere:**
+
+| Context | Syntax | Beanstalkd Tube |
+|---------|--------|-----------------|
+| ActiveJob | `queue_as :mailers` | `postburner.production.mailers` |
+| Postburner::Job | `queue 'mailers'` | `postburner.production.mailers` |
+| postburner.yml | `queues: [mailers]` | `postburner.production.mailers` |
+
+**Example:**
+
+```ruby
+# app/jobs/welcome_email_job.rb
+class WelcomeEmailJob < ApplicationJob
+  queue_as :mailers  # Uses base name 'mailers'
+end
+```
+
+```yaml
+# config/postburner.yml
+production:
+  workers:
+    email_worker:
+      queues:
+        - mailers  # Same base name 'mailers'
+```
+
+Both refer to the Beanstalkd tube `postburner.production.mailers`.
+
+**Naming convention:** Use underscores for multi-word queue names (e.g., `background_jobs`, `high_priority`). Avoid hyphens as they can cause issues with some Beanstalkd client libraries.
+
+**Important:** No need to set `config.active_job.queue_name_prefix` - Postburner handles prefixing automatically, when jobs are enqueued with postburner.
+
 ### Queue Configuration Methods
 
 For `Postburner::Job` subclasses (and backwards compatibility):
@@ -1333,7 +1376,25 @@ job.attempts # Array of attempt timestamps
 
 ## Beanstalkd Integration
 
-Direct access to Beanstalkd for advanced operations:
+Postburner uses [Beaneater](https://github.com/beanstalkd/beaneater) as the Ruby client for Beanstalkd. You can access the underlying Beaneater connection directly for advanced operations.
+
+### Connection Methods
+
+```ruby
+# Get a cached Beaneater connection (returns Beaneater instance)
+conn = Postburner.connection
+conn.tubes.to_a  # List all tubes
+conn.stats       # Server statistics
+
+# Block form - yields connection, recommended for one-off operations
+Postburner.connected do |conn|
+  conn.tubes.to_a  # List all tubes
+  conn.tubes['postburner.production.critical'].stats
+  conn.tubes['postburner.production.critical'].kick(10)  # Kick 10 buried jobs
+end
+```
+
+### Job-Level Access
 
 ```ruby
 # Get Beanstalkd job ID
@@ -1342,12 +1403,25 @@ job.bkid  # => 12345
 # Access Beaneater job object
 job.bk.stats
 # => {"id"=>12345, "tube"=>"critical", "state"=>"ready", ...}
+```
 
-# Connection management
+### Beaneater API
+
+The connection object is a standard Beaneater instance. See the [Beaneater documentation](https://github.com/beanstalkd/beaneater) for full API details:
+
+```ruby
 Postburner.connected do |conn|
-  conn.tubes.to_a  # List all tubes
-  conn.tubes['postburner.production.critical'].stats
-  conn.tubes['postburner.production.critical'].kick(10)  # Kick 10 buried jobs
+  # Tubes
+  conn.tubes.to_a                    # List all tube names
+  conn.tubes['my-tube'].stats        # Tube statistics
+  conn.tubes['my-tube'].peek(:ready) # Peek at next ready job
+  conn.tubes['my-tube'].kick(10)     # Kick 10 buried jobs
+
+  # Server
+  conn.stats                         # Server statistics
+
+  # Jobs
+  conn.jobs.find(12345)              # Find job by ID
 end
 ```
 
@@ -1557,6 +1631,15 @@ There is a CLAUDE.md file for guidance when using Claude Code. Please use it or
 
 We encourage AI tools, but do not vibe, as the code must look like it was written by a human. Code that contains AI agent idioms will be rejected. Code that doesn't follow the project conventions will be rejected.
 
+
+### Testing
+
+```bash
+bundle install
+bundle exec rails test # must have beanstalkd on 11300 by default
+bundle exec rails app:postburner:work # if you want to run the worker
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/postburner/active_job/adapter.rb

@@ -8,6 +8,24 @@ module ActiveJob
     # - **Default mode**: Fast execution via Beanstalkd only
     # - **Tracked mode** (opt-in): Full PostgreSQL audit trail
     #
+    # ## Queue Name Prefixing
+    #
+    # Postburner automatically prefixes all queue names with `postburner.{env}.`
+    # to create Beanstalkd tube names. This means:
+    #
+    # - `queue_as :default` → tube `postburner.production.default`
+    # - `queue_as :mailers` → tube `postburner.production.mailers`
+    #
+    # The same base queue names are used across:
+    # - ActiveJob: `queue_as :default`
+    # - Postburner::Job: `queue 'default'`
+    # - config/postburner.yml: `queues: [default]`
+    #
+    # All refer to the same Beanstalkd tube after prefixing.
+    #
+    # @note Do NOT set `config.active_job.queue_name_prefix` - Postburner
+    #   handles prefixing automatically via {#expand_tube_name}.
+    #
     # ## Usage
     #
     # @example Configure in Rails
@@ -16,6 +34,8 @@ module ActiveJob
     #
     # @example Default job (fast)
     #   class SendEmail < ApplicationJob
+    #     queue_as :mailers  # → postburner.production.mailers
+    #
     #     def perform(user_id)
     #       # No PostgreSQL overhead, executes quickly
     #     end
@@ -24,7 +44,7 @@ module ActiveJob
     # @example Tracked job (opt-in for audit trail)
     #   class ProcessPayment < ApplicationJob
     #     include Postburner::Tracked
-    #     tracked  # ← Enables PostgreSQL tracking
+    #     queue_as :critical  # → postburner.production.critical
     #
     #     def perform(payment_id)
     #       log "Processing payment..."

data/lib/postburner/configuration.rb

@@ -10,37 +10,48 @@ module Postburner
   # @example Programmatic configuration
   #   Postburner.configure do |config|
   #     config.beanstalk_url = 'beanstalk://localhost:11300'
-  #     config.worker_type = :threads_on_fork
   #     config.logger = Rails.logger
+  #     config.worker_config = { name: 'default', queues: ['default'], forks: 2, threads: 10 }
   #   end
   #
   # @example Loading from YAML
-  #   config = Postburner::Configuration.load_yaml('config/postburner.yml', 'production')
+  #   config = Postburner::Configuration.load_yaml('config/postburner.yml', 'production', 'imports')
   #
   class Configuration
-    attr_accessor :beanstalk_url, :logger, :queues, :default_queue, :default_priority, :default_ttr, :default_threads, :default_forks, :default_gc_limit
+    # Global settings
+    attr_accessor :beanstalk_url, :logger, :default_queue, :default_priority, :default_ttr
+
+    # Worker-specific settings (loaded for a single worker)
+    attr_accessor :worker_config
 
     # @param options [Hash] Configuration options
     # @option options [String] :beanstalk_url Beanstalkd URL (default: ENV['BEANSTALK_URL'] or localhost)
     # @option options [Logger] :logger Logger instance (default: Rails.logger)
-    # @option options [Hash] :queues Queue configurations
     # @option options [String] :default_queue Default queue name (default: 'default')
     # @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 [Integer] :default_threads Default thread count per fork (default: 1)
-    # @option options [Integer] :default_forks Default fork count (default: 0, single process)
-    # @option options [Integer] :default_gc_limit Default GC limit for worker restarts (default: nil, no limit)
+    # @option options [Hash] :worker_config Worker configuration hash with keys:
+    #   - :name [String] Worker name
+    #   - :queues [Array<String>] Queue/tube names to process
+    #   - :forks [Integer] Number of forked processes (0 = single process mode)
+    #   - :threads [Integer] Number of threads per fork
+    #   - :gc_limit [Integer, nil] Jobs to process before restart (nil = unlimited)
+    #   - :timeout [Integer] Reserve command timeout in seconds (1-10, default: 3)
     #
     def initialize(options = {})
       @beanstalk_url = options[:beanstalk_url] || ENV['BEANSTALK_URL'] || 'beanstalk://localhost:11300'
       @logger = options[:logger] || (defined?(Rails) ? Rails.logger : Logger.new(STDOUT))
-      @queues = options[:queues] || { 'default' => {} }
       @default_queue = options[:default_queue] || 'default'
       @default_priority = options[:default_priority] || 65536
       @default_ttr = options[:default_ttr] || 300
-      @default_threads = options[:default_threads] || 1
-      @default_forks = options[:default_forks] || 0
-      @default_gc_limit = options[:default_gc_limit]
+      @worker_config = options[:worker_config] || {
+        name: 'default',
+        queues: ['default'],
+        forks: 0,
+        threads: 1,
+        gc_limit: nil,
+        timeout: 3
+      }
     end
 
     # Loads configuration from a YAML file.
@@ -68,30 +79,31 @@ module Postburner
     #     beanstalk_url: beanstalk://localhost:11300
     #     default_priority: 131072 # change default priority from 65536 to 131072
     #
-    #   production: # <- environment config, i.e. defaults, NOT worker config
+    #   production: # <- environment config, i.e. defaults
     #     <<: *default
     #     default_forks: 2
     #     default_threads: 10
     #     default_gc_limit: 5000
     #     default_ttr: 300
-    #     workers: # <- worker config, i.e. overrides, NOT environment config
-    #       imports: # <- worker "group" name
+    #     workers: # <- worker configs
+    #       imports: # <- worker name
+    #         timeout: 3       # Reserve timeout in seconds (1-10, default: 3)
+    #                          # Lower values enable faster graceful shutdowns
     #         forks: 4         # Overrides default_forks
     #         threads: 1       # Overrides default_threads
     #         gc_limit: 500    # Overrides default_gc_limit
-    #         # ttr: 60        # Use default from production, i.e. 300 because not set
     #         queues:
     #           - imports
     #           - data_processing
     #
     def self.load_yaml(path, env = 'development', worker_name = nil)
       yaml = YAML.load_file(path, aliases: true)
-      # env_defaults = top-level environment config (development:, production:, etc.)
-      env_defaults = yaml[env.to_s] || yaml[env.to_sym]
+      # env_config = top-level environment config (development:, production:, etc.)
+      env_config = yaml[env.to_s] || yaml[env.to_sym]
 
-      raise ArgumentError, "Environment '#{env}' not found in #{path}" unless env_defaults
+      raise ArgumentError, "Environment '#{env}' not found in #{path}" unless env_config
 
-      workers = env_defaults['workers']
+      workers = env_config['workers']
       raise ArgumentError, "No 'workers:' section found in #{path} for environment '#{env}'" unless workers
 
       # Auto-select single worker or validate worker_name
@@ -114,55 +126,39 @@ module Postburner
         end
       end
 
-      # worker_config = specific worker configuration (workers: imports:)
-      worker_config = workers[worker_name]
+      # worker_yaml = specific worker configuration from YAML (workers: imports:)
+      worker_yaml = workers[worker_name]
 
-      # Convert queue array to hash format (queues no longer have per-queue config)
-      queue_list = worker_config['queues'] || []
-      queues_hash = {}
-      queue_list.each do |queue_name|
-        queues_hash[queue_name] = {}  # Empty hash - queues run in worker pool
-      end
+      # Build worker_config hash - worker-level overrides env-level defaults
+      worker_config = {
+        name: worker_name,
+        queues: worker_yaml['queues'] || ['default'],
+        forks: worker_yaml['forks'] || env_config['default_forks'] || 0,
+        threads: worker_yaml['threads'] || env_config['default_threads'] || 1,
+        gc_limit: worker_yaml['gc_limit'] || env_config['default_gc_limit'],
+        timeout: worker_yaml['timeout'] || 3
+      }
 
-      # Cascade: worker-level overrides env-level defaults
-      # Worker uses: forks, threads, gc_limit, ttr, priority (NO default_ prefix)
-      # Env uses: default_forks, default_threads, etc. (WITH default_ prefix)
       options = {
-        beanstalk_url: env_defaults['beanstalk_url'],
-        queues: queues_hash,
-        default_queue: worker_config['default_queue'] || env_defaults['default_queue'],
-        default_priority: worker_config['priority'] || env_defaults['default_priority'],
-        default_ttr: worker_config['ttr'] || env_defaults['default_ttr'],
-        default_threads: worker_config['threads'] || env_defaults['default_threads'],
-        default_forks: worker_config['forks'] || env_defaults['default_forks'],
-        default_gc_limit: worker_config['gc_limit'] || env_defaults['default_gc_limit']
+        beanstalk_url: env_config['beanstalk_url'],
+        default_queue: env_config['default_queue'],
+        default_priority: env_config['default_priority'],
+        default_ttr: env_config['default_ttr'],
+        worker_config: worker_config
       }
 
       new(options)
     end
 
-    # Returns queue configuration for a specific queue name.
-    #
-    # @param queue_name [String, Symbol] Name of the queue
-    #
-    # @return [Hash] Queue configuration with threads, gc_limit, etc.
-    #
-    # @example
-    #   config.queue_config('critical')  # => { threads: 1, gc_limit: 100 }
-    #
-    def queue_config(queue_name)
-      @queues[queue_name.to_s] || @queues[queue_name.to_sym] || {}
-    end
-
-    # Returns array of all configured queue names.
+    # Returns array of queue names from worker config.
     #
     # @return [Array<String>] Queue names
     #
     # @example
-    #   config.queue_names  # => ['default', 'critical', 'mailers']
+    #   config.queue_names  # => ['imports', 'data_processing']
     #
     def queue_names
-      @queues.keys.map(&:to_s)
+      @worker_config[:queues].map(&:to_s)
     end
 
     # Expands queue name to full tube name with environment prefix.
@@ -189,12 +185,35 @@ module Postburner
       env ||= defined?(Rails) ? Rails.env : nil
       queue_name ||= @default_queue
       [
-        'postburner',
-        env,
+        tube_prefix(env),
         queue_name,
       ].compact.join('.')
     end
 
+    # Returns the Beanstalkd tube name prefix for the given environment.
+    #
+    # Postburner automatically prefixes all queue names with this value.
+    # The ActiveJob adapter expands queue names using this prefix, so
+    # `queue_as :default` becomes `postburner.production.default` in production.
+    #
+    # @param env [String, Symbol, nil] Environment name (defaults to Rails.env or nil)
+    #
+    # @return [String] Tube prefix (e.g., "postburner.production")
+    #
+    # @example
+    #   config.tube_prefix('production')  # => "postburner.production"
+    #   config.tube_prefix                # => "postburner.test" (in test env)
+    #
+    # @note Do not set ActiveJob's `queue_name_prefix` - Postburner handles
+    #   queue name expansion automatically via the adapter.
+    #
+    def tube_prefix(env = nil)
+      env ||= defined?(Rails) ? Rails.env : nil
+      [
+        'postburner',
+        env,
+      ].compact.join('.')
+    end
 
     # Returns array of expanded tube names with environment prefix.
     #
@@ -203,7 +222,8 @@ module Postburner
     # @return [Array<String>] Array of expanded tube names
     #
     # @example
-    #   config.expanded_tube_names('production')  # => ['postburner.production.default', 'postburner.production.critical']
+    #   config.expanded_tube_names('production')  # => ['postburner.production.imports', 'postburner.production.data_processing']
+    #
     def expanded_tube_names(env = nil)
       queue_names.map { |q| expand_tube_name(q, env) }
     end
@@ -227,7 +247,7 @@ module Postburner
   # @example
   #   Postburner.configure do |config|
   #     config.beanstalk_url = 'beanstalk://localhost:11300'
-  #     config.worker_type = :threads_on_fork
+  #     config.worker_config = { name: 'default', queues: ['default'], forks: 2, threads: 10 }
   #   end
   #
   def self.configure

data/lib/postburner/runner.rb

@@ -87,7 +87,8 @@ module Postburner
       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'}"
+      wc = config.worker_config
+      config.logger.info "[Postburner] Worker config: forks=#{wc[:forks]}, threads=#{wc[:threads]}, gc_limit=#{wc[:gc_limit] || 'none'}, timeout=#{wc[:timeout]}s"
     end
 
     # Returns root directory for config file resolution.

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.6'
+  VERSION = '1.0.0.pre.8'
 end

data/lib/postburner/workers/base.rb

@@ -189,21 +189,16 @@ module Postburner
         [2 ** retry_count, 3600].min
       end
 
-      # Watches the configured queues in Beanstalkd.
+      # Watches all configured queues in Beanstalkd.
       #
       # @param connection [Postburner::Connection] Beanstalkd connection
-      # @param queue_name [String, nil] Optional specific queue name to watch (watches all if nil)
       #
       # @return [void]
       #
-      def watch_queues(connection, queue_name = nil)
-        if queue_name
-          tube_name = config.expand_tube_name(queue_name)
-          connection.beanstalk.tubes.watch!(tube_name)
-        else
-          tube_names = config.expanded_tube_names
-          connection.beanstalk.tubes.watch!(*tube_names)
-        end
+      def watch_queues(connection, queue_names=nil)
+        tube_names = queue_names.map { |q| config.expand_tube_name(q) }
+        tube_names = config.expanded_tube_names if tube_names.empty?
+        connection.beanstalk.tubes.watch!(*tube_names)
       end
     end
   end

data/lib/postburner/workers/worker.rb

@@ -4,7 +4,7 @@ require 'concurrent'
 
 module Postburner
   module Workers
-    # Puma-style worker with configurable forks and threads per queue.
+    # Puma-style worker with configurable forks and threads.
     #
     # This is the universal Postburner worker that scales from development
     # to production using forks and threads configuration. Just like Puma:
@@ -16,27 +16,18 @@ module Postburner
     # ### Single Process Mode (forks: 0)
     # ```
     # Main Process
-    # ├─ Queue 'default' Thread Pool (10 threads)
-    # ├─ Queue 'critical' Thread Pool (1 thread)
-    # └─ Queue 'mailers' Thread Pool (5 threads)
+    # └─ Thread Pool (N threads watching all queues)
     # ```
     #
     # ### Multi-Process Mode (forks: 1+)
     # ```
     # Parent Process
-    # ├─ Fork 0 (queue: critical)
-    # │   └─ Thread 1
-    # ├─ Fork 0 (queue: default)
-    # │   ├─ Thread 1-10
-    # ├─ Fork 1 (queue: default)  # Puma-style: multiple forks of same queue
-    # │   ├─ Thread 1-10
-    # ├─ Fork 2 (queue: default)
-    # │   └─ Thread 1-10
-    # ├─ Fork 3 (queue: default)
-    # │   └─ Thread 1-10
-    # │   └─ Total: 40 concurrent jobs for 'default' (4 forks × 10 threads)
-    # └─ Fork 0 (queue: mailers)
-    #     └─ Thread 1-5
+    # ├─ Fork 0
+    # │   └─ Thread Pool (N threads watching all queues)
+    # ├─ Fork 1
+    # │   └─ Thread Pool (N threads watching all queues)
+    # └─ Fork 2
+    #     └─ Thread Pool (N threads watching all queues)
     # ```
     #
     # ## Scaling Strategy
@@ -60,38 +51,25 @@ module Postburner
     # forks: 4
     # threads: 10
     # ```
-    # 4 processes × 10 threads = 40 concurrent jobs per queue
+    # 4 processes × 10 threads = 40 concurrent jobs
     #
     # ## Configuration
     #
     # @example Development (single-threaded)
-    #   development:  # <- environment config, i.e. defaults
-    #     default_forks: 0
-    #     default_threads: 1
-    #     workers:  # <- worker config, i.e. overrides
+    #   development:
+    #     workers:
     #       default:
+    #         forks: 0
+    #         threads: 1
     #         queues:
     #           - default
     #           - mailers
     #
-    # @example Staging (multi-threaded, single process)
-    #   staging:  # <- environment config, i.e. defaults
-    #     default_forks: 0
-    #     default_threads: 10
-    #     default_gc_limit: 5000
-    #     workers:  # <- worker config, i.e. overrides
-    #       default:
-    #         queues:
-    #           - critical
-    #           - default
-    #           - mailers
-    #
-    # @example Production (Puma-style: forks × threads with worker overrides)
-    #   production:  # <- environment config, i.e. defaults
+    # @example Production (Puma-style: forks × threads)
+    #   production:
     #     default_forks: 2
     #     default_threads: 10
-    #     default_gc_limit: 5000
-    #     workers:  # <- worker config, i.e. overrides
+    #     workers:
     #       default:
     #         forks: 4        # Overrides default_forks
     #         threads: 10     # Overrides default_threads
@@ -109,12 +87,13 @@ module Postburner
       # @return [void]
       #
       def start
-        logger.info "[Postburner::Worker] Starting..."
+        logger.info "[Postburner::Worker] Starting worker '#{worker_config[:name]}'..."
         logger.info "[Postburner::Worker] Queues: #{config.queue_names.join(', ')}"
+        logger.info "[Postburner::Worker] Config: #{worker_config[:forks]} forks, #{worker_config[:threads]} threads, gc_limit: #{worker_config[:gc_limit] || 'unlimited'}, timeout: #{worker_config[:timeout]}s"
         logger.info "[Postburner] #{config.beanstalk_url} watching tubes: #{config.expanded_tube_names.join(', ')}"
 
         # Detect mode based on fork configuration
-        if using_forks?
+        if worker_config[:forks] > 0
           start_forked_mode
         else
           start_single_process_mode
@@ -123,21 +102,17 @@ module Postburner
 
       private
 
-      # Checks if any queue is configured to use forks.
+      # Returns the worker configuration hash.
       #
-      # @return [Boolean] true if any queue has forks > 0
+      # @return [Hash] Worker config with :name, :queues, :forks, :threads, :gc_limit, :timeout
       #
-      def using_forks?
-        config.queue_names.any? do |queue_name|
-          queue_config = config.queue_config(queue_name)
-          fork_count = queue_config['forks'] || queue_config[:forks] || config.default_forks
-          fork_count > 0
-        end
+      def worker_config
+        config.worker_config
       end
 
       # Starts worker in single-process mode (forks: 0).
       #
-      # Creates thread pools for each queue in the main process.
+      # Creates a thread pool that watches all configured queues.
       # Suitable for development and moderate concurrency needs.
       #
       # @return [void]
@@ -147,12 +122,17 @@ module Postburner
 
         # Track total jobs processed across all threads
         @jobs_processed = Concurrent::AtomicFixnum.new(0)
-        @gc_limit = config.default_gc_limit
+        @gc_limit = worker_config[:gc_limit]
+
+        # Create thread pool
+        thread_count = worker_config[:threads]
+        @pool = Concurrent::FixedThreadPool.new(thread_count)
 
-        # Create thread pools for each queue
-        @pools = {}
-        config.queue_names.each do |queue_name|
-          spawn_queue_threads(queue_name)
+        # Spawn worker threads
+        thread_count.times do
+          @pool.post do
+            process_jobs
+          end
         end
 
         # Monitor for shutdown or GC limit
@@ -160,9 +140,10 @@ module Postburner
           sleep 0.5
         end
 
-        # Shutdown pools gracefully
+        # Shutdown pool gracefully
         logger.info "[Postburner::Worker] Shutting down..."
-        shutdown_pools
+        @pool.shutdown
+        @pool.wait_for_termination(30)
 
         if @gc_limit && @jobs_processed.value >= @gc_limit
           logger.info "[Postburner::Worker] Reached GC limit (#{@jobs_processed.value} jobs), exiting for restart..."
@@ -172,49 +153,24 @@ module Postburner
         end
       end
 
-      # Spawns thread pool for a specific queue in single-process mode.
-      #
-      # @param queue_name [String] Name of the queue to process
-      #
-      # @return [void]
-      #
-      def spawn_queue_threads(queue_name)
-        queue_config = config.queue_config(queue_name)
-        thread_count = queue_config['threads'] || queue_config[:threads] || config.default_threads
-
-        logger.info "[Postburner::Worker] Queue '#{queue_name}': #{thread_count} threads"
-
-        # Create thread pool
-        pool = Concurrent::FixedThreadPool.new(thread_count)
-        @pools[queue_name] = pool
-
-        # Spawn worker threads
-        thread_count.times do
-          pool.post do
-            process_jobs_in_single_process(queue_name)
-          end
-        end
-      end
-
-      # Processes jobs in a single thread (single-process mode).
+      # Processes jobs in a single thread.
       #
       # Each thread has its own Beanstalkd connection and reserves jobs
-      # from the specified queue.
-      #
-      # @param queue_name [String] Name of the queue to process
+      # from all configured queues.
       #
       # @return [void]
       #
-      def process_jobs_in_single_process(queue_name)
+      def process_jobs
         connection = Postburner::Connection.new
+        timeout = worker_config[:timeout]
 
-        # Watch only this queue
-        watch_queues(connection, queue_name)
+        # Watch all configured queues
+        watch_queues(connection, config.queue_names)
 
         until shutdown? || (@gc_limit && @jobs_processed.value >= @gc_limit)
           begin
-            # Reserve with short timeout
-            job = connection.beanstalk.tubes.reserve(timeout: 1)
+            # Reserve with configured timeout
+            job = connection.beanstalk.tubes.reserve(timeout: timeout)
 
             if job
               logger.debug "[Postburner::Worker] Thread #{Thread.current.object_id} reserved job #{job.id}"
@@ -238,34 +194,22 @@ module Postburner
         connection&.close rescue nil
       end
 
-      # Gracefully shuts down all thread pools (single-process mode).
-      #
-      # @return [void]
-      #
-      def shutdown_pools
-        @pools.each do |queue_name, pool|
-          pool.shutdown
-          pool.wait_for_termination(30)
-          logger.info "[Postburner::Worker] Queue '#{queue_name}' shutdown complete"
-        end
-      end
-
       # Starts worker in forked mode (forks: 1+).
       #
-      # Forks multiple child processes for each queue, each running
-      # a thread pool. Parent process monitors children and restarts them when they exit.
+      # Forks multiple child processes, each running a thread pool.
+      # Parent process monitors children and restarts them when they exit.
       #
       # @return [void]
       #
       def start_forked_mode
-        logger.info "[Postburner::Worker] Mode: Multi-process (forks: 1+)"
+        logger.info "[Postburner::Worker] Mode: Multi-process (#{worker_config[:forks]} forks)"
 
-        # Track children: { pid => { queue: 'name', fork_num: 0 } }
+        # Track children: { pid => fork_num }
         @children = {}
 
-        # Spawn configured number of forks for each queue
-        config.queue_names.each do |queue_name|
-          spawn_queue_workers(queue_name)
+        # Spawn configured number of forks
+        worker_config[:forks].times do |fork_num|
+          spawn_fork(fork_num)
         end
 
         # Parent process monitors children
@@ -274,18 +218,16 @@ module Postburner
             pid, status = Process.wait2(-1, Process::WNOHANG)
 
             if pid
-              child_info = @children.delete(pid)
+              fork_num = @children.delete(pid)
               exit_code = status.exitstatus
-              queue_name = child_info[:queue]
-              fork_num = child_info[:fork_num]
 
               if exit_code == 99
                 # GC restart - this is normal
-                logger.info "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num} reached GC limit, restarting..."
-                spawn_queue_worker(queue_name, fork_num) unless shutdown?
+                logger.info "[Postburner::Worker] Fork #{fork_num} reached GC limit, restarting..."
+                spawn_fork(fork_num) unless shutdown?
               else
-                logger.error "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num} exited unexpectedly (code: #{exit_code})"
-                spawn_queue_worker(queue_name, fork_num) unless shutdown?
+                logger.error "[Postburner::Worker] Fork #{fork_num} exited unexpectedly (code: #{exit_code})"
+                spawn_fork(fork_num) unless shutdown?
               end
             end
 
@@ -305,61 +247,36 @@ module Postburner
         logger.info "[Postburner::Worker] Shutdown complete"
       end
 
-      # Spawns all forked worker processes for a specific queue.
-      #
-      # @param queue_name [String] Name of the queue to process
-      #
-      # @return [void]
-      #
-      def spawn_queue_workers(queue_name)
-        queue_config = config.queue_config(queue_name)
-        fork_count = queue_config['forks'] || queue_config[:forks] || config.default_forks
-        thread_count = queue_config['threads'] || queue_config[:threads] || config.default_threads
-
-        # Skip if this queue has 0 forks (shouldn't happen in forked mode, but be defensive)
-        return if fork_count == 0
-
-        total_concurrency = fork_count * thread_count
-        logger.info "[Postburner::Worker] Queue '#{queue_name}': #{fork_count} forks × #{thread_count} threads = #{total_concurrency} total concurrency"
-
-        fork_count.times do |fork_num|
-          spawn_queue_worker(queue_name, fork_num)
-        end
-      end
-
-      # Spawns a single forked worker process for a specific queue.
+      # Spawns a single forked worker process.
       #
-      # @param queue_name [String] Name of the queue to process
       # @param fork_num [Integer] Fork number (0-indexed)
       #
       # @return [void]
       #
-      def spawn_queue_worker(queue_name, fork_num)
+      def spawn_fork(fork_num)
         pid = fork do
           # Child process
-          run_queue_worker(queue_name, fork_num)
+          run_fork(fork_num)
         end
 
-        @children[pid] = { queue: queue_name, fork_num: fork_num }
-        logger.info "[Postburner::Worker] Spawned worker for queue '#{queue_name}' fork #{fork_num} (pid: #{pid})"
+        @children[pid] = fork_num
+        logger.info "[Postburner::Worker] Spawned fork #{fork_num} (pid: #{pid})"
       end
 
-      # Runs the thread pool worker for a specific queue fork.
+      # Runs the thread pool worker in a forked process.
       #
       # This runs in the child process. Creates a thread pool and processes
       # jobs until GC limit is reached or shutdown is requested.
       #
-      # @param queue_name [String] Name of the queue to process
       # @param fork_num [Integer] Fork number (for logging)
       #
       # @return [void]
       #
-      def run_queue_worker(queue_name, fork_num)
-        queue_config = config.queue_config(queue_name)
-        thread_count = queue_config['threads'] || queue_config[:threads] || config.default_threads
-        gc_limit = queue_config['gc_limit'] || queue_config[:gc_limit] || config.default_gc_limit
+      def run_fork(fork_num)
+        thread_count = worker_config[:threads]
+        gc_limit = worker_config[:gc_limit]
 
-        logger.info "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num}: #{thread_count} threads, GC limit #{gc_limit || 'unlimited'}"
+        logger.info "[Postburner::Worker] Fork #{fork_num}: #{thread_count} threads, GC limit #{gc_limit || 'unlimited'}"
 
         # Track jobs processed in this fork
         jobs_processed = Concurrent::AtomicFixnum.new(0)
@@ -370,7 +287,7 @@ module Postburner
         # Each thread needs its own Beanstalkd connection
         thread_count.times do
           pool.post do
-            process_jobs_in_fork(queue_name, fork_num, jobs_processed, gc_limit)
+            process_jobs_in_fork(fork_num, jobs_processed, gc_limit)
           end
         end
 
@@ -384,43 +301,43 @@ module Postburner
         pool.wait_for_termination(30)
 
         if gc_limit && jobs_processed.value >= gc_limit
-          logger.info "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num} reached GC limit (#{jobs_processed.value} jobs), exiting for restart..."
+          logger.info "[Postburner::Worker] Fork #{fork_num} reached GC limit (#{jobs_processed.value} jobs), exiting for restart..."
           exit 99  # Special exit code for GC restart
         else
-          logger.info "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num} shutting down gracefully..."
+          logger.info "[Postburner::Worker] Fork #{fork_num} shutting down gracefully..."
           exit 0
         end
       rescue => e
-        logger.error "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num} error: #{e.message}"
+        logger.error "[Postburner::Worker] Fork #{fork_num} error: #{e.message}"
         logger.error e.backtrace.join("\n")
         exit 1
       end
 
-      # Processes jobs in a single thread within a fork (forked mode).
+      # Processes jobs in a single thread within a fork.
       #
       # Each thread has its own Beanstalkd connection and reserves jobs
-      # from the specified queue.
+      # from all configured queues.
       #
-      # @param queue_name [String] Name of the queue to process
       # @param fork_num [Integer] Fork number (for logging)
       # @param jobs_processed [Concurrent::AtomicFixnum] Shared counter of jobs processed
       # @param gc_limit [Integer, nil] Maximum jobs before triggering GC restart (nil = unlimited)
       #
       # @return [void]
       #
-      def process_jobs_in_fork(queue_name, fork_num, jobs_processed, gc_limit)
+      def process_jobs_in_fork(fork_num, jobs_processed, gc_limit)
         connection = Postburner::Connection.new
+        timeout = worker_config[:timeout]
 
-        # Watch only this queue
-        watch_queues(connection, queue_name)
+        # Watch all configured queues
+        watch_queues(connection, config.queue_names)
 
         until shutdown? || (gc_limit && jobs_processed.value >= gc_limit)
           begin
-            # Reserve with short timeout
-            job = connection.beanstalk.tubes.reserve(timeout: 1)
+            # Reserve with configured timeout
+            job = connection.beanstalk.tubes.reserve(timeout: timeout)
 
             if job
-              logger.debug "[Postburner::Worker] Queue '#{queue_name}' fork #{fork_num} thread #{Thread.current.object_id} reserved job #{job.id}"
+              logger.debug "[Postburner::Worker] Fork #{fork_num} thread #{Thread.current.object_id} reserved job #{job.id}"
               execute_job(job)
               jobs_processed.increment
             end

data/lib/postburner.rb

@@ -448,6 +448,25 @@ module Postburner
     @__watched_tubes ||= watched_tube_names.map { |tube_name| connection.tubes[tube_name] }
   end
 
+  # Returns the Beanstalkd tube name prefix for the given environment.
+  #
+  # Delegates to {Configuration#tube_prefix}. Postburner automatically
+  # prefixes all queue names with this value.
+  #
+  # @param env [String, Symbol, nil] Environment name (defaults to Rails.env or nil)
+  #
+  # @return [String] Tube prefix (e.g., "postburner.production")
+  #
+  # @example
+  #   Postburner.tube_prefix('production')  # => "postburner.production"
+  #   Postburner.tube_prefix                # => "postburner.test" (in test env)
+  #
+  # @see Configuration#tube_prefix
+  #
+  def self.tube_prefix(env = nil)
+    configuration.tube_prefix(env)
+  end
+
   # Returns detailed statistics about Beanstalkd tubes.
   #
   # Collects job counts (ready, delayed, buried, reserved) for each tube

metadata

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