go-joe / joe

A general-purpose bot library inspired by Hubot but written in Go. :robot:

Joe Bot 🤖

A general-purpose bot library inspired by Hubot but written in Go.

---

Joe is a library used to write chat bots in the Go programming language. It is very much inspired by the awesome Hubot framework developed by the folks at Github and brings its power to people who want to implement chat bots using Go.

Getting Started

Joe is a software library that is packaged as Go module. You can get it via:

go get github.com/go-joe/joe

Example usage

You can find all code examples, more explanation and complete recipes at https://joe-bot.net

Each bot consists of a chat Adapter (e.g. to integrate with Slack), a Memory implementation to remember key-value data (e.g. using Redis) and a Brain which routes new messages or custom events (e.g. receiving an HTTP call) to the corresponding registered handler functions.

By default joe.New(…) uses the CLI adapter which makes the bot read messages from stdin and respond on stdout. Additionally the bot will store key value data in-memory which means it will forget anything you told it when it is restarted. This default setup is useful for local development without any dependencies but you will quickly want to add other Modules to extend the bots capabilities.

The following example connects the Bot with a Slack workspace and stores key-value data in Redis. To allow the message handlers to access the memory we define them as functions on a custom ExampleBottype which embeds the joe.Bot.

package main

import (
	"fmt"

	"github.com/go-joe/joe"
	"github.com/go-joe/redis-memory"
	"github.com/go-joe/slack-adapter/v2"
)

type ExampleBot struct {
	*joe.Bot
}

func main() {
	b := &ExampleBot{
		Bot: joe.New("example",
			redis.Memory("localhost:6379"),
			slack.Adapter("xoxb-1452345…"),
		),
	}

	b.Respond("remember (.+) is (.+)", b.Remember)
	b.Respond("what is (.+)", b.WhatIs)

	err := b.Run()
	if err != nil {
		b.Logger.Fatal(err.Error())
	}
}

func (b *ExampleBot) Remember(msg joe.Message) error {
	key, value := msg.Matches[0], msg.Matches[1]
	msg.Respond("OK, I'll remember %s is %s", key, value)
	return b.Store.Set(key, value)
}

func (b *ExampleBot) WhatIs(msg joe.Message) error {
	key := msg.Matches[0]
	var value string
	ok, err := b.Store.Get(key, &value)
	if err != nil {
		return fmt.Errorf("failed to retrieve key %q from brain: %w", key, err)
	}

	if ok {
		msg.Respond("%s is %s", key, value)
	} else {
		msg.Respond("I do not remember %q", key)
	}

	return nil
}

Available modules

Joe ships with no third-party modules such as Redis integration to avoid pulling in more dependencies than you actually require. There are however already some modules that you can use directly to extend the functionality of your bot without writing too much code yourself.

If you have written a module and want to share it, please add it to this list and open a pull request.

Chat Adapters

• Slack Adapter: https://github.com/go-joe/slack-adapter
• Rocket.Chat Adapter: https://github.com/dwmunster/rocket-adapter
• Telegram Adapter: https://github.com/robertgzr/joe-telegram-adapter
• IRC Adapter: https://github.com/akrennmair/joe-irc-adapter
• Mattermost Adapter: https://github.com/dwmunster/joe-mattermost-adapter
• VK Adapter: https://github.com/tdakkota/joe-vk-adapter

Memory Modules

• Redis Memory: https://github.com/go-joe/redis-memory
• File Memory: https://github.com/go-joe/file-memory
• Bolt Memory: https://github.com/robertgzr/joe-bolt-memory
• Sqlite Memory: https://github.com/warmans/sqlite-memory

Other Modules

• HTTP Server: https://github.com/go-joe/http-server
• Cron Jobs: https://github.com/go-joe/cron

Built With

• zap - Blazing fast, structured, leveled logging in Go
• multierr - Package multierr allows combining one or more errors together
• testify - A simple unit test library

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and on the process for submitting pull requests to this repository.

Versioning

THIS SOFTWARE IS STILL IN ALPHA AND THERE ARE NO GUARANTEES REGARDING API STABILITY YET.

All significant (e.g. breaking) changes are documented in the CHANGELOG.md.

After the v1.0 release we plan to use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Friedrich Große - Initial work - fgrosse

See also the list of contributors who participated in this project.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Acknowledgments

• Hubot and its great community for the inspiration
• embedmd for a cool tool to embed source code in markdown files

joe's Issues

List support in Memory

I'd really like to have support for lists in Memory implementations, without having to build it up from KV considering that some of the Memory implementations have first class support (Redis). Would you want to add this concept to joe?

I'd also like to have Sets since my ultimate goal is actually a list of unique objects, and if we have List, and Set I can compose them into UniqList anyway.

Prefix Scans for Storage Keys

Summary

Since many uses of the Storage interface may have hierarchical keys, e.g. the permissions, it would be beneficial to have a way to iterate over keys matching a given prefix.

Basic example

