postburner 1.0.0.rc.6 → 1.0.0.rc.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b48c13a76dd9b1b6e54f825bbc50d95574c0decd4a57b8b6ba3d3fc8c5ea369c
-  data.tar.gz: 5a867eef5d36cce234b2874b5c18ff95d0ddb648fd1576e71c0a8c5946ddc12c
+  metadata.gz: 9e547f2f387408e6f3abed4bafba9f6c737c49ec3d7cbc65bfd80dd2ba509451
+  data.tar.gz: 7aa5b40f8224bc79abcba8d63f423410ed86cb74c9db9a47a47c83027744a667
 SHA512:
-  metadata.gz: 82e60e8af9d983550d7a07dac46b1c5611eb11245944e2ddac5a7411cf2d0b63a59697cab1a83965379bb92c274c1abd33a1a475498f981cbcb8589d520ac61c
-  data.tar.gz: 430829a786da22122f8ce4a47e8e966feb524877539f7a0e4086db912731235064c6888d0662d67c438e0c2e2d590a2a4496e33a56658b3022f70fbbb58ca050
+  metadata.gz: 24aa9c290a6f34ea9630823da4849a96d28cf786bbfdac43e8e2ba45fc79d04fa49d2d99ef1917740baca2e282693ce80e928a010df653cb55b78f9f19d15f39
+  data.tar.gz: e39b5f65a04804282d5050115111c1906377ad9da2cc169c805235a43d6933687e01ecc2619c2869fb99cb004e6b7d6fed3009ccd2b720a4e13e9998eb83eae6

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+## v1.0.0.rc.8 - 2026-10-05
+
+### Fixed
+
+- **A testing strategy no longer drops ActiveJob enqueues outside the test environment.** `NullQueue`, `InlineTestQueue`, and `TimeTravelTestQueue` still keep `Postburner::Job` off Beanstalkd in every environment. `perform_later`, `deliver_later`, and `broadcast_*_later` skip the put only when `Rails.env.test?` and the strategy is a testing strategy. In production the adapter always puts, including after `Postburner.null_strategy!`.
+- **The test strategy is chosen at boot.** The engine reads `config.active_job.queue_adapter` from `after_initialize`, so the choice is in place before the first test and does not wait for `ActiveJob::Base` to load. A strategy assigned in an initializer, or later in `test_helper.rb`, is kept. `:test` selects `InlineTestQueue`. `:postburner` selects `NullQueue`.
+- **Boot no longer reads `config.active_job` unless the test environment has that railtie.** An application that requires Active Record, Action Controller, and Action View without the ActiveJob railtie has no `config.active_job`. The test-strategy hook returns before touching it outside test, and when `config` does not respond to `active_job`.
+
+### Changed
+
+- **`perform_later` waits for the surrounding transaction to commit.** Selecting the Postburner adapter sets `ActiveJob::Base.enqueue_after_transaction_commit = true`. A job enqueued inside a joinable transaction is put after commit and dropped on rollback. A Beanstalkd error on that put is raised after the data is committed. The flag lives on `ActiveJob::Base`, so a job class that uses another adapter in the same process inherits the same deferral.
+- **In the test environment, `:postburner` does not write to Beanstalkd.** `Postburner::Job#queue!` keeps the row (`NullQueue`). ActiveJob enqueues still write a tracked row when the job is tracked, still emit the enqueue notification, and do not put. `Postburner.default_strategy!` or `Postburner.strict_strategy!` is the opt-in that puts.
+
+### Upgrade notes
+
+- A test that asserts a real tube job after `perform_later` or `queue!` calls `Postburner.default_strategy!` or `Postburner.strict_strategy!`.
+- `Postburner.null_strategy!` in production still skips the tube for `Postburner::Job` only. ActiveJob continues to put.
+
+## v1.0.0.rc.7 - 2026-08-03
+
+### Fixed
+
+- **Delayed jobs can release before their `run_at`.** Beanstalkd delays are whole seconds, so a fractional delay has to round. Insertions are now computed as `(at - now).ceil`.
+- **Premature re-insert could spin.** `NiceQueue`/`DefaultQueue` re-inserted a premature job with a fractional second value. Re-insert delay is now `[early.ceil, 1].max`.
+
+### Changed
+
+- Premature-job messages now report how early the job arrived: the `PREMATURE; RE-INSERTED` audit log entry and the `Postburner::Job::PrematurePerform` message both include the delta in seconds, which makes sub-second scheduling drift visible instead of silent.
+
 ## v1.0.0.rc.6 - 2026-06-27
 
 ### Highlights

data/README.md

@@ -919,15 +919,15 @@ Pay attention to the following when writing jobs:
 
 ## Queue Strategies
 
