angry_batch 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8363c90cc908a4ae3fa64957ebfc422580dd91041dfd32d0d2eb7607e9130a62
-  data.tar.gz: b83a95d6938a4ad2e2cc20d3e7fc9edbd0f998e7c1256749d7c2ba6c90f22a04
+  metadata.gz: c1f0b7ce33e9b643c38801a188cb1a5734f30d652a8e3cd7cdd0b3b65f88340a
+  data.tar.gz: fbace43e4e2a6740786caa4e04117bbdf62b40191e6834e9d5eb1e5db3e37692
 SHA512:
-  metadata.gz: 1ab00df9aef51980652bb56151d43ce16af63aa58a2e41f31badcb90f50b2687c9e74e119f6d77fa9f3113f6fb88aa441e2e0988275ef732942ab20f8f73f2e0
-  data.tar.gz: bba22c7ff6de71cdd1bfe285aeaead5163140536a19e2142e1e163b57dcec50ec0262519b2148a7ebed2db30cc4274d16200c6d0e576372684bf3633568e150a
+  metadata.gz: 72de753a921085e998d060d0cffa1018b3914def85adff93c9b7adbb61009f9d0f7bb295060519b2bbcd0c72db041b03e334f6d6ff170d19a9daf4d062ffb691
+  data.tar.gz: adfa172d9219a8f86ba12838c15426a5a12b725dec24a815bccf93b5423afe550e3a2b062cb0f8ad1e3230c82199d62c08ee0ec713011536e98bb323daf3cbe1

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Version 1.1.0 - 2026-09-05
+
+- New migration — run `rails generate angry_batch:install` and `rails db:migrate` when upgrading
+- Removed the `scheduling` state and the `AngryBatch::Batch.scheduling` scope; new batches start as `pending`
+- Jobs and handlers can access their batch via `batch`
+- Add jobs to a running batch with `batch.enqueue`
+- Attach `metadata:` to a batch, readable via `batch.metadata`
+- Track progress with `progress`, `pending_jobs_count`, `completed_jobs_count` and `failed_jobs_count`
+- `perform_later` returns the `AngryBatch::Batch` record
+- Jobs are enqueued after the surrounding transaction commits (Rails 7.2+)
+- Bug fixes
+
 ## Version 1.0.1 - 2026-05-11
 
 - Handle job failures via `after_discard` hook — marks job as `failed` and stores error message

data/README.md

@@ -33,6 +33,17 @@ rails generate angry_batch:install
 rails db:migrate
 ```
 
+### Upgrading from 1.0
+
+Version 1.1 adds columns to the batches table. Run the generator again; it detects the existing install and only creates the upgrade migration:
+
+```
+rails generate angry_batch:install
+rails db:migrate
+```
+
+The migration backfills the new counters from the existing job records. Jobs that finish on 1.0 code after the migration has run are not counted, so run the migration while your workers are stopped or drained, and restart them on 1.1 before enqueuing new batches.
+
 ## Usage
 
 ```ruby
@@ -42,7 +53,7 @@ class SomeJob
 end
 
 # Step 2: Create new batch queue
-queue = AngryBatch.new(label: 'Debug label')
+queue = AngryBatch.new(label: 'Debug label', metadata: { account: account })
 
 # Step 3: Add completion handler
 #   `on_complete` job will be called when all other queue jobs have completed
@@ -58,9 +69,94 @@ queue.enqueue SomeJob, argument2
 queue.enqueue SomeJob, argument3
 
 # Step 5: Trigger all jobs in the queue
