Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] add resume_gateway_url documentation #5282

Merged
merged 4 commits into from
Aug 9, 2022
Merged

[docs] add resume_gateway_url documentation #5282

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5501664
[docs] add resume_gateway_url documentation
daisyzhou Aug 4, 2022
e1e562b
Update docs/topics/Gateway.md
daisyzhou Aug 4, 2022
6ed3ffa
Update docs/topics/Gateway.md
daisyzhou Aug 5, 2022
0aa0869
Update docs/topics/Gateway.md
daisyzhou Aug 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions docs/topics/Gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ If the payload is valid, the gateway will respond with a [Ready](#DOCS_TOPICS_GA

The Internet is a scary place. Disconnections happen, especially with persistent connections. Due to Discord's architecture, this is a semi-regular event and should be expected and handled. Discord has a process for "resuming" (or reconnecting) a connection that allows the client to replay any lost events from the last sequence number they received in the exact same way they would receive them normally.

Your client should store the `session_id` from the [Ready](#DOCS_TOPICS_GATEWAY/ready), and the sequence number of the last event it received. When your client detects that it has been disconnected, it should completely close the connection and open a new one (following the same strategy as [Connecting](#DOCS_TOPICS_GATEWAY/connecting)). Once the new connection has been opened, the client should send a [Gateway Resume](#DOCS_TOPICS_GATEWAY/resume):
Your client should store the `session_id` and `resume_gateway_url` from the [Ready](#DOCS_TOPICS_GATEWAY/ready), and the sequence number of the last event it received. When your client detects that it has been disconnected, it should completely close the connection and open a new one (following the same strategy as [Connecting](#DOCS_TOPICS_GATEWAY/connecting)) to `resume_gateway_url`. Once the new connection has been opened, the client should send a [Gateway Resume](#DOCS_TOPICS_GATEWAY/resume):

###### Example Gateway Resume

Expand All @@ -188,6 +188,8 @@ Your client should store the `session_id` from the [Ready](#DOCS_TOPICS_GATEWAY/

If successful, the gateway will respond by replaying all missed events in order, finishing with a [Resumed](#DOCS_TOPICS_GATEWAY/resumed) event to signal replay has finished, and all subsequent events are new. It's also possible that your client cannot reconnect in time to resume, in which case the client will receive a [Opcode 9 Invalid Session](#DOCS_TOPICS_GATEWAY/invalid-session) and is expected to wait a random amount of time—between 1 and 5 seconds—then send a fresh [Opcode 2 Identify](#DOCS_TOPICS_GATEWAY/identify).

Failure to respect the `resume_gateway_url` may result in your client being forced to reconnect again after a short period of time.

### Disconnections

If the gateway ever issues a disconnect to your client, it will provide a close event code that you can use to properly handle the disconnection. A full list of these close codes can be found in the [Response Codes](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) documentation.
Expand Down Expand Up @@ -785,14 +787,15 @@ The ready event is dispatched when a client has completed the initial handshake

###### Ready Event Fields

| Field | Type | Description |
| ----------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| v | integer | [API version](#DOCS_REFERENCE/api-versioning-api-versions) |
| user | [user](#DOCS_RESOURCES_USER/user-object) object | information about the user including email |
| guilds | array of [Unavailable Guild](#DOCS_RESOURCES_GUILD/unavailable-guild-object) objects | the guilds the user is in |
| session_id | string | used for resuming connections |
| shard? | array of two integers (shard_id, num_shards) | the [shard information](#DOCS_TOPICS_GATEWAY/sharding) associated with this session, if sent when identifying |
| application | partial [application object](#DOCS_RESOURCES_APPLICATION/application-object) | contains `id` and `flags` |
| Field | Type | Description |
| ------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| v | integer | [API version](#DOCS_REFERENCE/api-versioning-api-versions) |
| user | [user](#DOCS_RESOURCES_USER/user-object) object | information about the user including email |
| guilds | array of [Unavailable Guild](#DOCS_RESOURCES_GUILD/unavailable-guild-object) objects | the guilds the user is in |
| session_id | string | used for resuming connections |
| resume_gateway_url | string | gateway url for resuming connections |
| shard? | array of two integers (shard_id, num_shards) | the [shard information](#DOCS_TOPICS_GATEWAY/sharding) associated with this session, if sent when identifying |
| application | partial [application object](#DOCS_RESOURCES_APPLICATION/application-object) | contains `id` and `flags` |

#### Resumed

Expand Down