# Callbacks

## Active Job callbacks

Wayfarer naturally supports all of [Active Job's life cycle callbacks](https://edgeguides.rubyonrails.org/active_job_basics.html#callbacks).

## `before_fetch`

Runs before a job fetches a page, either by making an HTTP request, or by
navigating a browser to its task URL.

```ruby
class DummyJob < Wayfarer::Base
  before_fetch :do_something

  private

  def do_something
    # before the task.url is fetched
  end
end
```

## `before_action`

Runs after a page was fetched, before an action method is called.

```ruby
class DummyJob < Wayfarer::Base
  before_action :do_something

  private

  def do_something
    # page is available at this point
  end
end
```

## `after_batch`

Runs once the last job in a batch performed:

```ruby
class DummyJob < Wayfarer::Base
  after_batch do
    # All jobs in batch done
  end
end
```

Internally, a batch counter is in-/decremented on certain events. Once the
counter reaches zero, `after_batch` callbacks runs in declaration order.

The counter is incremented when:

* A job is enqueued within the batch.

The counter is decremented when:

* A job succeeds.
* A job fails due to an unhandled exception.
* A job fails due to a discarded exception.
* A job fails and thereyby exhausts its maximum attempts.

!!! attention "Batch callbacks can fail jobs"

    If the last job's `after_batch` callbacks raises an exception, this can lead
    to the job getting retried. If the exception raised by the callback is
    unhandled or discarded, the callback never fully runs.

## Callback options

### Definition styles

Callbacks can be registered either by supplying a block or a symbol identifying
a callback instance method:

```ruby
class DummyJob < Wayfarer::Base
  before_action do
    # ...
  end

  before_action :my_callback

  private

  def my_callback
    # ...
  end
end
```

### Conditionals

Callbacks can be registered conditionally with the `:if` and `:unless` keywords:

```ruby
class DummyJob < Wayfarer::Base
  before_fetch :my_callback, if: :my_condition

  private

  def my_callback
  end

  def my_condition
  end
end
```

Callbacks can be registered for certain action methods only with the `:only` and
`:except` keywords:

```ruby
class DummyJob < Wayfarer::Base
  before_fetch :do_something, only: :foo

  before_fetch except: [:foo, :qux] do
    # runs only before bar
  end

  def foo
  end

  def bar
  end
end

```

### Early termination

Callbacks that return `false` halt the callback chain:

```ruby
class DummyJob < Wayfarer::Base
  before_action { false }

  before_action do
    # never runs
  end
end
```