postburner 1.0.0.pre.11 → 1.0.0.pre.12

data/README.md

@@ -1,6 +1,8 @@
 # Postburner
 
-Fast Beanstalkd-backed job queue with **optional PostgreSQL records** for ActiveJob.
+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
@@ -8,11 +10,20 @@ Postburner provides dual-mode job execution:
 
 Built for production environments where you want fast background processing for most jobs, but comprehensive auditing for critical operations.
 
-Depends on Beanstalkd, ActiveRecord, ActiveJob, Postgres.
+- **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)
+- **Scheduler** - Schedule jobs at fixed intervals, cron expressions, and calendar-aware anchor points.
+- **Beanstalkd** - Fast, reliable queue separate from your database, peristent storage
+- **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.
 
 ```ruby
 # Default job (fast, no PostgreSQL overhead)
-class SendSms < ApplicationJob
+class SendSmsJob < ApplicationJob # i.e. ActiveJob
   def perform(user_id)
     user = User.find(user_id)
     TextMessage.welcome(
@@ -23,7 +34,7 @@ class SendSms < ApplicationJob
 end
 
 # Default job with Beanstalkd configuration
-class DoSomething < ApplicationJob
+class DoSomethingJob < ApplicationJob # i.e. ActiveJob
   include Postburner::Beanstalkd # optional, allow access to beanstalkd
 
   priority 5000 # 0=highest, 65536=default, can set per job
@@ -35,7 +46,7 @@ class DoSomething < ApplicationJob
 end
 
 # Tracked job (full audit trail, includes Beanstalkd automatically)
-class ProcessPayment < ApplicationJob
+class ProcessPaymentJob < ApplicationJob # i.e. ActiveJob
   include Postburner::Tracked  # ← Opt-in to tracking (includes Beanstalkd)
 
   priority 0  # Highest priority
@@ -48,6 +59,31 @@ class ProcessPayment < ApplicationJob
   end
 end
 
+# Native Postburner::Job (always tracked, full api)
+class RunReportJob < Postburner::Job
+  queue 'critical'
+  priority 0
+  max_retries 0
+
+  def perform(args)
+    report = Report.find(args['report_id'])
+    report.run!
+    log "Ran report #{report.id}"
+  end
+end
+
+# Scheduled job (fixed interval, anchor based)
+Postburner::Schedule.create!(
+  name: 'daily_event_retention',
+  job_class: EventRetentionJob, # either Postburner::Job or ActiveJob
+  anchor: Time.zone.parse('2025-01-01 09:30:00'),
+  interval: 1,
+  interval_unit: 'days',
+  timezone: 'America/New_York',
+  catch_up: false,
+  args: { retention_days: 30 }
+)
+
 # Run worker (bin/postburner)
 bundle exec postburner --worker default
 
@@ -55,36 +91,49 @@ bundle exec postburner --worker default
 bundle exec rake postburner:work WORKER=default
 ```
 
