adapter

README

Contains:

• adapter: An interface representing an Adapter, which connects to a chat provider and converts provider-specific events into Gort events.
• events: descriptions of the various Gort events, provided by an Adapter implementation
• tokenize: splits a command string into parameter tokens.

Also contains some data wrapper structs:

• ProviderInfo - info about a generic provider
• ChannelInfo - info about a generic provider "channel" (which can contain provider-specific values, like ID)
• UserInfo - info about a generic user (which can contain provider-specific values, like ID)

Documentation

Index

• Variables
• func AddAdapter(a Adapter)
• func GetCommandEntry(ctx context.Context, bundleName, commandName string) (data.CommandEntry, error)
• func OnChannelMessage(ctx context.Context, event *ProviderEvent, data *ChannelMessageEvent) (*data.CommandRequest, error)
• func OnConnected(ctx context.Context, event *ProviderEvent, data *ConnectedEvent)
• func OnDirectMessage(ctx context.Context, event *ProviderEvent, data *DirectMessageEvent) (*data.CommandRequest, error)
• func StartListening(ctx context.Context) (<-chan data.CommandRequest, chan<- data.CommandResponse, <-chan error)
• func TokenizeParameters(commandString string) []string
• func TriggerCommand(ctx context.Context, rawCommand string, id RequestorIdentity) (*data.CommandRequest, error)
• type Adapter
  • func GetAdapter(name string) (Adapter, error)
• type AuthenticationErrorEvent
• type ChannelInfo
• type ChannelJoinedEvent
• type ChannelMessageEvent
• type ConnectedEvent
• type DirectMessageEvent
• type DisconnectedEvent
• type ErrorEvent
  • func (e ErrorEvent) Error() string
• type EventType
• type Info
• type ProviderEvent
• type ProviderInfo
  • func NewProviderInfoFromConfig(provider data.Provider) *ProviderInfo
• type RequestorIdentity
• type UserInfo

Variables

var (
	// ErrAdapterNameCollision is emitted by AddAdapter() if two adapters
	// have the same name.
	ErrAdapterNameCollision = errors.New("adapter name collision")

	// ErrAuthenticationFailure is emitted when an AuthenticationErrorEvent
	// is received.
	ErrAuthenticationFailure = errors.New("authentication failure")

	// ErrChannelNotFound is returned when OnChannelMessage can't find
	// information is the originating channel.
	ErrChannelNotFound = errors.New("channel not found")

	// ErrGortNotBootstrapped is returned by findOrMakeGortUser() if a user
	// attempts to trigger a command but Gort hasn't yet been bootstrapped.
	ErrGortNotBootstrapped = errors.New("gort hasn't been bootstrapped yet")

	// ErrSelfRegistrationOff is returned by findOrMakeGortUser() if an unknown
	// user attempts to trigger a command but self-registration is configured
	// to false.
	ErrSelfRegistrationOff = errors.New("user doesn't exist and self-registration is off")

	// ErrMultipleCommands is returned by GetCommandEntry when the same command
	// shortcut matches commands in two or more bundles.
	ErrMultipleCommands = errors.New("multiple commands match that pattern")

	// ErrNoSuchAdapter is returned by GetAdapter if a requested adapter name
	// can't be found.
	ErrNoSuchAdapter = errors.New("no such adapter")

	// ErrNoSuchCommand is returned by GetCommandEntry if a request command
	// isn't found.
	ErrNoSuchCommand = errors.New("no such bundle")

	// ErrUserNotFound is throws by several methods if a provider fails to
	// return requested user information.
	ErrUserNotFound = errors.New("user not found")
)

Functions

func AddAdapter

func AddAdapter(a Adapter)

AddAdapter adds an adapter.

func GetCommandEntry

func GetCommandEntry(ctx context.Context, bundleName, commandName string) (data.CommandEntry, error)

GetCommandEntry accepts a tokenized parameter slice and returns any associated data.CommandEntry instances. If the number of matching commands is > 1, an error is returned.

func OnChannelMessage

func OnChannelMessage(ctx context.Context, event *ProviderEvent, data *ChannelMessageEvent) (*data.CommandRequest, error)

OnChannelMessage handles ChannelMessageEvent events. If a command is found in the text, it will emit a data.CommandRequest instance to the commands channel. TODO Support direct in-channel mentions.

func OnConnected

func OnConnected(ctx context.Context, event *ProviderEvent, data *ConnectedEvent)

OnConnected handles ConnectedEvent events.

func OnDirectMessage

func OnDirectMessage(ctx context.Context, event *ProviderEvent, data *DirectMessageEvent) (*data.CommandRequest, error)

OnDirectMessage handles DirectMessageEvent events.

func StartListening

func StartListening(ctx context.Context) (<-chan data.CommandRequest, chan<- data.CommandResponse, <-chan error)

StartListening instructs all relays to establish connections, receives all events from all relays, and forwards them to the various On* handler functions.