for _, key := range a.store.KeysWithPrefix("joe.permissions.mymodule.") {
  ...
}

Motivation

From #28

Since we are iterating over all keys the bot knows we should expect that also non-permission keys are among them.

I suggest you update your unit test to check this is also handled correctly.

Rather than push this onto any developer who needs to interact with the permissions, we could require the Storage interface to support prefix scans. Some storage engines may have a higher performance way of doing prefix scans and we could take advantage of that. If the storage engine does not offer it, the bot could handle the naive looping over keys itself. This removes the burden from developers to implement/test this independently.

Potential Issues

• If the prefix scan isn't optional for the Storage interface, a new release would break any third party implementations. As described above, this would not be an issue.

How to change default log level

Hi,
i'm just digging around how i can adjust the log level of the bot.

Maybe you can add a simple example how the log-level can be adjusted?

Thanks

Registering a default response when no match

I've been trying to figure out how I can make my bot respond with a helpful message when no message is matched.

Naively I've tried the following approach which results in both handlers to be executed

b.Respond("foo", b.FooHandler)
b.Respond(".*", b.HelpHandler)

Unless I'm missing something, there does not seem to be a way to register a default handler that would only be executed if no other handler matches the message.

There also does not appear to be a way to stop processing handlers after the FooHandler is executed.

Slack DM

Is there a way to message.Send DMs to users?
I'm sorry about the question but I couldn't find any reference to this in slack-adapter nor here.

CLIAdapter Character read problem in win10

• problem
  the minimal examples seems don't work in win10。
  as i run the examples and sent “ping” in cli there is nothing happen;

• analyse

the problem is happen in CLIAdapter ；Actually two more characters were read；

line, err := r.ReadString('\n')
fmt.Printf("len:%d\n",  len(line))
fmt.Printf("real line: %q\n", line)
lines <- line[:len(line)-1]
<========cmd=========>
example-bot > ping
len:6
real line: "ping\r\n"

So it's never been a match，Also will never enter the pong method

regex, _ := regexp.Compile("^(?i)ping$")
matches := regex.FindStringSubmatch("ping\r")
len(matches) == 0

• solution

i can solve it by use lines <- line[:len(line)-2] in CLIAdapter.

I don't know if other platforms or it will have an impact on other places

Add Reactions to Messages

Summary

Many chat services (e.g. Slack, Rocket.Chat, Mattermost, etc.) offer the ability to "react" to messages with emoji. It would be nice to be able to make use of that capability.

Basic example

func DoWork(msg joe.Message) error {
  msg.React(":+1:")
  time.Sleep(1 * time.Second)
  msg.Respond("Job is done")
}

Motivation

Using reactions is an easy way to acknowledge that a command has been received without cluttering up the chat with intermediate results. Simple commands could even skip output entirely and just use reactions.

Potential Issues

Not all Adapters will be able to support reactions (e.g. CLI Adapter). A decision would be necessary for how to handle reactions in this case. My thought would be to fail silently (optionally with a logger warning) and to document that reactions are optional for adapters. An alternative would be to error if not available and to offer a capability to test if reactions are available ReactionsEnabled or perhaps msg.ReactIfEnabled.

Edit 1

Perhaps a pragmatic way to handle the absence of reactions would be a ReactOrRespond function that would add a reaction if able, respond if not.

func DoWork(msg joe.Message) error {
  msg.ReactOrRespond(":+1:", "Job started")
  time.Sleep(1 * time.Second)
  msg.Respond("Job is done")
}

Possible to send a message without having Message struct?

Thanks for putting together this library, I'm just starting to explore it.
I was wondering if there is a recommended method to send an arbitrary message to a channel without needing to "Respond" to a message that has come in.

My [first] use case is that I want to send a message to a channel after receiving a webhook via the http-server.

I suppose one way that I might be able to achieve this is to have the webhook handler publish a joe.ReceiveMessageEvent event with the desired channel that I want to send a message to, then listen for this 'silent' event emitted and respond to it. This will likely work, but it seems like quite a workaround to achieve my goal.

Any insight you can provide would be appreciated.

Thanks

Why do we actually only allow struct events

It would probably be useful to be able to let events also be custom scalar types.

E.g. this:

type CustomType int

Telegram integration

Is there any example with Telegram? Would be cool to see a small example :)

Allow for specifying whether message is DM in `ReceiveMessageEvent`

Currently, the standard joe.ReceiveMessageEvent sent by all documented adapters does not specify whether the message is "private" (a one-on-one chat in Slack, a /msg in IRC, etc).

This can be useful in having handlers process commands differently (e.g. allow admin-level commands in direct chats) depending on the communication mode, without having to either parse the Channel or Data fields (which assumes the handler knows which adapter is being used) or having to use custom events, which assume adapter support.

Slack interactive messages

Do you have any plans to add slack interactive message and dialogs features?

joetest: registration errors are hidden by test bot

Registration errors are hidden by the test bot because they are only returned if the handler is registered before the bot is started.