-Postburner uses different strategies to control job execution. These affect `Postburner::Job` subclasses (not ActiveJob classes).
+Postburner uses different strategies to control `Postburner::Job` execution. In the test environment a testing strategy also tells the ActiveJob adapter not to put to Beanstalkd. Outside test the adapter always puts. `DefaultQueue` and `StrictQueue` put in every environment.
 
 | Strategy | When to Use | Behavior | Requires Beanstalkd |
 |----------|-------------|----------|---------------------|
-| **DefaultQueue** | Production | Async, gracefully requeues premature jobs | Yes |
-| **StrictQueue** | Production | Async via Beanstalkd, raises error on premature execution | Yes |
-| **NullQueue** | Test (usually) | Jobs created but not inserted into Beanstalkd, manual execution | No |
-| **InlineTestQueue** | Test | Inline execution (error raised for delayed jobs) | No |
-| **TimeTravelTestQueue** | Test | Inline execution, (auto time-travels for delayed jobs) | No |
+| **DefaultQueue** | Production, or a test that needs a real tube | Async, gracefully requeues premature jobs. The ActiveJob adapter puts. | Yes |
+| **StrictQueue** | Production, or a test that needs a real tube | Async via Beanstalkd, raises error on premature execution. The ActiveJob adapter puts. | Yes |
+| **NullQueue** | Test default when the adapter is `:postburner`. Also deferred or manual `Postburner::Job` execution | Jobs created but not inserted into Beanstalkd. In test, the ActiveJob adapter does not put. Outside test, the adapter still puts. | No |
+| **InlineTestQueue** | Test default when the adapter is `:test` | Inline execution (error raised for delayed jobs). In test, the ActiveJob adapter does not put. | No |
+| **TimeTravelTestQueue** | Test | Inline execution, (auto time-travels for delayed jobs). In test, the ActiveJob adapter does not put. | No |
 
 ```ruby
 # Switch strategies
@@ -950,45 +950,33 @@ There are 4 hook methods that are used with inheritance:
 
 ### Automatic Test Mode
 
-In Rails test environments, Postburner automatically uses inline execution via the `InlineTestQueue` strategy:
+`config.active_job.queue_adapter` is the only setup. At the end of boot the test environment selects a strategy that does not write to Beanstalkd. A strategy assigned in an initializer is already set by then and is kept. A strategy assigned in `test_helper.rb` runs after boot and is kept:
+
+| `queue_adapter` | `Postburner::Job#queue!` | ActiveJob `perform_later` |
+|-----------------|--------------------------|---------------------------|
+| `:test` | `InlineTestQueue` (runs in process) | Rails keeps the job in memory |
+| `:postburner` | `NullQueue` (row kept, run it with `Postburner::Job.perform`) | Tracked jobs still write their row. Nothing is put. |
 
 ```ruby
-# test/test_helper.rb - automatic!
-Postburner.testing?  # => true in tests
+Postburner.default_strategy!   # this example needs a real tube
+SendEmail.perform_later(123)   # now the adapter puts
 ```
 
-Postburner provides test-friendly execution modes that don't require Beanstalkd.
-
-### Testing Default Jobs (ActiveJob)
-
-Use standard ActiveJob test helpers:
-
-```ruby
-class MyTest < ActiveSupport::TestCase
-  test "job executes" do
-    SendEmail.perform_later(123)
-    # Job executes immediately in test mode
-  end
+`Postburner.strict_strategy!` is the same opt-in with strict premature handling. `assert_enqueued_jobs` still needs the `:test` adapter, via `config/environments/test.rb` or `queue_adapter_for_test`.
 
-  test "job with delay" do
-    travel 1.hour do
-      SendEmail.set(wait: 1.hour).perform_later(123)
-    end
-  end
-end
-```
+An application that does not load the ActiveJob railtie has no `config.active_job`, so test boot leaves `DefaultQueue` in place and `Postburner::Job#queue!` puts. Call `Postburner.null_strategy!` in that app. `:inline` and `:async` leave `DefaultQueue` for the same reason: only `:test` and `:postburner` select a strategy that does not put.
 
 ### Testing Tracked Jobs
 
-Tracked jobs create database records you can inspect:
+With the `:postburner` adapter in test, `perform_later` writes the `TrackedJob` row and leaves `bkid` nil:
 
 ```ruby
-test "tracked job logs execution" do
+test "tracked job records the enqueue" do
   ProcessPayment.perform_later(456)
 
   job = Postburner::TrackedJob.last
-  assert job.processed_at.present?
-  assert_includes job.logs.map { |l| l[1]['message'] }, "Processing payment 456"
+  assert job.queued_at.present?
+  assert_nil job.bkid
 end
 ```
 
