hugot: github.com/tcolgate/hugot Index | Examples | Files | Directories

package hugot

import "github.com/tcolgate/hugot"

Package hugot provides a simple interface for building extensible chat bots in an idiomatic go style. It is heavily influenced by net/http, and uses an internal message format that is compatible with Slack messages.

Note: This package requires go1.7

Adapters

Adapters are used to integrate with external chat systems. Currently the following adapters exist:

slack - github.com/tcolgate/hugot/adapters/slack - for https://slack.com/
mattermost - github.com/tcolgate/hugot/adapters/mattermost - for https://www.mattermost.org/
irc - github.com/tcolgate/hugot/adapters/irc - simple irc adapter
shell - github.com/tcolgate/hugot/adapters/shell - simple readline based adapter
ssh - github.com/tcolgate/hugot/adapters/ssh - Toy implementation of unauth'd ssh interface

Examples of using these adapters can be found in github.com/tcolgate/hugot/cmd

Handlers

Handlers process messages. There are a several built in handler types:

- Plain Handlers will execute for every message sent to them.

- Background handlers, are started when a bot is started. They do not receive messages but can send them. They are intended to implement long lived background tasks that react to external inputs.

- WebHook handlers can be used to implement web hooks by adding the bot to a http.ServeMux. A URL is built from the name of the handler.

In addition to these basic handlers some more complex handlers are supplied.

- Hears Handlers will execute for any message which matches a given regular expression.

- Command Handlers act as command line tools. Message are attempted to be processed as a command line. Quoted text is handle as a single argument. The passed message can be used as a flag.FlagSet.

- A Mux. The Mux will multiplex message across a set of handlers. In addition, a top level "help" Command handler is added to provide help on usage of the various handlers added to the Mux.

WARNING: The API is still subject to change.

Code:

slackToken := flag.String("token", os.Getenv("SLACK_TOKEN"), "Slack API Token")
nick := flag.String("nick", "minion", "Bot nick")
flag.Parse()

// The context can be used to shutdown the bot and any
// Background handlers gracefully.
ctx := context.Background()
a, err := slack.New(*slackToken, *nick)
if err != nil {
    glog.Fatal(err)
}

testweb.Register()
tableflip.Register()
ping.Register()

// This will start the default bot and process
// all messages seen by the slack adapter
bot.ListenAndServe(ctx, nil, a)

Index

Examples

Package Files

adapter.go background.go context.go doc.go handler.go message.go webhook.go

func AttachmentFieldFromTemplates Uses

func AttachmentFieldFromTemplates(tmpls *template.Template, data interface{}) (slack.AttachmentField, error)

AttachmentFieldFromTemplates builds an attachment field from a set of templates templates can include "field_title","field_value", and "field_short". "field_short" should expand to "true" or "false".

func IsTextOnly Uses

func IsTextOnly(s Sender) bool

IsTextOnly returns true if the sender only support text.

func NewAdapterContext Uses

func NewAdapterContext(ctx context.Context, a Adapter) context.Context

NewAdapterContext creates a context for passing an adapter. This is mainly used by web handlers.

type Adapter Uses

type Adapter interface {
    Sender
    Receiver
}

Adapter can be used to communicate with an external chat system such as slack or IRC.

func AdapterFromContext Uses

func AdapterFromContext(ctx context.Context) (Adapter, bool)

AdapterFromContext returns the Adapter stored in a context.

type Attachment Uses

type Attachment slack.Attachment

Attachment represents a rich message attachment and is directly modeled on the Slack attachments API

func AttachmentFromTemplates Uses

func AttachmentFromTemplates(tmpls *template.Template, data interface{}, fields ...slack.AttachmentField) (Attachment, error)

AttachmentFromTemplates builds an attachment from aset of templates. Template can include the following individual template items: title, title_link, color, author_name, author_link, author_icon, image_url, thumb_url, pretext, text, fallback, fields_json. fields_json will be parsed as json, and any fields found will be appended to those in the fields arguments

type BackgroundFunc Uses

type BackgroundFunc func(ctx context.Context, w ResponseWriter)

BackgroundFunc describes the calling convention for Background handlers

type BackgroundHandler Uses

type BackgroundHandler interface {
    Describer
    StartBackground(ctx context.Context, w ResponseWriter)
}

BackgroundHandler gets run when the bot starts listening. They are intended for publishing messages that are not in response to any specific incoming message.

func NewBackgroundHandler Uses

func NewBackgroundHandler(name, desc string, f BackgroundFunc) BackgroundHandler

NewBackgroundHandler wraps f up as a BackgroundHandler with the name and description provided.

type ChannelManager Uses

type ChannelManager interface {
    Adapter
    Join(channel string) error
    Invite(channel string, user string) error
    CreateChannel(channel string) error
    LeaveChannel(channel string) error
    SetChannelTopic(channel, topic string)
}

ChannelManager is implemented by adapters that allow us to manage channels

type Describer Uses

type Describer interface {
    Describe() (string, string)
}

Describer returns the name and description of a handler. This is used to identify the handler within Command and HTTP Muxs, and to provide a descriptive name for the handler in help text.

type Handler Uses

type Handler interface {
    Describer
    ProcessMessage(ctx context.Context, w ResponseWriter, m *Message) error
}

Handler is a handler with no actual functionality

type HandlerFunc Uses

type HandlerFunc func(ctx context.Context, w ResponseWriter, m *Message) error

HandlerFunc describes a function that can be used as a hugot handler.

type Message Uses

type Message struct {
    To      string
    From    string
    Channel string

    UserID string // Verified user identitify within the source adapter

    Text        string // A plain text message
    Attachments []Attachment

    Private bool
    ToBot   bool

    Store storage.Storer
}

