shard

README

Disgo Shard Manager

The Disgo Shard Manager is a Go module that automatically handles sharding for your Discord Bot.

The Disgo Shard Manager works by managing the connection of multiple disgo.Session and setting the Session.Shard field:

1. The Client requests GET /gateway/bot to retrieve the recommended number of shards by Discord.
2. These shards (defining traffic routes of guild event data) are assigned to a disgo.Session, which is then connected to Discord.

For more information about the concept of sharding, read What is a Discord Shard?.

Implementation

Sharding is a three-step process that involves implementing shard-logic in your application and sharding your infrastructure (optional).

Import

Get a specific version of shard by specifying a tag or branch.

go get github.com/switchupcb/disgo/shard@v1.10.1

Disgo branches are referenced by API version (i.e v10).

Sharding the Discord Bot

Set the Client.Config.Gateway.ShardManager field to a shard.InstanceShardManager.

bot.Config.Gateway.ShardManager = new(shard.InstanceShardManager)

Change the instantiated disgo.Session variable to the bot's shard.InstanceShardManager.

// Change this line.
s := disgo.NewSession()

// To this line.
s := bot.Config.Gateway.ShardManager

// Find and replace existing `SendEvent` function calls with `SendEvents`
// to send events with every Shard Manager session.

This is all that's required to implement sharding.

Discord's sharding requirement aims to minimize the amount of data that Discord sends per WebSocket Session. Nothing is stopping you from running a Discord Bot that creates multiple sessions and handles them in one instance.

But read on if you want to shard the Discord Bot's infrastructure too.

Sharding the Infrastructure

Discord doesn't let you select which shard a guild is defined on. This has implications on how you shard the infrastructure of a Discord Bot.

Ignoring a shard is equivalent to ignoring all incoming guild event data from that shard. So it's expected that you handle every event from a shard in a Discord Bot instance (unless a load balancer is involved).

These constraints define the most straightforward sharding strategy:

1. Host multiple instances of your Discord Bot (copies of a single codebase); each with the ability to handle all incoming events.
2. Host a central "Shard Manager instance" that each Discord Bot instance communicates to shard.

This sharding strategy is based on active-active load balancing and must be implemented using a modified shard manager.

Read "Implementing a Sharding Strategy (Guide)" for more information about implementing an alternative sharding strategy.

QA

When do I need to shard?

Discord requires you to shard your Discord Bot once it's in a certain number of guilds.

What are the implications of using one server to shard?

Servers are computers with CPU, RAM, and Storage. You typically run one application on a server because you expect that application to use all of the server's resources (i.e 100% CPU, 100% RAM, etc).

Placing multiple applications on one server is only useful when your application does NOT use all of the server's resources, cores, etc. This strategy implies that your application handles a low amount of data, experiences a bottleneck (e.g., waiting on a network request), or maintains a consistent load.

If a server with two cores — without any form of multithreading — has an application using <100% CPU on one core, then you can add an additional application (that uses the other core) to the server without a performance hit.

In practice, scaling this way is NOT this straightforward.

If you need to shard your bot efficiently, you probably need to use multiple servers with multiple applications that all represent your "Discord Bot" as a single entity: This entity — containing multiple servers — is known as a cluster.

Each servers' application(s) would accept a different amount of shards and process the shard's data accordingly. Keep in mind that these applications CAN be built from the same codebase that was used before sharding, but require modification if the bot implements cross-guild functionality.

Otherwise, all most cases require is for you to implement this module in your application.

Documentation

Overview

Package shard provides a shard manager for Disgo.

Index

• Constants
• type InstanceShardManager
  • func (sm *InstanceShardManager) Connect(bot *disgo.Client) error
  • func (sm *InstanceShardManager) Disconnect() error
  • func (sm *InstanceShardManager) GetSessions() []*disgo.Session
  • func (sm *InstanceShardManager) Ready(bot *disgo.Client, session *disgo.Session, ready *disgo.Ready)
  • func (sm *InstanceShardManager) Reconnect() error
  • func (sm *InstanceShardManager) SetLimit(bot *disgo.Client) (*disgo.GetGatewayBotResponse, error)
  • func (sm *InstanceShardManager) SetNumShards(shards int)

Constants

const (
	// LogCtxShardManager represents the log key for an InstanceShardManager.
	LogCtxShardManager = "shardmanager"
)

Types

type InstanceShardManager

type InstanceShardManager struct {
	// Shards represents the number of shards this shard manager uses.
	//
	// When Shards = 0, the automatic shard manager is used.
	Shards int

	// Limit contains information about a client's sharding limits.
	Limit *disgo.ShardLimit

	// Sessions represents a list of sessions sorted by shard_id (in order of connection).
	Sessions []*disgo.Session
}

InstanceShardManager is a shard manager for a Discord Bot that runs on a single instance.

This shard manager routes every shard to every session (1).

func (*InstanceShardManager) Connect

func (sm *InstanceShardManager) Connect(bot *disgo.Client) error

func (*InstanceShardManager) Disconnect

func (sm *InstanceShardManager) Disconnect() error

Disconnect disconnects from the Discord Gateway using the Shard Manager.

func (*InstanceShardManager) GetSessions

func (sm *InstanceShardManager) GetSessions() []*disgo.Session

func (*InstanceShardManager) Ready

func (sm *InstanceShardManager) Ready(bot *disgo.Client, session *disgo.Session, ready *disgo.Ready)

func (*InstanceShardManager) Reconnect

func (sm *InstanceShardManager) Reconnect() error

Reconnect connects to the Discord Gateway using the Shard Manager.

func (*InstanceShardManager) SetLimit

func (sm *InstanceShardManager) SetLimit(bot *disgo.Client) (*disgo.GetGatewayBotResponse, error)

func (*InstanceShardManager) SetNumShards

func (sm *InstanceShardManager) SetNumShards(shards int)