@@ -1014,16 +1002,16 @@ class EmailTest < ActiveSupport::TestCase
 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.
+**How this works:** `assert_enqueued_emails` and `assert_enqueued_jobs` read Rails' `:test` adapter. They do not see jobs enqueued through `:postburner`. Set the test adapter when a test needs those assertions. With `:postburner` left in place, test enqueues stay out of Beanstalkd until the test calls `Postburner.default_strategy!` or `Postburner.strict_strategy!`.
 
-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:
+Rails uses the `:test` adapter in the test environment unless the application sets another one:
 
 ```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.
+Without the `:test` adapter, `assert_enqueued_emails` does not see the enqueue. Postburner does not run the job in its place, and it does not put one on a tube either.
 
 **`Postburner::Mailer`** bypasses ActiveJob entirely, so `assert_enqueued_emails` cannot see these jobs regardless of adapter. Assert on side effects instead:
 

data/app/concerns/postburner/insertion.rb

@@ -85,7 +85,15 @@ module Postburner
       self.run_at = case
                     when at.present?
                       # this is rudimentary, add error handling
-                      options[:delay] ||= at.to_i - now.to_i
+                      #
+                      # Ceil, don't floor. Beanstalkd delays are whole seconds,
+                      # so some rounding is unavoidable -- but it must round
+                      # *away* from now. Flooring both sides (`at.to_i -
+                      # now.to_i`) drops frac(at) and frac(now) independently,
+                      # releasing the job early by frac(at) - frac(now)
+                      # whenever that is positive. Consumers then see a job
+                      # arrive before its own run_at.
+                      options[:delay] ||= [(at.to_time - now).ceil, 0].max
                       at
                     when options[:delay].present?
                       now + options[:delay].seconds

data/app/models/postburner/orphaned_job.rb

@@ -33,12 +33,12 @@ module Postburner
   # application code.
   #
   # @example Typical lifecycle
-  #   # A DB row exists with type: 'Flex::TriggerNoShowDeliveriesJob' (class deleted)
+  #   # A DB row exists with type: 'MyApp::RemovedJob' (class deleted)
   #   job = Postburner::Job.find(42)
   #   job.class         # => Postburner::OrphanedJob
-  #   job.type          # => 'Flex::TriggerNoShowDeliveriesJob'
+  #   job.type          # => 'MyApp::RemovedJob'
   #   job.orphaned?     # => true
-  #   job.missing_class_name  # => 'Flex::TriggerNoShowDeliveriesJob'
+  #   job.missing_class_name  # => 'MyApp::RemovedJob'
   #   job.perform             # => raises Postburner::Job::OrphanedJobError
   #   job.remove!             # soft-deletes fine despite readonly?
   #

data/app/models/postburner/schedule.rb

@@ -895,7 +895,7 @@ module Postburner
 
     # Calculate next time for month-based intervals.
     #
-    # Handles variable month lengths like Flex subscription billing.
+    # Handles variable month lengths, as monthly billing cycles require.
     # Always snaps to the anchor's day-of-month (or end of month if shorter).
     #
     # Uses Rails Duration for month arithmetic with day adjustment.
@@ -944,7 +944,7 @@ module Postburner
       next_time = anchor_time + (n * interval).months
 
       # Adjust day to match anchor's day (or end of month if shorter)
-      # This is the Flex pattern for "snap back" behavior
+      # "Snap back" behavior: a short month never permanently shifts the day
       if next_time.end_of_month.day >= requested_day
         next_time.change(day: requested_day)
       else

data/app/models/postburner/schedule_execution.rb

@@ -144,7 +144,9 @@ module Postburner
       # BOTH enqueue paths defer the actual Beanstalkd insertion until this
       # transaction commits:
       #  - Postburner::Job#queue! inserts via an after-commit hook;
-      #  - the ActiveJob adapter declares enqueue_after_transaction_commit?.
+      #  - selecting the Postburner adapter sets
+      #    ActiveJob::Base.enqueue_after_transaction_commit, so Rails holds
+      #    the adapter enqueue until this transaction commits.
       # So the real Beanstalkd id (and, for tracked ActiveJobs, the TrackedJob
       # row) only exists AFTER the transaction below. We capture the job here and
       # link/record the Beanstalkd id afterward.
@@ -276,9 +278,8 @@ module Postburner
 
     # Validate that the next execution matches the cached next_run_at.
     #
-    # Similar to Flex::SubscriptionIteration validation. Ensures that the
-    # pre-calculated next_run_at in this execution matches the actual run_at
-    # of the next execution created.
+    # Ensures that the pre-calculated next_run_at in this execution matches
+    # the actual run_at of the next execution created.
     #
     # This validation helps detect calculation bugs or manual tampering with
     # execution records.
