hugot

README

Hugot

Hugot is a package for building chat bots. It is inspired by Go's http stdlib package.

Please see the GoDoc for examples and usage.

Documentation

Overview

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.

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/
irc - github.com/tcolgate/hugot/adapters/irc - simple irc adapter
shell - github.com/tcolgate/hugot/adapters/shell - simple readline based adapter

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:

RawHandlers will execute for every message sent to them.

HearsHandlers will execute for any message which matches a given regular expression. They are passed all string sub-matches from any capture groups.

Command Handlers act on any direct message. 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

Background handlers, are started when the 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.

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

Mux

The Mux, and CommandMux 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 it.

WARNING: the interface is new and is subject to change. In particular, the Comman/CommandMux code is overly complex and the interface may be simplified to make this easier to use. The HTTP support is currently unused and the interface may change depending on experience of actually using it.

Index

• Variables
• func Add(h Handler) error
• func AddBackgroundHandler(h BackgroundHandler) error
• func AddHTTPHandler(h HTTPHandler) *url.URL
• func AddHearsHandler(h HearsHandler) error
• func AddRawHandler(h RawHandler) error
• func ListenAndServe(ctx context.Context, a Adapter, h Handler)
• func RunBackgroundHandler(ctx context.Context, h BackgroundHandler, w ResponseWriter)
• func RunCommandHandler(ctx context.Context, h CommandHandler, w ResponseWriter, m *Message) error
• func RunHandlers(ctx context.Context, h Handler, a Adapter)
• func RunHearsHandler(ctx context.Context, h HearsHandler, w ResponseWriter, m *Message) bool
• func RunRawHandler(ctx context.Context, h RawHandler, w ResponseWriter, m *Message) bool
• type Adapter
• type Attachment
• type BackgroundFunc
• type BackgroundHandler
  • func NewBackgroundHandler(name, desc string, f BackgroundFunc) BackgroundHandler
• type Channel
• type CommandFunc
• type CommandHandler
  • func NewCommandHandler(name, desc string, f CommandFunc) CommandHandler
• type CommandMux
  • func AddCommandHandler(h CommandHandler) *CommandMux
  • func NewCommandMux(base CommandHandler) *CommandMux
  • func (cx *CommandMux) AddCommandHandler(c CommandHandler) *CommandMux
  • func (cx *CommandMux) Command(ctx context.Context, w ResponseWriter, m *Message) error
  • func (cx *CommandMux) SubCommands() map[string]*CommandMux
• type Describer
• type ErrUsage
  • func (e ErrUsage) Error() string
• type HTTPHandler
  • func NewHTTPHandler(name, desc string, h http.Handler) HTTPHandler
  • func NewHTTPHandlerFunc(name, desc string, h http.HandlerFunc) HTTPHandler
• type Handler
• type HeardFunc
• type HearsHandler
  • func NewHearsHandler(name, desc string, rgxp *regexp.Regexp, f HeardFunc) HearsHandler
• type Message
  • func (m *Message) Parse() error
  • func (m *Message) Reply(txt string) *Message
  • func (m *Message) Replyf(s string, is ...interface{}) *Message
• type Mux
  • func NewMux(name, desc string) *Mux
  • func (mx *Mux) Add(h Handler) error
  • func (mx *Mux) AddBackgroundHandler(h BackgroundHandler) error
  • func (mx *Mux) AddCommandHandler(h CommandHandler) *CommandMux
  • func (mx *Mux) AddHTTPHandler(h HTTPHandler) *url.URL
  • func (mx *Mux) AddHearsHandler(h HearsHandler) error
  • func (mx *Mux) AddRawHandler(h RawHandler) error
  • func (mx *Mux) Describe() (string, string)
  • func (mx *Mux) Handle(ctx context.Context, w ResponseWriter, m *Message) error
  • func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (mx *Mux) StartBackground(ctx context.Context, w ResponseWriter)
• type RawFunc
• type RawHandler
  • func NewRawHandler(name, desc string, f RawFunc) RawHandler
• type Receiver
• type ResponseWriter
  • func NewNullResponseWriter(m Message) ResponseWriter
• type Sender
• type User

Variables

var (
	// ErrSkipHears is used by Command handlers to indicate they have
	// handled a mesage and that any following Hear handlers should be
	// skipped.
	ErrSkipHears = errors.New("skip hear messages")

	// ErrNextCommand is returned if the command wishes the message
	// to be passed to one of the sub-ommands of a CommandMux.
	ErrNextCommand = errors.New("pass this to the next command")

	// ErrUnknownCommand is returned by a command mux if the command did
	// not match any of it's registered handlers.
	ErrUnknownCommand = errors.New("unknown command")

	// ErrBadCLI implies that we could not process this message as a
	// command line. E.g. due to potentially mismatched quoting or bad
	// escaping.
	ErrBadCLI = errors.New("coul not process as command line")
)

Functions

func Add

func Add(h Handler) error

