@spec await_ready(timeout()) :: :ok | {:error, :timeout}

Waits until every shard on this node has connected once, for things to do once the bot is up:

def handle_continue(:start, state) do
  :ok = Lingo.Gateway.await_ready()
  ...
end

Returns :ok right away when they already have, or when the bot runs without a gateway, and {:error, :timeout} if timeout (ms) runs out. It doesn't wait again for reconnects or a reshard. Each shard's own sessions are :ready and :resumed events.

Call it from handle_continue, as above, not from init: a supervisor starts its children one by one, so waiting in init holds up the rest of your application until every shard connects, minutes for a large bot. It covers this node's shards only, and exits if the bot's shard manager restarts while it waits.

@spec latencies() :: %{required(non_neg_integer()) => non_neg_integer()}

Every shard's last heartbeat round trip in ms.

@spec latency(non_neg_integer()) :: non_neg_integer() | nil

A shard's last heartbeat round trip in ms, or nil.

@spec request_channel_info(String.t(), [String.t()]) :: :ok

Asks for extra channel info, like voice channel statuses. It arrives as :channel_info.

@spec request_guild_members(
  String.t(),
  keyword()
) :: :ok

Asks for a guild's members. They arrive as :guild_members_chunk events and fill the cache. Options: :query, :limit, :presences, :user_ids and :nonce.

@spec request_soundboard_sounds([String.t()]) :: :ok

Asks for the soundboard sounds of some guilds. They arrive as :soundboard_sounds events.

@spec reshard() ::
  {:ok, %{from: pos_integer(), to: pos_integer()}}
  | :noop
  | {:error,
     :fixed_count
     | :fixed_ids
     | :in_progress
     | :not_started
     | :identify_limit
     | Lingo.Error.t()}

Asks Discord for the recommended shard count and, when it differs, moves to it without downtime: the new shards connect next to the running ones, delivering nothing, and take over once all are ready (events at the very moment of the switch may arrive twice or not at all). The old shards then close. The new shards' :ready events aren't delivered either, and await_ready/1 doesn't wait for them.

Returns once the reshard has started, with {:ok, %{from: old, to: new}}; the [:lingo, :gateway, :reshard, :stop] telemetry event says when the new shards took over. A reshard whose shards don't all get ready in time is abandoned. Otherwise it returns:

• :noop - Discord recommends the count already running
• {:error, :fixed_count} or {:error, :fixed_ids} - the :sharding option fixes them; a bot split across nodes always does
• {:error, :in_progress} - a reshard is already under way
• {:error, :not_started} - the shards haven't started yet
• {:error, :identify_limit} - the day's identifies wouldn't cover the new shards
• {:error, %Lingo.Error{}} - asking Discord failed

@spec restart_shard(non_neg_integer()) :: :ok | {:error, term()}

Reconnects a shard from scratch, identifying again.

@spec sessions() :: [Lingo.Gateway.SessionStore.session()]

The sessions of the shards on this node, as a Lingo.Gateway.SessionStore saves them.

@spec shard_count() :: non_neg_integer()

How many shards the bot runs in total.

@spec shard_for_guild(String.t()) :: non_neg_integer()

The shard a guild's events arrive on.

@spec shard_status(non_neg_integer()) :: atom()

The connection state of a shard, such as :connected, or :dead.

@spec shard_statuses() :: %{required(non_neg_integer()) => atom()}

The connection state of every shard.

@spec update_presence(
  atom(),
  keyword()
) :: :ok

Sets the bot's status (:online, :idle, :dnd or :invisible) on every shard, with an optional text: or activity:.