@@ -379,11 +380,12 @@ module Postburner
     # Creates and enqueues an ActiveJob instance with the scheduled run_at time.
     # Handles both Hash args (passed as keyword arguments) and Array args (splatted).
     #
-    # IMPORTANT: the Postburner ActiveJob adapter declares
-    # enqueue_after_transaction_commit?, so the actual Beanstalkd put is deferred
-    # until the surrounding transaction commits. This method therefore only
-    # *registers* the enqueue; the resulting beanstalk_job_id (and, for tracked
-    # ActiveJobs, the TrackedJob record) are not available until after commit.
+    # IMPORTANT: selecting the Postburner adapter sets
+    # ActiveJob::Base.enqueue_after_transaction_commit, so Rails defers the
+    # actual Beanstalkd put until the surrounding transaction commits. This
+    # method therefore only *registers* the enqueue; the resulting
+    # beanstalk_job_id (and, for tracked ActiveJobs, the TrackedJob record)
+    # are not available until after commit.
     # Linking is the caller's responsibility via {#link_activejob!}.
     #
     # @return [ActiveJob::Base] the enqueued job, to be linked after commit
@@ -407,7 +409,9 @@ module Postburner
       job.priority = cached_schedule['priority'] if cached_schedule['priority']
 
       # Enqueue with scheduled time (use instance method enqueue, not class method perform_later)
-      delay = (run_at - Time.current).to_i
+      # ceil so the job is never released before run_at; see
+      # Postburner::Insertion#queue!
+      delay = (run_at - Time.current).ceil
       delay = 0 if delay < 0
 
       if delay > 0

data/lib/postburner/active_job/adapter.rb

@@ -53,6 +53,17 @@ module ActiveJob
     #   end
     #
     class PostburnerAdapter
+      # Rails 8 reads `ActiveJob::Base.enqueue_after_transaction_commit` and
+      # never calls {#enqueue_after_transaction_commit?}. Setting it here, when
+      # the adapter is selected, covers jobs that inherit `ActiveJob::Base`
+      # directly (Turbo broadcasts, Action Mailer). A job class that uses a
+      # different adapter in the same process inherits the same deferral.
+      # The put then runs after commit, so a Beanstalkd failure raises after
+      # the surrounding data is committed and the enqueue is dropped on rollback.
+      def initialize(*)
+        ActiveJob::Base.enqueue_after_transaction_commit = true
+      end
+
       # Enqueues a job for immediate execution.
       #
       # @param job [ActiveJob::Base] The job to enqueue
@@ -71,19 +82,17 @@ module ActiveJob
       # @return [void]
       #
       def enqueue_at(job, timestamp)
-        if tracked?(job)
+        if Postburner.suppress_active_job_enqueue?
+          enqueue_for_test(job, timestamp)
+        elsif tracked?(job)
           enqueue_tracked(job, timestamp)
         else
           enqueue_default(job, timestamp)
         end
       end
 
-      # Indicates whether the adapter supports enqueuing after transaction commit.
-      #
-      # Returns true because Postburner uses Beanstalkd (external queue),
-      # which means jobs are safely enqueued outside the database transaction.
-      # This allows Rails to automatically defer job enqueuing until after
-      # the current database transaction commits.
+      # @deprecated Rails 8 does not call this. {#initialize} sets
+      #   `ActiveJob::Base.enqueue_after_transaction_commit` instead.
       #
       # @return [Boolean] Always returns true
       #
@@ -147,6 +156,32 @@ module ActiveJob
         hook.call(job) || {}
       end
 
+      # Test enqueue. Writes a tracked row when the job is tracked, emits the
+      # enqueue notification, and does not put to Beanstalkd.
+      #
+      # Reached only from {Postburner.suppress_active_job_enqueue?}, which is
+      # true in the test environment while a testing strategy is active.
+      # Outside test the adapter puts even when the strategy is {Postburner::NullQueue}.
+      # {Postburner.default_strategy!} and {Postburner.strict_strategy!} are
+      # the opt-in that puts in test.
+      #
+      # @param job [ActiveJob::Base] The job instance
+      # @param timestamp [Time, nil] When to execute the job
+      #
+      # @return [void]
+      #
+      def enqueue_for_test(job, timestamp)
+        tracked_job = tracked?(job) ? create_tracked_record(job, timestamp) : nil
+        job.provider_job_id = nil
+        instrument_enqueue(
+          job,
+          timestamp,
+          tracked: !tracked_job.nil?,
+          postburner_job_id: tracked_job&.id,
+          beanstalk_job_id: nil
+        )
+      end
+
       # Enqueues a tracked job (with PostgreSQL audit trail).
       #
       # Creates a Postburner::TrackedJob record, then queues minimal payload
