postburner 1.0.0.rc.6 → 1.0.0.rc.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b48c13a76dd9b1b6e54f825bbc50d95574c0decd4a57b8b6ba3d3fc8c5ea369c
-  data.tar.gz: 5a867eef5d36cce234b2874b5c18ff95d0ddb648fd1576e71c0a8c5946ddc12c
+  metadata.gz: 41b3c95f8abde17bb19b725dd0c39ce65b97a53e73afb77c7237e2e51f37d7e9
+  data.tar.gz: 7e5de5424a027d59c9552624bd555ae38da4f30823f3ffc28ef86601c96301e0
 SHA512:
-  metadata.gz: 82e60e8af9d983550d7a07dac46b1c5611eb11245944e2ddac5a7411cf2d0b63a59697cab1a83965379bb92c274c1abd33a1a475498f981cbcb8589d520ac61c
-  data.tar.gz: 430829a786da22122f8ce4a47e8e966feb524877539f7a0e4086db912731235064c6888d0662d67c438e0c2e2d590a2a4496e33a56658b3022f70fbbb58ca050
+  metadata.gz: d2f90b3d590adfc16247f285f8ea27cef03d9dd72af5671bc92117d2418442dcf6f331c68d5380a2917687ea2353524f972fdd7edeca4fe9a8e1b6b965dff9ef
+  data.tar.gz: 06accd7ecd5c01aa83532e7f8cd69e2aca53459e7b8f8f8c0a290163555a2f24f47df8ecb4407e39d7401680547b7f016b9111221688e5dc10c2fea43eb49ba6

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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/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

@@ -276,9 +276,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.
@@ -407,7 +406,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

@@ -170,7 +170,9 @@ module ActiveJob
         )
 
         # 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
@@ -232,7 +234,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|

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/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.7'
 end

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