sharding

Documentation

Index

• Constants
• func ShardIDByGuild(guildID snowflake.ID, shardCount int) int
• func ShardMaxConcurrencyKey(shardID int, maxConcurrency int) int
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Apply(opts []ConfigOpt)
• type ConfigOpt
  • func WithAutoScaling(autoScaling bool) ConfigOpt
  • func WithGatewayConfigOpts(opts ...gateway.ConfigOpt) ConfigOpt
  • func WithGatewayCreateFunc(gatewayCreateFunc gateway.CreateFunc) ConfigOpt
  • func WithLogger(logger *slog.Logger) ConfigOpt
  • func WithRateLimiter(rateLimiter RateLimiter) ConfigOpt
  • func WithRateLimiterConfigOpt(opts ...RateLimiterConfigOpt) ConfigOpt
  • func WithShardCount(shardCount int) ConfigOpt
  • func WithShardIDs(shardIDs ...int) ConfigOpt
  • func WithShardSplitCount(shardSplitCount int) ConfigOpt
• type RateLimiter
  • func NewNoopRateLimiter() RateLimiter
  • func NewRateLimiter(opts ...RateLimiterConfigOpt) RateLimiter
• type RateLimiterConfig
  • func DefaultRateLimiterConfig() *RateLimiterConfig
  • func (c *RateLimiterConfig) Apply(opts []RateLimiterConfigOpt)
• type RateLimiterConfigOpt
  • func WithMaxConcurrency(maxConcurrency int) RateLimiterConfigOpt
  • func WithRateLimiterLogger(logger *slog.Logger) RateLimiterConfigOpt
• type ShardManager
  • func New(token string, eventHandlerFunc gateway.EventHandlerFunc, opts ...ConfigOpt) ShardManager

Constants

const MaxConcurrency = 1

MaxConcurrency is the default number of shards that can log in at the same time.

const ShardSplitCount = 2

ShardSplitCount is the default count a shard should be split into when it needs re-sharding.

Functions

func ShardIDByGuild

func ShardIDByGuild(guildID snowflake.ID, shardCount int) int

ShardIDByGuild returns the shard ID for the given guildID and shardCount.

func ShardMaxConcurrencyKey

func ShardMaxConcurrencyKey(shardID int, maxConcurrency int) int

ShardMaxConcurrencyKey returns the bucket the given shardID with maxConcurrency belongs to.

Types

type Config

type Config struct {
	// Logger is the logger of the ShardManager. Defaults to log.Default()
	Logger *slog.Logger
	// ShardIDs is a map of shardIDs the ShardManager should manage. Leave this nil to manage all shards.
	ShardIDs map[int]struct{}
	// ShardCount is the total shard count of the ShardManager. Leave this at 0 to let Discord calculate the shard count for you.
	ShardCount int
	// ShardSplitCount is the count a shard should be split into if it is too large. This is only used if AutoScaling is enabled.
	ShardSplitCount int
	// AutoScaling will automatically re-shard shards if they are too large. This is disabled by default.
	AutoScaling bool
	// GatewayCreateFunc is the function which is used by the ShardManager to create a new gateway.Gateway. Defaults to gateway.New.
	GatewayCreateFunc gateway.CreateFunc
	// GatewayConfigOpts are the ConfigOpt(s) which are applied to the gateway.Gateway.
	GatewayConfigOpts []gateway.ConfigOpt
	// RateLimiter is the RateLimiter which is used by the ShardManager. Defaults to NewRateLimiter()
	RateLimiter RateLimiter
	// RateLimiterConfigOpts are the RateLimiterConfigOpt(s) which are applied to the RateLimiter.
	RateLimiterConfigOpts []RateLimiterConfigOpt
}

Config lets you configure your ShardManager instance.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func (*Config) Apply

func (c *Config) Apply(opts []ConfigOpt)

Apply applies the given ConfigOpt(s) to the Config

type ConfigOpt

type ConfigOpt func(config *Config)

ConfigOpt is a type alias for a function that takes a Config and is used to configure your Server.

func WithAutoScaling

func WithAutoScaling(autoScaling bool) ConfigOpt

WithAutoScaling sets whether the ShardManager should automatically re-shard shards if they are too large. This is disabled by default.

func WithGatewayConfigOpts

func WithGatewayConfigOpts(opts ...gateway.ConfigOpt) ConfigOpt

WithGatewayConfigOpts lets you configure the gateway.Gateway created by the ShardManager.

func WithGatewayCreateFunc

