From 59224cf588d092dd1338d3b420537a9aa45d9821 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Fri, 24 May 2024 01:41:45 +0100 Subject: [PATCH 1/5] Update manual shard method documentation in Nostrum.Shard.Supervisor --- lib/nostrum/shard/supervisor.ex | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/lib/nostrum/shard/supervisor.ex b/lib/nostrum/shard/supervisor.ex index 1a2afc70e..8adef3740 100644 --- a/lib/nostrum/shard/supervisor.ex +++ b/lib/nostrum/shard/supervisor.ex @@ -145,7 +145,17 @@ defmodule Nostrum.Shard.Supervisor do @doc """ Disconnects the shard with the given shard number from the Gateway. - This function returns `resume_information` given to `Nostrum.Shard.Supervisor.reconnect/1`. + + This function returns `t:resume_information/0` which can be provided + to `reconnect/1` to reconnect a shard to the gateway and (attempt) to + catch up on any missed events. + + ### Examples + + ```elixir + iex> Nostrum.Shard.Supervisor.disconnect(4) + %{shard_num: 4, ...} + ``` """ @spec disconnect(shard_num()) :: resume_information() def disconnect(shard_num) do @@ -165,8 +175,23 @@ defmodule Nostrum.Shard.Supervisor do end @doc """ - Reconnect to the gateway using the given `resume_information`. - For more information about resume, please visit [the Discord Developer Portal](https://discord.com/developers/docs/topics/gateway#resuming). + Reconnect to the gateway using the provided `t:resume_information/0`. + + Resuming is performed by the gateway on a best effort basis, it is not guaranteed + that a resume will work (though Nostrum will handle failed attempts at a resumption), + it is also not guaranteed that missed events will be delivered, or delivered events may + be received multiple times after a resumption. + + For more information about resuming sessions, visit + [the Discord Developer Portal](https://discord.com/developers/docs/topics/gateway#resuming). + + ### Examples + + ```elixir + iex> resume = Nostrum.Shard.Supervisor.disconnect(4) + %{shard_num: 4, ...} + iex> Nostrum.Shard.Supervisor.reconnect(resume) + ``` """ @spec reconnect(resume_information()) :: DynamicSupervisor.on_start_child() def reconnect( From fefb6420e1d459df35d516789584845a3391e501 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Fri, 24 May 2024 01:42:08 +0100 Subject: [PATCH 2/5] Add new advanced docs page on manual sharding --- guides/advanced/manual_sharding.md | 26 ++++++++++++++++++++++++++ mix.exs | 1 + 2 files changed, 27 insertions(+) create mode 100644 guides/advanced/manual_sharding.md diff --git a/guides/advanced/manual_sharding.md b/guides/advanced/manual_sharding.md new file mode 100644 index 000000000..48d523f40 --- /dev/null +++ b/guides/advanced/manual_sharding.md @@ -0,0 +1,26 @@ +# Manual Sharding + +Advanced users can use methods located in the `Nostrum.Shard.Supervisor` module +to manually connect shards to the gateway as well as initiate manual disconnect +and reconnects (attempting to `RESUME` sessions where possible). + +You can set the `num_shards` option in your `nostrum` application config to +`:manual` to prevent Nostrum from automatically starting shards. You should use +the methods in the shard supervisor such as `Nostrum.Shard.Supervisor.connect/2` +to manually start shards if using this configuration option. + +## Reconnection example + +```elixir +# On Node A +iex> Nostrum.Shard.Supervisor.connect(0, 1) +iex> resume_info = Nostrum.Shard.Supervisor.disconnect(0) +%{shard_num: 0, ...} + +# On another node +iex> Nostrum.Shard.Supervisor.reconnect(resume_info) +``` + +Discord will perform a best effort attempt to resume the gateway from the time +of disconnection, relaying any missed events. Note that this can result in some +events being missed or some events being delivered twice. diff --git a/mix.exs b/mix.exs index 12c4b0fac..a4b3b18b7 100644 --- a/mix.exs +++ b/mix.exs @@ -82,6 +82,7 @@ defmodule Nostrum.Mixfile do "guides/advanced/multi_node.md", "guides/advanced/hot_code_upgrade.md", "guides/advanced/gateway_compression.md", + "guides/advanced/manual_sharding.md", "guides/cheat-sheets/api.cheatmd", "guides/cheat-sheets/qlc.cheatmd", "guides/cheat-sheets/voice.cheatmd" From 0853449a4302a6af1eed8464a9aca4c1136c51f2 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Fri, 24 May 2024 17:11:51 +0100 Subject: [PATCH 3/5] Change wording to remove mentions of duplicate events This should not happen with RESUME events, the only situation we can have in theory is the gateway losing events if the reconnect fails. We already market this functionality only to advanced users who should be aware of the risks and intricacies of reconnection. --- guides/advanced/manual_sharding.md | 5 +++-- lib/nostrum/shard/supervisor.ex | 9 +++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/guides/advanced/manual_sharding.md b/guides/advanced/manual_sharding.md index 48d523f40..4c1d90b56 100644 --- a/guides/advanced/manual_sharding.md +++ b/guides/advanced/manual_sharding.md @@ -22,5 +22,6 @@ iex> Nostrum.Shard.Supervisor.reconnect(resume_info) ``` Discord will perform a best effort attempt to resume the gateway from the time -of disconnection, relaying any missed events. Note that this can result in some -events being missed or some events being delivered twice. +of disconnection, relaying any missed events. Resumption is not guaranteed to +work, in the event it fails Nostrum will reconnect the shard from scratch, +though this may mean some events are missed. diff --git a/lib/nostrum/shard/supervisor.ex b/lib/nostrum/shard/supervisor.ex index 8adef3740..3b610ae67 100644 --- a/lib/nostrum/shard/supervisor.ex +++ b/lib/nostrum/shard/supervisor.ex @@ -177,10 +177,11 @@ defmodule Nostrum.Shard.Supervisor do @doc """ Reconnect to the gateway using the provided `t:resume_information/0`. - Resuming is performed by the gateway on a best effort basis, it is not guaranteed - that a resume will work (though Nostrum will handle failed attempts at a resumption), - it is also not guaranteed that missed events will be delivered, or delivered events may - be received multiple times after a resumption. + Resuming is performed by the gateway on a best effort basis, it is not + guaranteed that a resume will work (though Nostrum will handle failed attempts + at a resumption). If a reconnect is successful, any events received during the + reconnection period should be received. If the reconnect fails, events + received between the disconnect and re-authentication may be lost. For more information about resuming sessions, visit [the Discord Developer Portal](https://discord.com/developers/docs/topics/gateway#resuming). From 4671ff2c4a6bd0f2299a7d467fd93ad323650479 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Fri, 24 May 2024 17:41:14 +0100 Subject: [PATCH 4/5] Link to manual sharding docs from intro under :manual sharding option --- guides/intro/intro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/intro/intro.md b/guides/intro/intro.md index 5b25b3a26..6c53e8b01 100644 --- a/guides/intro/intro.md +++ b/guides/intro/intro.md @@ -45,8 +45,8 @@ Apart from the `token` field mentioned above, the following fields are also supp should contain the total amount of shards that your bot is expected to have. Useful for splitting a single bot across multiple servers, but see also [the multi-node documentation](../advanced/multi_node.md). - - `:manual`: nostrum does not automatically spawn shards. You should use - `Nostrum.Shard.Supervisor.connect/2` to spawn shards instead. + - `:manual`: nostrum does not automatically spawn shards. See the [Manual + Sharding](../advanced/manual_sharding.md) guide for more information. - `gateway_intents` - a list of atoms representing gateway intents for Nostrum to subscribe to from the Discord API. More information can be found in the [gateway intents](./gateway_intents.md) documentation page. From ebd658b7ba6bba16b94d0271703dbf6986c87fe6 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Fri, 24 May 2024 17:13:26 +0100 Subject: [PATCH 5/5] Dynamically generate extras pages instead of hardcoded list This means that any future additions into `guides` will automatically be built by ExDoc when documentation is generated. There is no longer a need to add the page and then update the Mix file with the new page. --- mix.exs | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/mix.exs b/mix.exs index a4b3b18b7..a178ad24a 100644 --- a/mix.exs +++ b/mix.exs @@ -70,23 +70,10 @@ defmodule Nostrum.Mixfile do end def extras do - [ - "guides/intro/intro.md", - "guides/intro/api.md", - "guides/intro/application_commands.md", - "guides/intro/gateway_intents.md", - "guides/functionality/state.md", - "guides/functionality/event_handling.md", - "guides/functionality/voice.md", - "guides/advanced/pluggable_caching.md", - "guides/advanced/multi_node.md", - "guides/advanced/hot_code_upgrade.md", - "guides/advanced/gateway_compression.md", - "guides/advanced/manual_sharding.md", - "guides/cheat-sheets/api.cheatmd", - "guides/cheat-sheets/qlc.cheatmd", - "guides/cheat-sheets/voice.cheatmd" - ] + # We manually move the `intro.md` document to the top of the list so it + # remains first on the navigation sidebar + ["guides/intro/intro.md"] ++ + (Path.wildcard("guides/**/*.{md,cheatmd}") -- ["guides/intro/intro.md"]) end def groups_for_modules do