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,107 +1,96 @@
 # 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.
-```go
-func Delete() error
-```
-The Delete method will delete the message from the text channel
-
 ### 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
-	//Example: bolt.New(bolt.WithIndicator('!')) would support commands like !ping
-	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelCmd))
+	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelAll))
+
 	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 {
-				return msg.Respond("pong")
+			Payload: func(c *bolt.Context) error {
+				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",
-			Payload: func(msg bolt.Message) error {
-				return msg.React(bolt.ReactionThumbsUp)
-			},
-		},
-		// .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())
+			Trigger: "wait",
+			Payload: func(c *bolt.Context) error {
+				return c.Respond("okay")
 			},
 			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",
-			Payload: func(msg bolt.Message) error {
-				return msg.Respond("admin")
+			Trigger: "timeout",
+			Payload: func(c *bolt.Context) error {
+				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"},
 		},
 	)
 
-	//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 {
+		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)
@@ -111,4 +100,5 @@ func main() {
 ```
 
 ## 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,22 +1,33 @@
 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 |
@@ -24,28 +35,42 @@ const (
 		dg.IntentGuildMessageReactions
 )
 
-// basic bot structure containing discordgo connection as well as the command map
 type bolt struct {
-	*dg.Session                    //holds discordgo internals
-	commands    map[string]Command //maps trigger phrase to command struct for fast lookup
-	indicator   string             //the indicator used to detect whether a message is a command
-	logLvl      LogLevel           //determines how much the bot logs
+	//discordgo internals
+	*dg.Session
+	//maps trigger phrase to command struct for instant lookup
+	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)
-	handleCommand(msgEvent *MessageCreateEvent, s *dg.Session, lg int) error
+	msgEventHandler(s *dg.Session, msg *dg.MessageCreate)
+	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(guild string, roles []string, 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 {
@@ -56,62 +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,
 		commands:    make(map[string]Command, 0),
 		logLvl:      LogLevelAll,
+		indicator:   DEFAULT_INDICATOR,
+		wg:          sync.WaitGroup{},
+		maxRoutines: DEFAULT_MAX_GOROUTINES,
 	}
-	//set default command indicator
-	b.indicator = "."
 
-	//apply options
+	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 call
-// that handles safe shutdown of the bot
+// Start applies the message event handler function to the bot and opens the initial websocket connection
+// 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.messageHandler)
-
+	b.AddHandler(b.msgEventHandler)
 	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 {
-		return err
+	//give handler routines a 5 second window to finish processes before closing connection
+	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
-func (b *bolt) stop() error {
-	return b.Close()
-}
-
-// adds commands to bot command map for use
+// AddCommands registers command handlers. Any messages that begin with the command indicator will be forwarded
+// to the handler
 func (b *bolt) AddCommands(cmd ...Command) {
 	for _, c := range cmd {
 		b.commands[c.Trigger] = c
 	}
 }
 
-// handler function that parses message data, handles logging the message based on logLevel, and executes
-// the payload function in a goroutine
-func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) {
+// AddMessageHandler registers the generic message handler, any messages that are not commands will be forwarded
+// 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 {
@@ -124,106 +176,73 @@ 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 || b.logLvl == LogLevelAll {
-			//log command responses
+		if b.logLvl != LogLevelErr {
 			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 {
-		mCreate := &MessageCreateEvent{
-			AuthorUsername: msg.Author.Username,
-			AuthorID:       msg.Author.ID,
-			AuthorRoles:    msg.Member.Roles,
-			MsgID:          msg.ID,
-			Msg:            msg.Content,
-			MsgChanID:      msg.ChannelID,
-			MsgGuildID:     msg.GuildID,
-			MsgAttachments: msg.Attachments,
-		}
-
 		if b.logLvl == LogLevelCmd {
-			//log commands
-			log.Printf("< %s | %s | %s > %s\n", mCreate.MsgGuildName, mCreate.MsgChanName, mCreate.AuthorUsername, mCreate.Msg)
+			log.Printf("< %s | %s | %s > %s\n", m.Server, m.Channel, m.Author.Name, m.Content)
 		}
 
-		//handled in its own goroutine to allow for async commands
-		go func() {
-			err := b.handleCommand(mCreate, s, lg)
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleCommand(&m, lg)
 			if err != nil {
 				log.Println(err)
 			}
-		}()
-	}
-}
-
-// parses command from message and handles timeout checks, role checks, and command execution. All command responses are sent back to Discord
-func (b *bolt) handleCommand(msgEvent *MessageCreateEvent, s *dg.Session, lg int) error {
-	words := strings.Split(msgEvent.Msg, " ")
-	run, ok := b.commands[words[0][lg:]]
-	if !ok {
-		return nil //command doesn't exist, maybe log or respond to author
-	}
-
-	//has command met its timeout requirements
-	tc, err := b.timeoutCheck(msgEvent.MsgID, msgEvent.MsgChanID, msgEvent.MsgGuildID, s, run)
+			<-b.pool //release routine
+		})
+	} else {
+		b.pool <- struct{}{} //'aquire' a routine
+		b.wg.Go(func() {
+			err := b.handleMessage(&m)
 			if err != nil {
-		return fmt.Errorf("failed to calculate timeout for %s\n%e", run.Trigger, err)
+				log.Println(err)
 			}
-	if !tc {
-		return nil
-	}
-
-	//does user have correct permissions
-	if run.Roles != nil {
-		check, err := b.roleCheck(msgEvent.MsgGuildID, msgEvent.AuthorRoles, s, run)
-		if err != nil {
-			return fmt.Errorf("failed to perform permission checks for %s\n%e", run.Trigger, err)
-		}
-		if !check {
-			reply := b.createReply("you do not have permissions to run that command", msgEvent.MsgID, msgEvent.MsgChanID, msgEvent.MsgGuildID)
-			_, err := s.ChannelMessageSendComplex(msgEvent.MsgChanID, reply)
-			if err != nil {
-				return err
-			}
-			return nil
+			<-b.pool //release routine
+		})
 	}
 }
 
-	//populate message struct exposed to client
-	plMsg := Message{
-		Author:    msgEvent.AuthorUsername,
-		ID:        msgEvent.AuthorID,
-		msgID:     msgEvent.MsgID,
-		Words:     words,
-		Content:   msgEvent.Msg,
-		Channel:   msgEvent.MsgChanName,
-		channelID: msgEvent.MsgChanID,
-		Server:    msgEvent.MsgGuildName,
-		serverID:  msgEvent.MsgGuildID,
-		sesh:      b,
+// mapEventToMsg maps the Discord event message struct into bolt's user-friendly Message struct
+func (b *bolt) mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message {
+	m := Message{
+		Author: Author{
+			Name:  msg.Author.Username,
+			ID:    msg.Author.ID,
+			Roles: msg.Member.Roles,
+		},
+		ID:        msg.ID,
+		Content:   msg.Content,
+		Channel:   channel.Name,
+		ChannelID: channel.ID,
+		Server:    server.Name,
+		ServerID:  server.ID,
 	}
 
-	//check for file attachments
-	if len(msgEvent.MsgAttachments) > 0 {
+	w := strings.Fields(msg.Content)
+	if len(w) > 0 {
+		m.Words = w
+	}
+
+	if len(msg.Mentions) > 0 {
+		m.Mentions = msg.Mentions
+	}
+
+	if len(msg.Attachments) > 0 {
 		var att []MessageAttachment
-		for _, a := range msgEvent.MsgAttachments {
+		for _, a := range msg.Attachments {
 			att = append(att, MessageAttachment{
 				ID:           a.ID,
 				URL:          a.URL,
@@ -237,13 +256,69 @@ func (b *bolt) handleCommand(msgEvent *MessageCreateEvent, s *dg.Session, lg int
 			})
 		}
 
-		plMsg.Attachments = att
+		m.Attachments = att
 	}
 
-	//run command payload
-	err = run.Payload(plMsg)
+	return m
+}
+
+// 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
@@ -252,7 +327,7 @@ func (b *bolt) handleCommand(msgEvent *MessageCreateEvent, s *dg.Session, lg int
 	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,
@@ -266,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
-func (b *bolt) getRemainingTimeout(timeout time.Time) string {
+// remainingTimeout calculates the amount of time left before a command can be run again. Returning a 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
@@ -284,14 +360,18 @@ 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
+
+// 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
-	//TODO: improve role search performance to support bigger lists
+	//this needs a bit of love, looping through roles could get messy as server and role lists grow on big servers
+	//especially with the Role() call inside of the loop
 	for _, r := range roles {
 		//get role name from ID
 		n, err := s.State.Role(guild, r)
@@ -306,19 +386,16 @@ func (b *bolt) roleCheck(guild string, roles []string, s *dg.Session, run Comman
 		}
 	}
 
-	//can't find role, don't run command
-	if !found {
-		return false, nil
+	return found, 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
+// 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) {
-		reply := b.createReply(fmt.Sprintf("that command cannot be run for another %s", b.getRemainingTimeout(wait)), msgID, channelID, guildID)
+	now := time.Now()
+	if !now.After(wait) && !now.Equal(wait) {
+		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
-	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 the command
+	//the trigger phrase for the command, this field cannot include the command indicator. If the command is .ping
+	//Trigger should be "ping"
+	Trigger string
+	//handler function to run when command is detected
+	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

@@ -2,59 +2,20 @@ package bolt
 
 import (
 	"fmt"
+	"time"
 
 	dg "github.com/bwmarrin/discordgo"
 )
 
-// the message struct is passed to the command payload providing basic
-// message information and needed methods
-type Message struct {
-	Author      string   //username of message author
-	ID          string   //discord ID of message author
-	msgID       string   //id string of message
-	Words       []string //words from message split on whitespace
-	Content     string   //entire message content
-	Channel     string   //message channel
-	channelID   string   //id of channel message was sent in
-	Server      string   //message guild
-	serverID    string   //id of guild message was sent in
-	Attachments []MessageAttachment
-	sesh        *bolt
-}
+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
+)
 
-// applies reaction to message
-func (m *Message) React(emoji Reaction) error {
-	return m.sesh.MessageReactionAdd(m.channelID, m.msgID, fmt.Sprint(emoji))
-}
+// command and message payload function type
+type Payload func(c *Context) error
 
-// sends response to message
-func (m *Message) Respond(res string) error {
-	rep := m.sesh.createReply(res, m.msgID, m.channelID, m.serverID)
-	_, err := m.sesh.ChannelMessageSendComplex(m.channelID, rep)
-	return err
-}
-
-// deletes the message from the channel
-func (m *Message) Delete() error {
-	return m.sesh.ChannelMessageDelete(m.channelID, m.msgID, nil)
-}
-
-// this struct has all of the needed information from the messageCreate event so that
-// commands can be run asynchronously. Passing the messageCreate to payloads can block routines
-type MessageCreateEvent struct {
-	AuthorUsername string
-	AuthorID       string
-	AuthorRoles    []string
-	MsgID          string
-	Msg            string
-	MsgChanID      string
-	MsgChanName    string
-	MsgGuildID     string
-	MsgGuildName   string
-	MsgAttachments []*dg.MessageAttachment
-}
-
-// message attachment details
 type MessageAttachment struct {
 	ID           string
 	URL          string
@@ -66,3 +27,102 @@ type MessageAttachment struct {
 	Size         int
 	DurationSecs float64
 }
+
+// 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 Author
+	//current message ID
+	ID string
+	//message content split on whitespace to allow for easy argument parsing with commands
+	Words []string
+	//entire message content unchanged
+	Content string
+	//channel message was sent in, name and ID
+	Channel   string
+	ChannelID string
+	//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 @
+}
+
+// Context is the struct passed to message and command handlers, it contains all needed message data as well as
+// some methods to make interaction with the message as easy as possible
+type Context struct {
+	Message *Message
+	bolt    *bolt
+}
+
+// React applies the reaction to the message
+func (c *Context) React(emoji Reaction) error {
+	return c.bolt.MessageReactionAdd(c.Message.ChannelID, c.Message.ID, fmt.Sprint(emoji))
+}
+
+// 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

@@ -1,9 +1,9 @@
 package bolt
 
-// built-in Discord reactions
 type Reaction string
 
-// a few easy-to-use emojis, Discordgo/Discord API requires them to be saved like this.
+// 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 = "👎"