sharding

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
}

type ConfigOpt func(config *Config)

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)
}

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

type RateLimiterConfigOpt func(config *RateLimiterConfig)

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
}