postburner 0.7.2 → 0.9.0.rc.1

data/lib/postburner.rb

@@ -1,8 +1,317 @@
 require "postburner/version"
 require "postburner/engine"
+require "postburner/strategies/queue"
+require "postburner/strategies/nice_queue"
+require "postburner/strategies/test_queue"
+require "postburner/strategies/immediate_test_queue"
+require "postburner/strategies/null_queue"
 
+# Postburner - PostgreSQL-backed job queue system built on Backburner and Beanstalkd.
+#
+# Postburner is a Ruby on Rails Engine that provides a database-backed job queue with
+# full audit trails, inspection capabilities, and multiple execution strategies. Every
+# job is stored as an ActiveRecord model, enabling database queries, foreign key
+# relationships, and comprehensive statistics tracking.
+#
+# ## Core Concepts
+#
+# - **Jobs:** Subclass {Postburner::Job} and implement `perform` method
+# - **Queue Strategies:** Control how jobs are executed (async, inline, test modes)
+# - **Beanstalkd Integration:** Production queuing via Backburner
+# - **Database Persistence:** Full audit trail with timestamps, logs, and errors
+# - **Callbacks:** ActiveJob-style lifecycle hooks (enqueue, attempt, processing, processed)
+#
+# ## Queue Strategies
+#
+# Postburner uses a strategy pattern to control job execution:
+#
+# - **{NiceQueue}** (default): Async via Beanstalkd, gracefully handles premature execution
+# - **{Queue}**: Async via Beanstalkd, strict premature execution errors
+# - **{TestQueue}**: Inline/synchronous, requires explicit time travel for scheduled jobs
+# - **{ImmediateTestQueue}**: Inline/synchronous with automatic time travel
+# - **{NullQueue}**: Creates jobs without queueing, manual execution with time travel
+#
+# ## Auto-Detection
+#
+# Postburner automatically detects Rails test mode and switches to {TestQueue} when:
+# - `Rails.env.test?` is true
+# - `ActiveJob::Base.queue_adapter_name == :test`
+#
+# ## Usage
+#
+# @example Creating and queueing a job
+#   class ProcessPayment < Postburner::Job
+#     queue 'critical'
+#     queue_priority 0
+#
+#     def perform(args)
+#       payment = Payment.find(args['payment_id'])
+#       payment.process!
+#       log "Payment #{payment.id} processed"
+#     end
+#   end
+#
+#   job = ProcessPayment.create!(args: { 'payment_id' => 123 })
+#   job.queue!(delay: 1.hour)
+#
+# @example Switching queue strategies
+#   # Production with graceful premature handling (default)
+#   Postburner.nice_async_strategy!
+#
+#   # Production with strict premature errors
+#   Postburner.async_strategy!
+#
+#   # Test mode with explicit time control
+#   Postburner.inline_test_strategy!
+#
+#   # Test mode with automatic time travel
+#   Postburner.inline_immediate_test_strategy!
+#
+# @example Using Beanstalkd connection
+#   Postburner.connected do |conn|
+#     conn.tubes['my.tube'].stats
+#     conn.tubes['my.tube'].kick(3)
+#   end
+#
+# @example Checking if in test mode
+#   if Postburner.testing?
+#     # Jobs execute inline
+#   else
+#     # Jobs queued to Beanstalkd
+#   end
+#
+# @see Postburner::Job
+# @see NiceQueue
+# @see Queue
+# @see TestQueue
+# @see ImmediateTestQueue
+#
 module Postburner
+  # @!attribute [rw] queue_strategy
+  #   The current queue strategy class used for job execution.
+  #
+  #   Defaults to {NiceQueue} for production, auto-switches to {TestQueue}
+  #   in Rails test environment.
+  #
+  #   @return [Class] One of Queue, NiceQueue, TestQueue, or ImmediateTestQueue
+  #
+  #   @example
+  #     Postburner.queue_strategy
+  #     # => Postburner::NiceQueue
+  #
+  #   @see #nice_async_strategy!
+  #   @see #async_strategy!
+  #   @see #inline_test_strategy!
+  #   @see #inline_immediate_test_strategy!
+  #
+  mattr_accessor :queue_strategy
 