func WithGatewayCreateFunc(gatewayCreateFunc gateway.CreateFunc) ConfigOpt

WithGatewayCreateFunc sets the function which is used by the ShardManager to create a new gateway.Gateway.

func WithLogger

func WithLogger(logger *slog.Logger) ConfigOpt

WithLogger sets the logger of the ShardManager.

func WithRateLimiter

func WithRateLimiter(rateLimiter RateLimiter) ConfigOpt

WithRateLimiter lets you inject your own RateLimiter into the ShardManager.

func WithRateLimiterConfigOpt

func WithRateLimiterConfigOpt(opts ...RateLimiterConfigOpt) ConfigOpt

WithRateLimiterConfigOpt lets you configure the default RateLimiter used by the ShardManager.

func WithShardCount

func WithShardCount(shardCount int) ConfigOpt

WithShardCount sets the shard count of the ShardManager.

func WithShardIDs

func WithShardIDs(shardIDs ...int) ConfigOpt

WithShardIDs sets the shardIDs the ShardManager should manage.

func WithShardSplitCount

func WithShardSplitCount(shardSplitCount int) ConfigOpt

WithShardSplitCount sets the count a shard should be split into if it is too large. This is only used if AutoScaling is enabled.

type RateLimiter

type RateLimiter interface {
	// Close gracefully closes the RateLimiter.
	// If the context deadline is exceeded, the RateLimiter will be closed immediately.
	Close(ctx context.Context)

	// WaitBucket waits for the given shardID bucket to be available for new logins.
	// If the context deadline is exceeded, WaitBucket will return immediately and no login will be attempted.
	WaitBucket(ctx context.Context, shardID int) error

	// UnlockBucket unlocks the given shardID bucket.
	UnlockBucket(shardID int)
}

RateLimiter limits how many shards can log in to Discord at the same time.

func NewNoopRateLimiter

func NewNoopRateLimiter() RateLimiter

NewNoopRateLimiter creates a new noop RateLimiter.

func NewRateLimiter

func NewRateLimiter(opts ...RateLimiterConfigOpt) RateLimiter

NewRateLimiter creates a new default RateLimiter with the given RateLimiterConfigOpt(s).

type RateLimiterConfig

type RateLimiterConfig struct {
	Logger         *slog.Logger
	MaxConcurrency int
}

RateLimiterConfig lets you configure your RateLimiter instance.

func DefaultRateLimiterConfig

func DefaultRateLimiterConfig() *RateLimiterConfig

DefaultRateLimiterConfig returns a RateLimiterConfig with sensible defaults.

func (*RateLimiterConfig) Apply

func (c *RateLimiterConfig) Apply(opts []RateLimiterConfigOpt)

Apply applies the given RateLimiterConfigOpt(s) to the RateLimiterConfig

type RateLimiterConfigOpt

type RateLimiterConfigOpt func(config *RateLimiterConfig)

RateLimiterConfigOpt is a type alias for a function that takes a RateLimiterConfig and is used to configure your Server.

func WithMaxConcurrency

func WithMaxConcurrency(maxConcurrency int) RateLimiterConfigOpt

WithMaxConcurrency sets the maximum number of concurrent identifies in 5 seconds.

func WithRateLimiterLogger

func WithRateLimiterLogger(logger *slog.Logger) RateLimiterConfigOpt

WithRateLimiterLogger sets the logger for the RateLimiter.

type ShardManager

type ShardManager interface {
	// Open opens all configured shards.
	Open(ctx context.Context)
	// Close closes all shards.
	Close(ctx context.Context)

	// OpenShard opens a specific shard.
	OpenShard(ctx context.Context, shardID int) error

	// CloseShard closes a specific shard.
	CloseShard(ctx context.Context, shardID int)

	// ShardByGuildID returns the gateway.Gateway for the shard that contains the given guild.
	ShardByGuildID(guildId snowflake.ID) gateway.Gateway

	// Shard returns the gateway.Gateway for the given shard ID.
	Shard(shardID int) gateway.Gateway

	// Shards returns a copy of all shards as a map.
	Shards() map[int]gateway.Gateway
}

ShardManager manages multiple gateway.Gateway connections. For more information on sharding see: https://discord.com/developers/docs/topics/gateway#sharding

func New

func New(token string, eventHandlerFunc gateway.EventHandlerFunc, opts ...ConfigOpt) ShardManager

New creates a new default ShardManager with the given token, eventHandlerFunc and ConfigOpt(s).