From 17758ba077672042239ee0c75fa8783d0b42b3f9 Mon Sep 17 00:00:00 2001 From: meep Date: Fri, 10 May 2024 16:40:54 +0200 Subject: [PATCH 1/5] Clarified how sharding works and removed some dangling spaces --- docs/topics/Gateway.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index fa61d5fe0e..19ca71eb9a 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -3,7 +3,7 @@ The Gateway API lets apps open secure WebSocket connections with Discord to receive events about actions that take place in a server/guild, like when a channel is updated or a role is created. There are a few cases where apps will *also* use Gateway connections to update or request resources, like when updating voice state. > info -> In *most* cases, performing REST operations on Discord resources can be done using the [HTTP API](#DOCS_REFERENCE/http-api) rather than the Gateway API. +> In *most* cases, performing REST operations on Discord resources can be done using the [HTTP API](#DOCS_REFERENCE/http-api) rather than the Gateway API. The Gateway is Discord's form of real-time communication used by clients (including apps), so there are nuances and data passed that simply isn't relevant to apps. Interacting with the Gateway can be tricky, but there are [community-built libraries](#DOCS_TOPICS_COMMUNITY_RESOURCES/libraries) with built-in support that simplify the most complicated bits and pieces. If you're planning on writing a custom implementation, be sure to read the following documentation in its entirety so you understand the sacred secrets of the Gateway (or at least those that matter for apps). @@ -72,7 +72,7 @@ Gateway connections are persistent WebSockets which introduce more complexity th At a high-level, Gateway connections consist of the following cycle: ![Flowchart with an overview of Gateway connection lifecycle](gateway-lifecycle.svg) - + 1. App establishes a connection with the Gateway after fetching and caching a WSS URL using the [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint. 2. Discord sends the app a [Hello (opcode `10`)](#DOCS_TOPICS_GATEWAY/hello-event) event containing a heartbeat interval in milliseconds. **Read the section on [Connecting](#DOCS_TOPICS_GATEWAY/connecting)** 3. Start the Heartbeat interval. App must send a [Heartbeat (opcode `1`)](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) event, then continue to send them every heartbeat interval until the connection is closed. **Read the section on [Sending Heartbeats](#DOCS_TOPICS_GATEWAY/sending-heartbeats)** @@ -463,7 +463,7 @@ Apps **without** the intent will receive empty values in fields that contain use - Content in messages that an app sends - Content in DMs with the app - Content in which the app is [mentioned](#DOCS_REFERENCE/message-formatting-formats) -- Content of the message a [message context menu command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/message-commands) is used on +- Content of the message a [message context menu command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/message-commands) is used on ## Rate Limiting @@ -561,27 +561,33 @@ When connecting to the gateway as a bot user, guilds that the bot is a part of w ## Sharding -As apps grow and are added to an increasing number of guilds, some developers may find it necessary to divide portions of their app's operations across multiple processes. As such, the Gateway implements a method of user-controlled guild sharding which allows apps to split events across a number of Gateway connections. Guild sharding is entirely controlled by an app, and requires no state-sharing between separate connections to operate. While all apps *can* enable sharding, it's not necessary for apps in a smaller number of guilds. +As apps grow and are added to an increasing number of guilds, some developers may find it necessary to divide portions of their app's operations across multiple processes. As such, the Gateway implements a method of user-controlled guild sharding which allows apps to split events across a number of Gateway sessions. Guild sharding is entirely controlled by an app, and requires no state-sharing between separate sessions to operate. While all apps *can* enable sharding, it's not necessary for apps in a smaller number of guilds. > warn -> Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. +> Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. -To enable sharding on a connection, the app should send the `shard` array in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. +Sessions that would like to only receive events from a subset of guilds should send the `shard` array in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload. The first item in this array is `shard_id`, the zero-based integer value of the current shard, while the second is `total_shards` and represents the total number of shards. > info > The [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field -To calculate which events will be sent to which shard, the following formula can be used: +A certain gateway session is only subscribed to events from guilds with a `guild_id` that fulfil the following formula, using the `shard_id` and `num_shards` that the session provided in the Identify event: ###### Sharding Formula ```python -shard_id = (guild_id >> 22) % num_shards +shard_id == (guild_id >> 22) % num_shards ``` -As an example, if you wanted to split the connection between three shards, you'd use the following values for `shard` for each connection: `[0, 3]`, `[1, 3]`, and `[2, 3]`. Note that only the first shard (`[0, 3]`) would receive DMs. +Every session with `shard_id = 0` will be subscribed to DM's and other non-guild related events. + +As an example, if you wanted to split events equally between three shards, you'd use the following values for `shard` for each session: `[0, 3]`, `[1, 3]`, and `[2, 3]`. DM's would only be sent to the `[0, 3]` shard. + +Note that `num_shards` does not relate to (or limit) the total number of potential sessions, and can be different between multiple sessions existing at the same time. It is only used to decide whether an event will be sent to the associated session using the [Sharding Formula](#sharding-formula) above. In the simple case like the example above, where every session has the same `num_shards` and the sessions respective `shard_id`'s cover every value from `0` to `num_shards - 1`, the events will be split evenly between the sessions. This is probably how most bots will operate. + +On the other hand, sessions do not have to be identified in an evenly-distributed manner when sharding. You can establish multiple sessions with the same `[shard_id, num_shards]`, or sessions with different `num_shards` values, in which case events may be sent to multiple sessions. For example, two sessions with the respective `shard` arrays `[2, 3]` and `[4, 5]` will both receive events from the guild with id `613425648685547541` (you can open up Python and check for yourself that `2 == (613425648685547541 >> 22) % 3` and `4 == (613425648685547541 >> 22) % 5`). -Note that `num_shards` does not relate to (or limit) the total number of potential sessions. It is only used for *routing* traffic. As such, sessions do not have to be identified in an evenly-distributed manner when sharding. You can establish multiple sessions with the same `[shard_id, num_shards]`, or sessions with different `num_shards` values. This allows you to create sessions that will handle more or less traffic for more fine-tuned load balancing, or to orchestrate "zero-downtime" scaling/updating by handing off traffic to a new deployment of sessions with a higher or lower `num_shards` count that are prepared in parallel. +This allows you to create sessions that will handle more or less traffic for more fine-tuned load balancing, or to orchestrate "zero-downtime" scaling/updating by handing off traffic to a new deployment of sessions with a higher or lower `num_shards` count that are prepared in parallel. ###### Max Concurrency From 8f3636b61cdf9ff2556c59605af888eeeb46cd57 Mon Sep 17 00:00:00 2001 From: meep Date: Fri, 10 May 2024 16:53:02 +0200 Subject: [PATCH 2/5] Fix link --- docs/topics/Gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index 19ca71eb9a..2fa4ec9299 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -583,7 +583,7 @@ Every session with `shard_id = 0` will be subscribed to DM's and other non-guild As an example, if you wanted to split events equally between three shards, you'd use the following values for `shard` for each session: `[0, 3]`, `[1, 3]`, and `[2, 3]`. DM's would only be sent to the `[0, 3]` shard. -Note that `num_shards` does not relate to (or limit) the total number of potential sessions, and can be different between multiple sessions existing at the same time. It is only used to decide whether an event will be sent to the associated session using the [Sharding Formula](#sharding-formula) above. In the simple case like the example above, where every session has the same `num_shards` and the sessions respective `shard_id`'s cover every value from `0` to `num_shards - 1`, the events will be split evenly between the sessions. This is probably how most bots will operate. +Note that `num_shards` does not relate to (or limit) the total number of potential sessions, and can be different between multiple sessions existing at the same time. It is only used to decide whether an event will be sent to the associated session using the [Sharding Formula](#DOCS_TOPICS_GATEWAY_EVENTS/sharding-sharding-formula) above. In the simple case like the example above, where every session has the same `num_shards` and the sessions respective `shard_id`'s cover every value from `0` to `num_shards - 1`, the events will be split evenly between the sessions. This is probably how most bots will operate. On the other hand, sessions do not have to be identified in an evenly-distributed manner when sharding. You can establish multiple sessions with the same `[shard_id, num_shards]`, or sessions with different `num_shards` values, in which case events may be sent to multiple sessions. For example, two sessions with the respective `shard` arrays `[2, 3]` and `[4, 5]` will both receive events from the guild with id `613425648685547541` (you can open up Python and check for yourself that `2 == (613425648685547541 >> 22) % 3` and `4 == (613425648685547541 >> 22) % 5`). From 1e8ea76371071d79263d7e5a8cb6dc795c728bba Mon Sep 17 00:00:00 2001 From: meep Date: Fri, 10 May 2024 16:58:30 +0200 Subject: [PATCH 3/5] Actually fix link Sorry :) --- docs/topics/Gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index 2fa4ec9299..2e68cb57d8 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -583,7 +583,7 @@ Every session with `shard_id = 0` will be subscribed to DM's and other non-guild As an example, if you wanted to split events equally between three shards, you'd use the following values for `shard` for each session: `[0, 3]`, `[1, 3]`, and `[2, 3]`. DM's would only be sent to the `[0, 3]` shard. -Note that `num_shards` does not relate to (or limit) the total number of potential sessions, and can be different between multiple sessions existing at the same time. It is only used to decide whether an event will be sent to the associated session using the [Sharding Formula](#DOCS_TOPICS_GATEWAY_EVENTS/sharding-sharding-formula) above. In the simple case like the example above, where every session has the same `num_shards` and the sessions respective `shard_id`'s cover every value from `0` to `num_shards - 1`, the events will be split evenly between the sessions. This is probably how most bots will operate. +Note that `num_shards` does not relate to (or limit) the total number of potential sessions, and can be different between multiple sessions existing at the same time. It is only used to decide whether an event will be sent to the associated session using the [Sharding Formula](#DOCS_TOPICS_GATEWAY/sharding-sharding-formula) above. In the simple case like the example above, where every session has the same `num_shards` and the sessions respective `shard_id`'s cover every value from `0` to `num_shards - 1`, the events will be split evenly between the sessions. This is probably how most bots will operate. On the other hand, sessions do not have to be identified in an evenly-distributed manner when sharding. You can establish multiple sessions with the same `[shard_id, num_shards]`, or sessions with different `num_shards` values, in which case events may be sent to multiple sessions. For example, two sessions with the respective `shard` arrays `[2, 3]` and `[4, 5]` will both receive events from the guild with id `613425648685547541` (you can open up Python and check for yourself that `2 == (613425648685547541 >> 22) % 3` and `4 == (613425648685547541 >> 22) % 5`). From e2c697464b47e54410acc3c7b232170e6f197540 Mon Sep 17 00:00:00 2001 From: meep <15966053+GitMeep@users.noreply.github.com> Date: Sat, 11 May 2024 00:49:51 +0900 Subject: [PATCH 4/5] Apply suggestions from code review Thank you for looking it through and fixing my mistakes :) Co-authored-by: Zoddo --- docs/topics/Gateway.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index 2e68cb57d8..ea13749046 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -566,12 +566,12 @@ As apps grow and are added to an increasing number of guilds, some developers ma > warn > Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. -Sessions that would like to only receive events from a subset of guilds should send the `shard` array in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload. The first item in this array is `shard_id`, the zero-based integer value of the current shard, while the second is `total_shards` and represents the total number of shards. +Sessions that would like to only receive events from a subset of guilds should send the `shard` array in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload. The first item in this array is `shard_id`, the zero-based integer value of the current shard, while the second is `num_shards` and represents the total number of shards. > info > The [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field -A certain gateway session is only subscribed to events from guilds with a `guild_id` that fulfil the following formula, using the `shard_id` and `num_shards` that the session provided in the Identify event: +A certain gateway session is only subscribed to events from guilds with a `guild_id` that fulfil the following formula, using the `shard_id` and `num_shards` that the session provided in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event: ###### Sharding Formula @@ -579,9 +579,9 @@ A certain gateway session is only subscribed to events from guilds with a `guild shard_id == (guild_id >> 22) % num_shards ``` -Every session with `shard_id = 0` will be subscribed to DM's and other non-guild related events. +Every session with `shard_id = 0` will be subscribed to DMs and other non-guild related events. -As an example, if you wanted to split events equally between three shards, you'd use the following values for `shard` for each session: `[0, 3]`, `[1, 3]`, and `[2, 3]`. DM's would only be sent to the `[0, 3]` shard. +As an example, if you wanted to split events equally between three shards, you'd use the following values for `shard` for each session: `[0, 3]`, `[1, 3]`, and `[2, 3]`. DMs would only be sent to the `[0, 3]` shard. Note that `num_shards` does not relate to (or limit) the total number of potential sessions, and can be different between multiple sessions existing at the same time. It is only used to decide whether an event will be sent to the associated session using the [Sharding Formula](#DOCS_TOPICS_GATEWAY/sharding-sharding-formula) above. In the simple case like the example above, where every session has the same `num_shards` and the sessions respective `shard_id`'s cover every value from `0` to `num_shards - 1`, the events will be split evenly between the sessions. This is probably how most bots will operate. From 9cb9abc1c46e9818983ed947f905fb37d159c594 Mon Sep 17 00:00:00 2001 From: meep <15966053+GitMeep@users.noreply.github.com> Date: Fri, 17 May 2024 07:47:17 +0900 Subject: [PATCH 5/5] Apply suggestions from code review Word choice and formula disambiguation Co-authored-by: Oliver Wilkes Co-authored-by: Zoddo --- docs/topics/Gateway.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index ea13749046..3975ee298d 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -571,12 +571,12 @@ Sessions that would like to only receive events from a subset of guilds should s > info > The [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field -A certain gateway session is only subscribed to events from guilds with a `guild_id` that fulfil the following formula, using the `shard_id` and `num_shards` that the session provided in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event: +A certain gateway session is only subscribed to events from guilds with a `guild_id` that satisfies the following formula, using the `shard_id` and `num_shards` that the session provided in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event: ###### Sharding Formula ```python -shard_id == (guild_id >> 22) % num_shards +(guild_id >> 22) % num_shards == shard_id ``` Every session with `shard_id = 0` will be subscribed to DMs and other non-guild related events.