ext

Documentation

Index

• Constants
• Variables
• type Context
  • func NewContext(update *gotgbot.Update, data map[string]interface{}) *Context
  • func (c *Context) Args() []string
• type Dispatcher
  • func NewDispatcher(updates chan json.RawMessage, opts *DispatcherOpts) *Dispatcher
  • func (d *Dispatcher) AddHandler(handler Handler)
  • func (d *Dispatcher) AddHandlerToGroup(handler Handler, group int)
  • func (d *Dispatcher) ProcessRawUpdate(b *gotgbot.Bot, r json.RawMessage)
  • func (d *Dispatcher) ProcessUpdate(b *gotgbot.Bot, update *gotgbot.Update, data map[string]interface{})
  • func (d *Dispatcher) Start(b *gotgbot.Bot)
  • func (d *Dispatcher) Stop()
• type DispatcherAction
• type DispatcherErrorHandler
• type DispatcherOpts
• type DispatcherPanicHandler
• type Handler
• type PollingOpts
• type Updater
  • func NewUpdater(opts *UpdaterOpts) Updater
  • func (u *Updater) Idle()
  • func (u *Updater) StartPolling(b *gotgbot.Bot, opts *PollingOpts) error
  • func (u *Updater) StartWebhook(b *gotgbot.Bot, opts WebhookOpts) error
  • func (u *Updater) Stop() error
• type UpdaterOpts
• type WebhookOpts
  • func (w *WebhookOpts) GetListenAddr() string
  • func (w *WebhookOpts) GetWebhookURL(domain string) string

Constants

const DefaultMaxRoutines = 50

Variables

var (
	EndGroups      = errors.New("group iteration ended")
	ContinueGroups = errors.New("group iteration continued")
)

var ErrMissingCertOrKeyFile = errors.New("missing certfile or keyfile")

Types

type Context

type Context struct {
	*gotgbot.Update
	Data map[string]interface{}

	// EffectiveMessage is the message which triggered the update, if possible
	EffectiveMessage *gotgbot.Message
	// EffectiveChat is the chat the update was triggered in, if possible
	EffectiveChat *gotgbot.Chat
	// EffectiveUser is the user who triggered the update, if possible.
	// Note: when adding a user, the user who ADDED should be the EffectiveUser;
	// they caused the update. If a user joins naturally, then they are the EffectiveUser.
	//
	// WARNING: It may be better to rely on EffectiveSender instead, which allows for easier use
	// in the case of linked channels, anonymous admins, or anonymous channels.
	EffectiveUser *gotgbot.User
	// EffectiveSender is the sender of the update. This can be either:
	// - a user
	// - an anonymous admin of the current chat, speaking through the chat
	// - the linked channel of the current chat
	// - an anonymous user, speaking through a channel
	EffectiveSender *gotgbot.Sender
}

TODO: extend to be used as a generic cancel context?

func NewContext

func NewContext(update *gotgbot.Update, data map[string]interface{}) *Context

NewContext populates a context with the relevant fields from the current update. It takes a data field in the case where custom data needs to be passed.

func (*Context) Args

func (c *Context) Args() []string

Args gets the list of whitespace-separated arguments of the message text.

type Dispatcher

type Dispatcher struct {
	// Error handles any errors that occur during handler execution. The return type determines how to handle the
	// current group iteration. Default is DispatcherActionNoop; move to next group.
	Error DispatcherErrorHandler
	// Panic handles any panics that occur during handler execution.
	// If this field is nil, the stack is logged to ErrorLog.
	Panic DispatcherPanicHandler
	// ErrorLog is the output to log to when handling a library error, or recovering from a panic from user code.
	ErrorLog *log.Logger
	// contains filtered or unexported fields
}

func NewDispatcher

func NewDispatcher(updates chan json.RawMessage, opts *DispatcherOpts) *Dispatcher

NewDispatcher creates a new dispatcher, which process and handles incoming updates from the updates channel.

func (*Dispatcher) AddHandler

func (d *Dispatcher) AddHandler(handler Handler)

AddHandler adds a new handler to the dispatcher. The dispatcher will call CheckUpdate() to see whether the handler should be executed, and then HandleUpdate() to execute it.

func (*Dispatcher) AddHandlerToGroup

func (d *Dispatcher) AddHandlerToGroup(handler Handler, group int)

AddHandlerToGroup adds a handler to a specific group; lowest number will be processed first.

func (*Dispatcher) ProcessRawUpdate

func (d *Dispatcher) ProcessRawUpdate(b *gotgbot.Bot, r json.RawMessage)

func (*Dispatcher) ProcessUpdate

func (d *Dispatcher) ProcessUpdate(b *gotgbot.Bot, update *gotgbot.Update, data map[string]interface{})

ProcessUpdate iterates over the list of groups to execute the matching handlers.

func (*Dispatcher) Start

func (d *Dispatcher) Start(b *gotgbot.Bot)

Start to handle incoming updates.

func (*Dispatcher) Stop

func (d *Dispatcher) Stop()

Stop waits for all currently processing updates to finish, and then returns.

type DispatcherAction

type DispatcherAction int64

