view release on metacpan or  search on metacpan

lib/Discord/Client/Gateway.pm  view on Meta::CPAN

=head2 completion

Returns the lifetime Future, resolving on orderly shutdown and failing on
fatal errors.

=head2 close

Returns a Future waiting for transport shutdown. Cancels timers, writes and
handlers. Repeated calls return the same Future. Injected REST clients and
Identify limiters remain caller-owned.

=head2 on

C<on(EVENT =E<gt> CODE)> registers an event callback and returns the Gateway.
Callbacks and failure handling are described under L</EVENTS AND FAILURES>.

=head2 send

C<send(opcode, data)> returns a Future completing after the write, only while
ready. Heartbeat, Identify and Resume are driver-managed. Payloads must fit
4096 bytes. The SDK limits traffic to 120 payloads per 60 seconds and reserves
capacity for protocol traffic.

Cancelling removes an unsent write. Cancelling an active write resets the
connection because delivery is uncertain. Application writes are not replayed.

=head2 state

Returns the connection state string.

=head2 loop

Returns the IO::Async::Loop.

=head2 session

Returns the internal protocol object. Use events for application work.

=head2 identify_limiter

Returns the internal Identify scheduler. Its API is not a public contract.

=head2 stats

Returns a hashref of counters, queue sizes and heartbeat latency.

=head1 EVENTS AND FAILURES

Event names are uppercase. Callbacks receive C<($data, $gateway, $packet)>.
C<on('*' =E<gt> CODE)> receives C<($event, $data, $gateway, $packet)>.
Unknown events and fields are preserved; unknown opcodes produce C<OPCODE>
with C<{op, d}>.

Return handler Futures. Pending Futures do not delay heartbeats or incoming
packets, but blocking Perl code blocks the loop. Thrown exceptions and failed
Futures produce C<handler> errors without stopping the connection.

C<on_error =E<gt> CODE> receives C<($error, $gateway)> synchronously. Without it,
the SDK warns with a generic message. Errors omit raw frames, exceptions and
credentials. Fatal L<close codes|https://docs.discord.com/developers/topics/opcodes-and-status-codes> appear in C<close_code> and stop reconnecting.

When the callback queue is full, the incoming event's application callbacks are
dropped. Through L<Discord::Client>, SDK cache and READY state updates and
interaction dispatch occur before this queue and are preserved. Interaction
dispatch still has its own bounded capacity.
A C<queue_full> error is reported once per saturation episode; C<stats> counts
all C<dropped_events> and C<dropped_callbacks>. Earlier work continues. Dropped
events are not replayed; applications needing a complete stream must reconcile
state. Each callback invocation uses capacity, even with a shared Future.

=head1 RECONNECTS AND IDENTIFY

The SDK schedules heartbeats from HELLO and reconnects if ACK is missing.
Resume uses the saved URL, session ID and sequence. Non-resumable sessions
Identify again; fatal close codes stop the driver.
Reconnects use jittered backoff, reset after stable operation. Opcode 7 starts
the first Resume attempt immediately. Compression is not requested.

C<shard =E<gt> [$id, $total]> selects a shard. Identify uses session-start metadata
from C</gateway/bot> and a five-second cooldown per concurrency bucket.
The cooldown starts when Identify is sent. Resume consumes no session start.
Exhausted budgets wait for reset and refresh metadata. An exhausted budget with
zero C<reset_after> refreshes every second until starts or a positive delay
become available. Heartbeats continue during Identify waits.

For several shards, use L<the shard manager|Discord::Client::Gateway::Shards>. Identify coordination
is local to one process; separate processes need external coordination.

=head1 OPTIONS

=over 4

=item C<max_outgoing>

Queued and active writes; default 128.

=item C<max_events>

Queued callback invocations; default 1024.

=item C<max_handlers>

Pending callback invocations; default 64.

=item C<connect_timeout>

Seconds for connection/HELLO or sent authentication; default 30.

=item C<backoff_base>

Initial backoff in seconds; default 1.

=item C<backoff_max>

Maximum backoff in seconds; default 60.

=item C<stable_after>

Seconds before resetting backoff; default 60.