# Custom agents

Wayfarer offers an interface for integrating third-party browsers and HTTP
clients as user agents.

There are two types of agents:

1. Stateful agents, i.e. browsers, which carry state and support navigation.
   These follow HTTP redirects implicitly.
2. Stateless agents, which deal with HTTP requests/responses only.
   These handle HTTP redirects explicitly.

## Implementation

Both types can be implemented with callback methods:

=== "Stateful"

    ```ruby
    class StatefulAgent
      include Wayfarer::Networking::Strategy

      def renew_on # optional
        [MyBrowser::IrrecoverableError]
      end

      def create
        MyBrowser.new
      end

      def destroy(browser) # optional
        browser.quit
      end

      def navigate(browser, url)
        browser.goto(url)
      end

      def live(browser)
        success(url: browser.url,
                body: browser.body,
                status_code: browser.status_code,
                headers: browser.headers)
      end
    end
    ```

=== "Stateless"

    ```ruby
    class StatelessAgent
      include Wayfarer::Networking::Strategy

      def renew_on # optional
        [MyClient::IrrecoverableError]
      end

      def create
        MyClient.new
      end

      def destroy(client) # optional
        client.close
      end

      def fetch(client, url)
        response = client.get(url)

        return redirect(response.redirect_url) if response.redirect?

        success(url: url,
                body: response.body,
                status_code: response.status_code,
                headers: response.headers)
      end
    end
    ```


Register the strategy:

```ruby
Wayfarer::Networking::Pool.registry[:my_agent] = MyAgent.new
```

Use the strategy:

```ruby
Wayfarer.config.network.agent = :my_agent
```

### Remarks

#### Self-healing

* A strategy's `#renew_on` method may return a list of exception classes upon
  which the existing instance gets destroyed and replaced with a newly created
  one.
* Stateless clients must not raise exceptions when encountering certain HTTP
  response codes (for example, 5xx).