postburner 1.0.0.pre.14 → 1.0.0.pre.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71c6a81826b32021b0f0083c1771b27423e1b25198d7c00669cbab1150c431e7
-  data.tar.gz: 26403dba984c15f4bad94d81f1f5833d6a6bb16c0bb216a236f6bcaf07c0d019
+  metadata.gz: 8e032f7d37f1680fe34a1402f8eb9f0b3ca61aa9231f6d540c35c3a919e3f58d
+  data.tar.gz: bd35338dd14bc499c4c7d9f57d30eff3902615cd72876f766f1e379f12baba77
 SHA512:
-  metadata.gz: bc088b5d6e5b36b514562635ee3ed75955dfe809efe981e3ddbdc47c5f5387715233b7eb0eec8b4e78f97cf715202beabb7f8b90df553c605eec058eee462a9c
-  data.tar.gz: 40dbfc6f0979226d5c67780ffe31c73700a6a7b7faf97bf8e7fd127a2c889e708db91835bc9389032191ae2fae6460f3cc1b21f28ee17a6a3f00dbc84c31fbea
+  metadata.gz: f207c1d4dd840bee6b00ad71de9cc1b774d9b2376f7f34125fcc3a164220a340badc6b1ef17931d3dc09a0bb78a09c66b1f1f9ffdf1ead3e9737c44a39fe9a29
+  data.tar.gz: e0212499c62223a87720462226660045585ac4bde21258eb54aeed9d85683c0c9652477a6cf5824bdffa7e30314efb1e1cbb9d146eae8ef3ade2202af73f2abe

data/README.md

@@ -2,24 +2,20 @@
 
 Fast Beanstalkd-backed job queue with **optional PostgreSQL records**.
 
-Depends on Beanstalkd, Postgres, ActiveRecord, and ActiveJob (1).
-
 Postburner provides dual-mode job execution:
 - **Fast jobs**: Fast execution via Beanstalkd
 - **Tracked jobs**: Audited jobs logs, timing, errors, and statistics
 
 Built for production environments where you want fast background processing for most jobs, but comprehensive auditing for critical operations.
 
-- **ActiveJob native** - Works seamlessly with Rails, ActionMailer, ActiveStorage
-- **Dual-mode execution** - Default or tracked (database backed)
-- **Rich audit trail** - Logs, timing, errors, retry tracking (tracked jobs only)
-- **ActiveRecord** - Query jobs with ActiveRecord (Tracked jobs only)
+- **ActiveJob Adapter** - To use with Rails, ActionMailer, ActiveStorage
+- **Dual-mode execution** - Beanstalkd only or tracked (database backed)
+- **Rich audit trail** - Logs, timing, errors, instrumentation, retry tracking (tracked jobs only)
+- **ActiveRecord** - Query jobs with ActiveRecord (on opt in)
 - **Scheduler** - Schedule jobs at fixed intervals, cron expressions, and calendar-aware anchor points.
-- **Beanstalkd** - Fast, reliable queue separate from your database, peristent storage
+- **Test-friendly** - Testing jobs can be tricky, so we go beyond just inline.
 - **Process isolation** - Forking workers with optional threading for throughput
-- **Test-friendly** - Inline execution without Beanstalkd in tests
-
-(1) An ActiveJob adapter is provided for seamless integration with the default Rails stack, you can use Postburner without ActiveJob by using the `Postburner::Job` class directly.
+- **Beanstalkd** - Fast, reliable queue separate from your database, persistent storage
 
 ```ruby
 # Default job (fast, no PostgreSQL overhead)
@@ -75,7 +71,7 @@ end
 # Scheduled job (fixed interval, anchor based)
 Postburner::Schedule.create!(
   name: 'daily_event_retention',
-  job_class: EventRetentionJob, # either Postburner::Job or ActiveJob
+  job_class: EventRetentionJob, # either Postburner::Job or ActiveJob ancestor
   anchor: Time.zone.parse('2025-01-01 09:30:00'),
   interval: 1,
   interval_unit: 'days',
@@ -101,6 +97,7 @@ bundle exec rake postburner:work WORKER=default
   - [Postburner::Job](#postburnerjob)
   - [Scheduler](#scheduler)
   - [Job Management](#job-management)
+- [Writing Jobs](#writing-jobs)
 - [Queue Strategies](#queue-strategies)
 - [Testing](#testing)
 - [Workers](#workers)
@@ -132,7 +129,7 @@ Postburner [beanstalkd](https://beanstalkd.github.io/) is used with PostgreSQL t
 
 ```ruby
 # Gemfile