Add adds the provided handler to the DefaultMux

func AddBackgroundHandler

func AddBackgroundHandler(h BackgroundHandler) error

AddBackgroundHandler adds the provided handler to the DefaultMux

func AddHTTPHandler

func AddHTTPHandler(h HTTPHandler) *url.URL

AddHTTPHandler adds the provided handler to the DefaultMux

func AddHearsHandler

func AddHearsHandler(h HearsHandler) error

AddHearsHandler adds the provided handler to the DefaultMux

func AddRawHandler

func AddRawHandler(h RawHandler) error

AddRawHandler adds the provided handler to the DefaultMux

func ListenAndServe

func ListenAndServe(ctx context.Context, a Adapter, h Handler)

ListenAndServe runs the handler h, passing all messages to/from the provided adapter. The context may be used to gracefully shut down the server.

func RunBackgroundHandler

func RunBackgroundHandler(ctx context.Context, h BackgroundHandler, w ResponseWriter)

RunBackgroundHandler starts the provided BackgroundHandler in a new go routine. WARNING: probably not to be used directly and may be made private in the future.

func RunCommandHandler

func RunCommandHandler(ctx context.Context, h CommandHandler, w ResponseWriter, m *Message) error

RunCommandHandler initializes the message m as a command message and passed it to the given handler.WARNING: probably not to be used directly and may be made private in the future.

func RunHandlers

func RunHandlers(ctx context.Context, h Handler, a Adapter)

RunHandlers process messages from adapter a, and passes them to the provided handler h. ctx can be used to stop the processesing and inform any running handlers. WARNING: probably not to be used directly and may be made private in the future.

func RunHearsHandler

func RunHearsHandler(ctx context.Context, h HearsHandler, w ResponseWriter, m *Message) bool

RunHearsHandler will match the go routine. WARNING: probably not to be used directly and may be made private in the future.

func RunRawHandler

func RunRawHandler(ctx context.Context, h RawHandler, w ResponseWriter, m *Message) bool

RunRawHandler passing message m to the provided handler. go routine. WARNING: probably not to be used directly and may be made private in the future.

Types

type Adapter

type Adapter interface {
	Sender
	Receiver
}

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

type Attachment

type Attachment slack.Attachment

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

type BackgroundFunc

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

BackgroundFunc describes the calling convention for Background handlers

type BackgroundHandler

type BackgroundHandler interface {
	Handler
	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

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

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

type Channel

type Channel string

Channel represents discussion channel, such as an IRC channel or Slack channel. The Adapter is responsible for translating between a human name for the channel, and any internal representation

type CommandFunc

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

CommandFunc describes the calling convention for CommandHandler

type CommandHandler

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

CommandHandler handlers are used to implement CLI style commands. Before the Command method is called, the in the incoming message m will have the Text of the message parsed into invidual strings, accouting for quoting. m.Args(0) will be the name of the command as the handler was called, as per os.Args(). Command should add any requires falgs to m and then call m.Parse() ErrNextCommand can be returned to inform the command mux to hand the resulting Args to any known sub CommandHandler.

func NewCommandHandler

func NewCommandHandler(name, desc string, f CommandFunc) CommandHandler

NewCommandHandler wraps the given function f as a CommandHandler with the provided name and description.

type CommandMux

type CommandMux struct {
	CommandHandler
	// contains filtered or unexported fields
}

CommandMux is a handler that support "nested" command line commands.

func AddCommandHandler

func AddCommandHandler(h CommandHandler) *CommandMux

AddCommandHandler adds the provided handler to the DefaultMux

func NewCommandMux

func NewCommandMux(base CommandHandler) *CommandMux

NewCommandMux creates a new CommandMux. The provided base command handler will be called first. This can process any initial flags if desired. If the base command handler returns ErrNextCommand, any command handlers that have been added to this mux will then be called with the message Args having been appropriately adjusted

func (*CommandMux) AddCommandHandler

func (cx *CommandMux) AddCommandHandler(c CommandHandler) *CommandMux

AddCommandHandler adds a sub-command to an existing CommandMux

func (*CommandMux) Command

func (cx *CommandMux) Command(ctx context.Context, w ResponseWriter, m *Message) error

Command implements the Command handler for a CommandMux

func (*CommandMux) SubCommands

func (cx *CommandMux) SubCommands() map[string]*CommandMux

SubCommands returns any known subcommands of this command mux

type Describer

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 ErrUsage

type ErrUsage struct {
	// contains filtered or unexported fields
}

ErrUsage indicates that Command handler was used incorrectly. The string returned is a usage message generated by a call to -help for this command

func (ErrUsage) Error

func (e ErrUsage) Error() string

Error implements the Error interface for an ErrUsage.

type HTTPHandler

type HTTPHandler interface {
	Handler
	http.Handler
}

HTTPHandler handlers are used to add webhooks to your handlers.

func NewHTTPHandler

func NewHTTPHandler(name, desc string, h http.Handler) HTTPHandler

NewHTTPHandler creates a new HTTPHandler with the http.Handler h, and the provided name and description

func NewHTTPHandlerFunc

func NewHTTPHandlerFunc(name, desc string, h http.HandlerFunc) HTTPHandler

NewHTTPHandlerFunc creates a new HTTPHandler with the http.HandlerFunc h, and the provided name and description

type Handler

type Handler interface {
	Describer
}

Handler is a handler with no actual functionality

type HeardFunc

type HeardFunc func(ctx context.Context, w ResponseWriter, m *Message, submatches [][]string) // Called once a message matches, and is passed any submatches from the regexp capture groups

HeardFunc describes the calling convention for a Hears handler.

type HearsHandler

type HearsHandler interface {
	Handler
	Hears() *regexp.Regexp                                                          // Returns the regexp we want to hear
	Heard(ctx context.Context, w ResponseWriter, m *Message, submatches [][]string) // Called once a message matches, and is passed any submatches from the regexp capture groups
}

HearsHandler is a handler which responds to messages matching a specific pattern

func NewHearsHandler

func NewHearsHandler(name, desc string, rgxp *regexp.Regexp, f HeardFunc) HearsHandler

NewHearsHandler wraps f as a Hears handler that reponnds to the regexp provided, with the given name a description

type Message

type Message struct {
	To      string
	From    string
	Channel string

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

	Private bool
	ToBot   bool

	*flag.FlagSet
	// contains filtered or unexported fields
}

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) Parse

