To use sidekiq-batch in your Ruby application, add it to your Gemfile and run bundle, or install it directly via the gem command.

```ruby
gem 'sidekiq-batch'

Or via CLI

$ gem install sidekiq-batch

To enable batch functionality, you must configure both the Sidekiq client and server middleware. This ensures that batch IDs (bid) are correctly propagated from the client to the worker and that job success/failure is reported back to the batch.

Calling Sidekiq::Batch::Middleware.configure automatically sets up the following:

1. Client Middleware: Adds Sidekiq::Batch::Middleware::ClientMiddleware to both client and server configurations to inject bid into job payloads.
2. Server Middleware: Adds Sidekiq::Batch::Middleware::ServerMiddleware to the server configuration to track job completion.
3. Worker Extension: Includes Sidekiq::Batch::Extension::Worker into Sidekiq::Worker to support batch-aware worker behavior.

# Simply call the configuration method to set up the middleware and extensions
Sidekiq::Batch::Middleware.configure

The invalidate_all method marks a batch as invalid in Redis. This is useful for cancelling the effects of a batch or preventing its callbacks from running if the batch's context is no longer relevant.

batch = Sidekiq::Batch.new
# ... perform work ...

# Mark this batch as invalid
batch.invalidate_all

You can register callbacks that trigger automatically when a batch reaches certain lifecycle events. Supported events are:

• :success: Triggered when all jobs in the batch have completed successfully.
• :complete: Triggered when all jobs in the batch have finished (regardless of whether they succeeded or failed).

The on method accepts the event name, the callback class/method string, and an optional hash of arguments.

batch = Sidekiq::Batch.new

# Callback when all jobs succeed
batch.on(:success, 'MyCallbackClass#perform')

# Callback with specific options
batch.on(:complete, 'MyCallbackClass#perform', { 'some_option' => 'value' })

batch.jobs do
  MyWorker.perform_async(1)
end

To inspect specifically which jobs failed within a batch, call failure_info. This returns an array of members from the Redis set BID-{bid}-failed. If no failures exist, it returns an empty array [].

status = Sidekiq::Batch::Status.new(bid)
if status.failures > 0
  puts "Failed job details: #{status.failure_info}"
end

A batch can be invalidated (e.g., via invalidate_all). Use the valid? method to check if the current batch and all its parent batches are still valid. If a batch or any of its ancestors has been invalidated, valid? will return false.

batch = Sidekiq::Batch.new(some_bid)

if batch.valid?
  # Proceed with batch-related logic
else
  # The batch or its parent has been invalidated
end

Use Sidekiq::Batch.new to create a new batch. You can wrap multiple Sidekiq jobs within a jobs block to associate them with the batch. The batch tracks the progress of these jobs and can trigger callbacks when the batch reaches specific states.

Key attributes:

• bid: The unique batch identifier.
• description: A string describing the batch's purpose.
• parent: Returns the parent Sidekiq::Batch instance if this batch is a child of another.

batch = Sidekiq::Batch.new
batch.description = "Processing user reports"

batch.jobs do
  # Any Sidekiq jobs pushed here will be part of this batch
  MyWorker.perform_async(1)
  MyWorker.perform_async(2)
end

The Sidekiq::Batch::Extension::Worker module provides helper methods to access the current batch context from inside a Sidekiq worker. When a worker is running as part of a batch, you can use these methods to retrieve the batch ID or check the batch's validity.

Available methods:

• bid: Returns the current batch ID (bid).
• batch: Returns the current Sidekiq::Batch object.
• valid_within_batch?: Returns true if the current batch is valid, false otherwise.

class MyWorker
  include Sidekiq::Batch::Extension::Worker

  def perform(*args)
    if valid_within_batch?
      puts "Running in batch: #{bid}"
    end
  end
end