Message describes a Message from or to a user. It is intended to provided a resonable lowest common denominator for modern chat systems. It takes the Slack message format to provide that minimum but makes no assumption about support for any markup. If used within a command handler, the message can also be used as a flag.FlagSet for adding and processing the message as a CLI command.

func (*Message) Copy Uses

func (m *Message) Copy() *Message

Copy is used to provide a deep copy of a message

func (*Message) Reply Uses

func (m *Message) Reply(txt string) *Message

Reply returns a messsage with Text tx and the From and To fields switched

func (*Message) Replyf Uses

func (m *Message) Replyf(s string, is ...interface{}) *Message

Replyf returns message with txt set to the fmt.Printf style formatting, and the from/to fields switched.

type Receiver Uses

type Receiver interface {
    Receive() <-chan *Message // Receive returns a channel that can be used to read one message, nil indicated there will be no more messages
}

Receiver cam ne used to receive messages

type ResponseWriter Uses

type ResponseWriter interface {
    Sender
    io.Writer

    SetChannel(c string) // Forces messages to a certain channel
    SetTo(to string)     // Forces messages to a certain user
    SetSender(a Sender)  // Forces messages to a different sender or adapter

    Copy() ResponseWriter // Returns a copy of this response writer
}

ResponseWriter is used to Send messages back to a user.

func NewNullResponseWriter Uses

func NewNullResponseWriter(m Message) ResponseWriter

NewNullResponseWriter creates a ResponseWriter that discards all message sent to it.

func NewResponseWriter Uses

func NewResponseWriter(s Sender, m Message, adapterName string) ResponseWriter

NewResponseWriter creates a response writer that will send mesages via the provided sender.

func ResponseWriterFromContext Uses

func ResponseWriterFromContext(ctx context.Context) (ResponseWriter, bool)

ResponseWriterFromContext constructs a ResponseWriter from the adapter stored in the context. A destination Channel/User must be set to send messages..

type Sender Uses

type Sender interface {
    Send(ctx context.Context, m *Message)
}

Sender can be used to send messages

func SenderFromContext Uses

func SenderFromContext(ctx context.Context) (Sender, bool)

SenderFromContext can be used to retrieve a valid sender from a context. This is mostly useful in WebHook handlers for sneding messages back to the inbound Adapter.

type TextOnly Uses

type TextOnly interface {
    Sender
    IsTextOnly()
}

TextOnly is an interface to hint to handlers that the adapter they are talking to is a text only handler, to help adjust output.

type WebHookHandler Uses

type WebHookHandler interface {
    Describer
    URL() *url.URL      // Is called to retrieve the location of the Handler
    SetURL(*url.URL)    // Is called after the WebHook is added, to inform it where it lives
    SetAdapter(Adapter) // Is called to set the default adapter for this handler to use
    http.Handler
}

WebHookHandler handlers are used to expose a registered handler via a web server. The SetURL method is called to inform the handler what it's external URL will be. This will normally be done by the Mux. Other handlers can use URL to generate links suitable for external use. You can use the http.Handler Request.Context() to get a ResponseWriter to write into the bots adapters. You need to SetChannel the resulting ResponseWriter to send messages.

func NewWebHookHandler Uses

func NewWebHookHandler(name, desc string, hf http.HandlerFunc) WebHookHandler

NewWebHookHandler creates a new WebHookHandler provided name and description.

type WebHookHandlerFunc Uses

type WebHookHandlerFunc func(ctx context.Context, hw ResponseWriter, w http.ResponseWriter, r *http.Request)

WebHookHandlerFunc describes the calling convention for a WebHook.

Directories

PathSynopsis
adaptersPackage adapters contains a set of implementations of adapters that can be used to integrate hugot with existing chat networks.
adapters/ircPackage irc implements a simple adapter for IRC using github.com/fluffle/goirc/client
adapters/mattermostPackage mattermost implements an adapter for http://mm.com
adapters/shellPackage shell implements a simple adapter that provides a readline style shell adapter for debugging purposes
adapters/slackPackage slack implements an adapter for http://slack.com using github.com/slack-go/slack
adapters/sshPackage ssh implements an adapter that serves SSH connections.
bot
cmd/hugot
cmd/hugot-irc
cmd/hugot-mm
cmd/hugot-multi
cmd/hugot-shell
cmd/hugot-ssh
handlersPackage handlers provides a set of useful handlers for manipulating messages.
handlers/aliasPackage alias imeplements user customizable aliases for commands.
handlers/basic
handlers/commandPackage command provides CLI style interactive commands.
handlers/command/pingPackage ping provides a handler that replies to any message sent
handlers/command/testcliPackage testcli provides an example Command handler with nested command handling.
handlers/command/uptimePackage uptime provides a handler that replies to any message sent
handlers/hears
handlers/hears/tableflipPackage tableflip provides an exacmple Hears handler that will flip tables on behalf of embittered users.
handlers/mux
handlers/rolesPackage roles is intended to provide Roles Based access controls for users and channels.
handlers/testwebPackage testweb provides an example webhook handler
hugottest
scopePackage scope describes hugot's mesage scoping.
storagePackage storage describes an interface for storing of hugot handler data in a Key/Value store.
storage/etcdPackage etcd implemets a hugot store over an etcd datastore
storage/memoryPackage memory implements a hugot store in memory.
storage/prefixPackage prefix implements a hugot Storer that wraps another store and ddds an additional prefix to all keys.
storage/propertiesPackage properties implements a layer on top of the scoped store.
storage/redisPackage redis implements a hugot Store that is backed by a redis database using gopkg.in/redis.v5
storage/scopedPackage scoped implements scoping for a hugot Store.

Package hugot imports 13 packages (graph) and is imported by 29 packages. Updated 2020-05-03. Refresh now. Tools for package owners.