-in the queue.perform_later
+#   returns the AngryBatch::Batch record
+batch = queue.perform_later
+```
+
+### Accessing the batch from a job
+
+Every job that includes `AngryBatch::Batchable` can call `batch` while performing. It returns the `AngryBatch::Batch` record, or `nil` when the job was enqueued outside of a batch (or the batch record has already been cleaned up).
+
+```ruby
+class SomeJob < ApplicationJob
+  include AngryBatch::Batchable
+
+  def perform(argument)
+    batch.label            # => 'Debug label'
+    batch.metadata         # => { account: #<Account> }
+    batch.progress         # => 33
+  end
+end
+```
+
+Completion and failure handlers get the same access when they include `AngryBatch::Batchable`. Handlers are not part of the batch, so including the module in them does not affect the batch counters.
+
+```ruby
+class ToBeCalledWhenAllOtherJobsAreCompletedJob < ApplicationJob
+  include AngryBatch::Batchable
+
+  def perform(argument)
+    batch.metadata[:account]
+  end
+end
 ```
 
+### Metadata
+
+`metadata:` accepts a hash and is stored using ActiveJob argument serialization. Symbols, dates, nested hashes, and ActiveRecord models (via GlobalID) round-trip as-is. Values ActiveJob cannot serialize raise `ActiveJob::SerializationError` when the queue is created.
+
+Metadata is read-only after the batch is created. If a model referenced in metadata is deleted before a job reads it, `batch.metadata` raises `ActiveJob::DeserializationError`, the same way job arguments do.
+
+### Adding jobs from inside a job
+
+A running job can add more jobs to its own batch. The batch does not complete until they finish, and jobs added this way can add jobs themselves.
+
+```ruby
+class ExportProjectJob < ApplicationJob
+  include AngryBatch::Batchable
+
+  def perform(project)
+    project.files.find_each do |file|
+      batch.enqueue ExportFileJob, file
+    end
+  end
+end
+```
+
+`batch.enqueue` uses the same validation as the queue: the job must be an ActiveJob and include `AngryBatch::Batchable`. It can also be called on any pending `AngryBatch::Batch` record outside of a job.
+
+Once a batch is completed or failed, `batch.enqueue` raises `AngryBatch::BatchFinishedError`. To run a second stage from a completion handler, create a new batch instead.
+
+If a job raises after adding jobs, the added jobs still run. The batch ends `failed` once they are done, and the `on_failure` handlers run then. Note that a retried job (`retry_on`) runs `batch.enqueue` again and adds the jobs a second time.
+
+If a job cannot be enqueued, whether a `before_enqueue` callback aborted it or your queue backend raised, the error is raised to the caller. A queue that cannot accept jobs is an infrastructure problem rather than a failed unit of work, so it belongs in your exception tracker and not in `on_failure`. The batch stays `pending` until you deal with it, and is reaped by `AngryBatch::CleanupCronJob` if you never do.
+
+### Transactions
+
+Jobs are pushed to your queue after the surrounding database transaction commits, so a worker never sees a job before its batch record exists. If the transaction rolls back, the batch and its jobs are discarded together and nothing is pushed. This applies to `perform_later` and to `batch.enqueue` alike.
+
+```ruby
+Account.transaction do
+  account.update! exporting: true
+
+  queue.perform_later # pushed once this transaction commits
+end
+```
+
+On Rails 7.1 there is no hook for this and jobs are pushed immediately, so avoid enqueuing inside your own transaction there.
+
+### Progress
+
+Batches keep `jobs_count`, `completed_jobs_count`, and `failed_jobs_count` up to date as jobs finish. `pending_jobs_count` and `progress` (0 to 100) are derived from them.
+
+The counters on a record are a snapshot. Call `batch.reload` to refresh them, for example after `batch.enqueue` on the same instance.
+
+### Errors
+
+A job is marked `failed` when ActiveJob discards it: `discard_on`, exhausted `retry_on`, or an unhandled exception. The batch is `failed` as soon as one job failed and every job has finished. A job only transitions once; a later successful run of a job already marked `failed` does not change it.
+
+Prefer `retry_on` over adapter-level retries. With adapter-level retries (for example Sidekiq's own retry), the first unhandled exception marks the job `failed` even if a later attempt succeeds.
+
 ### Cleaning completed jobs
 
 `AngryBatch` stores jobs in the database. You have to run `AngryBatch::CleanupCronJob` in a cron to clean the records.

data/lib/angry_batch/batch.rb

@@ -4,15 +4,18 @@
 #
 # Table name: angry_batch_batches
 #
-#  id                :bigint(8)        not null, primary key
-#  complete_handlers :jsonb            not null
-#  failure_handlers  :jsonb            not null
-#  finished_at       :datetime
-#  jobs_count        :integer          default(0), not null
-#  label             :string
-#  state             :string           default("scheduling"), not null
-#  created_at        :datetime         not null
-#  updated_at        :datetime         not null
+#  id                   :bigint(8)        not null, primary key
+#  complete_handlers    :jsonb            not null
+#  completed_jobs_count :integer          default(0), not null
+#  failed_jobs_count    :integer          default(0), not null
+#  failure_handlers     :jsonb            not null
+#  finished_at          :datetime
+#  jobs_count           :integer          default(0), not null
+#  label                :string
+#  metadata             :jsonb            not null
+#  state                :string           default("pending"), not null
+#  created_at           :datetime         not null
+#  updated_at           :datetime         not null
 #
 # Indexes
 #
@@ -24,7 +27,6 @@ class AngryBatch::Batch < ActiveRecord::Base
   has_many :jobs, class_name: 'AngryBatch::Job', dependent: :delete_all
 
   enum :state, {
-    scheduling: 'scheduling',
     pending: 'pending',
     completed: 'completed',
     failed: 'failed',
@@ -32,20 +34,58 @@ class AngryBatch::Batch < ActiveRecord::Base
 
   class << self
     def expired
-      completed.where(updated_at: ...2.days.ago)
-        .or(failed.where(updated_at: ...4.weeks.ago))
-        .or(pending.where(updated_at: ...4.weeks.ago))
+      completed.where(updated_at: ...2.days.ago).or(failed.where(updated_at: ...4.weeks.ago)).or(pending.where(updated_at: ...4.weeks.ago))
     end
   end
 
+  def enqueue(job_class, *, **)
+    AngryBatch::Helper.assert_batchable(job_class)
+
+    job = job_class.new(*, **)
+
+    with_lock do
+      raise AngryBatch::BatchFinishedError, "Batch #{id} is #{state}" unless pending?
+
+      AngryBatch::Helper.add_job_to_batch(self, job)
+    end
+
+    AngryBatch::Helper.after_transaction do
+      raise ActiveJob::EnqueueError, ["#{job_class} was not enqueued", job.enqueue_error&.message].compact.join(': ') unless job.enqueue
+    end
+
+    job
+  end
+
+  def metadata
+    raw = read_attribute(:metadata)
+
+    unless defined?(@metadata) && @metadata_raw == raw
+      @metadata = ActiveJob::Arguments.deserialize([raw || {}]).first
+      @metadata_raw = raw
+    end
+
+    @metadata
+  end
+
+  def pending_jobs_count
+    jobs_count - completed_jobs_count - failed_jobs_count
+  end
+
+  def progress
+    return 0 if jobs_count.zero?
+
+    ((completed_jobs_count + failed_jobs_count) * 100 / jobs_count).clamp(0, 100)
+  end
+
   def check_status_of_jobs
     handlers_to_enqueue = with_lock do
       return unless pending?
-      return unless jobs_count == jobs.finished.count
+      return if jobs_count.zero?
+      return unless pending_jobs_count <= 0
 
       self.finished_at = Time.current
 
-      if jobs.failed.none?
+      if failed_jobs_count.zero?
         update! state: 'completed'
         complete_handlers
       else
@@ -60,8 +100,17 @@ class AngryBatch::Batch < ActiveRecord::Base
   private
 
   def enqueue_handlers(handlers)
+    error = nil
+
     handlers.each do |(job_class, job_arguments)|
-      job_class.constantize.perform_later(*ActiveJob::Arguments.deserialize(job_arguments || []))
+      job = job_class.constantize.new(*ActiveJob::Arguments.deserialize(job_arguments || []))
+      job.angry_batch_id = id if job.is_a?(AngryBatch::Batchable)
+
+      raise ActiveJob::EnqueueError, "#{job_class} was not enqueued" unless job.enqueue
+    rescue StandardError => e
+      error ||= e
     end
+
+    raise error if error
   end
 end

data/lib/angry_batch/batchable.rb

@@ -10,4 +10,21 @@ module AngryBatch::Batchable
       AngryBatch::Handle.job_failed(job, exception)
     end
   end
+
+  attr_accessor :angry_batch_id
+
+  def serialize
+    super.merge('angry_batch_id' => angry_batch_id)
+  end
+
+  def deserialize(job_data)
+    super
+    self.angry_batch_id = job_data['angry_batch_id']
+  end
+
+  def batch
+    return @batch if defined?(@batch)
+
+    @batch = angry_batch_id && AngryBatch::Batch.find_by(id: angry_batch_id)
+  end
 end

data/lib/angry_batch/builder.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 class AngryBatch::Builder
-  def initialize(label: nil)
+  def initialize(label: nil, metadata: {})
+    @metadata = ActiveJob::Arguments.serialize([metadata || {}]).first
     @batch = AngryBatch::Batch.new(
       label: label,
-      state: 'scheduling',
+      metadata: @metadata,
       complete_handlers: [],
       failure_handlers: [],
     )
@@ -20,22 +21,24 @@ class AngryBatch::Builder
 
   def on_complete(job_class, *, **)
     raise AngryBatch::BatchArgumentError, 'Batch is already running' if performed?
-    raise AngryBatch::BatchArgumentError, "#{job_class} must be a subclass of ActiveJob::Base" unless job_class.is_a?(Class) && job_class < ActiveJob::Base
+
+    AngryBatch::Helper.assert_job_class(job_class)
 
     @batch.complete_handlers << [job_class, job_class.new(*, **).serialize['arguments']]
   end
 
   def on_failure(job_class, *, **)
     raise AngryBatch::BatchArgumentError, 'Batch is already running' if performed?
-    raise AngryBatch::BatchArgumentError, "#{job_class} must be a subclass of ActiveJob::Base" unless job_class.is_a?(Class) && job_class < ActiveJob::Base
+
+    AngryBatch::Helper.assert_job_class(job_class)
 
     @batch.failure_handlers << [job_class, job_class.new(*, **).serialize['arguments']]
   end
 
   def enqueue(job_class, *, **)
     raise AngryBatch::BatchArgumentError, 'Batch is already running' if performed?
-    raise AngryBatch::BatchArgumentError, "#{job_class} must be a subclass of ActiveJob::Base" unless job_class.is_a?(Class) && job_class < ActiveJob::Base
-    raise AngryBatch::BatchArgumentError, "#{job_class} must include AngryBatch::Batchable" unless job_class.included_modules.include?(AngryBatch::Batchable)
+
+    AngryBatch::Helper.assert_batchable(job_class)
 
     @jobs << job_class.new(*, **)
   end
@@ -47,25 +50,23 @@ class AngryBatch::Builder
     ActiveRecord::Base.transaction(requires_new: true) do
       @batch.save!
 
+      @jobs.each { |job| AngryBatch::Helper.add_job_to_batch(@batch, job) }
+    end
+
+    @performed = true
+
+    AngryBatch::Helper.after_transaction do
       @jobs.each do |job|
-        @batch.jobs.create!(
-          active_job_idx: job.job_id,
-          active_job_class: job.class.name,
-          active_job_arguments: job.serialize['arguments'],
-        )
+        raise ActiveJob::EnqueueError, ["#{job.class.name} was not enqueued", job.enqueue_error&.message].compact.join(': ') unless job.enqueue
       end
-
-      @batch.update!(state: 'pending')
     end
 
-    @performed = true
-    @jobs.each(&:enqueue)
-    @batch.check_status_of_jobs
-  rescue
+    @batch
+  rescue StandardError
     unless @performed
       @batch = AngryBatch::Batch.new(
         label: @batch.label,
-        state: 'scheduling',
+        metadata: @metadata,
         complete_handlers: @batch.complete_handlers,
         failure_handlers: @batch.failure_handlers,
       )

data/lib/angry_batch/handle.rb

@@ -4,30 +4,25 @@ module AngryBatch::Handle
   extend self
 
   def job_completed(job)
-    record = AngryBatch::Job.find_by(active_job_idx: job.job_id)
-
-    return if record.blank?
-
-    record.with_lock do
-      return if record.failed?
-
-      record.update!(state: 'completed')
-    end
-
-    record.batch&.check_status_of_jobs
-  rescue ActiveRecord::RecordNotFound
-    nil
+    finish(job, state: 'completed')
   end
 
   def job_failed(job, exception = nil)
+    finish(job, state: 'failed', error_message: exception&.message)
+  end
+
+  private
+
+  def finish(job, state:, **attributes)
     record = AngryBatch::Job.find_by(active_job_idx: job.job_id)
 
     return if record.blank?
 
     record.with_lock do
-      return if record.completed?
-
-      record.update!(state: 'failed', error_message: exception&.message)
+      if record.pending?
+        record.update!(state: state, **attributes)
+        AngryBatch::Batch.increment_counter(:"#{state}_jobs_count", record.batch_id) # rubocop:disable Rails/SkipsModelValidations
+      end
     end
 
     record.batch&.check_status_of_jobs

data/lib/angry_batch/helper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AngryBatch::Helper
+  extend self
+
+  def assert_job_class(job_class)
+    return if job_class.is_a?(Class) && job_class < ActiveJob::Base
+
+    raise AngryBatch::BatchArgumentError, "#{job_class} must be a subclass of ActiveJob::Base"
+  end
+
+  def assert_batchable(job_class)
+    assert_job_class(job_class)
+
+    return if job_class.included_modules.include?(AngryBatch::Batchable)
+
+    raise AngryBatch::BatchArgumentError, "#{job_class} must include AngryBatch::Batchable"
+  end
+
+  def add_job_to_batch(batch, job)
+    job.angry_batch_id = batch.id
+
+    batch.jobs.create!(
+      active_job_idx: job.job_id,
+      active_job_class: job.class.name,
+      active_job_arguments: job.serialize['arguments'],
+    )
+  end
+
+  # NOTE(rstankov): pushing after the commit keeps workers from seeing a job
+  # before its record. Rails < 7.2 has no hook for it and pushes immediately.
+  if ActiveRecord.respond_to?(:after_all_transactions_commit)
+    def after_transaction(&)
+      ActiveRecord.after_all_transactions_commit(&)
+    end
+  else
+    def after_transaction
+      yield
+    end
+  end
+end

data/lib/angry_batch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AngryBatch
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

data/lib/angry_batch.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'angry_batch/version'
+require_relative 'angry_batch/helper'
 require_relative 'angry_batch/job'
 require_relative 'angry_batch/batch'
 require_relative 'angry_batch/handle'
@@ -17,6 +18,9 @@ module AngryBatch
 
   class BatchArgumentError < ArgumentError
   end
+
+  class BatchFinishedError < StandardError
+  end
 end
 
 if defined?(Rails)

data/lib/generators/angry_batch/install_generator.rb

@@ -12,7 +12,16 @@ module AngryBatch
       end
 
       def copy_migrations
-        migration_template 'create_angry_batch_tables.rb', 'db/migrate/create_angry_batch_tables.rb'
+        existing = self.class.migration_exists?(File.join(destination_root, 'db/migrate'), 'create_angry_batch_tables')
+
+        if existing.nil?
+          migration_template 'create_angry_batch_tables.rb', 'db/migrate/create_angry_batch_tables.rb'
+          return
+        end
+
+        return if File.read(existing).include?('completed_jobs_count')
+
+        migration_template 'add_metadata_and_counters_to_angry_batch_tables.rb', 'db/migrate/add_metadata_and_counters_to_angry_batch_tables.rb', skip: true
       end
     end
   end

data/lib/generators/angry_batch/templates/add_metadata_and_counters_to_angry_batch_tables.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class AddMetadataAndCountersToAngryBatchTables < ActiveRecord::Migration[7.0]
+  def up
+    change_table :angry_batch_batches do |t|
+      begin
+        t.jsonb :metadata, null: false, default: {}
+      rescue NoMethodError
+        t.json :metadata, null: false, default: {}
+      end
+
+      t.integer :completed_jobs_count, null: false, default: 0
+      t.integer :failed_jobs_count, null: false, default: 0
+    end
+
+    change_column_default :angry_batch_batches, :state, from: 'scheduling', to: 'pending'
+
+    execute "UPDATE angry_batch_batches SET state = 'pending' WHERE state = 'scheduling'"
+
+    execute <<~SQL.squish
+      UPDATE angry_batch_batches SET
+        completed_jobs_count = (SELECT COUNT(*) FROM angry_batch_jobs WHERE angry_batch_jobs.batch_id = angry_batch_batches.id AND angry_batch_jobs.state = 'completed'),
+        failed_jobs_count = (SELECT COUNT(*) FROM angry_batch_jobs WHERE angry_batch_jobs.batch_id = angry_batch_batches.id AND angry_batch_jobs.state = 'failed')
+    SQL
+  end
+
+  def down
+    change_column_default :angry_batch_batches, :state, from: 'pending', to: 'scheduling'
+
+    remove_column :angry_batch_batches, :metadata
+    remove_column :angry_batch_batches, :completed_jobs_count
+    remove_column :angry_batch_batches, :failed_jobs_count
+  end
+end

data/lib/generators/angry_batch/templates/create_angry_batch_tables.rb

@@ -6,15 +6,19 @@ class CreateAngryBatchTables < ActiveRecord::Migration[7.0]
       begin
         t.jsonb :complete_handlers, null: false, default: []
         t.jsonb :failure_handlers, null: false, default: []
+        t.jsonb :metadata, null: false, default: {}
       rescue NoMethodError
         t.json :complete_handlers, null: false, default: []
         t.json :failure_handlers, null: false, default: []
+        t.json :metadata, null: false, default: {}
       end
 
       t.datetime :finished_at
       t.integer  :jobs_count, null: false, default: 0
+      t.integer  :completed_jobs_count, null: false, default: 0
+      t.integer  :failed_jobs_count, null: false, default: 0
       t.string   :label
-      t.string   :state, null: false, default: 'scheduling'
+      t.string   :state, null: false, default: 'pending'
 
       t.timestamps
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: angry_batch
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Radoslav Stankov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -255,9 +255,11 @@ files:
 - lib/angry_batch/builder.rb
 - lib/angry_batch/cleanup_cron_job.rb
 - lib/angry_batch/handle.rb
+- lib/angry_batch/helper.rb
 - lib/angry_batch/job.rb
 - lib/angry_batch/version.rb
 - lib/generators/angry_batch/install_generator.rb
+- lib/generators/angry_batch/templates/add_metadata_and_counters_to_angry_batch_tables.rb
 - lib/generators/angry_batch/templates/create_angry_batch_tables.rb
 homepage: https://github.com/RStankov/AngryBatch
 licenses: