postburner 1.0.0.rc.2 → 1.0.0.rc.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87f24f24d68086fe55b2fe315d36bc3ec9104a242066d6a78f5b61e2633f673d
-  data.tar.gz: 9ed74afc5b63a477ee254e4812f1db19fd7d9c94064afa7084d5ec6d62ee7af9
+  metadata.gz: 9aa20d7fa2c867942efc6c70f7ad56548e651192068c9505a2854310cbb95043
+  data.tar.gz: 74606e227872a914c3a806227d74206d4b66a33b7160753cbbb48a15d48a7d9c
 SHA512:
-  metadata.gz: a1a9bca8fe3cc955cb9f60c6f459cf3514bfe127806c7dda710cdd0e89822b1d398887b72d23c1f414deb5575621d829e7496f51ac6491485e9444190e70f8f6
-  data.tar.gz: d916eaaa41debc35e5460b9360e1bb5717bc93a1b16d180d774dd2a49b3fd106ffb1a80ee0c74595eb9b42939669273e623fac460e75d5c1706b2ccab23b834f
+  metadata.gz: cf4238e6bc83f1447de5c846032aad268d904fb5f74c1462424c69ffed8e40ffe316c51c2d248b2a6b46b7fb96df9b572f028368cc9e8e65e4baf8bffa7175b5
+  data.tar.gz: c93242ccd8501c5b337417f60633474104550360276c607a48308ed6bfcbcd5bd77aeafa9df7e6f0e6cb0f15094ffe4ada75ef13f2704e98c2fd31bc674fe791

data/README.md

@@ -85,7 +85,7 @@ bundle exec rake postburner:work WORKER=default
 
 ## Table of Contents
 
