Clustering and Sharding

In Discord's API, there is a need for doing "Sharding", basically splitting the bot into multiple parts when it's on a lot of guilds.

Specifically, Discord requires a maximum of 2500 guilds per websocket connection (what receives most events, and sometimes sends some). This means that a bot must establish multiple websocket connections as it grows larger.

Detritus has two ways of dealing with the sharding requirements: ClusteringClient and ShardingClient. Let's take a look at how they both work!

ClusteringClient

Clustering is the simplest way to deal with a sharded bot, since what it does is simply establish multiple websocket connections from the same process, as much as is necessary. This greatly simplifies data exchange between shards, as well as caching, because everything is in one process and can communicate. However, because it is single-threaded, it cannot scale well for larger bots. Also, again since everything is a single process, you're limited to the typical 4GB of RAM for reach nodejs process (though that can be raised if you want).

ShardingClient

Actual Sharding can be done using the ShardingClient which will spawn completely separate threads for each of your shards. Obviously, this leads to the contrary of Clustering: it can scale much more, but is more complicated due to the inter-process communication required to exchange data between processes. It also has a bit more overhead since some things can be duplicated between shards (like users being cached, for example).

Which one to choose?

Basically you choose the ClusteringClient if you have a relatively simple bot that doesn't use too much resources, all the way up to perhaps 25k, 40k guilds depending on what sort of power you need.

You choose the ShardingClient if you require more control over your processes and memory used, and for "very large bots" and their massive requirements.