postburner 1.0.0.pre.7 → 1.0.0.pre.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d37676412b662bd876f2d2d09ac57e09876e5f0d8a7186c37f4f71f3d40ad89
-  data.tar.gz: 7c9e1badc1628b5cab1edaa164e449d7a926e65198009773a702a3b6f49888cd
+  metadata.gz: 38a691a9f1e5d99c0d6f19cbe7c4c605bd1e570787d1cb7c8b5ee862b3efa84c
+  data.tar.gz: 962f60d03662ee7dc119503f190d5f6376cd7be35a14b52c140d75141a837b0c
 SHA512:
-  metadata.gz: b7bafbb9a871ce492a3f36537b237bbcb0a38e5291065384d2d2c2003bde2ebd078e9f2fd5455023bd9d81b38701a391b09d4dbeb336bfb7759e8c550497e5e9
-  data.tar.gz: 9515f40b1fe1e1782dd4a9fc6fd0c5e78e6a30c6678f656d6534eb2344360ec2c03ca745a0aedf7e3e3ec676a1d9edd092d8ff0db5b50966d24ade078496d440
+  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):

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

@@ -184,10 +184,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.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

@@ -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.8
 platform: ruby
 authors:
 - Matt Smith