shards

README

Shards

Configurable, scalable and automatic sharding library for discordgo.

Features

• Automatic scaling: head-ache free configuration runs out of the box.
• Zero-downtime restarts: make downtime a thing of the past.
• Slash commands: integrate the latest in Discord functionality.

Installing

This assumes you already have a working Go environment, if not please install Go first.

go get github.com/servusdei2018/shards/v2

Usage

Import the package into your project, like so:

import "github.com/servusdei2018/shards/v2"

Buy me a Coffee

License

The MIT License (MIT)

Copyright (c) 2023-present The Shards Authors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• Constants
• type Manager
  • func New(token string) (mgr *Manager, err error)
  • func (m *Manager) AddHandler(handler interface{})
  • func (m *Manager) ApplicationCommandBulkOverwrite(guildID string, cmds []*discordgo.ApplicationCommand) (errs []error)
  • func (m *Manager) ApplicationCommandCreate(guildID string, cmd *discordgo.ApplicationCommand) (errs []error)
  • func (m *Manager) ApplicationCommandDelete(guildID string, cmd *discordgo.ApplicationCommand) (errs []error)
  • func (m *Manager) GuildCount() (count int)
  • func (m *Manager) RegisterIntent(intent discordgo.Intent)
  • func (m *Manager) Restart() (nMgr *Manager, err error)
  • func (m *Manager) SessionForDM() *discordgo.Session
  • func (m *Manager) SessionForGuild(guildID int64) *discordgo.Session
  • func (m *Manager) SetShardCount(count int)
  • func (m *Manager) Shutdown() (err error)
  • func (m *Manager) Start() (err error)
• type Shard
  • func (s *Shard) AddHandler(handler interface{})
  • func (s *Shard) ApplicationCommandBulkOverwrite(guildID string, cmds []*discordgo.ApplicationCommand) error
  • func (s *Shard) ApplicationCommandCreate(guildID string, cmd *discordgo.ApplicationCommand) error
  • func (s *Shard) ApplicationCommandDelete(guildID string, cmd *discordgo.ApplicationCommand) error
  • func (s *Shard) GuildCount() (count int)
  • func (s *Shard) Init(token string, ID, ShardCount int, intent discordgo.Intent) (err error)
  • func (s *Shard) Stop() (err error)

Constants

const (
	// TIMELIMIT specifies how long to pause between connecting shards.
	TIMELIMIT = time.Millisecond * 500
	// VERSION specifies the shards module version. Follows semantic versioning (semver.org).
	VERSION = "2.4.0"
)

Types

type Manager

type Manager struct {
	sync.RWMutex

	// Discord gateway.
	Gateway *discordgo.Session
	// Discord intent.
	Intent discordgo.Intent
	// Shards managed by this Manager.
	Shards []*Shard
	// Total Shard count.
	ShardCount int
	// contains filtered or unexported fields
}

Manager facilitates the management of Shards.

func New

func New(token string) (mgr *Manager, err error)

New creates a new Manager with the recommended number of shards. After calling New, call Start to begin connecting the shards.

Example: mgr := shards.New("Bot TOKEN")

func (*Manager) AddHandler

func (m *Manager) AddHandler(handler interface{})

AddHandler registers an event handler for all Shards.

func (*Manager) ApplicationCommandBulkOverwrite

func (m *Manager) ApplicationCommandBulkOverwrite(guildID string, cmds []*discordgo.ApplicationCommand) (errs []error)

ApplicationCommandBulkOverwrite registers a series of application commands for all Shards, overwriting existing commands.

func (*Manager) ApplicationCommandCreate

func (m *Manager) ApplicationCommandCreate(guildID string, cmd *discordgo.ApplicationCommand) (errs []error)

ApplicationCommandCreate registers an application command for all Shards.

func (*Manager) ApplicationCommandDelete

func (m *Manager) ApplicationCommandDelete(guildID string, cmd *discordgo.ApplicationCommand) (errs []error)

ApplicationCommandDelete deregisters an application command for all Shards.

func (*Manager) GuildCount

func (m *Manager) GuildCount() (count int)

GuildCount returns the amount of guilds that a Manager's Shards are handling.

func (*Manager) RegisterIntent

func (m *Manager) RegisterIntent(intent discordgo.Intent)

RegisterIntent sets the Intent for all Shards' sessions.

func (*Manager) Restart

func (m *Manager) Restart() (nMgr *Manager, err error)

Restart restarts the Manager, and rescales if necessary, all with zero downtime.

func (*Manager) SessionForDM

func (m *Manager) SessionForDM() *discordgo.Session

SessionForDM returns the proper session for sending and receiving DM's.

func (*Manager) SessionForGuild

func (m *Manager) SessionForGuild(guildID int64) *discordgo.Session

SessionForGuild returns the proper session for the specified guild.

func (*Manager) SetShardCount

func (m *Manager) SetShardCount(count int)

SetShardCount sets the shard count. The new shard count won't take effect until the Manager is restarted.

func (*Manager) Shutdown

func (m *Manager) Shutdown() (err error)

Shutdown gracefully terminates the Manager.

func (*Manager) Start

func (m *Manager) Start() (err error)

Start starts the Manager.

type Shard

type Shard struct {
	sync.RWMutex

	// The Discord session handling this Shard.
	Session *discordgo.Session
	// This Shard's ID.
	ID int
	// Total Shard count.
	ShardCount int
	// contains filtered or unexported fields
}

A Shard represents a shard.

func (*Shard) AddHandler

func (s *Shard) AddHandler(handler interface{})

AddHandler registers an event handler for a Shard.

Shouldn't be called after Init or results in undefined behavior.

func (*Shard) ApplicationCommandBulkOverwrite

func (s *Shard) ApplicationCommandBulkOverwrite(guildID string, cmds []*discordgo.ApplicationCommand) error

ApplicationCommandBulkOverwrite registers a series of application commands for a Shard, overwriting existing commands.

Shouldn't be called before Initialization.

func (*Shard) ApplicationCommandCreate

func (s *Shard) ApplicationCommandCreate(guildID string, cmd *discordgo.ApplicationCommand) error

ApplicationCommandCreate registers an application command for a Shard.

Shouldn't be called before Initialization.

func (*Shard) ApplicationCommandDelete

func (s *Shard) ApplicationCommandDelete(guildID string, cmd *discordgo.ApplicationCommand) error

ApplicationCommandDelete deregisters an application command for a Shard.

Shouldn't be called before Initialization.

func (*Shard) GuildCount

func (s *Shard) GuildCount() (count int)

GuildCount returns the amount of guilds that a Shard is handling.

func (*Shard) Init

func (s *Shard) Init(token string, ID, ShardCount int, intent discordgo.Intent) (err error)

Init initializes a shard with a bot token, its Shard ID, the total amount of shards, and a Discord intent.

func (*Shard) Stop

func (s *Shard) Stop() (err error)

Stop stops a shard.