# twilight-gateway-queue
Ratelimiting functionality for queueing new gateway sessions.
The gateway ratelimits how often clients can initialize new sessions.
Instances of a queue are given to shards so that they can request to
initialize a session.
Queue implementations must point to the same broker so that all shards
across all shard groups, processes, and other forms of multi-serviced
applications, can work together and use the same ratelimiting source. That is,
if two shard groups are in two different processes, then the the two processes
must use some unified form of ratelimiting: this can either mean using IPC to
communicate ratelimiting or a broker.
## Provided queues
Most users only need the [`LocalQueue`]: it's a single-process queue for
smaller bots. Larger bots need the [`LargeBotQueue`], which supports
single-process [Sharding for Large Bots] through the use of bucket
releasing.
By default, the gateway's `stream` module and `Shard`s use the [`LocalQueue`].
This can be overridden via the `ShardBuilder::queue` configuration method.
## Advanced use cases
Large bots, and smaller bots out of design, may need to implement their own
queue. The most common reason to need this is if you have shard groups in
multiple processes. A broker to manage ratelimiting across shard groups is
required, so a [`Queue`] trait is provided that shards can use to make requests
to create sessions.
## Features
### Twilight-HTTP
The `twilight-http` feature brings in support for [`LargeBotQueue`].
This is enabled by default.
[Sharding for Large Bots]: https://discord.com/developers/docs/topics/gateway#sharding-for-large-bots