Merge pull request 'feature/improvements' (#8) from feature/improvements into main

Reviewed-on: #8

.gitignore

@@ -25,3 +25,5 @@ go.work.sum
 # env file
 .env
 
+/cmd/*
+/cmd

README.md

@@ -1,106 +1,104 @@
 # bolt
 
-The nuts-and-bolts of Discord bots. Bolt is a wrapper for [discordgo](https://github.com/bwmarrin/discordgo) that provides quick and easy bootstrapping for simple Discord bots.
+A fast [discordgo](https://github.com/bwmarrin/discordgo) wrapper for bootstrapping Discord bots.
 
 ## Usage
-### Token
+### Prerequisites
 Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN"
 
-### Commands
-Commands are represented by the command struct and contain all needed information for bolt to handle the command payload. Including the command timeout as well as the Roles allowed to run the command.
-```go
-type Command struct {
-	Trigger string        //command that triggers payload NOT including the indicator
-	Payload Payload       //payload function to run when a command is detected
-	Timeout time.Duration //the amount of time before command can be run again
-	lastRun time.Time     //timestamp of last command run
-	Roles   []string      //roles that can use command, if none are set anyone can run
-}
-```
-
-### Payload
-Payload functions are executed when a command is detected
-```go
-type Payload func(msg Message) error
-```
-Payload functions are given a Message argument containing the needed data for handling commands
-```go
-type Message struct {
-	Author      string   //username of message author
-	ID          string   //discord ID of message author
-	Words       []string //words from message split on whitespace
-	Content     string   //entire message content
-	Channel     string   //message channel
-	Server      string   //message guild
-	Attachments []MessageAttachment //message attachments
-}
-```
-The Message struct also exposes some methods to support replying to, or acknowledging command messages
-```go
-func (m *Message) React(emoji Reaction) error
-```
-The React method will react to the command message by adding the requested emoji as a reaction. Bolt comes with a few preset emoji's for easy handling but any valid emoji string can be passed.
-```go
-func (m *Message) Respond(res string) error
-```
-The Respond method will send the value of <b>res</b> in response to the command message.
-
 ### Example
 ```go
 package main
 
 import (
+	"fmt"
+	"strings"
 	"time"
 
 	"code.jakeyoungdev.com/jake/bolt"
+	_ "github.com/joho/godotenv/autoload"
 )
 
+/*
+A basic example of a bot with two commands and a general message handler for non-command messages. The bot uses a
+verbose log level which will log everything for debugging purposes, and registers Discord Intents for message and admin
+related permissions. This allows the bot to parse messages, send them, delete them, etc. as well as timeout and mute users.
+
+This example registers three commands:
+
+1. .ping - a basic ping/pong command that can be run by anyone at any time
+2. .wait - a dummy command that replies "okay" it can only be run by users with the "user" role and can only be ran once every 25 seconds
+3. .timeout - a admin command that can only be run by users with an "admin" role, this command will timeout any mentioned users for 5 minutes
+
+A message handler is also registered in this example, message handlers are used to handle messages that do not contain a command. This enables
+auto-moderation from the bot without manual intervention. The example message handler does two arbitrary things to demo functionality:
+
+1. Checks the message content for the phrase "swear word" and, if found, times the user out for 5 minutes
+2. Checks the message for the phrase "im going to yell in VoiceChat" and mutes the message author until Unmute is called on them
+*/
+
 func main() {
-	//bolt defaults the command indicator to '.' however that can be changed with the options
+	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelAll))
-	//Example: bolt.New(bolt.WithIndicator('!')) would support commands like !ping
+
-	b := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
+	if err != nil {
+		panic(err)
+	}
 
 	b.AddCommands(
-		// basic ping pong command, .ping can be run at anytime by anyone and will reply "pong"
 		bolt.Command{
 			Trigger: "ping",
-			Payload: func(msg bolt.Message) error {
+			Payload: func(c *bolt.Context) error {
-				return msg.Respond("pong")
+				return c.Respond("pong")
 			},
 		},
-		// .react will add a +1 reaction to the command message, .react can be run by anyone at any rate
 		bolt.Command{
-			Trigger: "react",
+			Trigger: "wait",
-			Payload: func(msg bolt.Message) error {
+			Payload: func(c *bolt.Context) error {
-				return msg.React(bolt.ReactionThumbsUp)
+				return c.Respond("okay")
-			},
-		},
-		// .time responds with the current date/time, .time can be run once every 25 seconds by any role
-		bolt.Command{
-			Trigger: "time",
-			Payload: func(msg bolt.Message) error {
-				return msg.Respond(time.Now().String())
 			},
 			Timeout: time.Second * 25,
+			Roles:   []string{"user"},
 		},
-		// .role command can be ran every 10 seconds by anyone with the admin role and will return the string "admin"
 		bolt.Command{
-			Trigger: "role",
+			Trigger: "timeout",
-			Payload: func(msg bolt.Message) error {
+			Payload: func(c *bolt.Context) error {
-				return msg.Respond("admin")
+				if len(c.Message.Mentions) > 0 {
+					count := 0
+					for _, m := range c.Message.Mentions {
+						err := c.Timeout(m.ID, time.Now().Add(time.Minute*5))
+						if err != nil {
+							return err
+						}
+						count++
+					}
+
+					return c.Respond(fmt.Sprintf("timed out %d users\n", count))
+				}
+				return nil
 			},
-			Timeout: time.Second * 10,
+			Roles: []string{"admin"},
-			Roles:   []string{"admin"},
 		},
 	)
 
-	//start is a blocking call that handles safe-shutdown, all configuration and setup should be done before calling Start()
+	b.AddMessageHandler(func(c *bolt.Context) error {
-	err := b.Start()
+		if strings.Contains(c.Message.Content, "swear word") {
+			return c.Timeout(c.Message.Author.ID, time.Now().Add(time.Hour*1))
+		}
+
+		if c.Message.Content == "im going to yell in VoiceChat" {
+			return c.Mute(c.Message.Author.ID)
+		}
+		return nil
+	})
+
+	err = b.Start()
 	if err != nil {
 		panic(err)
 	}
 }
+
 ```
 
 ## Development
-bolt is in development at the moment and may break occasionally before a v1 release
+bolt is in early development and may encounter breaking changes until a full v1 rollout, I will do my best to communicate
+these changes. Use a tagged version to avoid any surprises with live code in main

bolt.go

@@ -1,50 +1,76 @@
 package bolt
 
 import (
+	"context"
 	"fmt"
 	"log"
 	"os"
 	"os/signal"
 	"slices"
 	"strings"
-	"syscall"
+	"sync"
 	"time"
 
 	dg "github.com/bwmarrin/discordgo"
 )
 
 const (
-	TOKEN_ENV_VAR = "DISCORD_TOKEN" //label for token environment variable
+	//the name of the environment variable that should contain the token for the bot, it is
+	//required for bolt to run
+	TOKEN_ENV_VAR = "DISCORD_TOKEN"
 
-	BOT_INTENTS = dg.IntentGuilds |
+	//bot default command indicator, if messages begin with this substring they are processed
+	//through the command handler instead of the generic message handler
+	DEFAULT_INDICATOR = "."
+	//max amount of concurrent goroutines that bolt can use for events. A lower amount
+	//may lower the resource usage of bolt but may cause a delay in event handling
+	DEFAULT_MAX_GOROUTINES = 250
+
+	//minimum intents for bots to function, intents can be changed with options
+	DEFAULT_INTENTS = dg.IntentGuilds |
 		dg.IntentGuildMembers |
 		dg.IntentGuildPresences |
 		dg.IntentMessageContent |
-		dg.IntentsGuildMessages
+		dg.IntentsGuildMessages |
+		dg.IntentGuildMessageReactions
 )
 
-// basic bot structure containing discordgo connection as well as the command map
 type bolt struct {
-	*dg.Session                    //holds discordgo internals
+	//discordgo internals
-	commands    map[string]Command //maps trigger phrase to command struct for fast lookup
+	*dg.Session
-	indicator   string             //the indicator used to detect whether a message is a command
+	//maps trigger phrase to command struct for instant lookup
-	logLvl      LogLevel           //determines how much the bot logs
+	commands map[string]Command
+	//used to detect whether a message is a command
+	indicator string
+	//verbosity of logs bolt outputs
+	logLvl LogLevel
+	//waitgroup for event routines
+	wg sync.WaitGroup
+	//pool is a buffered channel used as a semaphore for event handler routines, it is limited to
+	//only spawn maxRoutines to handle events
+	pool        chan struct{}
+	maxRoutines int
+	//generic message handler func
+	msgHandlerf Payload
 }
 
 type Bolt interface {
 	Start() error
 	AddCommands(cmd ...Command)
+	AddMessageHandler(p Payload)
 	//filtered methods
 	stop() error
-	messageHandler(s *dg.Session, msg *dg.MessageCreate)
+	msgEventHandler(s *dg.Session, msg *dg.MessageCreate)
-	handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Guild, channel *dg.Channel, lg int) error
+	mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message
+	handleCommand(msgEvent *Message, lg int) error
+	handleMessage(event *Message) error
 	createReply(content, message, channel, guild string) *dg.MessageSend
-	getRemainingTimeout(timeout time.Time) string
+	remainingTimeout(timeout time.Time) string
-	roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
+	roleCheck(guild string, roles []string, s *dg.Session, run Command) (bool, error)
-	timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error)
+	timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error)
 }
 
-// create a new bolt interface
+// New creates a new bolt instance and applies any supplied options
 func New(opts ...Option) (Bolt, error) {
 	_, check := os.LookupEnv(TOKEN_ENV_VAR)
 	if !check {
@@ -55,61 +81,89 @@ func New(opts ...Option) (Bolt, error) {
 	if err != nil {
 		return nil, fmt.Errorf("failed to create Discord session: %e", err)
 	}
-	bot.Identify.Intents = BOT_INTENTS
 
 	b := &bolt{
-		Session:  bot,
+		Session:     bot,
-		commands: make(map[string]Command, 0),
+		commands:    make(map[string]Command, 0),
-		logLvl:   LogLevelAll,
+		logLvl:      LogLevelAll,
+		indicator:   DEFAULT_INDICATOR,
+		wg:          sync.WaitGroup{},
+		maxRoutines: DEFAULT_MAX_GOROUTINES,
 	}
-	//set default command indicator
-	b.indicator = "."
 
-	//apply options to bolt
+	b.Identify.Intents = DEFAULT_INTENTS
 	for _, opt := range opts {
 		opt(b)
 	}
 
+	//options can change max routine number, so create after
+	b.pool = make(chan struct{}, b.maxRoutines)
+
 	return b, nil
 }
 
-// starts the bot, commands are added and the connection to Discord is opened, this is a BLOCKING
+// Start applies the message event handler function to the bot and opens the initial websocket connection
-// call that handles safe shutdown of the bot
+// with Discord. Start is a blocking call that also handles safe shutdown, on Interrupt, bolt will give
+// command routines a window to finish before closing the connection.
 func (b *bolt) Start() error {
-	//register commands and open connection
+	b.AddHandler(b.msgEventHandler)
-	b.AddHandler(b.messageHandler)
-
 	err := b.Open()
 	if err != nil {
 		return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
 	}
 
-	//safe shutdown handler
+	log.Println("bot started")
+
 	sigChannel := make(chan os.Signal, 1)
-	signal.Notify(sigChannel, syscall.SIGINT)
+	signal.Notify(sigChannel, os.Interrupt)
 	<-sigChannel
 
-	if err := b.stop(); err != nil {
+	//give handler routines a 5 second window to finish processes before closing connection
-		return err
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)
+	defer cancel()
+	closeChan := make(chan struct{}, 0)
+	go func() {
+		b.wg.Wait()
+		close(closeChan)
+	}()
+
+	select {
+	case <-ctx.Done():
+		log.Println("shutdown timed out waiting for handlers to finish, some may have been incomplete")
+	case <-closeChan:
+		log.Println("handler routines cleaned")
 	}
 
-	return nil
+	log.Println("exiting")
+	return b.stop()
 }
 
-// stops the bot
+// AddCommands registers command handlers. Any messages that begin with the command indicator will be forwarded
-func (b *bolt) stop() error {
+// to the handler
-	return b.Close()
-}
-
-// adds commands to bot command map for use
 func (b *bolt) AddCommands(cmd ...Command) {
 	for _, c := range cmd {
 		b.commands[c.Trigger] = c
 	}
 }
 
-// handler function that parses message data and executes any command payloads
+// AddMessageHandler registers the generic message handler, any messages that are not commands will be forwarded
-func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
+// to the handler
+func (b *bolt) AddMessageHandler(p Payload) {
+	b.msgHandlerf = p
+}
+
+// stop closes the websocket connection to Discord
+func (b *bolt) stop() error {
+	return b.Close()
+}
+
+// msgEventHandler is a beefy boy that handles message logging, command parsing, and executing payload functions. It needs cleanup then
+// i'll worry about this comment
+
+// msgEventHandler handles the routing of messages to either the command or message handlers. If LogLvl is set, logging is handled here before
+// the event is mapped to the Message struct and forwarded to the handlers. Each message is handled in its own goroutine, the max allowed goroutines
+// is set as a default and can be altered using options for better performance.
+func (b *bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 	//get server information
 	server, err := s.Guild(msg.GuildID)
 	if err != nil {
@@ -122,84 +176,70 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
 		return
 	}
 
-	//if there is no content it is likely an image, gif, or sticker, updating message content for
-	//better logging and to avoid confusion
-	if len(msg.Content) == 0 {
-		msg.Content = "[Embedded Content]"
-	}
-
 	//the bot will ignore it's own messages to prevent command loops
 	if msg.Author.ID == s.State.User.ID {
-		if b.logLvl == LogLevelCmd {
+		if b.logLvl != LogLevelErr {
-			//log command responses
 			log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
 		}
 		return
 	}
 
 	if b.logLvl == LogLevelAll {
-		//log message
 		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
 	}
 
-	//does the message have the command indicator
+	m := b.mapEventToMsg(msg, channel, server)
 	lg := len(b.indicator)
 	if msg.Content[:lg] == b.indicator {
-		err := b.handleCommand(msg, s, server, channel, lg)
+		if b.logLvl == LogLevelCmd {
-		if err != nil {
+			log.Printf("< %s | %s | %s > %s\n", m.Server, m.Channel, m.Author.Name, m.Content)
-			log.Println(err)
-			return
 		}
+
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleCommand(&m, lg)
+			if err != nil {
+				log.Println(err)
+			}
+			<-b.pool //release routine
+		})
+	} else {
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleMessage(&m)
+			if err != nil {
+				log.Println(err)
+			}
+			<-b.pool //release routine
+		})
 	}
 }
 
-// parses command from message and handles timeout checks, role checks, and command execution. All command responses are sent back to Discord
+// mapEventToMsg maps the Discord event message struct into bolt's user-friendly Message struct
-func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Guild, channel *dg.Channel, lg int) error {
+func (b *bolt) mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message {
-	if b.logLvl == LogLevelCmd {
+	m := Message{
-		//log commands
+		Author: Author{
-		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+			Name:  msg.Author.Username,
-	}
+			ID:    msg.Author.ID,
-
+			Roles: msg.Member.Roles,
-	words := strings.Split(msg.Content, " ")
+		},
-	run, ok := b.commands[words[0][lg:]]
+		ID:        msg.ID,
-	if !ok {
-		return nil //command doesn't exist, maybe log or respond to author
-	}
-
-	//has command met its timeout requirements
-	tc, err := b.timeoutCheck(msg, s, run)
-	if err != nil {
-		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
-	}
-	if !tc {
-		return nil
-	}
-
-	//does user have correct permissions
-	if run.Roles != nil {
-		check, err := b.roleCheck(msg, s, run)
-		if err != nil {
-			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
-		}
-		if !check {
-			return nil
-		}
-	}
-
-	plMsg := Message{
-		Author:    msg.Author.Username,
-		ID:        msg.Author.ID,
-		msgID:     msg.ID,
-		Words:     words,
 		Content:   msg.Content,
 		Channel:   channel.Name,
-		channelID: msg.ChannelID,
+		ChannelID: channel.ID,
 		Server:    server.Name,
-		serverID:  server.ID,
+		ServerID:  server.ID,
-		sesh:      b,
+	}
+
+	w := strings.Fields(msg.Content)
+	if len(w) > 0 {
+		m.Words = w
+	}
+
+	if len(msg.Mentions) > 0 {
+		m.Mentions = msg.Mentions
 	}
 
-	//check for file attachments
 	if len(msg.Attachments) > 0 {
 		var att []MessageAttachment
 		for _, a := range msg.Attachments {
@@ -216,13 +256,69 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
 			})
 		}
 
-		plMsg.Attachments = att
+		m.Attachments = att
 	}
 
-	//run command payload
+	return m
-	err = run.Payload(plMsg)
+}
+
+// handleMessage forwards the message data to the handler function, if one is set
+func (b *bolt) handleMessage(event *Message) error {
+	if b.msgHandlerf != nil {
+		return b.msgHandlerf(&Context{
+			Message: event,
+			bolt:    b,
+		})
+	}
+
+	return nil
+}
+
+// handleCommand maps the first word of the message to the command payload, if it exists. It then forwards the message
+// data to the handler after checking the timeout and role restrictions. If restrictions have not been met a generic
+// response is sent to the message
+// TODO: accept a string for timeout/role rejection messages to allow customization
+func (b *bolt) handleCommand(msg *Message, lg int) error {
+	run, ok := b.commands[msg.Words[0][lg:]]
+	if !ok {
+		return nil //command doesn't exist
+	}
+
+	//has command met its timeout requirements, if timeout has not expired a response is sent to the message
+	//from the timeoutCheck method
+	tc, err := b.timeoutCheck(msg.ID, msg.ChannelID, msg.ServerID, b.Session, run)
 	if err != nil {
-		return fmt.Errorf("failed to execute payload function: %e", err)
+		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
+	}
+	//method handles sending a response, so we do not need to send another here, simply return
+	if !tc {
+		return nil
+	}
+
+	//does user have correct permissions to run this command
+	if run.Roles != nil {
+		check, err := b.roleCheck(msg.ServerID, msg.Author.Roles, b.Session, run)
+		if err != nil {
+			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
+		}
+		if !check {
+			//this alert should probably be moved into the roleCheck function to match the pattern of the timeoutCheck method
+			reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.ServerID)
+			_, err := b.Session.ChannelMessageSendComplex(msg.ChannelID, reply)
+			if err != nil {
+				return err
+			}
+			return nil
+		}
+	}
+
+	//execute handler func with message context
+	err = run.Payload(&Context{
+		Message: msg,
+		bolt:    b,
+	})
+	if err != nil {
+		return fmt.Errorf("encountered an error while handling command (%s): %e", msg.Words[0], err)
 	}
 
 	//update run time
@@ -231,7 +327,7 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu
 	return nil
 }
 
-// basic wrapper function to create easy Discord responses
+// createReploy is a basic wrapper function to map message data to the actual MessageSend struct
 func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageSend {
 	details := &dg.MessageReference{
 		MessageID: message,
@@ -245,8 +341,9 @@ func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageS
 	}
 }
 
-// used to calculate the remaining time left in a timeout and returning it in a human-readable format
+// remainingTimeout calculates the amount of time left before a command can be run again. Returning a string
-func (b *bolt) getRemainingTimeout(timeout time.Time) string {
+// representing a readable version of the time left, example: 1h (1 hour)
+func (b *bolt) remainingTimeout(timeout time.Time) string {
 	r := time.Until(timeout)
 	var (
 		timeLeft int
@@ -263,19 +360,23 @@ func (b *bolt) getRemainingTimeout(timeout time.Time) string {
 		}
 	}
 
+	//provide a user-friendly time string to send back to the user
 	return fmt.Sprintf("%d%s", timeLeft, metric)
 }
 
 // checks if the author of msg has the correct role to run the requested command
-func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error) {
+
+// roleCheck loops through the provided user role ID's grabs the role "name" and ensures the role is present
+// in the commands whitelist. If the role exists in the Command whitelist a true response is returned
+func (b *bolt) roleCheck(guild string, roles []string, s *dg.Session, run Command) (bool, error) {
 	var found bool
-	//loop thru author roles, there may be a better way to check for this UNION
+	//this needs a bit of love, looping through roles could get messy as server and role lists grow on big servers
-	//TODO: improve role search performance to support bigger lists
+	//especially with the Role() call inside of the loop
-	for _, r := range msg.Member.Roles {
+	for _, r := range roles {
 		//get role name from ID
-		n, err := s.State.Role(msg.GuildID, r)
+		n, err := s.State.Role(guild, r)
 		if err != nil {
-			return false, fmt.Errorf("failed to get role from ID %s\n%e", msg.GuildID, err)
+			return false, fmt.Errorf("failed to get role from ID %s\n%e", guild, err)
 		}
 		//does this role exist in command roles
 		check := slices.Contains(run.Roles, n.Name)
@@ -285,25 +386,17 @@ func (b *bolt) roleCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (boo
 		}
 	}
 
-	//can't find role, don't run command, alert user of missing permissions
+	return found, nil
-	if !found {
-		reply := b.createReply("you do not have permissions to run that command", msg.ID, msg.ChannelID, msg.GuildID)
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
-		if err != nil {
-			return false, fmt.Errorf("failed to send permission response: %e", err)
-		}
-		return false, nil
-	}
-
-	return true, nil
 }
 
-// check if the command timeout has been met, responding with remaining time if timeout has not been met yet.
+// timeoutCheck determines if a Command timeout has expired, if it hasn't expired a response is sent back to the message alerting the user
-func (b *bolt) timeoutCheck(msg *dg.MessageCreate, s *dg.Session, run Command) (bool, error) {
+// of the remaining time
+func (b *bolt) timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error) {
 	wait := run.lastRun.Add(run.Timeout)
-	if !time.Now().After(wait) {
+	now := time.Now()
-		reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.getRemainingTimeout(wait)), msg.ID, msg.ChannelID, msg.GuildID)
+	if !now.After(wait) && !now.Equal(wait) {
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
+		reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.remainingTimeout(wait)), msgID, channelID, guildID)
+		_, err := s.ChannelMessageSendComplex(channelID, reply)
 		if err != nil {
 			return false, fmt.Errorf("failed to send timeout response: %e", err)
 		}

command.go

@@ -4,14 +4,18 @@ import (
 	"time"
 )
 
-// custom Discord commands
+// Command represents a bolt command in its entirety
 type Command struct {
-	Trigger string        //command that triggers payload NOT including the indicator
+	//the trigger phrase for the command, this field cannot include the command indicator. If the command is .ping
-	Payload Payload       //payload function to run when a command is detected
+	//Trigger should be "ping"
-	Timeout time.Duration //the amount of time before command can be run again
+	Trigger string
-	lastRun time.Time     //timestamp of last command run
+	//handler function to run when command is detected
-	Roles   []string      //roles that can use command, if none are set anyone can run the command
+	Payload Payload
+	//the amount of time that must pass before a command can be run again
+	Timeout time.Duration
+	//timestamp of last command run
+	lastRun time.Time
+	//the roles that are allowed to execute this command, the command author must have at least one of these roles
+	//in order to use the command
+	Roles []string
 }
-
-// command payload functions, any strings returned are sent as a response to the command
-type Payload func(msg Message) error

go.mod

@@ -1,8 +1,11 @@
 module code.jakeyoungdev.com/jake/bolt
 
-go 1.24.0
+go 1.25.0
 
-require github.com/bwmarrin/discordgo v0.29.0
+require (
+	github.com/bwmarrin/discordgo v0.29.0
+	github.com/joho/godotenv v1.5.1
+)
 
 require (
 	github.com/gorilla/websocket v1.4.2 // indirect

go.sum

@@ -2,6 +2,8 @@ github.com/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+Eg
 github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/gorilla/websocket v1.4.2 h1:+/TMaTYc4QFitKJxsQ7Yye35DkWvkdLcvGKqM+x0Ufc=
 github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b h1:7mWr3k41Qtv8XlltBkDkl8LoP3mpSgBW8BUoxtEdbXg=
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=

message.go

@@ -1,22 +1,21 @@
 package bolt
 
-import "fmt"
+import (
+	"fmt"
+	"time"
 
-//built-in Discord reactions
+	dg "github.com/bwmarrin/discordgo"
-type Reaction string
-
-const (
-	ReactionThumbsUp      Reaction = ":+1:"
-	ReactionThumbsDown    Reaction = ":-1:"
-	ReactionPointUp       Reaction = ":point_up:"
-	ReactionPointDown     Reaction = ":point_down:"
-	ReactionHotdog        Reaction = ":hotdog:"
-	ReactionGiraffe       Reaction = ":giraffe:"
-	ReactionWatermelon    Reaction = ":watermelon:"
-	ReactionNoPedestrians Reaction = ":no_pedestrian:"
 )
 
-// information about attachments to messages
+const (
+	// the max length allowed for basic messages, if the message content exceeds this amount
+	// then messages are split unto chunks of max size
+	MSG_MAX_LENGTH = 2000
+)
+
+// command and message payload function type
+type Payload func(c *Context) error
+
 type MessageAttachment struct {
 	ID           string
 	URL          string
@@ -29,29 +28,101 @@ type MessageAttachment struct {
 	DurationSecs float64
 }
 
-// represents a Discord message
+// Author contains basic information about message authors
+type Author struct {
+	Name  string
+	ID    string
+	Roles []string
+}
+
+// Message contains all needed data to handle message events
 type Message struct {
-	Author      string   //username of message author
+	Author Author
-	ID          string   //discord ID of message author
+	//current message ID
-	msgID       string   //id string of message
+	ID string
-	Words       []string //words from message split on whitespace
+	//message content split on whitespace to allow for easy argument parsing with commands
-	Content     string   //entire message content
+	Words []string
-	Channel     string   //message channel
+	//entire message content unchanged
-	channelID   string   //id of channel message was sent in
+	Content string
-	Server      string   //message guild
+	//channel message was sent in, name and ID
-	serverID    string   //id of guild message was sent in
+	Channel   string
-	Attachments []MessageAttachment
+	ChannelID string
-	sesh        *bolt
+	//guild message was sent in, name and ID
+	Server   string
+	ServerID string
+	//message extras
+	Attachments []MessageAttachment //any attachments bound to the message
+	Mentions    []*dg.User          //users mention in the message with @
 }
 
-// applies reaction to message
+// Context is the struct passed to message and command handlers, it contains all needed message data as well as
-func (m *Message) React(emoji Reaction) error {
+// some methods to make interaction with the message as easy as possible
-	return m.sesh.MessageReactionAdd(m.channelID, m.msgID, fmt.Sprint(emoji))
+type Context struct {
+	Message *Message
+	bolt    *bolt
 }
 
-// sends the value of res in response to the message
+// React applies the reaction to the message
-func (m *Message) Respond(res string) error {
+func (c *Context) React(emoji Reaction) error {
-	rep := m.sesh.createReply(res, m.msgID, m.channelID, m.serverID)
+	return c.bolt.MessageReactionAdd(c.Message.ChannelID, c.Message.ID, fmt.Sprint(emoji))
-	_, err := m.sesh.ChannelMessageSendComplex(m.channelID, rep)
+}
+
+// Respond sends a response to the message, handling chunking if the message exceeds max length
+func (c *Context) Respond(res string) error {
+	if len(res) > MSG_MAX_LENGTH {
+		for len(res) > 0 {
+			//send full chunk size allowed by discord
+			sc := res[:MSG_MAX_LENGTH]
+			rep := c.bolt.createReply(sc, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+			_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, rep)
+			if err != nil {
+				return err
+			}
+			res = res[MSG_MAX_LENGTH:]
+
+			//if we have left than a full chunk send the rest and break the loop
+			if len(res) < MSG_MAX_LENGTH {
+				final := c.bolt.createReply(res, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+				_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, final)
+				if err != nil {
+					return err
+				}
+
+				break
+			}
+		}
+
+		return nil
+	}
+
+	//short enough message to send in one go, so ship it
+	rep := c.bolt.createReply(res, c.Message.ID, c.Message.ChannelID, c.Message.ServerID)
+	_, err := c.bolt.ChannelMessageSendComplex(c.Message.ChannelID, rep)
 	return err
 }
+
+// Delete removes the message from the current channel
+func (c *Context) Delete() error {
+	return c.bolt.ChannelMessageDelete(c.Message.ChannelID, c.Message.ID, nil)
+}
+
+// Timeout creates a user timeout for the supplied userID that lasts until duration is exceeded or the
+// timeout is cleared
+func (c *Context) Timeout(userId string, duration time.Time) error {
+	return c.bolt.GuildMemberTimeout(c.Message.ServerID, userId, &duration)
+}
+
+// ClearTimeout clears existing user timeouts, allowing them access again
+func (c *Context) ClearTimeout(userId string) error {
+	return c.bolt.GuildMemberTimeout(c.Message.ServerID, userId, nil)
+}
+
+// Mute handles muting a user from Voice Chat, this mute stays until it is Unmute()'d
+func (c *Context) Mute(userId string) error {
+	return c.bolt.GuildMemberMute(c.Message.ServerID, userId, true)
+}
+
+// Unmute removes a mute on the user, allowing them vc access again
+func (c *Context) Unmute(userId string) error {
+	return c.bolt.GuildMemberMute(c.Message.ServerID, userId, false)
+}

option.go

@@ -1,23 +1,48 @@
 package bolt
 
-type Option func(b *bolt)
+import (
+	dg "github.com/bwmarrin/discordgo"
+)
 
+type Option func(b *bolt)
 type LogLevel int
 
 const (
-	LogLevelAll LogLevel = iota //logs all messages, and errors
+	LogLevelAll LogLevel = iota //log all messages, and errors
 	LogLevelCmd LogLevel = iota //log only commands and responses, and errors
-	LogLevelErr LogLevel = iota //logs only errors
+	LogLevelErr LogLevel = iota //log only errors
 )
 
-// sets the substring that must be present at the beginning of the message to indicate a command
+// WithIntents provides an option to use custom intents for the bot. Bolt comes preconfigured with the basic
+// intents needed to run a bot but those are completely overwritten by any supplied here
+func WithIntents(intents ...dg.Intent) Option {
+	return func(b *bolt) {
+		var full dg.Intent
+		for _, i := range intents {
+			full |= i
+		}
+
+		b.Identify.Intents = full
+	}
+}
+
+// WithMaxGoroutines limits the amount of handler routines the bot is able to spawn at the same time. A lower value
+// may cause higher latency but may reduce resources needed to run bolt
+func WithMaxGoroutines(max int) Option {
+	return func(b *bolt) {
+		b.maxRoutines = max
+	}
+}
+
+// WithIndicator sets the substring that must be present at the beginning of a message to trigger a
+// command, for example "." or "!"
 func WithIndicator(i string) Option {
 	return func(b *bolt) {
 		b.indicator = i
 	}
 }
 
-// sets the log level to determine how much bolt logs
+// WithLogLevel adjusts bolt logging verbosity
 func WithLogLevel(lvl LogLevel) Option {
 	return func(b *bolt) {
 		b.logLvl = lvl

reaction.go

@@ -0,0 +1,38 @@
+package bolt
+
+type Reaction string
+
+// a few easy-to-use emojis, Discordgo/Discord API requires them to be saved like this. Some appear "broken" but do not play friendly
+// when saved in-file
+const (
+	ReactionThumbsUp          Reaction = "👍"
+	ReactionThumbsDown        Reaction = "👎"
+	ReactionHundred           Reaction = "💯"
+	ReactionHeart             Reaction = "❤️"
+	ReactionPinkHeart         Reaction = "🩷"
+	ReactionOrangeHeart       Reaction = "🧡"
+	ReactionYellowHeart       Reaction = "💛"
+	ReactionGreenHeart        Reaction = "💚"
+	ReactionBlueHeart         Reaction = "💙"
+	ReactionBlackHeart        Reaction = "🖤"
+	ReactionPointUp           Reaction = "☝️"
+	ReactionPointDown         Reaction = "👇"
+	ReactionHotdog            Reaction = "🌭"
+	ReactionDog               Reaction = "🐶"
+	ReactionCat               Reaction = "🐱"
+	ReactionMonkey            Reaction = "🐒"
+	ReactionGiraffe           Reaction = "🦒"
+	ReactionDuck              Reaction = "🦆"
+	ReactionGoose             Reaction = "🪿"
+	ReactionWatermelon        Reaction = "🍉"
+	ReactionHoney             Reaction = "🍯"
+	ReactionSandwich          Reaction = "🥪"
+	ReactionPepper            Reaction = "🌶️"
+	ReactionNoPedestrians     Reaction = "🚷"
+	ReactionExclamation       Reaction = "❗"
+	ReactionDoubleExclamation Reaction = "‼️"
+	ReactionSkull             Reaction = "💀"
+	ReactionSpeakingHead      Reaction = "🗣️"
+	ReactionGreenCheck        Reaction = "✅"
+	ReactionDragon            Reaction = "🐉"
+)