- Overview
- Requirements
- Features
- Demo
- The Name
- Concepts
- Create Your Own Slackscot
- Contributing
- Some Credits
Overview
Slackscot is a slack bot core written in Go. Think of it as the assembly kit to making your own friendly slack bot. It comes with a set of plugins you might enjoy and a friendly API for you to realize your ambitious dreams (if you dreams include this sort of thing).
Requirements
Go 1.11 or above is required, mostly for go module support.
Features
-
Support for reactions to message updates.
slackscotdoes the following:-
Keeps track of plugin action responses and the message that triggered them
-
On message updates:
-
Update responses for each triggered action
-
Delete responses that aren't triggering anymore (or result in errors during the message update)
-
-
On deletion of triggering messages, responses are also deleted
-
Limitation: Sending a
messageautomatically splits it into multiple slack messages when it's too long. When updating messages, this spitting doesn't happen and results in anmessage too longerror. Effectively, the last message in the initial response might getdeletedas a result. Handling of this could be better but that is the current limitation😕
-
-
Support for threaded replies to user message with option to also
broadcaston channels (disabled bydefault). See configuration example below where both are enabled.- Plugin actions may also explicitely reply in threads with/without broadcasting via AnswerOption
-
Concurrent processing of unrelated messages with guarantees of proper ordering of message updates/deletions
-
Simple extensible storage
APIfor persistence in two flavors:StringStorerandBytesStorer. Both are basickey:valuemaps. A default file-based implementation is provided backed by leveldb -
Implementation of
StringStorerbacked by Google Cloud Datastore. See datastoredb's godoc for documentation, usage and example. -
In-memory implementation of
StringStorerwrapping anyStringStorerimplementation to offer low-latency and potentially cost-saving storage implementation well-suited for small datasets. Plays well with cloud storage like the [datastoredb]((https://godoc.org/github.com/alexandre-normand/slackscot/store/datastoredb) See inmemorydb's godoc for documentation, usage and example. -
Support for various configuration sources/formats via viper
-
Support for various ways to implement functionality:
scheduled actions: run something every second, minute, hour, week. Oh Monday is a plugin that demos this by sending aMondaygreeting every Monday at 10am (or the time you configure it to).commands: respond to a command directed at yourslackscot. That means something like@slackscot helpor a direct messagehelpsent toslackscot.hear actions(aka "listeners"): actions that evaluated for a match on every message thatslackscothears. You'll want to make sure yourMatchfunction isn't too heavy. An example is the "famous" finger quoter plugin
-
Experimental and subject to change: Testing functions to help validate plugin action behavior (see example in triggerer_test.go). Testing functions are found in assertplugin and assertanswer
-
Built-in
helpplugin supporting a decently formatted help message as a command listing all plugins' actions. If you'd like some actions to not be shown in the help, you can setHiddentotruein itsActionDefinition(especially useful forhear actions) -
The plugin interface as a logical grouping of one or many
commandsandhear actionsand/orscheduled actions -
Support for injected services providing plugins easy access to an optionally caching
user infoand alogger.
Demo
slackscotdeleting a triggered reaction after seeing a message updated that caused the first action to not trigger anymore and a new action to now trigger (it makes sense when you see it)
slackscotupdating a triggered reaction after seeing a triggering message being updated
slackscotdeleting a reaction after seeing the triggering message being deleted
slackscotthreaded replies enabled (withbroadcast => on)
The Name
The first concrete bot implementation using this code was youppi, named after the great mascot of the Montreal Expos and, when the Expos left Montreal, the Montreal Canadiens.
Slackscot is a variation on the expected theme of slackbot with the implication that this is the core to more than just a regular bot. You know, a friendly company mascot that hangs out on your slack.
Concepts
-
Commands: commands are well-defined actions with a format.Slackscothandles all direct messages as implicit commands as well as@mention <command>on channels. Responses to commands are directed to the person who invoked it. -
Hear actions: those are listeners that can potentially match on any message sent on channels thatslackscotis a member of. This can include actions that will randomly generate a response. Note that responses are not automatically directed to the person who authored the message triggering the response (although an implementation is free to use the user id of the triggering message if desired).
Create Your Own Slackscot
Slackscot provides the pieces to make your mascot but you'll have to assemble them for him/her to come alive. The easiest to get started is to look at a real example: youppi.
The godoc is also a good reference especially if you're looking to implement something like a new implementation of the storer interfaces.
Assembling the Parts and Bringing Your slackscot to Life
Here's an abbreviated example of how youppi does it:
package main
import (
"github.com/alexandre-normand/slackscot"
"github.com/alexandre-normand/slackscot/config"
"github.com/alexandre-normand/slackscot/plugins"
"github.com/alexandre-normand/slackscot/store"
"github.com/spf13/viper"
"gopkg.in/alecthomas/kingpin.v2"
"log"
"os"
"io"
)
const (
name = "youppi"
)
func main() {
kingpin.Version(VERSION)
kingpin.Parse()
// TODO: initialize storer implementations required by plugins and do any other initialization
// required
...
// This is the where we create youppi with all of its plugins
youppi, err := slackscot.NewBot(name, v, options...).
WithPlugin(plugins.NewKarma(karmaStorer)).
WithPlugin(plugins.NewTriggerer(triggererStorer)).
WithConfigurablePluginErr(plugins.FingerQuoterPluginName, func(conf *config.PluginConfig) (p *slackscot.Plugin, err error) { return plugins.NewFingerQuoter(conf) }).
WithConfigurablePluginCloserErr(plugins.EmojiBannerPluginName, func(conf *config.PluginConfig) (c io.Closer, p *slackscot.Plugin, err error) {
return plugins.NewEmojiBannerMaker(conf)
}).
WithConfigurablePluginErr(plugins.OhMondayPluginName, func(conf *config.PluginConfig) (p *slackscot.Plugin, err error) { return plugins.NewOhMonday(conf) }).
WithPlugin(plugins.NewVersionner(name, version)).
Build()
defer youppi.Close()
if err != nil {
log.Fatal(err)
}
err = youppi.Run()
if err != nil {
log.Fatal(err)
}
}
Configuration Example
You'll also need to define your configuration for the core, used built-in plugins and any configuration required by your own custom plugins (not shown here). Slackscot uses viper for loading configuration which means that you are free to use a different file format (yaml, toml, env variables, etc.) as desired.
{
"token": "your-slack-bot-token",
"debug": false,
"responseCacheSize": 5000,
"userInfoCacheSize": 0,
"maxAgeHandledMessages": 86400,
"timeLocation": "America/Los_Angeles",
"storagePath": "/your-path-to-bot-home",
"replyBehavior": {
"threadedReplies": true,
"broadcastThreadedReplies": true
},
"plugins": {
"ohMonday": {
"channelIDs": ["slackChannelId"]
},
"fingerQuoter": {
"frequency": "100",
"channelIDs": []
},
"emojiBanner": {
"figletFontUrl": "http://www.figlet.org/fonts/banner.flf"
}
}
}
Creating Your Own Plugins
It might be best to look at examples in this repo to guide you through it:
- The simplest plugin with a single
commandis the versioner - One example of
scheduled actionsis oh monday - One example of a mix of
hear actions/commandsthat also uses thestoreapi for persistence is the karma
Contributing
- Fork it (preferrably, outside the
GOPATHas per the new go modules guidelines) - Make your changes, commit them (don't forget to
go build ./...andgo test ./...) and push your branch to your fork - Open a PR and fill in the template (you don't have to but I'd appreciate context)
- Check the
code climateandtravisPR builds. You might have to fix things and there's no shame if you do. I probably won't merge something that doesn't passCIbuild but I'm willing to help to get it to pass🖖 .
Open-telemetry integration
Slackscot now supports integration with opentelemetry. To aid with the addition of new metrics, you can find a gowrap template here. To add a metrics to a new interface, you can do something like
gowrap gen -p . -i <interfaceName> -t opentelemetry.template -o <interfaceName>metrics.go
When updating the template, you should consider running go generate in order to refresh the already generated files with the template changes.
Some Credits
slackscot uses Norberto Lopes's Slack API Integration found at https://github.com/nlopes/slack. The core functionality of the bot is previously used James Bowman's Slack RTM API integration and was heavily inspired by talbot, also written by James Bowman.