-gem 'postburner', '~> 1.0.0.pre.11'
+gem 'postburner', '~> 1.0.0.pre.14'
 
 # config/application.rb
 config.active_job.queue_adapter = :postburner
@@ -140,28 +137,28 @@ config.active_job.queue_adapter = :postburner
 
 ```yaml
 # config/postburner.yml
-development:  # <- environment config, i.e. defaults
+development:  # <- environment config
   beanstalk_url: <%= ENV['BEANSTALK_URL'] || 'beanstalk://localhost:11300' %>
-  default_forks: 2
-  default_threads: 10
-  default_gc_limit: 500
+  forks: 2
+  threads: 10
+  gc_limit: 500
 
-  workers:  # <- worker config, i.e. overrides
+  workers:  # <- worker config (overrides env-level)
     default:
-      threads: 16        # Overrides default_threads
+      threads: 16        # Overrides env-level threads
       queues:
         - default
         - mailers
     critical:
-      forks: 4           # Overrides default_forks
-      threads: 8         # Overrides default_threads
-      gc_limit: 24       # Overrides default_gc_limit
+      forks: 4           # Overrides env-level forks
+      threads: 8         # Overrides env-level threads
+      gc_limit: 24       # Overrides env-level gc_limit
       queues:
         - payments
     slow:
-      forks: 4           # Overrides default_forks
-      threads: 1         # Overrides default_threads
-      gc_limit: 1        # Overrides default_gc_limit
+      forks: 4           # Overrides env-level forks
+      threads: 1         # Overrides env-level threads
+      gc_limit: 1        # Overrides env-level gc_limit
       queues:
         - imports
         - video
@@ -181,16 +178,45 @@ config.active_job.queue_adapter = :postburner
 #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
 ```
 
-## Usage
+### Enqueueing Jobs
 
-**Job Idempotency:** Jobs should be designed to be idempotent and safely re-runnable. Like all job queues, Postburner provides at-least-once delivery—in rare errant cases outside of Postburner's control, a job may be executed more than once, i.e. network issues, etc.
+```ruby
+# ActiveJob (standard Rails API)
+SendEmailJob.perform_later(user_id)                           # Enqueue immediately
+SendEmailJob.set(wait: 1.hour).perform_later(user_id)         # Delay by duration
+SendEmailJob.set(wait_until: Date.tomorrow.noon).perform_later(user_id)  # Run at specific time
+SendEmailJob.set(queue: 'critical').perform_later(user_id)    # Override queue
+SendEmailJob.set(priority: 0).perform_later(user_id)          # Override priority
+
+# Postburner::Job (always tracked, full API)
+job = ProcessPayment.create!(args: { 'payment_id' => 123 })
+job.queue!                                    # Enqueue immediately
+job.queue!(delay: 1.hour)                     # Delay by duration
+job.queue!(at: Date.tomorrow.noon)            # Run at specific time
+job.queue!(queue: 'critical')                 # Override queue
+job.queue!(priority: 0, ttr: 600)             # Set priority and TTR
+```
 
