decoupling start and shutdown

- start is no longer a blocking call
- giving it back to users
- the Stop method now waits for the timeout before closing

README.md

@@ -12,6 +12,8 @@ package main
 
 import (
 	"fmt"
+	"os"
+	"os/signal"
 	"strings"
 	"time"
 
@@ -21,25 +23,28 @@ import (
 
 /*
 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.
+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
+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:
+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() {
-	b, err := bolt.New(bolt.WithLogLevel(bolt.LogLevelAll))
-
+	b, err := bolt.New()
 	if err != nil {
 		panic(err)
 	}
@@ -95,8 +100,16 @@ func main() {
 	if err != nil {
 		panic(err)
 	}
-}
 
+	qc := make(chan os.Signal, 1)
+	signal.Notify(qc, os.Interrupt)
+	<-qc
+
+	err = b.Stop()
+	if err != nil {
+		panic(err)
+	}
+}
 ```
 
 ## Development

bolt.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"log"
 	"os"
-	"os/signal"
 	"slices"
 	"strings"
 	"sync"
@@ -35,7 +34,7 @@ const (
 		dg.IntentGuildMessageReactions
 )
 
-type bolt struct {
+type Bolt struct {
 	//discordgo internals
 	*dg.Session
 	//maps trigger phrase to command struct for instant lookup
@@ -52,26 +51,12 @@ type bolt struct {
 	maxRoutines int
 	//generic message handler func
 	msgHandlerf Payload
-}
-
-type Bolt interface {
-	Start() error
-	AddCommands(cmd ...Command)
-	AddMessageHandler(p Payload)
-	//filtered methods
-	stop() 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
-	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)
+	//command timeout when closing connection
+	grace time.Duration
 }
 
 // New creates a new bolt instance and applies any supplied options
-func New(opts ...Option) (Bolt, error) {
+func New(opts ...Option) (*Bolt, error) {
 	_, check := os.LookupEnv(TOKEN_ENV_VAR)
 	if !check {
 		return nil, fmt.Errorf("environment variable %s must be set", TOKEN_ENV_VAR)
@@ -82,13 +67,14 @@ func New(opts ...Option) (Bolt, error) {
 		return nil, fmt.Errorf("failed to create Discord session: %e", err)
 	}
 
-	b := &bolt{
+	b := &Bolt{
 		Session:     bot,
 		commands:    make(map[string]Command, 0),
 		logLvl:      LogLevelAll,
 		indicator:   DEFAULT_INDICATOR,
 		wg:          sync.WaitGroup{},
 		maxRoutines: DEFAULT_MAX_GOROUTINES,
+		grace:       time.Second * 5,
 	}
 
 	b.Identify.Intents = DEFAULT_INTENTS
@@ -103,25 +89,34 @@ func New(opts ...Option) (Bolt, error) {
 }
 
 // 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 {
+// with Discord
+func (b *Bolt) Start() error {
 	b.AddHandler(b.msgEventHandler)
-	err := b.Open()
-	if err != nil {
-		return fmt.Errorf("failed to open websocket connection with Discord: %e", err)
+	return b.Open()
+}
+
+// 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 {
+		//we can use a normal map here since writing only takes place once
+		b.commands[c.Trigger] = c
 	}
+}
 
-	log.Println("bot started")
+// 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
+}
 
-	sigChannel := make(chan os.Signal, 1)
-	signal.Notify(sigChannel, os.Interrupt)
-	<-sigChannel
-
-	//give handler routines a 5 second window to finish processes before closing connection
-	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)
+// Stop waits for the alloted grace period timeout before handling safe shutdown of the
+// Discord connection
+func (b *Bolt) Stop() error {
+	ctx, cancel := context.WithTimeout(context.Background(), b.grace)
 	defer cancel()
-	closeChan := make(chan struct{}, 0)
+
+	closeChan := make(chan struct{})
 	go func() {
 		b.wg.Wait()
 		close(closeChan)
@@ -131,39 +126,15 @@ func (b *bolt) Start() error {
 	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")
 	}
 
-	log.Println("exiting")
-	return b.stop()
-}
-
-// 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
-	}
-}
-
-// 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) {
+func (b *Bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 	//get server information
 	server, err := s.Guild(msg.GuildID)
 	if err != nil {
@@ -188,8 +159,12 @@ func (b *bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 		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 len(msg.Content) <= lg {
+		return
+	}
+
+	m := b.mapEventToMsg(msg, channel, server)
 	if msg.Content[:lg] == b.indicator {
 		if b.logLvl == LogLevelCmd {
 			log.Printf("< %s | %s | %s > %s\n", m.Server, m.Channel, m.Author.Name, m.Content)
@@ -216,7 +191,7 @@ func (b *bolt) msgEventHandler(s *dg.Session, msg *dg.MessageCreate) {
 }
 
 // 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 {
+func (b *Bolt) mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server *dg.Guild) Message {
 	m := Message{
 		Author: Author{
 			Name:  msg.Author.Username,
@@ -263,7 +238,7 @@ func (b *bolt) mapEventToMsg(msg *dg.MessageCreate, channel *dg.Channel, server
 }
 
 // handleMessage forwards the message data to the handler function, if one is set
-func (b *bolt) handleMessage(event *Message) error {
+func (b *Bolt) handleMessage(event *Message) error {
 	if b.msgHandlerf != nil {
 		return b.msgHandlerf(&Context{
 			Message: event,
@@ -277,8 +252,7 @@ func (b *bolt) handleMessage(event *Message) error {
 // 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 {
+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
@@ -328,7 +302,7 @@ func (b *bolt) handleCommand(msg *Message, lg int) error {
 }
 
 // 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 {
+func (b *Bolt) createReply(content, message, channel, guild string) *dg.MessageSend {
 	details := &dg.MessageReference{
 		MessageID: message,
 		ChannelID: channel,
@@ -343,7 +317,7 @@ func (b *bolt) createReply(content, message, channel, guild string) *dg.MessageS
 
 // 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 {
+func (b *Bolt) remainingTimeout(timeout time.Time) string {
 	r := time.Until(timeout)
 	var (
 		timeLeft int
@@ -364,11 +338,9 @@ func (b *bolt) remainingTimeout(timeout time.Time) string {
 	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) {
+func (b *Bolt) roleCheck(guild string, roles []string, s *dg.Session, run Command) (bool, error) {
 	var found bool
 	//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
@@ -391,7 +363,7 @@ func (b *bolt) roleCheck(guild string, roles []string, s *dg.Session, run Comman
 
 // 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) {
+func (b *Bolt) timeoutCheck(msgID, channelID, guildID string, s *dg.Session, run Command) (bool, error) {
 	wait := run.lastRun.Add(run.Timeout)
 	now := time.Now()
 	if !now.After(wait) && !now.Equal(wait) {

message.go

@@ -59,7 +59,7 @@ type Message struct {
 // some methods to make interaction with the message as easy as possible
 type Context struct {
 	Message *Message
-	bolt    *bolt
+	bolt    *Bolt
 }
 
 // React applies the reaction to the message

option.go

@@ -1,10 +1,12 @@
 package bolt
 
 import (
+	"time"
+
 	dg "github.com/bwmarrin/discordgo"
 )
 
-type Option func(b *bolt)
+type Option func(b *Bolt)
 type LogLevel int
 
 const (
@@ -16,7 +18,7 @@ const (
 // 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) {
+	return func(b *Bolt) {
 		var full dg.Intent
 		for _, i := range intents {
 			full |= i
@@ -29,7 +31,7 @@ func WithIntents(intents ...dg.Intent) Option {
 // 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) {
+	return func(b *Bolt) {
 		b.maxRoutines = max
 	}
 }
@@ -37,14 +39,22 @@ func WithMaxGoroutines(max int) Option {
 // 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) {
+	return func(b *Bolt) {
 		b.indicator = i
 	}
 }
 
 // WithLogLevel adjusts bolt logging verbosity
 func WithLogLevel(lvl LogLevel) Option {
-	return func(b *bolt) {
+	return func(b *Bolt) {
 		b.logLvl = lvl
 	}
 }
+
+// WithGracePeriod gives a grace period for commands to finish prior to closing the
+// websocket connection with Discord
+func WithGracePeriod(t time.Duration) Option {
+	return func(b *Bolt) {
+		b.grace = t
+	}
+}