+  # Initialize with NiceQueue (production) by default
+  # NiceQueue re-inserts premature jobs with appropriate delay
+  self.queue_strategy = Postburner::NiceQueue
+
+  # Auto-detect Rails test mode and switch to TestQueue
+  if defined?(Rails) && Rails.env.test? && defined?(ActiveJob::Base)
+    if ActiveJob::Base.queue_adapter_name == :test
+      self.queue_strategy = Postburner::TestQueue
+    end
+  end
+
+  # Activates strict test mode with inline job execution.
+  #
+  # Sets queue strategy to {TestQueue}, which executes jobs synchronously
+  # without Beanstalkd. Scheduled jobs (with future run_at) raise
+  # {Postburner::Job::PrematurePerform} exception, forcing explicit time
+  # management with `travel_to`.
+  #
+  # Use this strategy when you want explicit control over time progression
+  # in tests and want to catch scheduling bugs by failing loudly.
+  #
+  # @return [void]
+  #
+  # @example
+  #   Postburner.inline_test_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!  # Executes immediately
+  #   assert job.reload.processed_at
+  #
+  # @example With scheduled jobs
+  #   Postburner.inline_test_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(delay: 1.hour)
+  #   # Raises PrematurePerform - use travel_to instead
+  #
+  # @see TestQueue
+  # @see #inline_immediate_test_strategy!
+  #
+  def self.inline_test_strategy!
+    self.queue_strategy = Postburner::TestQueue
+  end
+
+  # Activates test mode with automatic time travel for scheduled jobs.
+  #
+  # Sets queue strategy to {ImmediateTestQueue}, which executes jobs
+  # synchronously and automatically uses time travel for jobs with future
+  # run_at timestamps.
+  #
+  # Use this strategy for integration/feature tests where you want
+  # convenience over explicit time control.
+  #
+  # @return [void]
+  #
+  # @example
+  #   Postburner.inline_immediate_test_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(delay: 1.hour)
+  #   # Automatically travels to scheduled time and executes
+  #   assert job.reload.processed_at
+  #
+  # @note Jobs execute in queue order, not scheduled time order
+  # @note Requires ActiveSupport::Testing::TimeHelpers
+  #
+  # @see ImmediateTestQueue
+  # @see #inline_test_strategy!
+  #
+  def self.inline_immediate_test_strategy!
+    self.queue_strategy = Postburner::ImmediateTestQueue
+  end
+
+  # Activates strict production mode with asynchronous job execution.
+  #
+  # Sets queue strategy to {Queue}, which queues jobs to Beanstalkd and
+  # raises {Postburner::Job::PrematurePerform} if a job is executed before
+  # its scheduled run_at time.
+  #
+  # Use this strategy for production debugging or when you want strict
+  # enforcement of scheduling. For most production use cases, prefer
+  # {#nice_async_strategy!} instead.
+  #
+  # @return [void]
+  #
+  # @example
+  #   Postburner.async_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(delay: 1.hour)
+  #   # Queued to Beanstalkd, will raise if picked up early
+  #
+  # @note Requires Beanstalkd server running
+  # @note NOT the default production strategy
+  #
+  # @see Queue
+  # @see #nice_async_strategy!
+  #
+  def self.async_strategy!
+    self.queue_strategy = Postburner::Queue
+  end
+
+  # Activates default production mode with graceful premature handling.
+  #
+  # Sets queue strategy to {NiceQueue} (the default), which queues jobs to
+  # Beanstalkd and gracefully handles premature execution by re-inserting
+  # jobs with appropriate delay.
+  #
+  # This is the recommended production strategy and is set by default on
+  # initialization.
+  #
+  # @return [void]
+  #
+  # @example
+  #   Postburner.nice_async_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(delay: 1.hour)
+  #   # Queued to Beanstalkd, automatically re-inserted if picked up early
+  #
+  # @note This is the DEFAULT strategy
+  # @note Requires Beanstalkd server running
+  #
+  # @see NiceQueue
+  # @see #async_strategy!
+  #
+  def self.nice_async_strategy!
+    self.queue_strategy = Postburner::NiceQueue
+  end
+
+  # Activates null mode for creating jobs without queueing to Beanstalkd.
+  #
+  # Sets queue strategy to {NullQueue}, which creates job records in the
+  # database but does NOT queue them to Beanstalkd. Jobs can be executed
+  # later by manually calling {NullQueue.handle_perform!}, which includes
+  # automatic time travel for scheduled jobs.
+  #
+  # Use this strategy for deferred batch processing, conditional execution,
+  # or scenarios where you want to create jobs in advance and execute them
+  # manually on-demand.
+  #
+  # @return [void]
+  #
+  # @example Create job without queueing
+  #   Postburner.null_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!
+  #   # Job created but NOT queued to Beanstalkd
+  #   job.bkid  # => nil
+  #
+  # @example Manually execute later
+  #   Postburner.null_strategy!
+  #   job = MyJob.create!(args: {})
+  #   job.queue!(delay: 1.hour)
+  #   # Later, manually execute with automatic time travel
+  #   Postburner::Job.perform(job.id)
+  #   # Job executes as if it's 1 hour in the future
+  #
+  # @note Jobs execute when manually triggered via Postburner::Job.perform
+  # @note Does not require Beanstalkd to be running
+  # @note Useful for batch processing and deferred execution patterns
+  #
+  # @see NullQueue
+  # @see Postburner::Job.perform
+  #
+  def self.null_strategy!
+    self.queue_strategy = Postburner::NullQueue
+  end
+
+  # Checks if currently using a test queue strategy.
+  #
+  # Returns true if the current queue strategy is {TestQueue} or
+  # {ImmediateTestQueue}, indicating that jobs execute inline/synchronously
+  # without Beanstalkd.
+  #
+  # @return [Boolean] true if using test strategy, false if using production strategy
+  #
+  # @example
+  #   Postburner.nice_async_strategy!
+  #   Postburner.testing?  # => false
+  #
+  #   Postburner.inline_test_strategy!
+  #   Postburner.testing?  # => true
+  #
+  # @see TestQueue
+  # @see ImmediateTestQueue
+  #
+  def self.testing?
+    queue_strategy.testing
+  end
+
+  # Returns a cached Beanstalkd connection.
+  #
+  # Creates a new {Backburner::Connection} using the configured Beanstalkd
+  # URL and caches it. Automatically reconnects if the connection is stale.
+  #
+  # For most use cases, prefer {#connected} which handles connection cleanup.
+  #
+  # @return [Backburner::Connection] Beanstalkd connection object
+  #
+  # @raise [Beaneater::NotConnected] if connection fails
+  #
+  # @example
+  #   conn = Postburner.connection
+  #   conn.tubes['my.tube'].stats
+  #
+  # @note Connection is cached in @_connection instance variable
+  # @note Automatically reconnects if connection is not active
+  #
+  # @see #connected
+  #
   def self.connection
     @_connection ||= Backburner::Connection.new(
       Backburner.configuration.beanstalk_url
@@ -11,6 +320,41 @@ module Postburner
     @_connection
   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.
+  #
+  # @overload connected
+  #   Returns the cached Beanstalkd connection.
+  #   @return [Backburner::Connection] Beanstalkd connection
+  #
+  # @overload connected {|conn| ... }
+  #   Yields connection and ensures cleanup.
+  #   @yieldparam conn [Backburner::Connection] Beanstalkd connection
+  #   @return [void]
+  #
+  # @example With block (recommended)
+  #   Postburner.connected do |conn|
+  #     conn.tubes.to_a.each do |tube|
+  #       puts tube.name
+  #     end
+  #   end
+  #   # Connection automatically closed
+  #
+  # @example Without block
+  #   conn = Postburner.connected
+  #   conn.tubes['my.tube'].stats
+  #
+  # @example Direct tube operations
+  #   Postburner.connected do |conn|
+  #     conn.tubes['critical'].kick(10)
+  #     conn.tubes['background'].stats
+  #   end
+  #
+  # @see #connection
+  #
   def self.connected
     if block_given?
       begin
@@ -23,6 +367,21 @@ module Postburner
     end
   end
 
+  # Removes all jobs from all tubes (not yet implemented).
+  #
+  # This is a destructive operation intended for development/testing cleanup.
+  # Requires confirmation string "CONFIRM" to prevent accidental execution.
+  #
+  # @param confirm [String] Must be exactly "CONFIRM" to execute
+  #
+  # @return [void]
+  #
+  # @example
+  #   Postburner.remove_all!("CONFIRM")
+  #
+  # @note Currently a no-op - implementation pending
+  # @todo Implement job removal from all tubes
+  #
   def self.remove_all!(confirm)
     return unless confirm == "CONFIRM"
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.9.0.rc.1
 platform: ruby
 authors:
 - Matt Smith
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-30 00:00:00.000000000 Z
+date: 2025-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: backburner
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.2.3
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: haml-rails
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +92,7 @@ files:
 - Rakefile
 - app/assets/config/postburner_manifest.js
 - app/assets/stylesheets/postburner/application.css
+- app/concerns/postburner/callbacks.rb
 - app/controllers/postburner/application_controller.rb
 - app/controllers/postburner/jobs_controller.rb
 - app/controllers/postburner/static_controller.rb
@@ -98,6 +112,12 @@ files:
 - lib/generators/postburner/install/templates/migrations/create_postburner_jobs.rb.erb
 - lib/postburner.rb
 - lib/postburner/engine.rb
+- lib/postburner/strategies/immediate_test_queue.rb
+- lib/postburner/strategies/nice_queue.rb
+- lib/postburner/strategies/null_queue.rb
+- lib/postburner/strategies/queue.rb
+- lib/postburner/strategies/test_queue.rb
+- lib/postburner/time_helpers.rb
 - lib/postburner/version.rb
 - lib/tasks/postburner_tasks.rake
 homepage: https://gitlab.nearapogee.com/opensource/postburner
@@ -107,7 +127,6 @@ metadata:
   homepage_uri: https://gitlab.nearapogee.com/opensource/postburner
   source_code_uri: https://gitlab.nearapogee.com/opensource/postburner
   changelog_uri: https://gitlab.nearapogee.com/opensource/postburner/-/blob/master/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -122,8 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Postgres backed beanstalkd queue via backburner
 test_files: []