-**TTR (Time-to-Run):** If a job exceeds its TTR without completion, Beanstalkd releases it back to the queue while still running—causing duplicate execution. For long-running jobs, call `extend!` periodically to reset the TTR, or set a sufficiently high TTR value. You must include the `Postburner::Beanstalkd` or `Postburner::Tracked` module with `ActiveJob` to use `extend!`.
+### ActiveJob vs Postburner::Job TL;DR
+
+`Postburner::Job` as simple subclass of `ActiveRecord`, so the normal
+`ActiveRecord` API applies! Thus the workflow is to create an instance,
+then queue it!
+
+| Operation | ActiveJob | Postburner::Job |
+|-----------|-----------|-----------------|
+| **Enqueue immediately** | `MyJob.perform_later(args)` | `MyJob.create!(args: {}).queue!` |
+| **Delay** | `.set(wait: 1.hour)` | `job.queue!(delay: 1.hour)` |
+| **Run at** | `.set(wait_until: time)` | `job.queue!(at: time)` |
+| **Set queue** | `.set(queue: 'critical')` | `job.queue!(queue: 'critical')` |
+| **Set priority** | `.set(priority: 0)` | `job.queue!(priority: 0)` |
+| **Set TTR** | `.set(ttr: 300)` | `job.queue!(ttr: 300)` |
+
+## Usage
 
 ### Default Jobs
 
@@ -241,8 +267,8 @@ end
 ```
 
 **Configuration options:**
-- `queue_priority` - Beanstalkd priority (0-4294967295, lower = higher priority)
-- `queue_ttr` - Time-to-run in seconds before job times out
+- `priority` - Beanstalkd priority (0-4294967295, lower = higher priority)
+- `ttr` - Time-to-run in seconds before job times out
 
 Jobs without `Postburner::Beanstalkd` use defaults from `config/postburner.yml`:
 - `default_priority: 65536`
@@ -276,7 +302,7 @@ end
 
 Tracked jobs store full execution details in PostgreSQL, providing comprehensive audit trails (i.e. logging, timing, errors, retry tracking) for critical operations.
 
-**Note:** `Postburner::Tracked` automatically includes `Postburner::Beanstalkd`, giving you access to `queue_priority`, `queue_ttr`, `bk`, and `extend!`.
+**Note:** `Postburner::Tracked` automatically includes `Postburner::Beanstalkd`, giving you access to `priority`, `ttr`, `bk`, and `extend!`.
 
 ```ruby
 class ProcessPayment < ApplicationJob
@@ -339,7 +365,7 @@ job.duration  # Execution time in milliseconds
 job.lag       # Queue lag in milliseconds
 ```
 
-### Direct Postburner::Job Usage
+### Postburner::Job Usage
 
 Direct `Postburner::Job` subclasses are **always tracked**:
 
@@ -367,6 +393,15 @@ job.queue!(delay: 1.hour)
 job.queue!(at: 2.days.from_now)
 ```
 
+> **Note:** The `args` parameter in `perform(args)` is optional. It's a convenience accessor to `self.args`, which is stored in a JSONB column on the job record. You can omit the parameter and access args directly:
+>
+> ```ruby
+> def perform
+>   payment = Payment.find(self.args['payment_id'])
+>   # ...
+> end
+> ```
+
 #### Instance-Level Queue Configuration
 
 Override queue priority and TTR per job instance for dynamic behavior:
@@ -375,8 +410,8 @@ Override queue priority and TTR per job instance for dynamic behavior:
 # Set priority during creation
 job = ProcessPayment.create!(
   args: { 'payment_id' => 123 },
-  queue_priority: 1500,  # Override class-level priority
-  queue_ttr: 300         # Override class-level TTR
+  priority: 1500,  # Override class-level priority
+  ttr: 300         # Override class-level TTR
 )
 job.queue!
 
@@ -427,7 +462,7 @@ Postburner includes a lightweight, fixed-rate scheduler for recurring jobs. Perf
 The scheduler uses **immediate enqueue** combined with a **watchdog safety net**:
 
 1. When an execution is created, it's immediately enqueued to Beanstalkd's delayed queue with the appropriate delay until `run_at`
