twistbot

Documentation

Overview

Package twistbot provides abstractions to build http endpoints working as Twist bot integrations.

Index

• Constants
• Variables
• type Handler
  • func (h *Handler) AddRule(rule Rule)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Message
  • func (m Message) Context(parent context.Context) (context.Context, context.CancelFunc)
  • func (msg Message) Reply(ctx context.Context, client *http.Client, text string, ...) error
  • func (m Message) ReplyDeadline() time.Time
• type Rule
• type Uploader
  • func (upl *Uploader) Upload(ctx context.Context, r io.Reader, name string) (uploadInfo json.RawMessage, err error)

Constants

const (
	OriginComment = "comment" // message comes from comment of a thread
	OriginMessage = "message" // message comes from direct conversation
	OriginThread  = "thread"  // message comes from thread's opening post
)

const DefaultUsage = "Sorry, I'm a bot, I don't know what you mean."

DefaultUsage is a text sent by Handler if none of its rules matched message and Handler's Usage is not set.

Variables

var SkipRule = errors.New("skip rule")

SkipDir is used as a return value from Rules to indicate that rule must be skipped.

Types

type Handler

type Handler struct {
	Token string // token used to verify incoming messages
	// text to reply with if no rules matched; if empty, DefaultUsage is
	// used
	Usage string
	// contains filtered or unexported fields
}

Handler accepts webhook call from Twist bot integration, decodes request into a Message, verifies its authenticity by comparing it with Token, then tries to process message by rules in order they were added by AddRule method.

func (*Handler) AddRule

func (h *Handler) AddRule(rule Rule)

AddRule plugs rule into Handler. Handler probes incoming Message against its rules in order they were added.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Message

type Message struct {
	// Text holds text of the message addressed to bot integration
	Text string `flag:"content"`

	// Origin can be one of comment | message | thread, see Origin*
	// constants
	Origin string `flag:"event_type"`

	// AsyncReplyURL is where asynchronous (delayed) reply should be posted
	// to, if needed.
	AsyncReplyURL string `flag:"url_callback"`

	// TTL is a unix timestamp after which replies posted to AsyncReplyURL
	// would be rejected.
	TTL int64 `flag:"url_ttl"`

	// Workspace id
	Workspace uint64 `flag:"workspace_id"`

	// UserID is the id of message author
	UserID uint64 `flag:"user_id"`

	// UserName is the name of message author
	UserName string `flag:"user_name"`

	// Token is used to verify authenticity of message — its unique value is
	// assigned to each integration.
	Token string `flag:"verify_token"`
}

Message presents data received from Twist bot integration.

func (Message) Context

func (m Message) Context(parent context.Context) (context.Context, context.CancelFunc)

Context returns context derived from parent which is canceled either when parent expires or reply deadline for this message is reached.

func (Message) Reply

func (msg Message) Reply(ctx context.Context, client *http.Client, text string, attachments ...json.RawMessage) error

Reply sends asynchronous reply to a given Message. It automatically takes into account reply deadline. If client is nil, http.DefaultClient is used.

Attachments are zero or more opaque attachment object, see Uploader documentation on how to upload file.

func (Message) ReplyDeadline

func (m Message) ReplyDeadline() time.Time

ReplyDeadline returns message reply deadline. Replies made after this time would be rejected.

type Rule

type Rule func(context.Context, http.ResponseWriter, Message) error

Rule is a function processing incoming message and replying on it. If rule doesn't know how to process message, it must return SkipRule without touching ResponseWriter. If rule successfully processed message, it must reply with nil to stop further processing; if rule replies with error, this error is logged to http.Server.ErrorLog and handler replies with 500 status code when appropriate (if ResponseWriter was not used yet).

Context passed is the one from incoming http.Request; if rule needs to do some background processing and reply asynchronously, it should create new context from message.

If function decides to reply right away, reply should be written plaintext to provided ResponseWriter. It's valid to not reply anything and just return nil. Function may decide to do a follow-up reply as a result of some background asynchronous operation. To do this, use Message.Reply method that posts reply to Message.AsyncReplyURL.

type Uploader

type Uploader struct {
	// Token to access Twist API. It is different from the one used to
	// verify messages.
	Token string
	// http client to use, if nil, http.DefaultClient is used
	Client *http.Client
}

Uploader uploads files to Twist as attachments.

func (*Uploader) Upload

func (upl *Uploader) Upload(ctx context.Context, r io.Reader, name string) (uploadInfo json.RawMessage, err error)

Upload uploads data read from r under given name and returns opaque json object describing uploaded object. It can then be used to describe attachment when replying to message.