func TokenizeParameters

func TokenizeParameters(commandString string) []string

TokenizeParameters splits a command string into parameter tokens. Any trigger characters (i.e., !) are expected to have already been removed.

func TriggerCommand

func TriggerCommand(ctx context.Context, rawCommand string, id RequestorIdentity) (*data.CommandRequest, error)

TriggerCommand is called by OnChannelMessage or OnDirectMessage when a valid command trigger is identified. This function is at the core Gort's command response capabilities, and it's the most complex in the project. This looks like a long, complicated function, but it's like 75% logging and tracing.

Types

type Adapter

type Adapter interface {
	// GetChannelInfo provides info on a specific provider channel accessible
	// to the adapter.
	GetChannelInfo(channelID string) (*ChannelInfo, error)

	// GetName provides the name of this adapter as per the configuration.
	GetName() string

	// GetPresentChannels returns a slice of channels that the adapter is present in.
	GetPresentChannels() ([]*ChannelInfo, error)

	// GetUserInfo provides info on a specific provider user accessible
	// to the adapter.
	GetUserInfo(userID string) (*UserInfo, error)

	// Listen causes the Adapter to initiate a connection to its provider and
	// begin relaying back events (including errors) via the returned channel.
	Listen(ctx context.Context) <-chan *ProviderEvent

	// SendErrorMessage sends an error message to a specified channel.
	// TODO Create a MessageBuilder at some point to replace this.
	SendErrorMessage(channelID string, title string, text string) error

	// SendMessage sends a standard output message to a specified channel.
	// TODO Create a MessageBuilder at some point to replace this.
	SendMessage(channel string, message string) error
}

Adapter represents a connection to a chat provider.

func GetAdapter

func GetAdapter(name string) (Adapter, error)

GetAdapter returns the requested adapter instance, if one exists. If not, an error is returned.

type AuthenticationErrorEvent

type AuthenticationErrorEvent struct {
	Msg string
}

AuthenticationErrorEvent indicates failure to authenticate

type ChannelInfo

type ChannelInfo struct {
	ID      string
	Members []string
	Name    string
}

ChannelInfo contains the basic information for a single channel in any provider.

type ChannelJoinedEvent

type ChannelJoinedEvent struct {
	Channel string
}

ChannelJoinedEvent indicates the bot has joined a channel

type ChannelMessageEvent

type ChannelMessageEvent struct {
	ChannelID string
	Text      string
	UserID    string
}

ChannelMessageEvent indicates received a message via a public or private channel (message.channels)

type ConnectedEvent

type ConnectedEvent struct {
}

ConnectedEvent indicates the client has successfully connected to the provider server

type DirectMessageEvent

type DirectMessageEvent struct {
	ChannelID string
	Text      string
	UserID    string
}

DirectMessageEvent indicates the bot has received a direct message from a user (message.im)

type DisconnectedEvent

type DisconnectedEvent struct {
	Intentional bool
}

DisconnectedEvent indicates the client has disconnected from the provider server

type ErrorEvent

type ErrorEvent struct {
	Code int
	Msg  string
}

ErrorEvent indicates an error reported by the provider. The occurs before a successful connection, Code will be unset.

func (ErrorEvent) Error

func (e ErrorEvent) Error() string

type EventType

type EventType string

EventType specifies the kind of event received from an adapter in response to an event from the chat server.

const (
	EventChannelMessage      EventType = "channel_message"
	EventConnected           EventType = "connected"
	EventConnectionError     EventType = "connection_error"
	EventDirectMessage       EventType = "direct_message"
	EventDisconnected        EventType = "disconnected"
	EventAuthenticationError EventType = "authentication_error"
	EventError               EventType = "error"
)

type Info

type Info struct {
	Provider *ProviderInfo
}

Info is used by events to wrap user and provider info.

type ProviderEvent

type ProviderEvent struct {
	// The type of event
	EventType EventType

	// The event instance
	Data interface{}

	// Contextual info (user, provider)
	Info *Info

	// The adapter that generated the event
	Adapter Adapter
}

ProviderEvent is the main wrapper. You will find all the other messages attached as Data

type ProviderInfo

type ProviderInfo struct {
	Type string
	Name string
}

ProviderInfo contains the basic information for a chat provider.

func NewProviderInfoFromConfig

func NewProviderInfoFromConfig(provider data.Provider) *ProviderInfo

NewProviderInfoFromConfig can create a ProviderInfo from a data.Provider instance.

type RequestorIdentity

type RequestorIdentity struct {
	Adapter     Adapter
	ChatUser    *UserInfo
	ChatChannel *ChannelInfo
	GortUser    *rest.User
}

type UserInfo

type UserInfo struct {
	ID                    string
	Name                  string
	DisplayName           string
	DisplayNameNormalized string
	Email                 string
	FirstName             string
	LastName              string
	RealName              string
	RealNameNormalized    string
}

UserInfo contains the basic information for a single user in any chat provider.