+## Table of Contents
+
+- [Why](#why)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Standard Jobs](#standard-jobs)
+  - [Tracked Jobs](#tracked-jobs)
+  - [Postburner::Job](#postburnerjob)
+  - [Scheduler](#scheduler)
+  - [Job Management](#job-management)
+- [Queue Strategies](#queue-strategies)
+- [Testing](#testing)
+- [Workers](#workers)
+- [Configuration](#configuration)
+- [Callbacks](#callbacks)
+- [Instrumentation](#instrumentation)
+- [Why Beanstalkd?](#why-beanstalkd)
+- [Beanstalkd Integration](#beanstalkd-integration)
+- [Installation](#installation)
+- [Deployment](#deployment)
+- [Web UI](#web-ui)
+
 ## Why
 
-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 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.
 
 Postburner is inspired by the [Backburner](https://github.com/nesquena/backburner) gem i.e. "burner", Postgres i.e. "Post", and the database backends (SolidQueue, Que, etc), and the in memory/redis backends (Sidekiq, Resque, etc). And puma's concurrency model.
 
-Thus old-school [beanstalkd](https://beanstalkd.github.io/) is used with PostgreSQL to cover all the cases we care about.
+Postburner [beanstalkd](https://beanstalkd.github.io/) is used with PostgreSQL to cover all the cases we care about.
 - Fast when you want it (light, ephemeral jobs like delayed turbo_stream rendering, communications)
-- Tracked when you need it (critical operations like payments, and processes.
+- Tracked when you need it critical operations like payments, and processes.
 - Able to record jobs before and after execution in PostgreSQL, with foreign keys and constraints.
 - Store the jobs outside of the database, but also persist them to disk for disaster recovery (beanstalkd binlogs)
+- Schedule jobs at fixed intervals, cron expressions, and calendar-aware anchor points.
 - Introspect the jobs either with ActiveRecord or Beanstalkd.
 - Only one worker type, that can be single/multi-process, with optional threading, and optional GC (Garbage Collection) limits (kill fork after processing N jobs).
 - Easy testing.
 
-## Features
-
-- **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)
-- **Beanstalkd** - Fast, reliable queue separate from your database, peristent storage
-- **Process isolation** - Forking workers with optional threading for throughput
-- **Test-friendly** - Inline execution without Beanstalkd in tests
-
 ## Quick Start
 
 ```ruby
 # Gemfile
-gem 'postburner', '~> 1.0.0.pre.3'
+gem 'postburner', '~> 1.0.0.pre.11'
 
 # config/application.rb
 config.active_job.queue_adapter = :postburner
@@ -138,174 +187,189 @@ bundle exec postburner           # start with bin/postburner
 bundle exec rake postburner:work # or with rake task
 ```
 
-## Table of Contents
+## Usage
 
-- [Why Beanstalkd?](#why-beanstalkd)
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Standard Jobs](#standard-jobs)
-  - [Tracked Jobs](#tracked-jobs)
-  - [Postburner::Job](#postburnerjob)
-- [Workers](#workers)
-- [Configuration](#configuration)
-- [Queue Strategies](#queue-strategies)
-- [Testing](#testing)
-- [Job Management](#job-management)
-- [Beanstalkd Integration](#beanstalkd-integration)
-- [Web UI](#web-ui)
+**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.
 
-## Why Beanstalkd?
+**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!`.
 
-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.
+### Default Jobs
 
-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
+Default jobs execute quickly via Beanstalkd without PostgreSQL overhead. Perfect for emails, cache warming, notifications, etc.
 
-Here is a picture of the typical job lifecycle:
+```ruby
+class SendWelcomeEmail < ApplicationJob
+  queue_as :mailers
 
-```
-   put            reserve               delete
-  -----> [READY] ---------> [RESERVED] --------> *poof*`
-```
+  def perform(user_id)
+    UserMailer.welcome(user_id).deliver_now
+  end
+end
 
-Here is a picture with more possibilities:
+# Enqueue immediately
+SendWelcomeEmail.perform_later(123)
 
-```
-   put with delay               release with delay
-  ----------------> [DELAYED] <------------.
-                        |                   |
-                        | (time passes)     |
-                        |                   |
-   put                  v     reserve       |       delete
-  -----------------> [READY] ---------> [RESERVED] --------> *poof*
-                       ^  ^                |  |
-                       |   \  release      |  |
-                       |    `-------------'   |
-                       |                      |
-                       | kick                 |
-                       |                      |
-                       |       bury           |
-                    [BURIED] <---------------'
-                       |
-                       |  delete
-                        `--------> *poof*
+# Enqueue with delay
+SendWelcomeEmail.set(wait: 1.hour).perform_later(123)
+
+# Enqueue at specific time
+SendWelcomeEmail.set(wait_until: Date.tomorrow.noon).perform_later(123)
 ```
 
-### Binlogs
+**Overview:**
+- Fast execution (no database writes)
+- Low overhead
+- Standard ActiveJob retry_on/discard_on support
+- No audit trail
+- No logging or statistics
 
-Beanstalkd lets you persist jobs to disk in case of a crash or restart. Just restart beanstalkd and the jobs will be back in the queue.
+#### Configuring Beanstalkd Priority and TTR
 
-```bash
-# Create binlog directory
-sudo mkdir -p /var/lib/beanstalkd
-sudo chown beanstalkd:beanstalkd /var/lib/beanstalkd  # If running as service
+For default jobs that need custom Beanstalkd configuration, include `Postburner::Beanstalkd`:
 
-# Start beanstalkd with binlog persistence
-beanstalkd -l 127.0.0.1 -p 11300 -b /var/lib/beanstalkd
+```ruby
+class SendWelcomeEmail < ApplicationJob
+  include Postburner::Beanstalkd
+
+  queue_as :mailers
+  priority 100    # Lower = higher priority (0 is highest)
+  ttr 300         # Time-to-run in seconds (5 minutes)
+
+  def perform(user_id)
+    UserMailer.welcome(user_id).deliver_now
+  end
+end
 ```
 
-**Other options:**
+**Configuration options:**
+- `queue_priority` - Beanstalkd priority (0-4294967295, lower = higher priority)
+- `queue_ttr` - Time-to-run in seconds before job times out
 
-```bash
-# Basic persistence
-beanstalkd -b /var/lib/beanstalkd
+Jobs without `Postburner::Beanstalkd` use defaults from `config/postburner.yml`:
+- `default_priority: 65536`
+- `default_ttr: 300`
 
-# With custom binlog file size (default varies)
-beanstalkd -b /var/lib/beanstalkd -s 10485760  # 10MB per binlog file
+### Tracked Jobs
 
-# Reduce fsync frequency for better performance (trades safety for speed)
-beanstalkd -b /var/lib/beanstalkd -f 200  # fsync at most every 200ms (default: 50ms)
+Tracked jobs store full execution details in PostgreSQL, providing comprehensive audit trails (i.e. logging, timing, errors, retry tracking) for critical operations.
 
-# Never fsync (maximum performance, higher risk of data loss on power failure)
-beanstalkd -b /var/lib/beanstalkd -F
-```
+**Note:** `Postburner::Tracked` automatically includes `Postburner::Beanstalkd`, giving you access to `queue_priority`, `queue_ttr`, `bk`, and `extend!`.
 
-**Beanstalkd switches:**
-- `-b <dir>` - Enable binlog persistence in specified directory
-- `-s <bytes>` - Maximum size of each binlog file (requires `-b`)
-- `-f <ms>` - Call fsync at most once every N milliseconds (requires `-b`, default: 50ms)
-- `-F` - Never call fsync (requires `-b`, maximum performance but higher data loss risk)
+```ruby
+class ProcessPayment < ApplicationJob
+  include Postburner::Tracked  # ← Opt-in to PostgreSQL tracking (includes Beanstalkd)
 
-**Note:** The fsync options control the trade-off between performance and safety. A power failure could result in loss of jobs added within the fsync interval.
+  queue_as :critical
+  priority 0              # Highest priority (Beanstalkd included automatically)
+  ttr 600                 # 10 minute timeout
+  retry_on StandardError, wait: :exponentially_longer, attempts: 5
 
-### Priority
+  def perform(payment_id)
+    payment = Payment.find(payment_id)
 
-Priority controls the order in which jobs are processed from the queue. Beanstalkd always processes the highest priority (lowest number) jobs first.
+    log "Starting payment processing for $#{payment.amount}"
 
-**Priority Range:** 0 to 4,294,967,295 (unsigned 32-bit integer)
-- `0` = Highest priority (processed first)
-- `4,294,967,295` = Lowest priority (processed last)
-- Default: `65536` (configurable in `config/postburner.yml`)
+    begin
+      payment.charge!
+      log! "Payment charged successfully"
+    rescue PaymentError => e
+      log_exception!(e)
+      raise
+    end
 
-When a worker reserves a job, Beanstalkd returns the highest priority job available in the tube. Jobs with the same priority are processed in FIFO order.
+    log "Payment complete", level: :info
+  end
+end
+```
 
-**ActiveJob with Postburner::Beanstalkd:**
+**Tracking provides:**
+- Complete execution history (queued_at, processing_at, processed_at)
+- Custom logs with `log` and `log!`
+- Exception tracking with `log_exception()` and `log_exception!()`
+- Timing statistics (lag, duration)
+- Retry attempts tracking
+- Query with ActiveRecord
+- Foreign key relationships
+- Beanstalkd operations via `bk` accessor
+- TTR extension via `extend!` method
+
+**Query tracked jobs:**
 
 ```ruby
-class ProcessPayment < ApplicationJob
-  include Postburner::Beanstalkd
+# Find by state
+Postburner::TrackedJob.where(processed_at: nil)
+Postburner::TrackedJob.where.not(removed_at: nil)
 
-  queue_as :critical
-  priority 0  # Highest priority - processed immediately
-end
+# Find with errors
+Postburner::TrackedJob.where("error_count > 0")
 
-class SendEmail < ApplicationJob
-  include Postburner::Beanstalkd
+# Statistics
+Postburner::TrackedJob.average(:duration)  # Average execution time
+Postburner::TrackedJob.maximum(:lag)       # Worst lag
 
-  queue_as :mailers
-  priority 1000  # Lower priority - processed after critical jobs
-end
+# Inspect execution
+job = Postburner::TrackedJob.last
+job.logs      # Array of log entries with timestamps
+job.errata    # Array of exceptions with backtraces
+job.attempts  # Array of attempt timestamps
+job.duration  # Execution time in milliseconds
+job.lag       # Queue lag in milliseconds
 ```
 
-**Postburner::Job:**
+### Direct Postburner::Job Usage
+
+Direct `Postburner::Job` subclasses are **always tracked**:
 
 ```ruby
-class CriticalJob < Postburner::Job
+class ProcessPayment < Postburner::Job
   queue 'critical'
-  priority 0  # Highest priority
+  priority 0
+  max_retries 0
 
   def perform(args)
-    # Critical business logic
+    payment = Payment.find(args['payment_id'])
+    payment.process!
+    log "Processed payment #{payment.id}"
   end
 end
 
-class BackgroundTask < Postburner::Job
-  queue 'default'
-  priority 5000  # Lower priority
+# Create and enqueue
+job = ProcessPayment.create!(args: { 'payment_id' => 123 })
+job.queue!
 
-  def perform(args)
-    # Non-urgent background work
-  end
-end
+# With delay
+job.queue!(delay: 1.hour)
+
+# At specific time
+job.queue!(at: 2.days.from_now)
 ```
 
-**Recommended Priority Ranges:**
+#### Instance-Level Queue Configuration
 
-| Priority Range | Use Case | Examples |
-|---------------|----------|----------|
-| 0-256 | Critical business operations | Payments, transactions, real-time notifications |
-| 256-4096 | High priority tasks | Password resets, order confirmations |
-| 4096-65536 | Standard background jobs | Email sending, data exports (65536 is default) |
-| 65536-262144 | Low priority maintenance | Cache warming, log cleanup |
-| 262144+ | Deferred/bulk operations | Analytics, batch reports |
+Override queue priority and TTR per job instance for dynamic behavior:
 
-**Configuration:**
-
-Set default priority in `config/postburner.yml`:
-
-```yaml
-production:
-  default_priority: 65536  # Default for jobs without explicit priority
-  default_ttr: 300
-```
+```ruby
+# 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
+)
+job.queue!
 
-**Dynamic Priority (Postburner::Job only):**
+# Set dynamically after creation
+job = ProcessPayment.create!(args: { 'payment_id' => 456 })
+job.priority = 2000
+job.ttr = 300
+job.queue!
 
-```ruby
+# Use in before_enqueue callback for conditional behavior
 class ProcessOrder < Postburner::Job
   queue 'orders'
-  priority 100  # Default
+  priority 100   # Default priority
+  ttr 120  # Default TTR
 
-  before_enqueue :adjust_priority
+  before_enqueue :set_priority_based_on_urgency
 
   def perform(args)
     order = Order.find(args['order_id'])
@@ -314,433 +378,474 @@ class ProcessOrder < Postburner::Job
 
   private
 
-  def adjust_priority
-    if args['urgent']
-      self.priority = 0  # Override to highest priority
+  def set_priority_based_on_urgency
+    if args['express_shipping']
+      self.priority = 0    # High priority for express orders
+      self.ttr = 600       # Allow 10 minutes to complete
+    else
+      self.priority = 1000 # Low priority for standard orders
+      self.ttr = 120       # Standard 2 minute timeout
     end
   end
 end
 
-# Usage
-ProcessOrder.create!(args: { 'order_id' => 123, 'urgent' => true }).queue!
+# Express order gets high priority automatically
+ProcessOrder.create!(args: { 'order_id' => 789, 'express_shipping' => true }).queue!
 ```
 
-### Time to Run (TTR)
+**Overview:**
+- Same as Tracked jobs
+- Access the ActiveRecord Postburner::Job directly.
 
-TTR (Time-to-Run) is the maximum duration in seconds that a worker has to process a reserved job before Beanstalkd automatically releases it back to the ready queue.
+### Scheduler
 
-1. Worker reserves a job from Beanstalkd
-2. TTR countdown begins immediately upon reservation
-3. If job completes within TTR, worker deletes/buries the job (success)
-4. If TTR expires before completion, Beanstalkd automatically releases the job back to ready queue
-5. Another worker can then reserve and process the same job
+Postburner includes a lightweight, fixed-rate scheduler for recurring jobs. Perfect for daily reports, weekly cleanups, or any task that needs to run on a predictable schedule.
 
-This mechanism protects against workers crashing or hanging—jobs won't be stuck indefinitely.
+The scheduler uses **immediate enqueue** combined with a **watchdog safety net**:
 
-**TTR Range:** 1 to 4,294,967,295 seconds (unsigned 32-bit integer)
-- Minimum: `1` second (Beanstalkd silently increases 0 to 1)
-- Default: `300` seconds (5 minutes, configurable in `config/postburner.yml`)
+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.
+3. A lightweight watchdog job in the `scheduler` tube acts as a safety net:
+   ```json
+   { "scheduler": true, "interval": 300 }
+   ```
+4. When a worker reserves the watchdog, it instantiates `Postburner::Scheduler` which:
+   - Acquires a PostgreSQL advisory lock for coordination
+   - Auto-bootstraps any unstarted schedules
+   - Ensures each schedule has a future execution queued
+   - Re-queues a new watchdog with delay for the next interval
 
-**ActiveJob with Postburner::Beanstalkd:**
+NOTE: The watchdog is ephemeral data in Beanstalkd, not a database record. `Postburner::Scheduler` is the handler class that does the work. This design requires no dedicated scheduler process - existing workers handle everything.
 
 ```ruby
-class ProcessPayment < ApplicationJob
-  include Postburner::Beanstalkd
-
-  queue_as :critical
-  priority 0
-  ttr 300  # 5 minutes to complete
-end
-
-class QuickEmail < ApplicationJob
-  include Postburner::Beanstalkd
+# Create a schedule for a daily report at 9:30 AM
+Postburner::Schedule.create!(
+  name: 'daily_metrics',
+  job_class: 'GenerateMetricsReportJob',
+  anchor: Time.zone.parse('2025-01-01 09:30:00'),
+  interval: 1,
+  interval_unit: 'days',
+  timezone: 'America/New_York',
+  args: { report_type: 'daily' }  # Passed as keyword args to perform(report_type:)
+)
+```
 
-  queue_as :mailers
-  ttr 60  # 1 minute for fast email jobs
-end
+The `args` hash is passed to each job execution. For ActiveJob classes, hash args become keyword arguments (`perform(report_type:)`). For `Postburner::Job` subclasses, args are passed as a hash to `perform(args)`.
 
-class LongRunningReport < ApplicationJob
-  include Postburner::Beanstalkd
+The scheduler automatically creates executions and enqueues jobs at the scheduled times.
 
-  queue_as :reports
-  ttr 3600  # 1 hour for complex reports
-end
-```
+### Configuration
 
-**Postburner::Job:**
+Add scheduler settings to `config/postburner.yml`:
 
-```ruby
-class DataImport < Postburner::Job
-  queue 'imports'
-  ttr 1800  # 30 minutes (equivalent to queue_ttr)
+```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
 
-  def perform(args)
-    # Long-running import logic
-  end
-end
+  workers:
+    default:
+      queues:
+        - default
+        - mailers
 ```
 
-**Extending TTR with `extend!` (Touch Command):**
-
-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)
+**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)
 
-```ruby
-class ProcessImport < ApplicationJob
-  include Postburner::Tracked  # Includes Beanstalkd and enables extend!
+**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!`)
+- Recovery time if an execution somehow fails to enqueue
+- How often `last_audit_at` is updated for monitoring
 
-  queue_as :imports
-  ttr 300  # 5 minutes initial TTR
+For most use cases, the default 300 seconds is appropriate. Lower values increase database queries without significant benefit since jobs are already queued in Beanstalkd.
 
-  def perform(file_id)
-    file = ImportFile.find(file_id)
+**No manual setup required:** Workers automatically watch the `scheduler` tube and create the watchdog job if one doesn't exist. Just start your workers and create schedules - the rest happens automatically.
 
-    file.each_batch(size: 100) do |batch|
-      batch.each do |row|
-        process_row(row)
-      end
+#### Creating Schedules
 
-      extend!  # Reset TTR to 300 seconds from now
-      log "Processed batch, extended TTR"
-    end
-  end
-end
-```
+##### Anchor-Based Scheduling (Recommended)
 
-**For Postburner::Job (via `bk` accessor):**
+Use an anchor time plus interval for predictable, drift-free scheduling:
 
 ```ruby
-class LargeDataProcessor < Postburner::Job
-  queue 'processing'
-  ttr 600  # 10 minutes
+# Every day at 9:00 AM Eastern
+Postburner::Schedule.create!(
+  name: 'daily_cleanup',
+  job_class: 'CleanupJob',
+  anchor: Time.zone.parse('2025-01-01 09:00:00'),
+  interval: 1,
+  interval_unit: 'days',
+  timezone: 'America/New_York'
+)
 
-  def perform(args)
-    dataset = Dataset.find(args['dataset_id'])
+# Every 6 hours starting from midnight
+Postburner::Schedule.create!(
+  name: 'sync_data',
+  job_class: 'DataSyncJob',
+  anchor: Time.zone.parse('2025-01-01 00:00:00'),
+  interval: 6,
+  interval_unit: 'hours',
+  timezone: 'UTC'
+)
 
-    dataset.each_chunk do |chunk|
-      process_chunk(chunk)
+# Weekly on Saturday at 2:00 AM
+Postburner::Schedule.create!(
+  name: 'weekly_report',
+  job_class: 'WeeklyReportJob',
+  anchor: Time.zone.parse('2025-01-04 02:00:00'),  # A Saturday
+  interval: 1,
+  interval_unit: 'weeks',
+  timezone: 'America/Los_Angeles'
+)
 
-      bk.extend!  # Reset TTR via beanstalkd job accessor
-      log "Chunk processed, TTR extended"
-    end
-  end
-end
+# Monthly on the 1st at midnight
+Postburner::Schedule.create!(
+  name: 'monthly_billing',
+  job_class: 'MonthlyBillingJob',
+  anchor: Time.zone.parse('2025-01-01 00:00:00'),
+  interval: 1,
+  interval_unit: 'months',
+  timezone: 'UTC'
+)
 ```
 
-**`extend!` and Beanstalkd `touch`**
+**Available interval units:** `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `years`
 
-- Calls Beanstalkd's `touch` command on the reserved job
-- Resets the TTR countdown to the original TTR value from the current moment
-- Example: Job has `ttr 300`. After 200 seconds, calling `extend!` gives you another 300 seconds (not just 100)
-- Can be called multiple times during job execution
-- Useful for iterative processing where each iteration is quick but total time is unpredictable
+##### Cron-Based Scheduling
 
-**Configuration:**
+For complex schedules, use cron expressions (requires the `fugit` gem):
 
-Set default TTR in `config/postburner.yml`:
+```ruby
+# Every weekday at 8:00 AM
+Postburner::Schedule.create!(
+  name: 'weekday_standup',
+  job_class: 'StandupReminderJob',
+  cron: '0 8 * * 1-5',
+  timezone: 'America/Chicago'
+)
 
-```yaml
-production:
-  default_priority: 65536
-  default_ttr: 300  # 5 minutes default for all jobs
+# Every 15 minutes
+Postburner::Schedule.create!(
+  name: 'health_check',
+  job_class: 'HealthCheckJob',
+  cron: '*/15 * * * *',
+  timezone: 'UTC'
+)
 ```
 
-**Recommended TTR Values:**
+#### Schedule Options
 
-| Job Type | TTR | Reasoning |
-|----------|-----|-----------|
-| Email sending | 60-120s | Network operations, should be fast |
-| API calls | 30-60s | External services, fast or timeout |
-| File processing | 600-1800s | Variable based on file size, use `extend!` |
-| Reports | 1800-3600s | Complex queries and aggregations |
-| Imports/Exports | 3600s+ | Large datasets, use `extend!` in loops |
+```ruby
+Postburner::Schedule.create!(
+  name: 'important_job',              # Required: unique identifier
+  job_class: 'MyJob',                 # Required: ActiveJob or Postburner::Job class name
+
+  # Scheduling (choose anchor+interval OR cron)
+  anchor: Time.zone.parse('...'),     # Start time for interval calculation
+  interval: 1,                        # Number of interval units
+  interval_unit: 'days',              # seconds/minutes/hours/days/weeks/months/years
+  # OR
+  cron: '0 9 * * *',                  # Cron expression (requires fugit gem)
+
+  # Optional
+  timezone: 'America/New_York',       # Default: 'UTC'
+  args: { key: 'value' },             # Arguments passed to job
+  queue: 'critical',                  # Override default queue
+  priority: 0,                        # Override default priority
+  enabled: true,                      # Enable/disable schedule
+  catch_up: false,                    # Skip missed executions (default: false)
+  description: 'Daily metrics run'    # Human-readable description
+)
+```
 
-**Best Practices:**
+#### Catch-Up Policy
 
-1. **Set realistic TTR values** based on expected job duration plus buffer
-2. **Use `extend!` for iterative work** where total time is unpredictable but each iteration is bounded
-3. **Don't set TTR too high** - it delays recovery from crashed workers
-4. **Monitor TTR timeouts** - frequent timeouts indicate jobs need more time or optimization
-5. **For Default jobs** (ActiveJob without `Postburner::Beanstalkd`), include the module to set custom TTR
+The `catch_up` option controls what happens when the worker is down and misses scheduled executions:
 
-**What happens on TTR timeout:**
+- **`catch_up: false` (default)** - Skip missed executions, create next future execution only (health checks, status updates, cache warming, monitoring)
+- **`catch_up: true`** - Run all missed executions when worker restarts (data processing pipelines, billing cycles, audit requirements, SLA-sensitive operations)
 
-```ruby
-# Job starts processing
-job = ProcessImport.perform_later(file_id)
+Notes:
+1) Previously created executions and enqueued jobs are not affected by the catch-up policy.
+2) If `catch_up` if off, then there the skipped executions are not created or tracked. It resumes from the next future execution.
 
-# Worker crashes or hangs after 200 seconds
-# At 300 seconds (TTR), Beanstalkd automatically:
-# 1. Releases job back to ready queue
-# 2. Increments the job's reserve count
-# 3. Makes job available for another worker
+```ruby
+# Skip missed executions (default)
+Postburner::Schedule.create!(
+  name: 'health_check',
+  job_class: 'HealthCheckJob',
+  interval: 1,
+  interval_unit: 'minutes',
+  catch_up: false  # Worker down 9:00-9:05 → skips 9:01-9:04, creates 9:06
+)
 
-# Another worker picks up the job and retries
-# (ActiveJob retry_on/discard_on handlers still apply)
+# Run all missed executions
+Postburner::Schedule.create!(
+  name: 'process_billing',
+  job_class: 'BillingJob',
+  interval: 1,
+  interval_unit: 'hours',
+  catch_up: true  # Worker down 9:00-12:00 → runs 9:00, 10:00, 11:00, 12:00
+)
 ```
 
-## Installation
+#### Managing Schedules
 
-### 1. Install Beanstalkd
+```ruby
+# Find schedules
+schedule = Postburner::Schedule.find_by(name: 'daily_cleanup')
+Postburner::Schedule.enabled  # All enabled schedules
 
-First [install beanstalkd](https://beanstalkd.github.io/download.html):
+# Disable temporarily
+schedule.update!(enabled: false)
 
-```bash
-sudo apt-get install beanstalkd
-brew install beanstalkd # for macOS/Linux
+# Change catch-up policy
+schedule.update!(catch_up: true)
 
-# Start beanstalkd (in-memory only)
-beanstalkd -l 127.0.0.1 -p 11300
+# Check next run time
+schedule.next_run_at  # => 2025-01-02 09:00:00 -0500
 
-# OR with persistence (recommended for production)
-mkdir -p /var/lib/beanstalkd
-beanstalkd -l 127.0.0.1 -p 11300 -b /var/lib/beanstalkd
+# Preview upcoming runs
+schedule.next_run_at_times(5)  # Next 5 run times
+
+# View executions
+schedule.executions.pending
+schedule.executions.completed
+schedule.executions.failed
 ```
 
-### 2. Add Gem
+#### Starting Schedules
 
-```ruby
-# Gemfile
-gem 'postburner', '~> 1.0.0.pre.1'
-```
+When you create a schedule, it won't run until the first execution is created. You have two options:
 
-```bash
-bundle install
-```
+**Option 1: Explicit start (immediate enqueue)**
 
-### 3. Install Migration
+Call `start!` to create and enqueue the first execution immediately to Beanstalkd:
 
-```bash
-rails generate postburner:install
-rails db:migrate
+```ruby
+schedule = Postburner::Schedule.create!(
+  name: 'daily_report',
+  job_class: 'DailyReportJob',
+  anchor: Time.zone.parse('2025-01-01 09:00:00'),
+  interval: 1,
+  interval_unit: 'days'
+)
+schedule.start!  # Creates execution AND enqueues to Beanstalkd
+schedule.started?  # => true
 ```
 
-This creates the `postburner_jobs` table for tracked jobs.
+The job is immediately in Beanstalkd's delayed queue and will run at the scheduled time.
 
-### 4. Configure ActiveJob
+**Option 2: Auto-bootstrap (eventual pickup)**
 
-```ruby
-# config/application.rb
-config.active_job.queue_adapter = :postburner
-```
+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:
 
-### 5. Create Worker Configuration
+```ruby
+schedule = Postburner::Schedule.create!(...)
+schedule.started?  # => false
 
-```bash
-cp config/postburner.yml.example config/postburner.yml
+# Later, scheduler runs and auto-bootstraps...
+schedule.reload.started?  # => true
 ```
 
-Edit `config/postburner.yml` for your environment (see [Configuration](#configuration)).
+Use `start!` when you need predictable timing. Skip it when eventual consistency is acceptable.
 
-## Usage
+#### Schedule Executions
 
-### Default Jobs
-
-Default jobs execute quickly via Beanstalkd without PostgreSQL overhead. Perfect for emails, cache warming, notifications, etc.
+Each scheduled run creates an execution record for tracking:
 
 ```ruby
-class SendWelcomeEmail < ApplicationJob
-  queue_as :mailers
+execution = Postburner::ScheduleExecution.find(123)
 
-  def perform(user_id)
-    UserMailer.welcome(user_id).deliver_now
-  end
-end
+execution.status        # pending, running, completed, failed, 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)
+```
 
-# Enqueue immediately
-SendWelcomeEmail.perform_later(123)
+**Execution lifecycle:**
+1. Execution created with `pending` status and immediately enqueued to Beanstalkd
+2. Status changes to `scheduled` once enqueued
+3. At `run_at` time, Beanstalkd releases job to worker
+4. For `Postburner::Job` (and `ActiveJob` with `Postburner::Tracked`) schedules: `before_attempt` callback creates next execution
+5. Watchdog periodically verifies future executions exist (safety net)
 
-# Enqueue with delay
-SendWelcomeEmail.set(wait: 1.hour).perform_later(123)
+#### Timezone Handling
 
-# Enqueue at specific time
-SendWelcomeEmail.set(wait_until: Date.tomorrow.noon).perform_later(123)
+Schedules respect timezones for consistent execution times regardless of server location:
+
+```ruby
+# Runs at 9:00 AM New York time (handles DST automatically)
+Postburner::Schedule.create!(
+  name: 'ny_morning_job',
+  job_class: 'MorningJob',
+  anchor: Time.zone.parse('2025-01-01 09:00:00'),
+  interval: 1,
+  interval_unit: 'days',
+  timezone: 'America/New_York'
+)
 ```
 
-**Overview:**
-- Fast execution (no database writes)
-- Low overhead
-- Standard ActiveJob retry_on/discard_on support
-- No audit trail
-- No logging or statistics
+The scheduler calculates next run times in the specified timezone, so jobs run at the expected local time even across daylight saving transitions.
 
-#### Configuring Beanstalkd Priority and TTR
+### Job Management
 
-For default jobs that need custom Beanstalkd configuration, include `Postburner::Beanstalkd`:
+#### Canceling Jobs
+
+**For Postburner::Job subclasses:**
 
 ```ruby
-class SendWelcomeEmail < ApplicationJob
-  include Postburner::Beanstalkd
+job = ProcessPayment.create!(args: { 'payment_id' => 123 })
+job.queue!(delay: 1.hour)
 
-  queue_as :mailers
-  priority 100    # Lower = higher priority (0 is highest)
-  ttr 300         # Time-to-run in seconds (5 minutes)
+# Soft delete (recommended) - removes from queue, sets removed_at
+job.remove!
+job.removed_at  # => 2025-11-19 12:34:56 UTC
+job.persisted?  # => true (still in database for audit)
 
-  def perform(user_id)
-    UserMailer.welcome(user_id).deliver_now
-  end
-end
-```
+# Hard delete - removes from both queue and database
+job.destroy!
 
-**Configuration options:**
-- `queue_priority` - Beanstalkd priority (0-4294967295, lower = higher priority)
-- `queue_ttr` - Time-to-run in seconds before job times out
+# Delete from Beanstalkd only (keeps database record)
+job.delete!
+```
 
-Jobs without `Postburner::Beanstalkd` use defaults from `config/postburner.yml`:
-- `default_priority: 65536`
-- `default_ttr: 300`
+**For tracked ActiveJob classes:**
 
-### Tracked Jobs
+```ruby
+# Find the TrackedJob record
+job = Postburner::TrackedJob.find(123)
+job.remove!  # Cancel execution
+```
 
-Tracked jobs store full execution details in PostgreSQL, providing comprehensive audit trails (i.e. logging, timing, errors, retry tracking) for critical operations.
+#### Retrying Buried Jobs
 
-**Note:** `Postburner::Tracked` automatically includes `Postburner::Beanstalkd`, giving you access to `queue_priority`, `queue_ttr`, `bk`, and `extend!`.
+Jobs that fail repeatedly get "buried" in Beanstalkd:
 
 ```ruby
-class ProcessPayment < ApplicationJob
-  include Postburner::Tracked  # ← Opt-in to PostgreSQL tracking (includes Beanstalkd)
+job = Postburner::Job.find(123)
+job.kick!  # Moves buried job back to ready queue
+```
 
-  queue_as :critical
-  priority 0              # Highest priority (Beanstalkd included automatically)
-  ttr 600                 # 10 minute timeout
-  retry_on StandardError, wait: :exponentially_longer, attempts: 5
+#### Inspecting Job State
 
-  def perform(payment_id)
-    payment = Payment.find(payment_id)
+```ruby
+job = Postburner::TrackedJob.find(123)
 
-    log "Starting payment processing for $#{payment.amount}"
+# Timestamps
+job.queued_at      # When queued to Beanstalkd
+job.run_at         # Scheduled execution time
+job.attempting_at  # First attempt started
+job.processing_at  # Current/last processing started
+job.processed_at   # Completed successfully
+job.removed_at     # Soft deleted
 
-    begin
-      payment.charge!
-      log! "Payment charged successfully"
-    rescue PaymentError => e
-      log_exception!(e)
-      raise
-    end
+# Statistics
+job.lag       # Milliseconds between scheduled and actual execution
+job.duration  # Milliseconds to execute
+job.attempt_count  # Number of attempts
+job.error_count    # Number of errors
 
-    log "Payment complete", level: :info
-  end
-end
+# Audit trail
+job.logs    # Array of log entries with timestamps
+job.errata  # Array of exceptions with backtraces
+job.attempts # Array of attempt timestamps
 ```
 
-**Tracking provides:**
-- Complete execution history (queued_at, processing_at, processed_at)
-- Custom logs with `log` and `log!`
-- Exception tracking with `log_exception()` and `log_exception!()`
-- Timing statistics (lag, duration)
-- Retry attempts tracking
-- Query with ActiveRecord
-- Foreign key relationships
-- Beanstalkd operations via `bk` accessor
-- TTR extension via `extend!` method
+## Queue Strategies
 
-**Query tracked jobs:**
+Postburner uses different strategies to control job execution. These affect `Postburner::Job` subclasses (not ActiveJob classes).
+
+| Strategy | When to Use | Behavior | Requires Beanstalkd |
+|----------|-------------|----------|---------------------|
+| **NiceQueue** (default) | Production | Async via Beanstalkd, gracefully re-queues premature jobs | Yes |
+| **Queue** | Production (strict) | Async via Beanstalkd, raises error on premature execution | Yes |
+| **TestQueue** | Testing with explicit time control | Inline execution, raises error for scheduled jobs | No |
+| **ImmediateTestQueue** | Testing with automatic time travel | Inline execution, auto time-travels for scheduled jobs | No |
+| **NullQueue** | Batch processing / deferred execution | Jobs created but not queued, manual execution | No |
 
 ```ruby
-# Find by state
-Postburner::TrackedJob.where(processed_at: nil)
-Postburner::TrackedJob.where.not(removed_at: nil)
+# Switch strategies
+Postburner.nice_async_strategy!           # Default production (NiceQueue)
+Postburner.async_strategy!                # Strict production (Queue)
+Postburner.inline_test_strategy!          # Testing (TestQueue)
+Postburner.inline_immediate_test_strategy! # Testing with time travel
+Postburner.null_strategy!                 # Deferred execution
+```
 
-# Find with errors
-Postburner::TrackedJob.where("error_count > 0")
+**Note:** These strategies only affect `Postburner::Job` subclasses. ActiveJob classes execute according to the ActiveJob adapter configuration.
 
-# Statistics
-Postburner::TrackedJob.average(:duration)  # Average execution time
-Postburner::TrackedJob.maximum(:lag)       # Worst lag
+## Testing
 
-# Inspect execution
-job = Postburner::TrackedJob.last
-job.logs      # Array of log entries with timestamps
-job.errata    # Array of exceptions with backtraces
-job.attempts  # Array of attempt timestamps
-job.duration  # Execution time in milliseconds
-job.lag       # Queue lag in milliseconds
-```
+Postburner provides test-friendly execution modes that don't require Beanstalkd.
 
-### Direct Postburner::Job Usage
+### Automatic Test Mode
 
-Direct `Postburner::Job` subclasses are **always tracked**:
+In Rails test environments, Postburner automatically uses inline execution:
 
 ```ruby
-class RunDonation < Postburner::Job
-  queue 'critical'
-  priority 0
-  max_retries 0
+# test/test_helper.rb - automatic!
+Postburner.testing?  # => true in tests
+```
 
-  def perform(args)
-    donation = Donation.find(args['donation_id'])
-    donation.process!
-    log "Processed donation #{donation.id}"
-  end
-end
+### Testing Default Jobs (ActiveJob)
 
-# Create and enqueue
-job = RunDonation.create!(args: { 'donation_id' => 123 })
-job.queue!
+Use standard ActiveJob test helpers:
 
-# With delay
-job.queue!(delay: 1.hour)
+```ruby
+class MyTest < ActiveSupport::TestCase
+  test "job executes" do
+    SendEmail.perform_later(123)
+    # Job executes immediately in test mode
+  end
 
-# At specific time
-job.queue!(at: 2.days.from_now)
+  test "job with delay" do
+    travel 1.hour do
+      SendEmail.set(wait: 1.hour).perform_later(123)
+    end
+  end
+end
 ```
 
-#### Instance-Level Queue Configuration
+### Testing Tracked Jobs
 
-Override queue priority and TTR per job instance for dynamic behavior:
+Tracked jobs create database records you can inspect:
 
 ```ruby
-# Set priority during creation
-job = RunDonation.create!(
-  args: { 'donation_id' => 123 },
-  queue_priority: 1500,  # Override class-level priority
-  queue_ttr: 300         # Override class-level TTR
-)
-job.queue!
+test "tracked job logs execution" do
+  ProcessPayment.perform_later(456)
 
-# Set dynamically after creation
-job = RunDonation.create!(args: { 'donation_id' => 456 })
-job.priority = 2000
-job.ttr = 300
-job.queue!
+  job = Postburner::TrackedJob.last
+  assert job.processed_at.present?
+  assert_includes job.logs.map { |l| l[1]['message'] }, "Processing payment 456"
+end
+```
 
-# Use in before_enqueue callback for conditional behavior
-class ProcessOrder < Postburner::Job
-  queue 'orders'
-  priority 100   # Default priority
-  ttr 120  # Default TTR
+### Testing Legacy Postburner::Job
 
-  before_enqueue :set_priority_based_on_urgency
+```ruby
+test "processes immediately" do
+  job = ProcessPayment.create!(args: { 'payment_id' => 123 })
+  job.queue!
 
-  def perform(args)
-    order = Order.find(args['order_id'])
-    order.process!
-  end
+  assert job.reload.processed_at
+end
 
-  private
+test "scheduled job with time travel" do
+  job = ProcessPayment.create!(args: { 'payment_id' => 123 })
 
-  def set_priority_based_on_urgency
-    if args['express_shipping']
-      self.priority = 0    # High priority for express orders
-      self.ttr = 600       # Allow 10 minutes to complete
-    else
-      self.priority = 1000 # Low priority for standard orders
-      self.ttr = 120       # Standard 2 minute timeout
-    end
+  travel_to(2.hours.from_now) do
+    job.queue!(delay: 2.hours)
+    assert job.reload.processed_at
   end
 end
-
-# Express order gets high priority automatically
-ProcessOrder.create!(args: { 'order_id' => 789, 'express_shipping' => true }).queue!
 ```
 
-**Overview:**
-- Same as Tracked jobs
-- Access the ActiveRecord Postburner::Job directly.
-
 ## Workers
 
 Postburner uses named worker configurations to support different deployment patterns. Each worker can have different fork/thread settings and process different queues, enabling flexible production deployments.
@@ -985,6 +1090,26 @@ Parent Process
 - Crash isolation (one fork down doesn't affect others)
 - Best for production high-volume workloads
 
+### Shutdown Timeout
+
+The `shutdown_timeout` controls how long workers wait for in-flight jobs to complete during graceful shutdown. This applies to thread pool termination and child process shutdown.
+
+```yaml
+production:
+  default_ttr: 300              # Default TTR for jobs
+  default_shutdown_timeout: 300 # Defaults to default_ttr if not specified
+
+  workers:
+    imports:
+      shutdown_timeout: 600     # Override: wait up to 10 minutes for long imports
+      queues:
+        - imports
+```
+
+**Best practice:** Set `shutdown_timeout` to match or exceed your longest-running job's TTR to avoid force-killing jobs during deployment.
+
+**Connection model:** Each worker thread maintains its own Beanstalkd connection for thread safety.
+
 ### GC Limits
 
 Set `default_gc_limit` at environment level or `gc_limit` per worker to automatically restart after processing N jobs.
@@ -1221,157 +1346,378 @@ end
 - `before_processing`, `around_processing`, `after_processing` - During execution
 - `after_processed` - Only after successful completion
 
-## Queue Strategies
+## Instrumentation
 
-Postburner uses different strategies to control job execution. These affect `Postburner::Job` subclasses (not ActiveJob classes).
+Postburner emits ActiveSupport::Notifications events following ActiveJob conventions. Use these for monitoring, logging, or alerting.
 
-| Strategy | When to Use | Behavior | Requires Beanstalkd |
-|----------|-------------|----------|---------------------|
-| **NiceQueue** (default) | Production | Async via Beanstalkd, gracefully re-queues premature jobs | Yes |
-| **Queue** | Production (strict) | Async via Beanstalkd, raises error on premature execution | Yes |
-| **TestQueue** | Testing with explicit time control | Inline execution, raises error for scheduled jobs | No |
-| **ImmediateTestQueue** | Testing with automatic time travel | Inline execution, auto time-travels for scheduled jobs | No |
-| **NullQueue** | Batch processing / deferred execution | Jobs created but not queued, manual execution | No |
+### Available Events
+
+| Event | When | Payload Keys |
+|-------|------|--------------|
+| `perform_start.postburner` | Before job execution | `:payload`, `:beanstalk_job_id` |
+| `perform.postburner` | Around job execution (includes duration) | `:payload`, `:beanstalk_job_id` |
+| `retry.postburner` | When default job is retried | `:payload`, `:beanstalk_job_id`, `:error`, `:wait`, `:attempt` |
+| `discard.postburner` | When default job exhausts retries | `:payload`, `:beanstalk_job_id`, `:error` |
+
+### Subscribing to Events
+
+```ruby
+# config/initializers/postburner_instrumentation.rb
+
+# Log all job executions
+ActiveSupport::Notifications.subscribe('perform.postburner') do |name, start, finish, id, payload|
+  duration = (finish - start) * 1000
+  Rails.logger.info "[Postburner] #{payload[:payload]['job_class']} completed in #{duration.round(2)}ms"
+end
+
+# Alert on discarded jobs
+ActiveSupport::Notifications.subscribe('discard.postburner') do |*args|
+  payload = args.last
+  Alerting.notify(
+    "Job discarded after max retries",
+    job_class: payload[:payload]['job_class'],
+    error: payload[:error].message
+  )
+end
+
+# Track retry metrics
+ActiveSupport::Notifications.subscribe('retry.postburner') do |*args|
+  payload = args.last
+  StatsD.increment('postburner.retry', tags: [
+    "job:#{payload[:payload]['job_class']}",
+    "attempt:#{payload[:attempt]}"
+  ])
+end
+```
+
+**Note:** These events are emitted by the worker for jobs processed through Beanstalkd. They complement (don't replace) ActiveJob's built-in instrumentation events.
+
+## Why Beanstalkd?
+
+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
+
+Here is a picture of the typical job lifecycle:
+
+```
+   put            reserve               delete
+  -----> [READY] ---------> [RESERVED] --------> *poof*`
+```
+
+Here is a picture with more possibilities:
+
+```
+   put with delay               release with delay
+  ----------------> [DELAYED] <------------.
+                        |                   |
+                        | (time passes)     |
+                        |                   |
+   put                  v     reserve       |       delete
+  -----------------> [READY] ---------> [RESERVED] --------> *poof*
+                       ^  ^                |  |
+                       |   \  release      |  |
+                       |    `-------------'   |
+                       |                      |
+                       | kick                 |
+                       |                      |
+                       |       bury           |
+                    [BURIED] <---------------'
+                       |
+                       |  delete
+                        `--------> *poof*
+```
+
+### Binlogs
+
+Beanstalkd lets you persist jobs to disk in case of a crash or restart. Just restart beanstalkd and the jobs will be back in the queue.
+
+```bash
+# Create binlog directory
+sudo mkdir -p /var/lib/beanstalkd
+sudo chown beanstalkd:beanstalkd /var/lib/beanstalkd  # If running as service
+
+# Start beanstalkd with binlog persistence
+beanstalkd -l 127.0.0.1 -p 11300 -b /var/lib/beanstalkd
+```
+
+**Other options:**
+
+```bash
+# Basic persistence
+beanstalkd -b /var/lib/beanstalkd
+
+# With custom binlog file size (default varies)
+beanstalkd -b /var/lib/beanstalkd -s 10485760  # 10MB per binlog file
+
+# Reduce fsync frequency for better performance (trades safety for speed)
+beanstalkd -b /var/lib/beanstalkd -f 200  # fsync at most every 200ms (default: 50ms)
+
+# Never fsync (maximum performance, higher risk of data loss on power failure)
+beanstalkd -b /var/lib/beanstalkd -F
+```
+
+**Beanstalkd switches:**
+- `-b <dir>` - Enable binlog persistence in specified directory
+- `-s <bytes>` - Maximum size of each binlog file (requires `-b`)
+- `-f <ms>` - Call fsync at most once every N milliseconds (requires `-b`, default: 50ms)
+- `-F` - Never call fsync (requires `-b`, maximum performance but higher data loss risk)
+
+**Note:** The fsync options control the trade-off between performance and safety. A power failure could result in loss of jobs added within the fsync interval.
+
+### Priority
+
+Priority controls the order in which jobs are processed from the queue. Beanstalkd always processes the highest priority (lowest number) jobs first.
+
+**Priority Range:** 0 to 4,294,967,295 (unsigned 32-bit integer)
+- `0` = Highest priority (processed first)
+- `4,294,967,295` = Lowest priority (processed last)
+- Default: `65536` (configurable in `config/postburner.yml`)
+
+When a worker reserves a job, Beanstalkd returns the highest priority job available in the tube. Jobs with the same priority are processed in FIFO order.
+
+**ActiveJob with Postburner::Beanstalkd:**
+
+```ruby
+class ProcessPayment < ApplicationJob
+  include Postburner::Beanstalkd
+
+  queue_as :critical
+  priority 0  # Highest priority - processed immediately
+end
+
+class SendEmail < ApplicationJob
+  include Postburner::Beanstalkd
+
+  queue_as :mailers
+  priority 1000  # Lower priority - processed after critical jobs
+end
+```
+
+**Postburner::Job:**
+
+```ruby
+class CriticalJob < Postburner::Job
+  queue 'critical'
+  priority 0  # Highest priority
+
+  def perform(args)
+    # Critical business logic
+  end
+end
+
+class BackgroundTask < Postburner::Job
+  queue 'default'
+  priority 5000  # Lower priority
+
+  def perform(args)
+    # Non-urgent background work
+  end
+end
+```
+
+**Recommended Priority Ranges:**
+
+| Priority Range | Use Case | Examples |
+|---------------|----------|----------|
+| 0-256 | Critical business operations | Payments, transactions, real-time notifications |
+| 256-4096 | High priority tasks | Password resets, order confirmations |
+| 4096-65536 | Standard background jobs | Email sending, data exports (65536 is default) |
+| 65536-262144 | Low priority maintenance | Cache warming, log cleanup |
+| 262144+ | Deferred/bulk operations | Analytics, batch reports |
+
+**Configuration:**
+
+Set default priority in `config/postburner.yml`:
+
+```yaml
+production:
+  default_priority: 65536  # Default for jobs without explicit priority
+  default_ttr: 300
+```
+
+**Dynamic Priority (Postburner::Job only):**
+
+```ruby
+class ProcessOrder < Postburner::Job
+  queue 'orders'
+  priority 100  # Default
+
+  before_enqueue :adjust_priority
+
+  def perform(args)
+    order = Order.find(args['order_id'])
+    order.process!
+  end
+
+  private
+
+  def adjust_priority
+    if args['urgent']
+      self.priority = 0  # Override to highest priority
+    end
+  end
+end
+
+# Usage
+ProcessOrder.create!(args: { 'order_id' => 123, 'urgent' => true }).queue!
+```
+
+### Time to Run (TTR)
+
+TTR (Time-to-Run) is the maximum duration in seconds that a worker has to process a reserved job before Beanstalkd automatically releases it back to the ready queue.
+
+1. Worker reserves a job from Beanstalkd
+2. TTR countdown begins immediately upon reservation
+3. If job completes within TTR, worker deletes/buries the job (success)
+4. If TTR expires before completion, Beanstalkd automatically releases the job back to ready queue
+5. Another worker can then reserve and process the same job
+
+This mechanism protects against workers crashing or hanging—jobs won't be stuck indefinitely.
 
-```ruby
-# Switch strategies
-Postburner.nice_async_strategy!           # Default production (NiceQueue)
-Postburner.async_strategy!                # Strict production (Queue)
-Postburner.inline_test_strategy!          # Testing (TestQueue)
-Postburner.inline_immediate_test_strategy! # Testing with time travel
-Postburner.null_strategy!                 # Deferred execution
-```
+**TTR Range:** 1 to 4,294,967,295 seconds (unsigned 32-bit integer)
+- Minimum: `1` second (Beanstalkd silently increases 0 to 1)
+- Default: `300` seconds (5 minutes, configurable in `config/postburner.yml`)
 
-**Note:** These strategies only affect `Postburner::Job` subclasses. ActiveJob classes execute according to the ActiveJob adapter configuration.
+**ActiveJob with Postburner::Beanstalkd:**
 
-## Testing
+```ruby
+class ProcessPayment < ApplicationJob
+  include Postburner::Beanstalkd # Or Postburner::Tracked
 
-Postburner provides test-friendly execution modes that don't require Beanstalkd.
+  queue_as :critical
+  priority 0
+  ttr 300  # 5 minutes to complete
+end
 
-### Automatic Test Mode
+class QuickEmail < ApplicationJob
+  include Postburner::Beanstalkd # Or Postburner::Tracked
 
-In Rails test environments, Postburner automatically uses inline execution:
+  queue_as :mailers
+  ttr 60  # 1 minute for fast email jobs
+end
 
-```ruby
-# test/test_helper.rb - automatic!
-Postburner.testing?  # => true in tests
-```
+class LongRunningReport < ApplicationJob
+  include Postburner::Beanstalkd # Or Postburner::Tracked
 
-### Testing Default Jobs (ActiveJob)
+  queue_as :reports
+  ttr 3600  # 1 hour for complex reports
+end
+```
 
-Use standard ActiveJob test helpers:
+**Postburner::Job:**
 
 ```ruby
-class MyTest < ActiveSupport::TestCase
-  test "job executes" do
-    SendEmail.perform_later(123)
-    # Job executes immediately in test mode
-  end
+class DataImport < Postburner::Job
+  queue 'imports'
+  ttr 1800  # 30 minutes (equivalent to queue_ttr)
 
-  test "job with delay" do
-    travel 1.hour do
-      SendEmail.set(wait: 1.hour).perform_later(123)
-    end
+  def perform(args)
+    # Long-running import logic
   end
 end
 ```
 
-### Testing Tracked Jobs
+**Extending TTR with `extend!` (Touch Command):**
 
-Tracked jobs create database records you can inspect:
+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)
 
 ```ruby
-test "tracked job logs execution" do
-  ProcessPayment.perform_later(456)
+class ProcessImport < ApplicationJob
+  include Postburner::Tracked  # Includes Beanstalkd and enables extend!
 
-  job = Postburner::TrackedJob.last
-  assert job.processed_at.present?
-  assert_includes job.logs.map { |l| l[1]['message'] }, "Processing payment 456"
+  queue_as :imports
+  ttr 300  # 5 minutes initial TTR
+
+  def perform(file_id)
+    file = ImportFile.find(file_id)
+
+    file.each_batch(size: 100) do |batch|
+      batch.each do |row|
+        process_row(row)
+      end
+
+      extend!  # Reset TTR to 300 seconds from now
+      log "Processed batch, extended TTR"
+    end
+  end
 end
 ```
 
-### Testing Legacy Postburner::Job
+**For Postburner::Job (via `bk` accessor):**
 
 ```ruby
-test "processes immediately" do
-  job = RunDonation.create!(args: { 'donation_id' => 123 })
-  job.queue!
+class LargeDataProcessor < Postburner::Job
+  queue 'processing'
+  ttr 600  # 10 minutes
 
-  assert job.reload.processed_at
-end
+  def perform(args)
+    dataset = Dataset.find(args['dataset_id'])
 
-test "scheduled job with time travel" do
-  job = RunDonation.create!(args: { 'donation_id' => 123 })
+    dataset.each_chunk do |chunk|
+      process_chunk(chunk)
 
-  travel_to(2.hours.from_now) do
-    job.queue!(delay: 2.hours)
-    assert job.reload.processed_at
+      bk.extend!  # Reset TTR via beanstalkd job accessor
+      log "Chunk processed, TTR extended"
+    end
   end
 end
 ```
 
-## Job Management
-
-### Canceling Jobs
-
-**For Postburner::Job subclasses:**
+**`extend!` and Beanstalkd `touch`**
 
-```ruby
-job = RunDonation.create!(args: { 'donation_id' => 123 })
-job.queue!(delay: 1.hour)
+- Calls Beanstalkd's `touch` command on the reserved job
+- Resets the TTR countdown to the original TTR value from the current moment
+- Example: Job has `ttr 300`. After 200 seconds, calling `extend!` gives you another 300 seconds (not just 100)
+- Can be called multiple times during job execution
+- Useful for iterative processing where each iteration is quick but total time is unpredictable
 
-# Soft delete (recommended) - removes from queue, sets removed_at
-job.remove!
-job.removed_at  # => 2025-11-19 12:34:56 UTC
-job.persisted?  # => true (still in database for audit)
+**Configuration:**
 
-# Hard delete - removes from both queue and database
-job.destroy!
+Set default TTR in `config/postburner.yml`:
 
-# Delete from Beanstalkd only (keeps database record)
-job.delete!
+```yaml
+production:
+  default_priority: 65536
+  default_ttr: 300  # 5 minutes default for all jobs
 ```
 
-**For tracked ActiveJob classes:**
-
-```ruby
-# Find the TrackedJob record
-job = Postburner::TrackedJob.find(123)
-job.remove!  # Cancel execution
-```
+**Recommended TTR Values:**
 
-### Retrying Buried Jobs
+| Job Type | TTR | Reasoning |
+|----------|-----|-----------|
+| Email sending | 60-120s | Network operations, should be fast |
+| API calls | 30-60s | External services, fast or timeout |
+| File processing | 600-1800s | Variable based on file size, use `extend!` |
+| Reports | 1800-3600s | Complex queries and aggregations |
+| Imports/Exports | 3600s+ | Large datasets, use `extend!` in loops |
 
-Jobs that fail repeatedly get "buried" in Beanstalkd:
+**Best Practices:**
 
-```ruby
-job = Postburner::Job.find(123)
-job.kick!  # Moves buried job back to ready queue
-```
+1. **Set realistic TTR values** based on expected job duration plus buffer
+2. **Use `extend!` for iterative work** where total time is unpredictable but each iteration is bounded
+3. **Don't set TTR too high** - it delays recovery from crashed workers
+4. **Monitor TTR timeouts** - frequent timeouts indicate jobs need more time or optimization
+5. **For Default jobs** (ActiveJob without `Postburner::Beanstalkd`), include the module to set custom TTR
 
-### Inspecting Job State
+**What happens on TTR timeout:**
 
 ```ruby
-job = Postburner::TrackedJob.find(123)
-
-# Timestamps
-job.queued_at      # When queued to Beanstalkd
-job.run_at         # Scheduled execution time
-job.attempting_at  # First attempt started
-job.processing_at  # Current/last processing started
-job.processed_at   # Completed successfully
-job.removed_at     # Soft deleted
+# Job starts processing
+job = ProcessImport.perform_later(file_id)
 
-# Statistics
-job.lag       # Milliseconds between scheduled and actual execution
-job.duration  # Milliseconds to execute
-job.attempt_count  # Number of attempts
-job.error_count    # Number of errors
+# Worker crashes or hangs after 200 seconds
+# At 300 seconds (TTR), Beanstalkd automatically:
+# 1. Releases job back to ready queue
+# 2. Increments the job's reserve count
+# 3. Makes job available for another worker
 
-# Audit trail
-job.logs    # Array of log entries with timestamps
-job.errata  # Array of exceptions with backtraces
-job.attempts # Array of attempt timestamps
+# Another worker picks up the job and retries
+# (ActiveJob retry_on/discard_on handlers still apply)
 ```
 
 ## Beanstalkd Integration
@@ -1463,12 +1809,32 @@ result = Postburner.clear_jobs!(['postburner.production.default'])
 
 # Pretty-print JSON output
 Postburner.clear_jobs!(['postburner.production.default'], silent: false)
+# OR
+Postburner.clear_jobs!(['postburner.production.default'])
 # Outputs formatted JSON to stdout
 
 # Silent mode (no output, just return data)
 result = Postburner.clear_jobs!(['postburner.production.default'], silent: true)
 ```
 
+**Shortcut using watched_tube_names or scheduler_tube_name:**
+
+Clear all configured tubes at once:
+
+```ruby
+Postburner.clear_jobs!(Postburner.watched_tube_names)
+# => { tubes: [...], totals: {...}, cleared: true }
+```
+
+Or clear scheduler tube, specifically:
+
+```ruby
+Postburner.clear_jobs!(Postburner.scheduler_tube_name)
+# => { tubes: [...], totals: {...}, cleared: true }
+```
+
+These shortcuts are useful for testing and development, but not recommended for production.
+
 **Safety validation:**
 
 Only tubes defined in your loaded configuration can be cleared. This prevents mistakes in multi-tenant Beanstalkd environments:
@@ -1481,21 +1847,6 @@ Postburner.clear_jobs!(['postburner.production.other-app'])
 #    Configured tubes: postburner.production.default, postburner.production.critical
 ```
 
-**Shortcut using watched_tube_names:**
-
-Clear all configured tubes at once:
-
-```ruby
-# Get all tubes from current configuration
-watched_tubes = Postburner.watched_tube_names
-# => ["postburner.production.default", "postburner.production.critical", "postburner.production.mailers"]
-
-# Clear all configured tubes
-Postburner.clear_jobs!(watched_tubes, silent: true)
-# or
-Postburner.clear_jobs!(Postburner.watched_tube_names, silent: true)
-```
-
 **Low-level Connection API:**
 
 For programmatic use without output formatting, use `Connection#clear_tubes!`:
@@ -1511,7 +1862,7 @@ Postburner.connected do |conn|
 end
 ```
 
-## Web UI
+## Web UI -- Dated
 
 Mount the inspection interface:
 
@@ -1532,8 +1883,63 @@ authenticate :user, ->(user) { user.admin? } do
 end
 ```
 
+## Installation
+
+### 1. Install Beanstalkd
+
+First [install beanstalkd](https://beanstalkd.github.io/download.html):
+
+```bash
+sudo apt-get install beanstalkd
+brew install beanstalkd # for macOS/Linux
+
+# Start beanstalkd (in-memory only)
+beanstalkd -l 127.0.0.1 -p 11300
+
+# OR with persistence (recommended for production)
+mkdir -p /var/lib/beanstalkd
+beanstalkd -l 127.0.0.1 -p 11300 -b /var/lib/beanstalkd
+```
+
+### 2. Add Gem
+
+```ruby
+# Gemfile
+gem 'postburner', '~> 1.0.0.pre.1'
+```
+
+```bash
+bundle install
+```
+
+### 3. Install Migration
+
+```bash
+rails generate postburner:install
+rails db:migrate
+```
+
+This creates the `postburner_jobs` table for tracked jobs.
+
+### 4. Configure ActiveJob
+
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :postburner
+```
+
+### 5. Create Worker Configuration
+
+```bash
+cp config/postburner.yml.example config/postburner.yml
+```
+
+Edit `config/postburner.yml` for your environment (see [Configuration](#configuration)).
+
 ## Deployment
 
+Some recipies that might be useful or instructive:
+
 ### Docker
 
 ```dockerfile