-2. For `Postburner::Job` and `ActiveJob` with `Postburner::Tracked` schedules the next execution when the current job runs - providing immediate pickup without waiting for the watchdog. Normal `ActiveJob` schedules need to rely on the watchdog to create the next execution, so set the `default_scheduler_interval` to pick up exections appropriately.
+2. For `Postburner::Job` and `ActiveJob` with `Postburner::Tracked` schedules the next execution when the current job runs - providing immediate pickup without waiting for the watchdog. Normal `ActiveJob` schedules need to rely on the watchdog to create the next execution, so set the `scheduler_interval` to pick up executions appropriately.
 3. A lightweight watchdog job in the `scheduler` tube acts as a safety net:
    ```json
    { "scheduler": true, "interval": 300 }
@@ -464,8 +499,8 @@ Add scheduler settings to `config/postburner.yml`:
 ```yaml
 production:
   beanstalk_url: <%= ENV['BEANSTALK_URL'] %>
-  default_scheduler_interval: 300  # Pickup new schedules every 5 minutes
-  default_scheduler_priority: 100  # Scheduler jobs run at priority 100
+  scheduler_interval: 300  # Pickup new schedules every 5 minutes
+  scheduler_priority: 100  # Scheduler jobs run at priority 100
 
   workers:
     default:
@@ -475,8 +510,8 @@ production:
 ```
 
 **Configuration options:**
-- `default_scheduler_interval` - How often (in seconds) to check for due schedules (default: 300)
-- `default_scheduler_priority` - Beanstalkd priority for watchdog jobs (default: 100)
+- `scheduler_interval` - How often (in seconds) to check for due schedules (default: 300)
+- `scheduler_priority` - Beanstalkd priority for watchdog jobs (default: 100)
 
 **Choosing an interval:** Since executions are enqueued immediately to Beanstalkd's delayed queue, the watchdog interval primarily affects:
 - How quickly new schedules are auto-bootstrapped (if you don't call `start!`)
@@ -636,8 +671,8 @@ schedule.next_run_at_times(5)  # Next 5 run times
 
 # View executions
 schedule.executions.pending
-schedule.executions.completed
-schedule.executions.failed
+schedule.executions.scheduled
+schedule.executions.skipped
 ```
 
 #### Starting Schedules
@@ -664,7 +699,7 @@ The job is immediately in Beanstalkd's delayed queue and will run at the schedul
 
 **Option 2: Auto-bootstrap (eventual pickup)**
 
-If you don't call `start!`, the scheduler watchdog will automatically bootstrap the schedule on its next run. This adds up to one `default_scheduler_interval` of delay before the first execution is enqueued:
+If you don't call `start!`, the scheduler watchdog will automatically bootstrap the schedule on its next run. This adds up to one `scheduler_interval` of delay before the first execution is enqueued:
 
 ```ruby
 schedule = Postburner::Schedule.create!(...)
@@ -683,10 +718,9 @@ Each scheduled run creates an execution record for tracking:
 ```ruby
 execution = Postburner::ScheduleExecution.find(123)
 
-execution.status        # pending, running, completed, failed, skipped
+execution.status        # pending, scheduled, skipped
 execution.run_at        # Scheduled time
 execution.enqueued_at   # When job was queued
-execution.completed_at  # When job finished
 execution.beanstalk_job_id  # Beanstalkd job ID
 execution.job_id            # Postburner::Job ID (if using Postburner::Job)
 ```
@@ -780,6 +814,14 @@ job.errata  # Array of exceptions with backtraces
 job.attempts # Array of attempt timestamps
 ```
 
