postburner 1.0.0.pre.7 → 1.0.0.pre.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d37676412b662bd876f2d2d09ac57e09876e5f0d8a7186c37f4f71f3d40ad89
-  data.tar.gz: 7c9e1badc1628b5cab1edaa164e449d7a926e65198009773a702a3b6f49888cd
+  metadata.gz: f609643606243463d7e6ad371fe5afc8efe7e944359a58fcc9cbe1d92d6c68dd
+  data.tar.gz: 57691caf6ca731bdc731c376d724fc466b9690d07594632c607a85a34bb3a9d5
 SHA512:
-  metadata.gz: b7bafbb9a871ce492a3f36537b237bbcb0a38e5291065384d2d2c2003bde2ebd078e9f2fd5455023bd9d81b38701a391b09d4dbeb336bfb7759e8c550497e5e9
-  data.tar.gz: 9515f40b1fe1e1782dd4a9fc6fd0c5e78e6a30c6678f656d6534eb2344360ec2c03ca745a0aedf7e3e3ec676a1d9edd092d8ff0db5b50966d24ade078496d440
+  metadata.gz: 1190b558cfe4f4dda02dc94855ea5a7eb87196b5c91735b357c8322542d3e8b952fd8f137474ab582abeff6c9d43016f1fc6c12d50884f9bd958a15208d211cb
+  data.tar.gz: 60d6106b1f646ea98130bb19f0ac6c625ccbe99a0bd7aba96901e00ef54389da93d6bdcb24f617a5d1ca34db1ec543700c07201170de7d990d3fc7b951e8e2f8

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):

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'erb'
+
 module Postburner
   # Configuration system for Postburner workers and connections.
   #
@@ -54,7 +56,10 @@ module Postburner
       }
     end
 
-    # Loads configuration from a YAML file.
+    # Loads configuration from a YAML file with ERB support.
+    #
+    # Supports ERB templating like Rails' database.yml, allowing environment
+    # variables and Ruby expressions in configuration.
     #
     # @param path [String] Path to YAML configuration file
     # @param env [String] Environment name (e.g., 'production', 'development')
@@ -73,10 +78,10 @@ module Postburner
     # @example Multiple workers (must specify)
     #   config = Postburner::Configuration.load_yaml('config/postburner.yml', 'production', 'imports')
     #
-    # @example config/postburner.yml example
+    # @example config/postburner.yml with ERB
     #
     #   default: &default
-    #     beanstalk_url: beanstalk://localhost:11300
+    #     beanstalk_url: <%= ENV.fetch('BEANSTALK_URL', 'beanstalk://localhost:11300') %>
     #     default_priority: 131072 # change default priority from 65536 to 131072
     #
     #   production: # <- environment config, i.e. defaults
@@ -97,7 +102,7 @@ module Postburner
     #           - data_processing
     #
     def self.load_yaml(path, env = 'development', worker_name = nil)
-      yaml = YAML.load_file(path, aliases: true)
+      yaml = YAML.load(ERB.new(File.read(path)).result, aliases: true)
       # env_config = top-level environment config (development:, production:, etc.)
       env_config = yaml[env.to_s] || yaml[env.to_sym]
 
@@ -184,10 +189,34 @@ module Postburner
     def expand_tube_name(queue_name = nil, env = nil)
       env ||= defined?(Rails) ? Rails.env : nil
       queue_name ||= @default_queue
+      [
+        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,
-        queue_name,
       ].compact.join('.')
     end
 

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.7'
+  VERSION = '1.0.0.pre.9'
 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

@@ -165,7 +165,7 @@ module Postburner
         timeout = worker_config[:timeout]
 
         # Watch all configured queues
-        watch_queues(connection, *config.queue_names)
+        watch_queues(connection, config.queue_names)
 
         until shutdown? || (@gc_limit && @jobs_processed.value >= @gc_limit)
           begin
@@ -329,7 +329,7 @@ module Postburner
         timeout = worker_config[:timeout]
 
         # Watch all configured queues
-        watch_queues(connection, *config.queue_names)
+        watch_queues(connection, config.queue_names)
 
         until shutdown? || (gc_limit && jobs_processed.value >= gc_limit)
           begin

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.7
+  version: 1.0.0.pre.9
 platform: ruby
 authors:
 - Matt Smith