Skip to content

Commit

Permalink
[docs] add resume_gateway_url documentation (#5282)
Browse files Browse the repository at this point in the history 
* [docs] add resume_gateway_url documentation

* Update docs/topics/Gateway.md

Co-authored-by: Florian Spieß <[email protected]>

* Update docs/topics/Gateway.md

Co-authored-by: snek <[email protected]>

* Update docs/topics/Gateway.md

Co-authored-by: snek <[email protected]>

Co-authored-by: Florian Spieß <[email protected]>
Co-authored-by: snek <[email protected]>
  • Loading branch information
@daisyzhou @MinnDevelopment @devsnek
3 people authored Aug 9, 2022
1 parent b21abbe commit 30b37e5
Showing 1 changed file with 12 additions and 9 deletions.
21 changes: 12 additions & 9 deletions docs/topics/Gateway.md
View file
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

0 comments on commit 30b37e5

Please sign in to comment.