const (
	// DispatcherActionNoop stops iteration of current group and moves to the next one.
	// This is the default action, and the same as would happen if the handler had completed successfully.
	DispatcherActionNoop DispatcherAction = iota
	// DispatcherActionContinueGroups continues iterating over current group as if the current handler did not match.
	// Functionally the same as returning ContinueGroups.
	DispatcherActionContinueGroups
	// DispatcherActionEndGroups ends all group iteration.
	// Functionally the same as returning EndGroups.
	DispatcherActionEndGroups
)

type DispatcherErrorHandler

type DispatcherErrorHandler func(b *gotgbot.Bot, ctx *Context, err error) DispatcherAction

DispatcherErrorHandler allows for handling the returned errors from matched handlers. It takes the non-nil error returned by the handler.

type DispatcherOpts

type DispatcherOpts struct {
	// Error handles any errors that occur during handler execution.
	Error DispatcherErrorHandler
	// Panic handles any panics that occur during handler execution.
	// If no panic handlers are defined, the stack is logged to ErrorLog.
	Panic DispatcherPanicHandler
	// ErrorLog is the output to log to when handling a library error, or recovering from a panic from user code.
	ErrorLog *log.Logger

	// MaxRoutines is used to decide how to limit the number of goroutines spawned by the dispatcher.
	// If MaxRoutines == 0, DefaultMaxRoutines is used instead.
	// If MaxRoutines < 0, no limits are imposed.
	// If MaxRoutines > 0, that value is used.
	MaxRoutines int
}

type DispatcherPanicHandler

type DispatcherPanicHandler func(b *gotgbot.Bot, ctx *Context, r interface{})

DispatcherPanicHandler allows for handling goroutine panics, where the 'r' value contains the reason for the panic.

type Handler

type Handler interface {
	// CheckUpdate checks whether the update should handled by this handler.
	CheckUpdate(b *gotgbot.Bot, u *gotgbot.Update) bool
	// HandleUpdate processes the update.
	HandleUpdate(b *gotgbot.Bot, ctx *Context) error
	// Name gets the handler name; used to differentiate handlers programmatically. Names should be unique.
	Name() string
}

type PollingOpts

type PollingOpts struct {
	// DropPendingUpdates decides whether or not to drop "pending" updates; these are updates which were sent before
	// the bot was started.
	DropPendingUpdates bool
	// Timeout is the local HTTP client timeout to be used. It is recommended to set this to GetUpdateOpts.Timeout+1.
	Timeout time.Duration
	// GetUpdatesOpts represents the opts passed to GetUpdates.
	// Note: It is recommended you edit the values here when running in production environments.
	// Changes might include:
	//    - Changing the "GetUpdatesOpts.AllowedUpates" to only refer to relevant updates
	//    - Using a non-0 "GetUpdatesOpts.Timeout" value. This is how "long" telegram will hold the long-polling call
	//    while waiting for new messages. A value of 0 causes telegram to reply immediately, which will then cause
	//    your bot to immediately ask for more updates. While this can seem fine, it will eventually causing
	//    telegram to delay your requests when left running over longer periods. If you are seeing lots
	//    of "context deadline exceeded" errors on GetUpdates, this is likely the cause.
	//    Keep in mind that a timeout of 10 does not mean you only get updates every 10s; by the nature of
	//    long-polling, Telegram responds to your request as soon as new messages are available.
	//    When setting this, it is recommended you set your PollingOpts.Timeout value to be slightly bigger (eg, +1).
	GetUpdatesOpts gotgbot.GetUpdatesOpts
}

PollingOpts represents the optional values to start long polling.

type Updater

type Updater struct {
	Dispatcher *Dispatcher
	UpdateChan chan json.RawMessage
	ErrorLog   *log.Logger
	// contains filtered or unexported fields
}

func NewUpdater

func NewUpdater(opts *UpdaterOpts) Updater

NewUpdater Creates a new Updater, as well as the necessary structures required for the associated Dispatcher.

func (*Updater) Idle

func (u *Updater) Idle()

Idle starts an infinite loop to avoid the program exciting while the background threads handle updates.

func (*Updater) StartPolling

func (u *Updater) StartPolling(b *gotgbot.Bot, opts *PollingOpts) error

StartPolling starts polling updates from telegram using the getUdpates long-polling method. See the PollingOpts for optional values to set in production environments.

func (*Updater) StartWebhook

func (u *Updater) StartWebhook(b *gotgbot.Bot, opts WebhookOpts) error

StartWebhook Starts the webhook server. The opts parameter allows for specifying TLS settings.

func (*Updater) Stop

func (u *Updater) Stop() error

Stop stops the current updater and dispatcher instances.

type UpdaterOpts

type UpdaterOpts struct {
	ErrorLog *log.Logger

	DispatcherOpts DispatcherOpts
}

type WebhookOpts

type WebhookOpts struct {
	Listen  string
	Port    int
	URLPath string

	CertFile string
	KeyFile  string
}

func (*WebhookOpts) GetListenAddr

func (w *WebhookOpts) GetListenAddr() string

GetListenAddr returns the local listening address, including port.

func (*WebhookOpts) GetWebhookURL

func (w *WebhookOpts) GetWebhookURL(domain string) string

GetWebhookURL returns the domain in the form domain/path. eg: example.com/super_secret_token