[[back to doc map]](README.md)

# Big-Picture Behaviour

This document describes the general behaviour of the `IRC::Client` clients.

## Table of Contents

- [Connection Maintenance](#connection-maintenance)
- [Nickname Maintenance](#nickname-maintenance)

---

## Connection Maintenance

The client is designed with the goal of being run indefinitely. As such, it
will restart server connections if they close.

If a connection fails or a disconnect happens, the client will wait
10 seconds (non-blockingly) and attempt to reconnect, repeating the process
if the reconnect fails too. This loop will continue indefinitely until either
the connection is established or the client explicitly quits the server
using the `.quit` method on the Client Object.

The described process applies to individual servers, regardless of how many
servers the client is asked to connect to. Thus, it's possible that one
server will be in the reconnect loop, while others will be connected and
functioning like normal. It's also possible for the user to `.quit` some
servers, while maintaining connection to others. The client object's
`.run` method will return only when *all* servers have been `.quit`

## Nickname Maintenance

If the first nickname assigned to the bot at the start (or one set
using `.nick` method) is in use, the bot will automatically use the next one
in the list. If *all* of the nicks are in use, it will wait a short period
of time, before retrying all nicks again.

Note: the same system will be applied if the proposed nick is an erroneous
one that cannot be used on the server—for example, it can contain invalid
characters or be too long. This means the bot will never succeed
in connecting to the server or changing a nick if the entire list of nicks it
possesses are invalid ones. Be sure to turn the debug output on and inspect
output for any suspect messages if you're having issues connecting.