func (m *Message) Parse() error

Parse process any Args for this message in line with any flags that have been added to the message.

func (*Message) Reply

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

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

func (*Message) Replyf

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 Mux

type Mux struct {
	*sync.RWMutex
	// contains filtered or unexported fields
}

Mux is a Handler that multiplexes messages to a set of Command, Hears, and Raw handlers.

var DefaultMux *Mux

DefaultMux is a default Mux instance, http Handlers will be added to http.DefaultServeMux

func NewMux

func NewMux(name, desc string) *Mux

NewMux creates a new Mux.

func (*Mux) Add

func (mx *Mux) Add(h Handler) error

Add a generic handler that supports one or more of the handler types. WARNING: This may be removed in the future. Prefer to the specific Add*Handler methods.

func (*Mux) AddBackgroundHandler

func (mx *Mux) AddBackgroundHandler(h BackgroundHandler) error

AddBackgroundHandler adds the provided handler to the Mux. It will be started with the Mux is started.

func (*Mux) AddCommandHandler

func (mx *Mux) AddCommandHandler(h CommandHandler) *CommandMux

AddCommandHandler Adds the provided handler to the mux. The returns CommandMux can be used to add sub-commands to this command handler.

func (*Mux) AddHTTPHandler

func (mx *Mux) AddHTTPHandler(h HTTPHandler) *url.URL

AddHTTPHandler registers h as a HTTP handler. The name of the Mux, and the name of the handler are used to construct a unique URL that can be used to send web requests to this handler

func (*Mux) AddHearsHandler

func (mx *Mux) AddHearsHandler(h HearsHandler) error

AddHearsHandler adds the provided handler to the mux. All messages matching the Hears patterns will be forwarded to the handler.

func (*Mux) AddRawHandler

func (mx *Mux) AddRawHandler(h RawHandler) error

AddRawHandler adds the provided handler to the Mux. All messages sent to the mux will be forwarded to this handler.

func (*Mux) Describe

func (mx *Mux) Describe() (string, string)

Describe implements the Describe method of Handler for the Mux

func (*Mux) Handle

func (mx *Mux) Handle(ctx context.Context, w ResponseWriter, m *Message) error

Handle implements the Handler interface. Message will first be passed to any registered RawHandlers. If the message has been deemed, by the Adapter to have been sent directly to the bot, any comand handlers will be processed. Then, if appropriate, the message will be matched against any Hears patterns and all matching Heard functions will then be called. Any unrecognized errors from the Command handlers will be passed back to the user that sent us the message.

func (*Mux) ServeHTTP

func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP iplements http.ServeHTTP for a Mux to allow it to act as a web server.

func (*Mux) StartBackground

func (mx *Mux) StartBackground(ctx context.Context, w ResponseWriter)

StartBackground starts any registered background handlers.

type RawFunc

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

RawFunc describes the calling convention for RawHandler. m is the incoming message. Responses can be written to w.

type RawHandler

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

RawHandler will recieve every message sent to the handler, without any filtering.

func NewRawHandler

func NewRawHandler(name, desc string, f RawFunc) RawHandler

NewRawHandler will wrap the function f as a RawHandler with the name and description provided

type Receiver

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

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
}

ResponseWriter is used to Send messages back to a user.

func NewNullResponseWriter

func NewNullResponseWriter(m Message) ResponseWriter

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

type Sender

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

Sender can be used to send messages

type User

type User string

User represents a user within the chat sytems. The adapter is responsible for translating the string User to and from it's external representation