+## Writing Jobs
+
+Pay attention to the following when writing jobs:
+
+**Job Idempotency:** Jobs should be designed to be idempotent and safely re-runnable. Like all job queues, Postburner provides at-least-once delivery—in rare errant cases outside of Postburner's control, a job may be executed more than once, i.e. network issues, etc.
+
+**TTR (Time-to-Run):** If a job exceeds its TTR without completion, Beanstalkd releases it back to the queue while still running—causing duplicate execution. For long-running jobs, call `extend!` periodically to reset the TTR, or set a sufficiently high TTR value. You must include the `Postburner::Beanstalkd` or `Postburner::Tracked` module with `ActiveJob` to use `extend!`.
+
 ## Queue Strategies
 
 Postburner uses different strategies to control job execution. These affect `Postburner::Job` subclasses (not ActiveJob classes).
@@ -905,25 +947,25 @@ Postburner uses named worker configurations to support different deployment patt
 Configure multiple named workers with different concurrency profiles:
 
 ```yaml
-production:  # <- environment config, i.e. defaults
+production:  # <- environment config
   beanstalk_url: <%= ENV['BEANSTALK_URL'] %>
-  default_forks: 2
-  default_threads: 10
-  default_gc_limit: 5000
+  forks: 2
+  threads: 10
+  gc_limit: 5000
 
-  workers:  # <- worker config, i.e. overrides
+  workers:  # <- worker config (overrides env-level)
     # Heavy, memory-intensive jobs - more processes, fewer threads
     imports:
-      forks: 4           # Overrides default_forks
-      threads: 1         # Overrides default_threads
-      gc_limit: 500      # Overrides default_gc_limit
+      forks: 4           # Overrides env-level forks
+      threads: 1         # Overrides env-level threads
+      gc_limit: 500      # Overrides env-level gc_limit
       queues:
         - imports
         - data_processing
 
     # General jobs - fewer processes, many threads
     general:
-      threads: 100       # Overrides default_threads (forks uses default_forks=2)
+      threads: 100       # Overrides env-level threads (forks uses env-level forks=2)
       queues:
         - default
         - mailers
@@ -957,12 +999,12 @@ development:  # <- environment config
 ```yaml
 staging:  # <- environment config
   beanstalk_url: beanstalk://localhost:11300
-  default_threads: 10
-  default_gc_limit: 5000
+  threads: 10
+  gc_limit: 5000
 
   workers:  # <- worker config
     default:
-      # Uses env defaults: default_threads=10, default_gc_limit=5000
+      # Uses env-level: threads=10, gc_limit=5000
       queues:
         - critical
         - default
@@ -971,25 +1013,25 @@ staging:  # <- environment config
 
 **Production (multiple workers with different profiles):**
 ```yaml
-production:  # <- environment config, i.e. defaults
+production:  # <- environment config
   beanstalk_url: <%= ENV['BEANSTALK_URL'] %>
-  default_forks: 2
-  default_threads: 10
-  default_gc_limit: 5000
+  forks: 2
+  threads: 10
+  gc_limit: 5000
 
-  workers:  # <- worker config, i.e. overrides
+  workers:  # <- worker config (overrides env-level)
     imports:
-      forks: 4           # Overrides default_forks (4 processes)
-      threads: 1         # Overrides default_threads (1 thread per process = 4 concurrent jobs)
-      gc_limit: 500      # Overrides default_gc_limit
+      forks: 4           # Overrides env-level forks (4 processes)
+      threads: 1         # Overrides env-level threads (1 thread per process = 4 concurrent jobs)
+      gc_limit: 500      # Overrides env-level gc_limit
       queues:
         - imports
         - data_processing
 
     general:
-      # forks uses default_forks=2 (2 processes)
-      threads: 100       # Overrides default_threads (100 threads per process = 200 concurrent jobs)
-      # gc_limit uses default_gc_limit=5000
+      # forks uses env-level forks=2 (2 processes)
+      threads: 100       # Overrides env-level threads (100 threads per process = 200 concurrent jobs)
+      # gc_limit uses env-level gc_limit=5000
       queues:
         - default
         - mailers
@@ -1148,8 +1190,8 @@ The `shutdown_timeout` controls how long workers wait for in-flight jobs to comp
 
 ```yaml
 production:
-  default_ttr: 300              # Default TTR for jobs
-  default_shutdown_timeout: 300 # Defaults to default_ttr if not specified
+  default_ttr: 300        # Default TTR for jobs
+  shutdown_timeout: 300   # Defaults to default_ttr if not specified
 
   workers:
     imports:
@@ -1164,7 +1206,7 @@ production:
 
 ### GC Limits
 
-Set `default_gc_limit` at environment level or `gc_limit` per worker to automatically restart after processing N jobs.
+Set `gc_limit` at environment level or per worker to automatically restart after processing N jobs.
 
 - Worker processes N jobs
 - Worker exits with code 99
@@ -1173,22 +1215,22 @@ Set `default_gc_limit` at environment level or `gc_limit` per worker to automati
 
 ```yaml
 production:  # <- environment config
-  default_forks: 2
-  default_threads: 10
-  default_gc_limit: 5000
+  forks: 2
+  threads: 10
+  gc_limit: 5000
 
   workers:  # <- worker config
     imports:
-      forks: 4           # Overrides default_forks
-      threads: 1         # Overrides default_threads
-      gc_limit: 500      # Overrides default_gc_limit (restart after 500 jobs, memory-intensive)
+      forks: 4           # Overrides env-level forks
+      threads: 1         # Overrides env-level threads
+      gc_limit: 500      # Overrides env-level gc_limit (restart after 500 jobs, memory-intensive)
       queues:
         - imports
         - data_processing
 
     general:
-      # Uses default_forks=2, default_threads=100, default_gc_limit=5000 (restart after 5000 jobs)
-      threads: 100       # Overrides default_threads
+      # Uses env-level forks=2, threads=100, gc_limit=5000 (restart after 5000 jobs)
+      threads: 100       # Overrides env-level threads
       queues:
         - default
         - mailers
@@ -1229,41 +1271,41 @@ test:  # <- environment config
 
 staging:  # <- environment config
   <<: *default
-  default_threads: 10      # Multi-threaded, single process
-  default_gc_limit: 5000
+  threads: 10      # Multi-threaded, single process
+  gc_limit: 5000
 
   workers:  # <- worker config
     default:
-      # Uses env defaults: default_threads=10, default_gc_limit=5000
+      # Uses env-level: threads=10, gc_limit=5000
       queues:
         - default
         - mailers
 
-production:  # <- environment config, i.e. defaults
+production:  # <- environment config
   <<: *default
-  default_forks: 2         # Default for workers
-  default_threads: 10      # Default for workers
-  default_gc_limit: 5000   # Default for workers
+  forks: 2         # Inherited by workers
+  threads: 10      # Inherited by workers
+  gc_limit: 5000   # Inherited by workers
 
-  workers:  # <- worker config, i.e. overrides
+  workers:  # <- worker config (overrides env-level)
     critical:
-      forks: 1             # Overrides default_forks
-      threads: 1           # Overrides default_threads (1 concurrent job)
-      gc_limit: 100        # Overrides default_gc_limit
+      forks: 1             # Overrides env-level forks
+      threads: 1           # Overrides env-level threads (1 concurrent job)
+      gc_limit: 100        # Overrides env-level gc_limit
       queues:
         - critical
 
     default:
-      forks: 4             # Overrides default_forks
-      threads: 10          # Overrides default_threads (40 total concurrent jobs: 4 × 10)
-      gc_limit: 1000       # Overrides default_gc_limit
+      forks: 4             # Overrides env-level forks
+      threads: 10          # Overrides env-level threads (40 total concurrent jobs: 4 × 10)
+      gc_limit: 1000       # Overrides env-level gc_limit
       queues:
         - default
 
     mailers:
-      # forks uses default_forks=2
-      threads: 5           # Overrides default_threads (10 total email senders: 2 × 5)
-      gc_limit: 500        # Overrides default_gc_limit
+      # forks uses env-level forks=2
+      threads: 5           # Overrides env-level threads (10 total email senders: 2 × 5)
+      gc_limit: 500        # Overrides env-level gc_limit
       queues:
         - mailers
 ```
