Allow Protocol Argument Passing (#112)

Due to the generic nature of this framework, platform specific
behaviors are hard to take advantage of. With this PR, protocol
plugins can offer additional information for message handlers to
read, and accept additional information as well.

In particular, this change was tested to allow a Slack response to
be made as a threaded reply, instead of only ever in the main channel.

EG:
func threadedEcho(cmd *bot.Cmd) (bot.CmdResult, error) {
	var params *slack.PostMessageParameters
	if ev, ok := cmd.MessageData.ProtoMsg.(*slack.MessageEvent); ok {
		params = &slack.PostMessageParameters{
			AsUser:          true,
			ThreadTimestamp: ev.Timestamp,
		}
	}
	return bot.CmdResult{
		Message:     fmt.Sprintf("%s: %s", cmd.User.Nick, cmd.Raw),
		Channel:     cmd.Channel,
		ProtoParams: params,
	}, nil
}

Author: toolateforteddy

bot.go

@@ -55,18 +55,31 @@ type Config struct {
 type responseMessage struct {
 	target, message string
 	sender          *User
+	protoParams     interface{}
+}
+
+// OutgoingMessage collects all the information for a message to go out.
+type OutgoingMessage struct {
+	Target      string
+	Message     string
+	Sender      *User
+	ProtoParams interface{}
 }
 
 // ResponseHandler must be implemented by the protocol to handle the bot responses
 type ResponseHandler func(target, message string, sender *User)
 
+// ResponseHandlerV2 may be implemented by the protocol to handle the bot responses
+type ResponseHandlerV2 func(OutgoingMessage)
+
 // ErrorHandler will be called when an error happens
 type ErrorHandler func(msg string, err error)
 
 // Handlers that must be registered to receive callbacks from the bot
 type Handlers struct {
-	Response ResponseHandler
-	Errored  ErrorHandler
+	Response   ResponseHandler
+	ResponseV2 ResponseHandlerV2
+	Errored    ErrorHandler
 }
 
 func logErrorHandler(msg string, err error) {
@@ -158,7 +171,7 @@ func (b *Bot) startPeriodicCommands() {
 
 // MessageReceived must be called by the protocol upon receiving a message
 func (b *Bot) MessageReceived(channel *ChannelData, message *Message, sender *User) {
-	command, err := parse(message.Text, channel, sender)
+	command, err := parse(message, channel, sender)
 	if err != nil {
 		b.SendMessage(channel.Channel, err.Error(), sender)
 		return
@@ -189,23 +202,47 @@ func (b *Bot) MessageReceived(channel *ChannelData, message *Message, sender *Us
 
 // SendMessage queues a message for a target recipient, optionally from a particular sender.
 func (b *Bot) SendMessage(target string, message string, sender *User) {
-	message = b.executeFilterCommands(&FilterCmd{
+	b.SendMessageV2(OutgoingMessage{
 		Target:  target,
 		Message: message,
-		User:    sender})
+		Sender:  sender,
+	})
+}
+
+// SendMessageV2 queues a message.
+func (b *Bot) SendMessageV2(om OutgoingMessage) {
+	message := b.executeFilterCommands(&FilterCmd{
+		Target:  om.Target,
+		Message: om.Message,
+		User:    om.Sender,
+	})
 	if message == "" {
 		return
 	}
 
 	select {
-	case b.msgsToSend <- responseMessage{target, message, sender}:
+	case b.msgsToSend <- responseMessage{
+		target:      om.Target,
+		message:     message,
+		sender:      om.Sender,
+		protoParams: om.ProtoParams,
+	}:
 	default:
 		b.errored("Failed to queue message to send.", errors.New("Too busy"))
 	}
 }
 
-func (b *Bot) sendResponse(target, message string, sender *User) {
-	b.handlers.Response(target, message, sender)
+func (b *Bot) sendResponse(resp responseMessage) {
+	if b.handlers.ResponseV2 != nil {
+		b.handlers.ResponseV2(OutgoingMessage{
+			Message:     resp.message,
+			ProtoParams: resp.protoParams,
+			Sender:      resp.sender,
+			Target:      resp.target,
+		})
+		return
+	}
+	b.handlers.Response(resp.target, resp.message, resp.sender)
 }
 
 func (b *Bot) errored(msg string, err error) {
@@ -218,7 +255,7 @@ func (b *Bot) processMessages() {
 	for {
 		select {
 		case msg := <-b.msgsToSend:
-			b.sendResponse(msg.target, msg.message, msg.sender)
+			b.sendResponse(msg)
 		case <-b.done:
 			return
 		}

cmd.go

@@ -41,8 +41,9 @@ func (c *ChannelData) URI() string {
 
 // Message holds the message info - for IRC and Slack networks, this can include whether the message was an action.
 type Message struct {
-	Text     string // The actual content of this Message
-	IsAction bool   // True if this was a '/me does something' message
+	Text     string      // The actual content of this Message
+	IsAction bool        // True if this was a '/me does something' message
+	ProtoMsg interface{} // The underlying object that we got from the protocol pkg
 }
 
 // FilterCmd holds information about what is output being filtered - message and
@@ -108,15 +109,17 @@ type customCommand struct {
 
 // CmdResult is the result message of V2 commands
 type CmdResult struct {
-	Channel string // The channel where the bot should send the message
-	Message string // The message to be sent
+	Channel     string // The channel where the bot should send the message
+	Message     string // The message to be sent
+	ProtoParams interface{}
 }
 
 // CmdResultV3 is the result message of V3 commands
 type CmdResultV3 struct {
-	Channel string
-	Message chan string
-	Done    chan bool
+	Channel     string
+	Message     chan string
+	Done        chan bool
+	ProtoParams interface{}
 }
 
 const (
@@ -389,7 +392,12 @@ func (b *Bot) handleCmd(c *Cmd) {
 		}
 
 		if result.Message != "" {
-			b.SendMessage(result.Channel, result.Message, c.User)
+			b.SendMessageV2(OutgoingMessage{
+				Target:      result.Channel,
+				Message:     result.Message,
+				Sender:      c.User,
+				ProtoParams: result.ProtoParams,
+			})
 		}
 	case v3:
 		result, err := cmd.CmdFuncV3(c)
@@ -401,7 +409,12 @@ func (b *Bot) handleCmd(c *Cmd) {
 			select {
 			case message := <-result.Message:
 				if message != "" {
-					b.SendMessage(result.Channel, message, c.User)
+					b.SendMessageV2(OutgoingMessage{
+						Target:      result.Channel,
+						Message:     message,
+						Sender:      c.User,
+						ProtoParams: result.ProtoParams,
+					})
 				}
 			case <-result.Done:
 				return

cmd_test.go

@@ -12,12 +12,13 @@ import (
 )
 
 var (
-	channel  string
-	replies  chan string
-	cmdError chan string
-	user     *User
-	msgs     []string
-	errs     []string
+	channel     string
+	replies     chan string
+	cmdError    chan string
+	user        *User
+	msgs        []string
+	errs        []string
+	protoParams interface{}
 )
 
 const (
@@ -52,6 +53,13 @@ func responseHandler(target string, message string, sender *User) {
 	replies <- message
 }
 
+func responseHandlerV2(om OutgoingMessage) {
+	channel = om.Target
+	user = om.Sender
+	protoParams = om.ProtoParams
+	replies <- om.Message
+}
+
 func errorHandler(msg string, err error) {
 	cmdError <- fmt.Sprintf("%s: %s", msg, err)
 }
@@ -63,6 +71,7 @@ func reset() {
 	cmdError = make(chan string, 10)
 	msgs = []string{}
 	errs = []string{}
+	protoParams = nil
 	commands = make(map[string]*customCommand)
 	periodicCommands = make(map[string]PeriodicConfig)
 	passiveCommands = make(map[string]*customCommand)
@@ -81,6 +90,19 @@ func newBot() *Bot {
 	)
 }
 
+func newBotV2() *Bot {
+	return New(&Handlers{
+		Response:   responseHandler,
+		ResponseV2: responseHandlerV2,
+		Errored:    errorHandler,
+	},
+		&Config{
+			Protocol: "test",
+			Server:   "test",
+		},
+	)
+}
+
 func registerValidCommand() {
 	RegisterCommand(cmd, cmdDescription, cmdExampleArgs,
 		func(c *Cmd) (string, error) {
@@ -496,6 +518,37 @@ func TestCmdV2(t *testing.T) {
 	}
 }
 
+func TestCmdV2WithProtoParams(t *testing.T) {
+	reset()
+	RegisterCommandV2("cmd", "", "",
+		func(c *Cmd) (CmdResult, error) {
+			return CmdResult{
+				Channel:     "#channel",
+				Message:     "message",
+				ProtoParams: &CmdResult{Message: "Nested!"},
+			}, nil
+		})
+
+	b := newBotV2()
+	b.MessageReceived(&ChannelData{Channel: "#go-bot"}, &Message{Text: "!cmd"}, &User{Nick: "user"})
+
+	waitMessages(t, 1, 0)
+
+	if channel != "#channel" {
+		t.Error("Wrong channel")
+	}
+	if !reflect.DeepEqual([]string{"message"}, msgs) {
+		t.Error("Invalid reply")
+	}
+	if pa, ok := protoParams.(*CmdResult); ok {
+		if pa.Message != "Nested!" {
+			t.Error("Information lost in copying.")
+		}
+	} else {
+		t.Error("Failed to pass proto args through.")
+	}
+}
+
 func TestCmdV2WithoutSpecifyingChannel(t *testing.T) {
 	reset()
 	RegisterCommandV2("cmd", "", "",
@@ -687,6 +740,30 @@ func TestFilterCommandSilence(t *testing.T) {
 	}
 }
 
+func TestFilterCommandSilenceSendV2(t *testing.T) {
+	reset()
+	passiveCommands = make(map[string]*customCommand)
+	ping := func(cmd *PassiveCmd) (string, error) { return "pong", nil }
+	silenced := func(cmd *FilterCmd) (string, error) { return "", nil }
+	errored := func(cmd *FilterCmd) (string, error) { return "Ignored", errors.New("error") }
+
+	RegisterPassiveCommand("ping", ping)
+	RegisterFilterCommand("silenced", silenced)
+	RegisterFilterCommand("errored", errored)
+
+	b := newBotV2()
+	b.MessageReceived(&ChannelData{Channel: "#go-bot"}, &Message{Text: "test"}, &User{Nick: "user"})
+
+	waitMessages(t, 0, 1)
+
+	if len(msgs) != 0 {
+		t.Fatal("Expected no messages!")
+	}
+	if len(errs) != 1 {
+		t.Error("Expected 1 error")
+	}
+}
+
 // how to test channels..
 // https://www.hugopicado.com/2016/10/01/testing-over-golang-channels.html
 

help.go

@@ -14,7 +14,10 @@ const (
 )
 
 func (b *Bot) help(c *Cmd) {
-	cmd, _ := parse(CmdPrefix+c.RawArgs, c.ChannelData, c.User)
+	msg := &Message{
+		Text: CmdPrefix + c.RawArgs,
+	}
+	cmd, _ := parse(msg, c.ChannelData, c.User)
 	if cmd == nil {
 		b.showAvailabeCommands(c.Channel, c.User)
 		return

parser.go

@@ -13,21 +13,20 @@ var (
 	re = regexp.MustCompile("\\s+") // Matches one or more spaces
 )
 
-func parse(s string, channel *ChannelData, user *User) (*Cmd, error) {
-	c := &Cmd{Raw: s}
-	s = strings.TrimSpace(s)
+func parse(m *Message, channel *ChannelData, user *User) (*Cmd, error) {
+	s := strings.TrimSpace(m.Text)
 
 	if !strings.HasPrefix(s, CmdPrefix) {
 		return nil, nil
 	}
 
-	c.Channel = strings.TrimSpace(channel.Channel)
-	c.ChannelData = channel
-	c.User = user
-
-	// Trim the prefix and extra spaces
-	c.Message = strings.TrimPrefix(s, CmdPrefix)
-	c.Message = strings.TrimSpace(c.Message)
+	c := &Cmd{
+		Channel:     strings.TrimSpace(channel.Channel),
+		ChannelData: channel,
+		Message:     strings.TrimSpace(strings.TrimPrefix(s, CmdPrefix)),
+		Raw:         m.Text,
+		User:        user,
+	}
 
 	// check if we have the command and not only the prefix
 	if c.Message == "" {
@@ -48,9 +47,8 @@ func parse(s string, channel *ChannelData, user *User) (*Cmd, error) {
 		c.Args = parsedArgs
 	}
 
-	c.MessageData = &Message{
-		Text: c.Message,
-	}
+	m.Text = c.Message
+	c.MessageData = m
 
 	return c, nil
 }

parser_test.go

@@ -98,7 +98,7 @@ func TestParser(t *testing.T) {
 
 	for _, test := range tests {
 		t.Run(test.msg, func(t *testing.T) {
-			cmd, _ := parse(test.msg, channel, user)
+			cmd, _ := parse(&Message{Text: test.msg}, channel, user)
 			if test.expected != nil && cmd != nil {
 				if test.expected.Raw != cmd.Raw {
 					t.Errorf("Expected Raw:\n%#v\ngot:\n%#v", test.expected.Raw, cmd.Raw)
@@ -156,7 +156,11 @@ func TestParser(t *testing.T) {
 }
 
 func TestInvalidArguments(t *testing.T) {
-	cmd, err := parse("!cmd Invalid \"arg", &ChannelData{Channel: "#go-bot"}, &User{Nick: "user123"})
+	cmd, err := parse(
+		&Message{Text: "!cmd Invalid \"arg"},
+		&ChannelData{Channel: "#go-bot"},
+		&User{Nick: "user123"},
+	)
 	if err == nil {
 		t.Error("Expected error, got nil")
 	}