refactor(gateway-queue)!: rewrite crate

book/src/chapter_2_multi-serviced_approach.md

@@ -14,19 +14,18 @@ One of the popular design choices when creating a multi-serviced application is
 to have a service that only connects shards to the gateway and sends the events
 to a broker to be processed. As bots grow into hundreds or thousands of shards,
 multiple instances of the application can be created and groups of shards can be
-managed by each. Twilight is an excellent choice for this use case: you can
-receive either events that come in in a loop and send the payloads to the
-appropriate broker stream, or you can loop over received payloads' bytes to send
-off.
+managed by each. Twilight is an excellent choice for this use case: just receive
+and send the payloads to the appropriate broker stream. Twilight shards need
+only partially deserialize payloads to function.
 
 ## Gateway session ratelimiting
 
 If multiple shard groups are used, then they need to be queued and their session
-initialization ratelimited. The Gateway includes a Queue trait which can be
+initialization ratelimited. The gateway includes a Queue trait which can be
 implemented; the gateway will submit a request to the queue before starting a
-session. Twilight comes with a queue that supports sharding and Large Bot
-sharding, but when multiple shard groups are in use then a custom queue will
-need to be implemented. Refer to [gateway-queue] for an example of this.
+session. Twilight comes with a queue that supports Large Bot sharding, but when
+multiple shard groups are in use then a custom queue will need to be implemented.
+Refer to [gateway-queue] for an example of this.
 
 ## HTTP proxy ratelimiting
 

twilight-gateway-queue/Cargo.toml

@@ -13,18 +13,8 @@ rust-version.workspace = true
 version = "0.15.2"
 
 [dependencies]
-tokio = { default-features = false, features = ["rt", "sync", "time"], version = "1.0" }
-tracing = { default-features = false, features = ["std", "attributes"], version = "0.1" }
-
-# Optional dependencies.
-twilight-http = { default-features = false, optional = true, path = "../twilight-http", version = "0.15.2" }
+tokio = { default-features = false, features = ["macros", "rt", "sync", "time"], version = "1.0" }
 
 [dev-dependencies]
 static_assertions = { default-features = false, version = "1" }
-
-[features]
-default = ["twilight-http"]
-
-[package.metadata.docs.rs]
-all-features = true
-rustdoc-args = ["--cfg", "docsrs"]
+tokio = { default-features = false, features = ["test-util"], version = "1.0" }

twilight-gateway-queue/README.md

@@ -1,42 +1,21 @@
 # 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
+Rate limiting functionality for gateway `IDENTIFY` commands.
+
+Discord allows bot's shards to send a limited amount of `IDENTIFY` commands
+every 5 seconds, with a daily limit from 1000 to 2000 commands, and invalidates
+*all* shard sessions upon exceeding it. Each identify window is called a bucket
+and is filled by shards' IDs modulo `max_concurrency`. Buckets must furthermore
+be started in order. See [Discord Docs/Sharding].
+
+To coordinate this, a [`Queue`] should process each identify request and shards
+should wait for its signal to proceed before continuing and otherwise retry. The
+provided [`InMemoryQueue`] never fails or cancels requests and is therefore a
+good starting point for custom implementations. For most cases, simply wrapping
+[`InMemoryQueue`] is be enough to add new capabilities such as multi-process
+support, see [`gateway-queue`] and [`gateway-queue-http`]. Integration tests can
+be found [here](https://github.com/twilight-rs/twilight/blob/main/twilight-gateway-queue/src/lib.rs).
+
+[Discord Docs/Sharding]: https://discord.com/developers/docs/topics/gateway#sharding
+[`gateway-queue`]: https://github.com/twilight-rs/gateway-queue
+[`gateway-queue-http`]: https://github.com/twilight-rs/twilight/blob/main/examples/gateway-queue-http.rs