@@ -1311,7 +1353,7 @@ 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.
+**Important:** No need to set `config.active_job.queue_name_prefix` - Postburner handles prefixing automatically when jobs are enqueued with postburner.
 
 ### Queue Configuration Methods
 
@@ -1534,16 +1576,16 @@ end
 
 Beanstalkd is a simple, fast, and reliable queue system. It is a good choice for production environments where you want fast background processing for most jobs, but comprehensive auditing for critical operations.
 
-The [protocol](https://github.com/beanstalkd/beanstalkd/blob/master/doc/protocol.txt) reads more like a README than a protocol. Check it out and you will instantly understand how it works. Here is a help
+The [protocol](https://github.com/beanstalkd/beanstalkd/blob/master/doc/protocol.txt) reads more like a README than a protocol. Check it out and you will instantly understand how it works.
 
-Here is a picture of the typical job lifecycle:
+Diagram of the typical job lifecycle:
 
 ```
    put            reserve               delete
   -----> [READY] ---------> [RESERVED] --------> *poof*`
 ```
 
-Here is a picture with more possibilities:
+Diagram with all lifecycle:
 
 ```
    put with delay               release with delay
@@ -1748,7 +1790,7 @@ end
 ```ruby
 class DataImport < Postburner::Job
   queue 'imports'
-  ttr 1800  # 30 minutes (equivalent to queue_ttr)
+  ttr 1800  # 30 minutes
 
   def perform(args)
     # Long-running import logic
@@ -1761,8 +1803,8 @@ end
 For jobs that may take longer than expected, you can extend the TTR dynamically using `extend!`. This calls Beanstalkd's `touch` command, which resets the TTR countdown.
 
 **Available for:**
-- `Postburner::Job` subclasses (always available via `bk.extend!`)
-- `Postburner::Tracked` ActiveJob classes (includes `extend!` method)
+- `Postburner::Job` subclasses (via `extend!` method)
+- `Postburner::Tracked` ActiveJob classes (via `extend!` method)
 
 ```ruby
 class ProcessImport < ApplicationJob
@@ -1799,7 +1841,7 @@ class LargeDataProcessor < Postburner::Job
     dataset.each_chunk do |chunk|
       process_chunk(chunk)
 
-      bk.extend!  # Reset TTR via beanstalkd job accessor
+      extend!  # Reset TTR (calls bk.touch internally)
       log "Chunk processed, TTR extended"
     end
   end
@@ -2000,7 +2042,7 @@ Postburner.connected do |conn|
 end
 ```
 
-## Web UI -- Dated
+## Web UI - v2 Coming Soon
 
 Mount the inspection interface:
 
@@ -2043,7 +2085,7 @@ beanstalkd -l 127.0.0.1 -p 11300 -b /var/lib/beanstalkd
 
 ```ruby
 # Gemfile
-gem 'postburner', '~> 1.0.0.pre.1'
+gem 'postburner', '~> 1.0.0.pre.14'
 ```
 
 ```bash
@@ -2094,7 +2136,7 @@ Key changes in v1.0:
 
 1. **Update Gemfile:**
    ```ruby
-   gem 'postburner', '~> 1.0.0.pre.1'
+   gem 'postburner', '~> 1.0.0.pre.14'
    ```
 
 2. **Remove Backburner config:**
@@ -2138,7 +2180,7 @@ We encourage AI tools, but do not vibe, as the code must look like it was writte
 ```bash
 bundle install
 bundle exec rails test # must have beanstalkd on 11300 by default
-bundle exec rails app:postburner:work # if you want to run the worker
+bundle exec rails app:postburner:work # run worker from engine root (uses test/dummy app)
 ```
 
 ## License

data/app/concerns/postburner/execution.rb

@@ -134,7 +134,7 @@ module Postburner
 
           run_callbacks :processing do
             begin
-              self.perform(args)
+              method(:perform).arity == 0 ? self.perform : self.perform(args)
             rescue Exception => exception
               self.persist_metadata!
               self.log! '[Postburner] Exception raised during perform prevented completion.'

data/app/concerns/postburner/insertion.rb

@@ -37,10 +37,12 @@ module Postburner
     # @param options [Hash] Queue options
     # @option options [Time, ActiveSupport::Duration] :at Absolute time to run the job
     # @option options [Integer, ActiveSupport::Duration] :delay Seconds to delay execution
-    # @option options [Integer] :pri Beanstalkd priority (lower = higher priority)
-    # @option options [Integer] :ttr Time-to-run in seconds before job times out
+    # @option options [Integer] :priority Priority (0-4294967295, 0 = HIGHEST), sets instance attribute
+    # @option options [Integer] :pri Beanstalkd priority (pass-through, for backwards compatibility)
+    # @option options [Integer] :ttr Time-to-run in seconds (1-4294967295, 0 is silently changed to 1)
+    # @option options [String] :queue Queue name override
     #
-    # @return [void]
+    # @return [true] on success (including if already queued)
     #
     # @raise [ActiveRecord::RecordInvalid] if job is not valid
     # @raise [AlreadyProcessed] if job was already processed
@@ -57,17 +59,25 @@ module Postburner
     #   job.queue!(at: '2025-01-15 09:00:00'.in_time_zone)
     #   job.queue!(at: Time.parse('2025-01-15 09:00:00 EST'))
     #
-    # @example Queue with priority
-    #   job.queue!(pri: 0, delay: 30.minutes)
+    # @example Queue with priority and TTR
+    #   job.queue!(priority: 0, ttr: 600)
+    #
+    # @example Queue to specific queue
+    #   job.queue!(queue: 'critical', delay: 30.minutes)
     #
     # @see #requeue!
     # @see Postburner.queue_strategy
     #
     def queue!(options={})
-      return if self.queued_at.present? && self.bkid.present?
+      return true if self.queued_at.present? && self.bkid.present?
       raise ActiveRecord::RecordInvalid, "Can't queue unless valid." unless self.valid?
       raise AlreadyProcessed, "Processed at #{self.processed_at}" if self.processed_at
 
+      # Extract and set instance-level overrides
+      self.priority = options.delete(:priority) if options.key?(:priority)
+      self.ttr = options.delete(:ttr) if options.key?(:ttr)
+      self.queue_name = options.delete(:queue) if options.key?(:queue)
+
       at = options.delete(:at)
       now = Time.current
 
@@ -86,6 +96,8 @@ module Postburner
       run_callbacks :enqueue do
         self.save!
       end
+
+      true
     end
 
     # Re-queues an existing job by removing it from Beanstalkd and queueing again.
@@ -96,10 +108,11 @@ module Postburner
     # @param options [Hash] Queue options (same as {#queue!})
     # @option options [Time, ActiveSupport::Duration] :at Absolute time to run the job
     # @option options [Integer, ActiveSupport::Duration] :delay Seconds to delay execution
-    # @option options [Integer] :pri Beanstalkd priority
-    # @option options [Integer] :ttr Time-to-run in seconds
+    # @option options [Integer] :priority Priority (0-4294967295, lower = higher priority)
+    # @option options [Integer] :ttr Time-to-run in seconds (1-4294967295)
+    # @option options [String] :queue Queue name override
     #
-    # @return [void]
+    # @return [true] on success
     #
     # @raise [ActiveRecord::RecordInvalid] if job is not valid
     # @raise [Beaneater::NotConnected] if Beanstalkd connection fails