@@ -162,15 +197,12 @@ module ActiveJob
       # @return [void]
       #
       def enqueue_tracked(job, timestamp)
-        # Create Postburner::TrackedJob record
-        tracked_job = Postburner::TrackedJob.create!(
-          args: Postburner::ActiveJob::Payload.serialize_for_tracked(job),
-          run_at: timestamp ? Time.zone.at(timestamp) : nil,
-          queued_at: Time.current
-        )
+        tracked_job = create_tracked_record(job, timestamp)
 
         # Calculate delay for Beanstalkd
-        delay = timestamp ? [timestamp.to_i - Time.current.to_i, 0].max : 0
+        # ceil so the job is never released before its timestamp; see
+        # Postburner::Insertion#queue!
+        delay = timestamp ? [(Time.zone.at(timestamp) - Time.current).ceil, 0].max : 0
 
         # Queue to Beanstalkd with minimal payload
         bkid = nil
@@ -196,25 +228,13 @@ module ActiveJob
         # callers (e.g. ScheduleExecution) can capture it after enqueue.
         job.provider_job_id = bkid
 
-        # Instrument enqueue event
-        job_payload = Postburner::Instrumentation.job_payload_from_activejob(
+        instrument_enqueue(
           job,
+          timestamp,
           tracked: true,
           postburner_job_id: tracked_job.id,
           beanstalk_job_id: bkid
         )
-        scheduled_at = timestamp ? Time.zone.at(timestamp) : nil
-
-        if scheduled_at && scheduled_at > Time.current
-          ActiveSupport::Notifications.instrument('enqueue_at.job.postburner', {
-            job: job_payload,
-            scheduled_at: scheduled_at
-          })
-        else
-          ActiveSupport::Notifications.instrument('enqueue.job.postburner', {
-            job: job_payload
-          })
-        end
       end
 
       # Enqueues a default job (Beanstalkd only, no PostgreSQL).
@@ -232,7 +252,9 @@ module ActiveJob
       # @return [void]
       #
       def enqueue_default(job, timestamp)
-        delay = timestamp ? [timestamp.to_i - Time.current.to_i, 0].max : 0
+        # ceil so the job is never released before its timestamp; see
+        # Postburner::Insertion#queue!
+        delay = timestamp ? [(Time.zone.at(timestamp) - Time.current).ceil, 0].max : 0
         bkid = nil
 
         Postburner.connected do |conn|
@@ -254,13 +276,47 @@ module ActiveJob
         # callers (e.g. ScheduleExecution) can capture it after enqueue.
         job.provider_job_id = bkid
 
-        # Instrument enqueue event
-        job_payload = Postburner::Instrumentation.job_payload_from_activejob(
+        instrument_enqueue(
           job,
+          timestamp,
           tracked: false,
           postburner_job_id: nil,
           beanstalk_job_id: bkid
         )
+      end
+
+      # Creates the PostgreSQL row for a tracked ActiveJob.
+      #
+      # @param job [ActiveJob::Base] The job instance
+      # @param timestamp [Numeric, nil] Scheduled time as a unix timestamp
+      #
+      # @return [Postburner::TrackedJob]
+      #
+      def create_tracked_record(job, timestamp)
+        Postburner::TrackedJob.create!(
+          args: Postburner::ActiveJob::Payload.serialize_for_tracked(job),
+          run_at: timestamp ? Time.zone.at(timestamp) : nil,
+          queued_at: Time.current
+        )
+      end
+
+      # Emits enqueue or enqueue_at for an ActiveJob.
+      #
+      # @param job [ActiveJob::Base]
+      # @param timestamp [Numeric, nil]
+      # @param tracked [Boolean]
+      # @param postburner_job_id [Integer, nil]
+      # @param beanstalk_job_id [Integer, nil]
+      #
+      # @return [void]
+      #
+      def instrument_enqueue(job, timestamp, tracked:, postburner_job_id:, beanstalk_job_id:)
+        job_payload = Postburner::Instrumentation.job_payload_from_activejob(
+          job,
+          tracked: tracked,
+          postburner_job_id: postburner_job_id,
+          beanstalk_job_id: beanstalk_job_id
+        )
         scheduled_at = timestamp ? Time.zone.at(timestamp) : nil
 
         if scheduled_at && scheduled_at > Time.current

data/lib/postburner/engine.rb

@@ -13,5 +13,21 @@ module Postburner
       g.skip_routes true
     end
 
+    # Choose the test strategy once boot has finished applying configuration.
+    # after_initialize runs after config/initializers and before a test helper
+    # continues. The configured adapter is already a name here, so this does
+    # not load ActiveJob::Base. An application that already assigned a
+    # strategy keeps that choice.
+    #
+    # The hook runs in every environment. {Postburner.install_test_queue_strategy_for}
+    # returns before reading +config.active_job+ outside test, and when the
+    # app did not load the ActiveJob railtie. That config namespace does not
+    # exist unless the railtie is required.
+    initializer "postburner.active_job_test_strategy", after: "active_job.set_configs" do |app|
+      app.config.after_initialize do
+        Postburner.install_test_queue_strategy_for(app)
+      end
+    end
+
   end
 end

data/lib/postburner/strategies/default_queue.rb

@@ -77,8 +77,13 @@ module Postburner
       # @note Logs "PREMATURE; RE-INSERTED" message to job's audit trail
       #
       def handle_premature_perform(job)
-        response = job.insert! delay: job.run_at - Time.current
-        job.log! "PREMATURE; RE-INSERTED: #{response}"
+        early = job.run_at - Time.current
+        # Never re-insert with a delay under a second. A fractional delay
+        # truncates to 0, so the job comes straight back, is judged premature
+        # again, and burns reserve/delete/put plus a DB write per pass until
+        # the clock catches up.
+        response = job.insert! delay: [early.ceil, 1].max
+        job.log! "PREMATURE (#{early.round(3)}s early); RE-INSERTED: #{response}"
       end
     end
   end

data/lib/postburner/strategies/inline_test_queue.rb

@@ -7,7 +7,7 @@ module Postburner
   # tests fast and predictable. It raises {Postburner::Job::PrematurePerform} if
   # a job has a future run_at, forcing you to use explicit time travel in tests.
   #
-  # @note Auto-detected when Rails.env.test? and ActiveJob adapter is :test
+  # @note Selected in the Rails test environment when the ActiveJob adapter is `:test`
   #
   # ## When to Use InlineTestQueue
   #

data/lib/postburner/strategies/null_queue.rb

@@ -9,7 +9,10 @@ module Postburner
   # to Beanstalkd. Jobs can be manually executed later using {.handle_perform!},
   # which includes automatic time travel for scheduled jobs.
   #
-  # @note This is a test-mode strategy (returns true for testing)
+  # @note This is a test-mode strategy (returns true for testing).
+  #   Selected in the Rails test environment when the ActiveJob adapter is `:postburner`.
+  #   Outside the test environment it still keeps {Postburner::Job} off
+  #   Beanstalkd. ActiveJob `perform_later` continues to put.
   #
   # ## When to Use NullQueue
   #

data/lib/postburner/strategies/strict_queue.rb

@@ -81,7 +81,10 @@ 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].present? ? [0, options[:delay].to_i].max : 0
+            # ceil, not to_i: callers may pass a Float delay (see
+            # DefaultQueue#handle_premature_perform), and truncating it would
+            # re-introduce the early release this guards against.
+            delay = options[:delay].present? ? [0, options[:delay].to_f.ceil].max : 0
             ttr = options[:ttr] || job.ttr || Postburner.configuration.default_ttr
             payload = JSON.generate(data)
 
@@ -119,7 +122,9 @@ module Postburner
       # @raise [Postburner::Job::PrematurePerform] Always raises for this strategy
       #
       def handle_premature_perform(job)
-        raise Postburner::Job::PrematurePerform, "Job has future run_at: #{job.run_at}"
+        early = job.run_at - Time.current
+        raise Postburner::Job::PrematurePerform,
+          "Job has future run_at: #{job.run_at} (#{early.round(3)}s early)"
       end
     end
   end

data/lib/postburner/version.rb

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

data/lib/postburner.rb

@@ -45,9 +45,19 @@ require "postburner/test_helpers"
 #
 # ## Auto-Detection
 #
-# Postburner automatically detects Rails test mode and switches to {InlineTestQueue} when:
-# - `Rails.env.test?` is true
-# - `ActiveJob::Base.queue_adapter_name == :test`
+# During `after_initialize`, {#install_test_queue_strategy!} reads
+# `config.active_job.queue_adapter` and selects the test strategy. It does
+# not wait for `ActiveJob::Base` to load, and it leaves a strategy the
+# application already assigned in place.
+#
+# - `:test` → {InlineTestQueue}. `Postburner::Job#queue!` runs in process.
+# - `:postburner` → {NullQueue}. The row is kept. In the test environment
+#   the ActiveJob adapter does not put. {#default_strategy!} or
+#   {#strict_strategy!} is the opt-in that writes to Beanstalkd.
+# - Any other adapter leaves the current strategy unchanged.
+#
+# Outside the test environment the adapter always puts. A testing strategy
+# still keeps {Postburner::Job} off Beanstalkd.
 #
 # ## Usage
 #
@@ -67,17 +77,17 @@ require "postburner/test_helpers"
 #   job.queue!(delay: 1.hour)
 #
 # @example Switching queue strategies
-#   # Production with graceful premature handling (default)
-#   Postburner.nice_async_strategy!
+#   # Production default. Premature jobs are re-inserted with a delay.
+#   Postburner.default_strategy!
 #
 #   # Production with strict premature errors
-#   Postburner.async_strategy!
+#   Postburner.strict_strategy!
 #
 #   # Test mode with explicit time control
 #   Postburner.inline_test_strategy!
 #
 #   # Test mode with automatic time travel
-#   Postburner.inline_immediate_test_strategy!
+#   Postburner.time_travel_test_strategy!
 #
 # @example Using Beanstalkd connection
 #   Postburner.connected do |conn|
@@ -87,7 +97,8 @@ require "postburner/test_helpers"
 #
 # @example Checking if in test mode
 #   if Postburner.testing?
-#     # Jobs execute inline
+#     # Postburner::Job stays off Beanstalkd. In the test environment the
+#     # ActiveJob adapter does not put either.
 #   else
 #     # Jobs queued to Beanstalkd
 #   end
@@ -99,13 +110,15 @@ require "postburner/test_helpers"
 # @see TimeTravelTestQueue
 #
 module Postburner
-  # @!attribute [rw] queue_strategy
+  # @!attribute [r] queue_strategy
   #   The current queue strategy class used for job execution.
   #
-  #   Defaults to {DefaultQueue} for production, auto-switches to {InlineTestQueue}
-  #   in Rails test environment.
+  #   Defaults to {DefaultQueue}. In the Rails test environment,
+  #   {#install_test_queue_strategy!} switches to {InlineTestQueue} when the
+  #   ActiveJob adapter is `:test`, and to {NullQueue} when it is `:postburner`,
+  #   unless the application has already assigned a strategy.
   #
-  #   @return [Class] One of StrictQueue, DefaultQueue, InlineTestQueue, or TimeTravelTestQueue
+  #   @return [Class] One of StrictQueue, DefaultQueue, InlineTestQueue, TimeTravelTestQueue, or NullQueue
   #
   #   @example
   #     Postburner.queue_strategy
@@ -116,18 +129,143 @@ module Postburner
   #   @see #inline_test_strategy!
   #   @see #time_travel_test_strategy!
   #
-  mattr_accessor :queue_strategy
+  mattr_reader :queue_strategy
+
+  # Assigns the queue strategy and records it as the application's choice.
+  #
+  # {#install_test_queue_strategy!} will not replace a strategy assigned
+  # through this writer or through a `*_strategy!` setter. The load-time
+  # default is applied without marking that choice.
+  #
+  # @param strategy [Class] A queue strategy class
+  # @return [Class]
+  #
+  def self.queue_strategy=(strategy)
+    @queue_strategy_explicit = true unless @applying_queue_strategy
+    @@queue_strategy = strategy
+  end
+
+  # True when application code assigned {#queue_strategy}, rather than the
+  # load-time default or {#install_test_queue_strategy!}.
+  #
+  # @return [Boolean]
+  #
+  def self.queue_strategy_explicit?
+    @queue_strategy_explicit == true
+  end
+
+  # Selects the queue strategy for the Rails test environment from the
+  # configured ActiveJob adapter. See the Auto-Detection section above.
+  #
+  # Called from {#install_test_queue_strategy_for} during `after_initialize`,
+  # which runs after `config/initializers` and before a test helper continues.
+  # The argument is `config.active_job.queue_adapter`. This method does not
+  # read `ActiveJob::Base.queue_adapter_name`, because that loads ActiveJob
+  # and forces `:async` when the adapter is still unset.
+  #
+  # No-op outside the test environment. No-op when {#queue_strategy_explicit?}
+  # is true. An adapter other than `:test` or `:postburner` leaves the
+  # current strategy unchanged.
+  #
+  # @param adapter [Symbol, String, Object, nil] Adapter name or instance.
+  #   `nil` reads `Rails.application.config.active_job.queue_adapter`.
+  # @return [void]
+  #
+  def self.install_test_queue_strategy!(adapter = nil)
+    return unless defined?(Rails) && Rails.env.test?
+    return if queue_strategy_explicit?
+
+    case adapter_name_for_install(adapter)
+    when "test"
+      apply_queue_strategy(InlineTestQueue)
+    when "postburner"
+      apply_queue_strategy(NullQueue)
+    end
+  end
+
+  # Engine entry point for {#install_test_queue_strategy!}.
+  #
+  # Returns before reading +config.active_job+ unless this is the test
+  # environment and the application loaded the ActiveJob railtie. Without
+  # that railtie, +Rails::Application::Configuration+ has no +active_job+
+  # method, and reading it raises during boot.
+  #
+  # @param app [Rails::Application]
+  # @return [void]
+  #
+  def self.install_test_queue_strategy_for(app)
+    return unless defined?(Rails) && Rails.env.test?
+    return unless app.config.respond_to?(:active_job)
+
+    install_test_queue_strategy!(app.config.active_job.queue_adapter)
+  end
+
+  # True when the ActiveJob adapter should record the enqueue and skip the
+  # Beanstalkd put.
+  #
+  # Limited to the test environment. A testing strategy in production still
+  # only governs {Postburner::Job}: `perform_later`, `deliver_later`, and
+  # `broadcast_*_later` keep writing to the tube.
+  #
+  # @return [Boolean]
+  #
+  def self.suppress_active_job_enqueue?
+    return false unless defined?(Rails) && Rails.env.test?
+    testing?
+  end
+
+  # Assigns a strategy without recording an application choice.
+  #
+  # @param strategy [Class]
+  # @return [Class]
+  # @api private
+  #
+  def self.apply_queue_strategy(strategy)
+    previous = @applying_queue_strategy
+    @applying_queue_strategy = true
+    self.queue_strategy = strategy
+  ensure
+    @applying_queue_strategy = previous
+  end
+  private_class_method :apply_queue_strategy
+
+  # @param adapter [Symbol, String, Object, nil]
+  # @return [String, nil]
+  # @api private
+  #
+  def self.adapter_name_for_install(adapter)
+    adapter = configured_active_job_adapter if adapter.nil?
+    return if adapter.nil?
 
-  # Initialize with DefaultQueue (production) by default
-  # DefaultQueue re-inserts premature jobs with appropriate delay
-  self.queue_strategy = Postburner::DefaultQueue
+    case adapter
+    when Symbol, String
+      adapter.to_s
+    else
+      return unless defined?(::ActiveJob) && ::ActiveJob.respond_to?(:adapter_name)
 
-  # Auto-detect Rails test mode and switch to InlineTestQueue
-  if defined?(Rails) && Rails.env.test? && defined?(::ActiveJob::Base)
-    if ::ActiveJob::Base.queue_adapter_name == :test
-      self.queue_strategy = Postburner::InlineTestQueue
+      ::ActiveJob.adapter_name(adapter).to_s.underscore
     end
   end
+  private_class_method :adapter_name_for_install
+
+  # @return [Object, nil]
+  # @api private
+  #
+  def self.configured_active_job_adapter
+    return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+    config = Rails.application.config
+    return unless config.respond_to?(:active_job)
+
+    config.active_job.queue_adapter
+  end
+  private_class_method :configured_active_job_adapter
+
+  # DefaultQueue re-inserts premature jobs with a delay. The test strategy is
+  # applied later by {#install_test_queue_strategy!}. Assigning it here does
+  # not count as an application choice. Reading the adapter name at require
+  # time would force :async before the application sets it.
+  apply_queue_strategy(Postburner::DefaultQueue)
 
   # Activates strict test mode with inline job execution.
   #
@@ -154,7 +292,7 @@ module Postburner
   #   # Raises PrematurePerform - use travel_to instead
   #
   # @see InlineTestQueue
-  # @see #inline_immediate_test_strategy!
+  # @see #time_travel_test_strategy!
   #
   def self.inline_test_strategy!
     self.queue_strategy = Postburner::InlineTestQueue
@@ -282,16 +420,18 @@ module Postburner
     self.queue_strategy = Postburner::NullQueue
   end
 
-  # Checks if currently using a test queue strategy.
+  # Checks if the current queue strategy is a testing strategy.
   #
-  # Returns true if the current queue strategy is {InlineTestQueue} or
-  # {TimeTravelTestQueue}, indicating that jobs execute inline/synchronously
-  # without Beanstalkd.
+  # True for {NullQueue}, {InlineTestQueue}, and {TimeTravelTestQueue}.
+  # Those strategies keep {Postburner::Job} off Beanstalkd. In the test
+  # environment they also tell the ActiveJob adapter not to put. Outside
+  # test, the adapter puts even when this is true. {DefaultQueue} and
+  # {StrictQueue} put in every environment.
   #
-  # @return [Boolean] true if using test strategy, false if using production strategy
+  # @return [Boolean] true if using a testing strategy
   #
   # @example
-  #   Postburner.nice_async_strategy!
+  #   Postburner.default_strategy!
   #   Postburner.testing?  # => false
   #
   #   Postburner.inline_test_strategy!

metadata

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