README
¶
gobot
A basic bot library for the chat service euphoria.io in golang.
Documentation
¶
Overview ¶
Package gobot provides a golang framework for bots running on the euphoria.io chat service.
Bots can have multiple Rooms, which can be added, removed, started, and stopped dynamically. The Handler interface allows the user to easily write their own code to extend the framework that can reply to incoming packets and also run in the background, with the ability to manipulate the room it is attached to.
A bolt database and a scope.Context are exposed by the room to be used as the user sees fit. The framework itself uses the Context but not the database. Therefore, one should be careful with scope.Context.Waitgroup() - do not Wait unless you are familiar with the internals of the package.
The bolt database provides a persistent key-value store on disk and the scope.Context provides an in-memory key-value store. The framework does not use either of these stores, so the user may use them without fear of collisions.
A small example of a handler is included in the handlers package. It simply replies to a message of "!ping" with "pong!". The program in the sample package uses this to create a simple, functioning bot with the framework.
Index ¶
Constants ¶
const (
// MAXRETRIES is the number of times to retry a connection to euphoria.
MAXRETRIES = 5
)
Variables ¶
This section is empty.
Functions ¶
func MakePacket ¶
func MakePacket(msgType proto.PacketType, payload interface{}) (*proto.Packet, error)
MakePacket is a convenience function that takes a payload and a PacketType and returns a Packet. The message ID of the packet is NOT set.
Types ¶
type Bot ¶
type Bot struct {
Rooms map[string]*Room
BotName string
DB *bolt.DB
// contains filtered or unexported fields
}
Bot is the highest level abstraction- it contains and controls multiple Room structs. Methods on Bot can add the bot to new rooms or, eventually, remove them.
Bot exposes a bolt database for the use of the user. The basic bot does not use the database, so there is no chance of collisions in bucket names or key-value instances.
func NewBot ¶
NewBot creates a bot with the given configuration. It will create a bolt DB if it does not already exist at the specified location.
func (*Bot) AddRoom ¶
func (b *Bot) AddRoom(cfg RoomConfig)
AddRoom adds a new Room to the bot with the given configuration. The context for this room is distinct from the Bot's context.
func (*Bot) RunAllRooms ¶
func (b *Bot) RunAllRooms()
RunAllRooms runs room.Run() for all rooms registered with the bot. It will only return when all rooms are exited- common usage will be running this as a goroutine.
type Connection ¶
type Connection interface {
Connect(r *Room) error
SendJSON(r *Room, msg interface{}) (string, error)
ReceiveJSON(r *Room, p chan *proto.Packet)
Close() error
}
Connection is an interface primarily designed to allow for a mock connecting during testing.
type Handler ¶
type Handler interface {
// HandleIncoming is called whenever a packet is received over the
// connection to euphoria. It is passed a pointer to the calling Room and
// a pointer to that incoming packet.
HandleIncoming(r *Room, p *proto.Packet) (*proto.Packet, error)
// Run is called whenever the Room the Handler is attached to has its Run
// method called. It allows for a Handler to maintain its own state and
// logic between incoming packets. Note, the access to the calling Room
// means that the Handler can send packets that are not directly in response
// to an incoming packet.
Run(r *Room)
// Stop is called whenever the Room the Handler is attached to has its Stop
// method called. The Handler must not block and be available to receive
// a signal from r.Ctx.Done() or check that r.Ctx.Alive() is false.
Stop(r *Room)
}
Handler is an interface that processes incoming packets and optionally returns a packet to be sent by the bot.
The Run method will be called when the Room is run. This allows a handler to maintain state and send packets that are not in response to an incoming packet.
type Room ¶
type Room struct {
RoomName string
Ctx scope.Context
Handlers []Handler
BotName string
Logger *logrus.Logger
DB *bolt.DB
// contains filtered or unexported fields
}
Room contains a connection to a euphoria room and uses Handlers to process packets and optionally reply to them. The DB member points to the same DB initialized by the parent Bot. The Ctx member is distinct from the Bot's ctx member.
func (*Room) Run ¶
Run starts up the necessary goroutines to send, receive, and dispatch packets to handlers.
type RoomConfig ¶
type RoomConfig struct {
RoomName string `yaml:"RoomName"`
Password string `yaml:"Password,omitempty"`
AddlHandlers []Handler
Conn Connection
}
RoomConfig controls the configuration of a new Room when it is added to a Bot.
type WSConnection ¶
type WSConnection struct {
// contains filtered or unexported fields
}
WSConnection is a type that satisfies the Connection interface and manages a websocket connection to a euphoria room.
func (*WSConnection) Close ¶
func (ws *WSConnection) Close() error
Close simply closes the websocket connection, if it is connected.
func (*WSConnection) Connect ¶
func (ws *WSConnection) Connect(r *Room) error
Connect tries to connect to a euphoria room with multiple retries upon error.
func (*WSConnection) ReceiveJSON ¶
func (ws *WSConnection) ReceiveJSON(r *Room, p chan *proto.Packet)
ReceiveJSON reads a message from the websocket and unmarshals it into the provided packet.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package handlers provides several pre-baked gobot.Handlers for convenience.
|
Package handlers provides several pre-baked gobot.Handlers for convenience. |
|
Package main provides some sample code for setting up a bot.
|
Package main provides some sample code for setting up a bot. |