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,83 +1,104 @@
 # bolt
 
-The nuts and bolts of a Discord bots. Bolt is a wrapper for [discordgo](https://github.com/bwmarrin/discordgo) that provides very quick 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. Any roles in the Command struct can run the command, if the Roles field is empty anyone can 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 the command
-}
-```
-
-### Payload
-Payload functions are executed when a command is detected, if no errors are returned and the returned string is not empty, then the returned string is sent in reply to the command message.
-```go
-type Payload func(msg Message) (string, error)
-```
-
 ### Example
 ```go
 package main
 
 import (
-	"log"
+	"fmt"
-	"os"
+	"strings"
-	"os/signal"
-	"syscall"
 	"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()
+	if err != nil {
+		panic(err)
+	}
 
 	b.AddCommands(
-        // .ping can be run at any time by anyone and will respond with 'pong'
 		bolt.Command{
 			Trigger: "ping",
-			Payload: func(msg bolt.Message) (string, error) {
+			Payload: func(c *bolt.Context) error {
-				return "pong", nil //any strings returned will be sent in response to the Discord message
+				return c.Respond("pong")
 			},
 		},
-        // .time can be run every 25 seconds by anyone and will respond with 'yer'
 		bolt.Command{
-			Trigger: "time",
+			Trigger: "wait",
-			Payload: func(msg bolt.Message) (string, error) {
+			Payload: func(c *bolt.Context) error {
-				return "yer", nil
+				return c.Respond("okay")
 			},
 			Timeout: time.Second * 25,
+			Roles:   []string{"user"},
 		},
-        // .role can be run every 10 seconds by anyone with the 'admin' role and will respond with 'hi'
+		bolt.Command{
-        bolt.Command{
+			Trigger: "timeout",
-            Trigger: "role",
+			Payload: func(c *bolt.Context) error {
-            Payload: func(msg bolt.Message) (string, error) {
+				if len(c.Message.Mentions) > 0 {
-				return "hi", nil
+					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,202 +1,324 @@
 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
+	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)
 }
 
-// setup
+// New creates a new bolt instance and applies any supplied options
-func init() {
+func New(opts ...Option) (Bolt, error) {
-	//validate environment variables
 	_, check := os.LookupEnv(TOKEN_ENV_VAR)
 	if !check {
-		log.Fatalf("the %s environment variable must be set", TOKEN_ENV_VAR)
+		return nil, fmt.Errorf("environment variable %s must be set", TOKEN_ENV_VAR)
 	}
-}
 
-// create a new bolt interface
-func New(opts ...Option) Bolt {
 	bot, err := dg.New(fmt.Sprintf("Bot %s", os.Getenv(TOKEN_ENV_VAR)))
 	if err != nil {
-		log.Fatal(err)
+		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,
-	//set default command indicator
+		indicator:   DEFAULT_INDICATOR,
-	b.indicator = "."
+		wg:          sync.WaitGroup{},
-
+		maxRoutines: DEFAULT_MAX_GOROUTINES,
-	//apply options to bolt
-	for _, o := range opts {
-		o(b)
 	}
 
-	return b
+	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 err
+		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 {
-		log.Println(err)
+		log.Printf("failed to get guild: %e\n", err)
 		return
 	}
 	channel, err := s.Channel(msg.ChannelID)
 	if err != nil {
-		log.Println(err)
+		log.Printf("failed to get channel from guild: %e\n", err)
 		return
 	}
 
-	//if there is no content it is likely an image or a GIF, updating message content for
-	//better logging and to avoid confusion
-	if len(msg.Content) == 0 {
-		msg.Content = "GIF/IMAGE"
-	}
-
-	//log message
-	log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
-
 	//the bot will ignore it's own messages to prevent command loops
 	if msg.Author.ID == s.State.User.ID {
+		if b.logLvl != LogLevelErr {
+			log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+		}
 		return
 	}
 
-	//does the message have the command indicator
+	if b.logLvl == LogLevelAll {
+		log.Printf("< %s | %s | %s > %s\n", server.Name, channel.Name, msg.Author.Username, msg.Content)
+	}
+
+	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 {
-	words := strings.Split(msg.Content, " ")
+	m := Message{
-	run, ok := b.commands[words[0][lg:]]
+		Author: Author{
-	if !ok {
+			Name:  msg.Author.Username,
-		return nil //command doesn't exist, maybe log or respond to author
+			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,
 	}
 
-	//has command met its timeout requirements
+	w := strings.Fields(msg.Content)
-	tc, err := b.timeoutCheck(msg, s, run)
+	if len(w) > 0 {
-	if err != nil {
+		m.Words = w
-		return err
 	}
+
+	if len(msg.Mentions) > 0 {
+		m.Mentions = msg.Mentions
+	}
+
+	if len(msg.Attachments) > 0 {
+		var att []MessageAttachment
+		for _, a := range msg.Attachments {
+			att = append(att, MessageAttachment{
+				ID:           a.ID,
+				URL:          a.URL,
+				ProxyURL:     a.ProxyURL,
+				Filename:     a.Filename,
+				ContentType:  a.ContentType,
+				Width:        a.Width,
+				Height:       a.Height,
+				Size:         a.Size,
+				DurationSecs: a.DurationSecs,
+			})
+		}
+
+		m.Attachments = att
+	}
+
+	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 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
+	//does user have correct permissions to run this command
 	if run.Roles != nil {
-		check, err := b.roleCheck(msg, s, run)
+		check, err := b.roleCheck(msg.ServerID, msg.Author.Roles, b.Session, run)
 		if err != nil {
-			return err
+			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
 		}
 	}
 
-	//run command payload
+	//execute handler func with message context
-	res, err := run.Payload(Message{
+	err = run.Payload(&Context{
-		Author:  msg.Author.Username,
+		Message: msg,
-		Words:   words,
+		bolt:    b,
-		Content: msg.Content,
-		Channel: channel.Name,
-		Server:  server.Name,
 	})
-
 	if err != nil {
-		return err
+		return fmt.Errorf("encountered an error while handling command (%s): %e", msg.Words[0], err)
-	}
-
-	//if a reply is returned send back to Discord
-	if res != "" {
-		reply := b.createReply(res, msg.ID, msg.ChannelID, msg.GuildID)
-		_, err := s.ChannelMessageSendComplex(msg.ChannelID, reply)
-		if err != nil {
-			return err
-		}
 	}
 
 	//update run time
@@ -205,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,
@@ -219,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
@@ -237,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, 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)
@@ -259,27 +386,19 @@ 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, 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, err
+			return false, fmt.Errorf("failed to send timeout response: %e", err)
 		}
 		return false, nil
 	}

command.go

@@ -1,24 +1,21 @@
 package bolt
 
-import "time"
+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
-// command payload functions, any strings returned are sent as a response to the command
+	//timestamp of last command run
-type Payload func(msg Message) (string, error)
+	lastRun time.Time
-
+	//the roles that are allowed to execute this command, the command author must have at least one of these roles
-// message information passed to payload function
+	//in order to use the command
-type Message struct {
+	Roles []string
-	Author  string   //username of message author
-	Words   []string //words from message split on whitespace
-	Content string   //entire message content
-	Channel string   //message channel
-	Server  string   //message guild
 }

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

@@ -0,0 +1,128 @@
+package bolt
+
+import (
+	"fmt"
+	"time"
+
+	dg "github.com/bwmarrin/discordgo"
+)
+
+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
+	ProxyURL     string
+	Filename     string
+	ContentType  string
+	Width        int
+	Height       int
+	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,10 +1,50 @@
 package bolt
 
-type Option func(b *bolt)
+import (
+	dg "github.com/bwmarrin/discordgo"
+)
 
-// sets the substring that must be present at the beginning of the message to indicate a command
+type Option func(b *bolt)
+type LogLevel int
+
+const (
+	LogLevelAll LogLevel = iota //log all messages, and errors
+	LogLevelCmd LogLevel = iota //log only commands and responses, and errors
+	LogLevelErr LogLevel = iota //log only errors
+)
+
+// 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
 	}
 }
+
+// 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 = "🐉"
+)