-- [Why](#why)
+- [Why Postburner?](#why-postburner)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
   - [Standard Jobs](#standard-jobs)
@@ -106,7 +106,7 @@ bundle exec rake postburner:work WORKER=default
 - [Installation](#installation)
 - [Web UI - v2 Coming Soon](#web-ui)
 
-## Why
+## Why Postburner?
 
 Postburner supports Async, Queues, Delayed, Priorities, Timeouts, and Retries from the [Backend Matrix](https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html). But uniquely, priorities are per job, in addition to the class level. Timeouts are per job and class level as well, and can be extended dynamically. Postburner also supports scheduling jobs at fixed intervals, cron expressions, and calendar-aware anchor points.
 
@@ -927,6 +927,53 @@ test "tracked job logs execution" do
 end
 ```
 
+### Testing Emails
+
+Standard ActiveJob test assertions (`assert_enqueued_emails`, `assert_enqueued_jobs`) work when using the `:test` ActiveJob adapter in your test environment, which is the Rails default:
+
+```ruby
+class EmailTest < ActiveSupport::TestCase
+  # assert_enqueued_emails works — Rails' :test adapter tracks the enqueue
+  test "welcome email is enqueued" do
+    assert_enqueued_emails 1 do
+      UserMailer.welcome(user).deliver_later
+    end
+  end
+
+  # assert_emails works — the job executes inline, delivering the email
+  test "welcome email is sent" do
+    assert_emails 1 do
+      SendWelcomeEmail.perform_later(user.id)
+    end
+  end
+end
+```
+
+**How this works:** `assert_enqueued_emails` and `assert_enqueued_jobs` are powered by Rails' `:test` ActiveJob adapter, which tracks enqueued jobs in an in-memory array. Postburner's queue strategies (`InlineTestQueue`, etc.) control `Postburner::Job` subclasses separately. The two systems coexist — ActiveJob assertions use the `:test` adapter, `Postburner::Job` assertions use database queries.
+
+By default, Rails uses the `:test` adapter in test mode unless you override it. Since you set `:postburner` as your adapter in `config/application.rb`, you should set it back to `:test` for your test environment:
+
+```ruby
+# config/environments/test.rb
+config.active_job.queue_adapter = :test
+```
+
+This is standard practice for any ActiveJob adapter (Sidekiq, SolidQueue, etc.) — the production adapter handles real execution, and the `:test` adapter enables Rails' built-in assertion helpers. Without this, `assert_enqueued_emails` will not work because Postburner's adapter executes jobs rather than tracking them in an array.
+
+**`Postburner::Mailer`** bypasses ActiveJob entirely, so `assert_enqueued_emails` cannot see these jobs regardless of adapter. Assert on side effects instead:
+
+```ruby
+test "mailer job sends email" do
+  job = Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1)
+
+  assert_emails 1 do
+    job.queue!  # Executes inline in test mode, delivering the email
+  end
+
+  assert job.reload.processed_at
+end
+```
+
 ### Switching Queue Strategies
 
 For tests requiring specific queue behaviors, use `switch_queue_strategy!` and `restore_queue_strategy!`:
@@ -2031,13 +2078,15 @@ Postburner uses [Beaneater](https://github.com/beanstalkd/beaneater) as the Ruby
 
 ### Connection Methods
 
+Postburner uses **thread-local connections** — each thread gets its own Beanstalkd socket, matching the pattern used by worker threads. This is safe under multi-threaded servers like Puma.
+
 ```ruby
-# Get a cached Beaneater connection (returns Beaneater instance)
+# Get the thread-local Beaneater connection (returns Beaneater instance)
 conn = Postburner.connection
 conn.tubes.to_a      # List all tubes
 conn.beanstalk.stats # Server statistics
 
-# Block form - yields connection, recommended for one-off operations
+# Block form - yields thread-local connection
 Postburner.connected do |conn|
   conn.tubes.to_a  # List all tubes
   conn.tubes['postburner.production.critical'].stats
@@ -2045,6 +2094,19 @@ Postburner.connected do |conn|
 end
 ```
 
+**Shutdown cleanup:**
+
+On process shutdown, call `disconnect_all!` to close every thread's connection cleanly:
+
+```ruby
+# config/puma.rb
+on_worker_shutdown do
+  Postburner.disconnect_all!
+end
+```
+
+This is optional — Ruby closes sockets on process exit — but gives you clean logs and explicit teardown.
+
 ### Job-Level Access
 
 ```ruby
@@ -2248,7 +2310,7 @@ beanstalkd -l 127.0.0.1 -p 11300 -b /var/lib/beanstalkd
 
 ```ruby
 # Gemfile
-gem 'postburner', '~> 1.0.0.pre.18'
+gem 'postburner', '~> 1.0.0.rc.2
 ```
 
 ```bash

data/app/models/postburner/mailer.rb

@@ -50,6 +50,20 @@ module Postburner
   # @example Queue to specific queue
   #   Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(queue: 'bulk_mailers')
   #
+  # == Testing
+  #
+  # Because Postburner::Mailer bypasses ActiveJob, Rails' +assert_enqueued_emails+
+  # will not detect these jobs. Use +assert_emails+ (which checks actual deliveries)
+  # or assert on the job record:
+  #
+  #   # Assert email was delivered (inline in test mode)
+  #   assert_emails 1 do
+  #     Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!
+  #   end
+  #
+  #   # Assert job was processed
+  #   assert job.reload.processed_at
+  #
   # @see Postburner::Job Base class for tracked jobs
   # @see Postburner::Configuration#default_mailer_queue Configuration option
   class Mailer < Job

data/lib/generators/postburner/install/install_generator.rb

@@ -1,3 +1,5 @@
+require 'time'
+
 class Postburner::InstallGenerator < Rails::Generators::Base
   source_root File.expand_path('templates', __dir__)
   include Rails::Generators::Migration
@@ -28,11 +30,15 @@ class Postburner::InstallGenerator < Rails::Generators::Base
     _max = timestamps.max || timestamp[-2..-1].to_i
     _next = _max + 1
     raise "MISSING NEXT" if _next.blank?
-    migration_number = "#{stem}#{_next}"
-    if migration_number.length != 14
-      raise "INCORRECT LENGTH stem=#{stem} _next=#{_next} _max=#{_max}"
+
+    # When seconds overflow past 99, roll forward by 1 minute and reset.
+    if _next > 99
+      rolled = Time.parse("#{stem}00 UTC") + 60
+      stem = rolled.strftime('%Y%m%d%H%M')
+      _next = 0
     end
-    migration_number
+
+    "#{stem}#{_next.to_s.rjust(2, '0')}"
   end
 
   private

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.rc.2'
+  VERSION = '1.0.0.rc.3'
 end

data/lib/postburner.rb

@@ -319,31 +319,31 @@ module Postburner
   #   conn = Postburner.connection
   #   conn.tubes['my.tube'].stats
   #
-  # @note Connection is cached in @_connection instance variable
+  # @note Connection is cached in Thread.current[:postburner_connection] (thread-local)
   # @note Automatically reconnects if connection is not active
   #
   # @see #connected
   #
   def self.connection
-    @_connection ||= Postburner::Connection.new
-    @_connection.reconnect! unless @_connection.connected?
-    @_connection
+    Thread.current[:postburner_connection] ||= Postburner::Connection.new
+    conn = Thread.current[:postburner_connection]
+    conn.reconnect! unless conn.connected?
+    conn
   end
 
   # Yields a Beanstalkd connection or returns cached connection.
   #
-  # When called with a block, yields the connection and ensures it's closed
-  # after the block completes. When called without a block, returns the
-  # cached connection.
+  # When called with a block, yields the thread-local connection.
+  # When called without a block, returns the thread-local connection.
   #
   # @overload connected
   #   Returns the cached Beanstalkd connection.
   #   @return [Postburner::Connection] Beanstalkd connection
   #
   # @overload connected {|conn| ... }
-  #   Yields connection and ensures cleanup.
+  #   Yields connection for the duration of the block.
   #   @yieldparam conn [Postburner::Connection] Beanstalkd connection
-  #   @return [void]
+  #   @return [Object] return value of the block
   #
   # @example With block (recommended)
   #   Postburner.connected do |conn|
@@ -351,7 +351,6 @@ module Postburner
   #       puts tube.name
   #     end
   #   end
-  #   # Connection automatically closed
   #
   # @example Without block
   #   conn = Postburner.connected
@@ -364,19 +363,44 @@ module Postburner
   #   end
   #
   # @see #connection
+  # @see #disconnect_all!
   #
   def self.connected
     if block_given?
-      begin
-        yield connection
-      ensure
-        connection.close if connection
-      end
+      yield connection
     else
       connection
     end
   end
 
+  # Closes and clears Beanstalkd connections on all known threads.
+  #
+  # Call this on worker shutdown to release sockets cleanly. Because connections
+  # are thread-local, a single `connection.close` call from the main thread would
+  # only close that thread's socket. This method iterates every live thread and
+  # closes each thread's connection, if any.
+  #
+  # @return [void]
+  #
+  # @example Puma worker shutdown (config/puma.rb)
+  #   on_worker_shutdown do
+  #     Postburner.disconnect_all!
+  #   end
+  #
+  def self.disconnect_all!
+    Thread.list.each do |thread|
+      if (conn = thread[:postburner_connection])
+        begin
+          conn.close if conn.respond_to?(:close) && conn.connected?
+        rescue => e
+          warn "Postburner: failed to close connection on shutdown: #{e.message}" if $VERBOSE
+        ensure
+          thread[:postburner_connection] = nil
+        end
+      end
+    end
+  end
+
   # Clears jobs from specified tubes or shows stats for all tubes.
   #
   # High-level method with formatted output. Delegates to Connection#clear_tubes!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc.2
+  version: 1.0.0.rc.3
 platform: ruby
 authors:
 - Matt Smith