ratelimiter

README

Rate Limiter - gotgbot

Name: Rate Limiter
Version: v1.0.7
Edit: 2 Feb 2021
By: ALiwoto and Contributors (C)

---

How to use

import "github.com/AnimeKaizoku/ratelimiter/ratelimiter"


func loadLimiter(d *ext.Dispatcher) {
	limiter = ratelimiter.NewLimiter(d, &ratelimiter.LimiterConfig{
		ConsiderChannel:  false,
		ConsiderUser:     true,
		ConsiderEdits:    false,
		IgnoreMediaGroup: true,
		TextOnly:         false,
		HandlerGroups:    []int{0, 1, 2},
	})

	// 14 messages per 6 seconds
	limiter.SetFloodWaitTime(6 * time.Second)
	limiter.SetMaxMessageCount(14)

	// add sudo users as exceptions, so they don't get rate-limited by library
	limiter.AddExceptionID(sudoUsers...)

	limiter.Start()
}

---

Helpful links:

• Support group on telegram
• Contact maintainer on telegram

Documentation

Index

• Constants
• type Limiter
  • func NewFullLimiter(dispatcher *ext.Dispatcher) *Limiter
  • func NewLimiter(dispatcher *ext.Dispatcher, config *LimiterConfig) *Limiter
  • func (l *Limiter) AddCondition(condition filters.Message)
  • func (l *Limiter) AddConditions(conditions ...filters.Message)
  • func (l *Limiter) AddCustomIgnore(id int64, d time.Duration, ignoreExceptions bool)
  • func (l *Limiter) AddException(ex filters.Message)
  • func (l *Limiter) AddExceptionID(id ...int64)
  • func (l *Limiter) AppendTriggerFunc(t handlers.Response)
  • func (l *Limiter) AppendTriggerFuncs(t ...handlers.Response)
  • func (l *Limiter) ClearAllConditions()
  • func (l *Limiter) ClearAllExceptionIDs()
  • func (l *Limiter) ClearAllExceptions()
  • func (l *Limiter) GetExceptions() []filters.Message
  • func (l *Limiter) GetStatus(id int64) *UserStatus
  • func (l *Limiter) IsAllowingChannels() bool
  • func (l *Limiter) IsAllowingEdits() bool
  • func (l *Limiter) IsEnabled() bool
  • func (l *Limiter) IsInExceptionList(id int64) bool
  • func (l *Limiter) IsStopped() bool
  • func (l *Limiter) IsTextOnly() bool
  • func (l *Limiter) RemoveCustomIgnore(id int64)
  • func (l *Limiter) SetAsConditions(conditions []filters.Message)
  • func (l *Limiter) SetAsExceptionList(list []int64)
  • func (l *Limiter) SetDefaultInterval()
  • func (l *Limiter) SetFloodWaitTime(d time.Duration)
  • func (l *Limiter) SetMaxCacheDuration(d time.Duration)
  • func (l *Limiter) SetMaxMessageCount(count int)
  • func (l *Limiter) SetPunishmentDuration(d time.Duration)
  • func (l *Limiter) SetTextOnly(t bool)
  • func (l *Limiter) SetTriggerFunc(t handlers.Response)
  • func (l *Limiter) SetTriggerFuncs(t ...handlers.Response)
  • func (l *Limiter) Start()
  • func (l *Limiter) Stop()
• type LimiterConfig
• type UserStatus
  • func (s *UserStatus) IsCustomLimited() bool
  • func (s *UserStatus) IsLimited() bool

Constants

const (
	DefaultTimeout        = 4 * time.Second
	DefaultPunishmentTime = 4 * time.Minute
	DefaultMaxTimeout     = 30 * time.Minute
	DefaultMessageCount   = 15
)

Types

type Limiter

type Limiter struct {

	// IgnoreMediaGroup should be set to true when we have to ignore
	// album messages (such as album musics, album photos, etc...) and
	// don't check them at all.
	// default value for this field is true.
	IgnoreMediaGroup bool

	// TextOnly should be set to true when we have to ignore
	// media messages (such as photos, videos, audios, etc...) and
	// don't check them at all.
	// If your bot has nothing to do with media messages, you can set
	// this to true.
	TextOnly bool

	// IsStrict will tell the limiter whether it should act more strict
	// or not. If this value is set to `true`, the user should NOT send
	// any messages to the bot until it's limit time is completely over.
	// otherwise the limitation will remain on the user until it stops
	// sending any messages to the bot.
	// (A truly bad way of handling anti-floodwait... we recommend not to
	// set this value to `true`, unless it's very very necessary).
	IsStrict bool

	// ConsiderUser will be true when the limiter needs to consider users
	// for their checking the messages. so the user's ID will be used as key
	// to access the map.
	ConsiderUser bool

	// ConsiderInline fields will determine whether we need to
	ConsiderInline bool
	// contains filtered or unexported fields
}

Limiter is the main struct of this library.

func NewFullLimiter

func NewFullLimiter(dispatcher *ext.Dispatcher) *Limiter

NewFullLimiter creates a new `Limiter` with the given dispatcher. it will initialize a limiter which checks for messages received from channels and edited messages.

func NewLimiter

func NewLimiter(dispatcher *ext.Dispatcher, config *LimiterConfig) *Limiter

NewLimiter creates a new `Limiter` with the given dispatcher. pass true for the second parameter if you want the limiter to check messages in channels too. pass true for the third parameter if you want the limiter to check edited messages too.

func (*Limiter) AddCondition

func (l *Limiter) AddCondition(condition filters.Message)

AddCondition will add a condition to be checked by this limiter, if this condition doesn't return true, the limiter won't check the message for anti-flood-wait.

func (*Limiter) AddConditions

func (l *Limiter) AddConditions(conditions ...filters.Message)

AddConditions will accept an array of the conditions and will add them to the condition list of this limiter. you can also pass only one value to this method.

func (*Limiter) AddCustomIgnore

func (l *Limiter) AddCustomIgnore(id int64, d time.Duration, ignoreExceptions bool)

func (*Limiter) AddException

func (l *Limiter) AddException(ex filters.Message)

AddException will add an exception filter to this limiter.

func (*Limiter) AddExceptionID

func (l *Limiter) AddExceptionID(id ...int64)

AddExceptionID will add a group/user/channel ID to the exception list of the limiter.

func (*Limiter) AppendTriggerFunc

func (l *Limiter) AppendTriggerFunc(t handlers.Response)

AppendTriggerFunc will append a trigger function to the trigger functions list of this limiter.

func (*Limiter) AppendTriggerFuncs

func (l *Limiter) AppendTriggerFuncs(t ...handlers.Response)

AppendTriggerFuncs will append trigger functions to the trigger functions list of this limiter.

func (*Limiter) ClearAllConditions

func (l *Limiter) ClearAllConditions()

ClearAllConditions clears all condition list.

func (*Limiter) ClearAllExceptionIDs

func (l *Limiter) ClearAllExceptionIDs()

ClearAllExceptions will clear all exception IDs of this limiter. this way, you will be sure that all of incoming updates will be checked for floodwait by this limiter.

func (*Limiter) ClearAllExceptions

func (l *Limiter) ClearAllExceptions()

ClearAllExceptions will clear all exception of this limiter. this way, you will be sure that all of incoming updates will be checked for floodwait by this limiter.

func (*Limiter) GetExceptions

func (l *Limiter) GetExceptions() []filters.Message

GetExceptions returns the filters array used by this limiter as its exceptions list.

func (*Limiter) GetStatus

func (l *Limiter) GetStatus(id int64) *UserStatus

GetStatus will get the status of a chat. if `l.ConsiderUser` parameter is set to `true`, the id should be the id of the user; otherwise you should use the id of the chat to get the status.

func (*Limiter) IsAllowingChannels

func (l *Limiter) IsAllowingChannels() bool

IsAllowingChannels will return true if and only if this limiter is checking for messages from channels.

func (*Limiter) IsAllowingEdits

func (l *Limiter) IsAllowingEdits() bool

IsAllowingEdits will return true if and only if this limiter is checking for "edited message" update from telegram.

func (*Limiter) IsEnabled

func (l *Limiter) IsEnabled() bool

IsEnabled returns true if and only if this limiter is enabled and is checking the incoming messages for floodwait. for enabling the limiter, you need to use `Start` method.

func (*Limiter) IsInExceptionList

func (l *Limiter) IsInExceptionList(id int64) bool

IsInExceptionList will check and see if an ID is in the exception list of the listener or not.

func (*Limiter) IsStopped

func (l *Limiter) IsStopped() bool

IsStopped returns true if this limiter is already stopped and doesn't check for incoming messages.

func (*Limiter) IsTextOnly

func (l *Limiter) IsTextOnly() bool

IsTextOnly will return true if and only if this limiter is checking for text-only messages.

func (*Limiter) RemoveCustomIgnore

func (l *Limiter) RemoveCustomIgnore(id int64)

func (*Limiter) SetAsConditions

func (l *Limiter) SetAsConditions(conditions []filters.Message)

SetAsConditions will accept an array of conditions and will set the conditions of the limiter to them.

func (*Limiter) SetAsExceptionList

func (l *Limiter) SetAsExceptionList(list []int64)

SetAsExceptionList will set its argument at the exception list of this limiter. Please notice that this method won't append the list to the already existing exception list; but it will set it to this, so the already existing exception IDs assigned to this limiter will be lost.

func (*Limiter) SetDefaultInterval

func (l *Limiter) SetDefaultInterval()

SetDefaultInterval will set a default value to the checker's interval. It's recommended that users use `SetMaxCacheDuration` method instead of this one. If you haven't set any other parameters for the limiter, this will set the interval to 60 seconds at least.

func (*Limiter) SetFloodWaitTime

func (l *Limiter) SetFloodWaitTime(d time.Duration)

SetFloodWaitTime will set the flood wait duration for each chat to send `maxCount` message per this amount of time. if they send more than this amount of messages during this time, they will be limited by this limiter and so their messages won't be handled in the current group. (Notice: if `ConsiderUser` is set to `true`, this duration will be applied to unique users in the chat; not the total chat.)

func (*Limiter) SetMaxCacheDuration

func (l *Limiter) SetMaxCacheDuration(d time.Duration)

SetMaxCacheDuration will set the max duration for caching algorithm. WARNING: this value should always be greater than the `timeout` + `punishment` values of the limiter; otherwise this method will set the max cache duration to `timeout` + `punishment` + 1.

func (*Limiter) SetMaxMessageCount

func (l *Limiter) SetMaxMessageCount(count int)

SetMaxMessageCount sets the possible messages count in the anti-flood-wait amount of time (which is `l.timeout`). in that period of time, chat (or user) needs to send less than this much message, otherwise they will be limited by this limiter and so as a result of that their messages will be ignored by the bot.

func (*Limiter) SetPunishmentDuration

func (l *Limiter) SetPunishmentDuration(d time.Duration)

SetPunishmentDuration will set the punishment duration of the chat (or a user) after being limited by this limiter. Users needs to spend this amount of time + `l.timeout` to become free and so the handlers will work again for it. NOTICE: if `IsStrict` is set to `true`, as long as user sends message to the bot, the amount of passed-punishment time will become 0; so the user needs to stop sending messages to the bot until the punishment time is passed, otherwise the user will be limited forever.

func (*Limiter) SetTextOnly

func (l *Limiter) SetTextOnly(t bool)

SetTextOnly will set the limiter to check for text-only messages. pass true to this method to make the limiter check for text-only messages.

func (*Limiter) SetTriggerFunc

func (l *Limiter) SetTriggerFunc(t handlers.Response)

SetTriggerFunc will set the trigger function of this limiter. The trigger function will be triggered when the limiter limits a user. The information passed by it will be the information related to the last message of the user. If you want to set more than one trigger function, use `SetTriggerFuncs` method.

func (*Limiter) SetTriggerFuncs

func (l *Limiter) SetTriggerFuncs(t ...handlers.Response)

SetTriggerFuncs will set the trigger functions of this limiter. The trigger functions will be triggered when the limiter limits a user. The information passed by it will be the information related to the last message of the user.

func (*Limiter) Start

func (l *Limiter) Start()

Start will start the limiter. When the limiter is started (enabled), it will check for check for incoming messages; if they are considered as flood, the limiter won't let the handler functions to be called.

func (*Limiter) Stop

func (l *Limiter) Stop()

Stop method will make this limiter stop checking the incoming messages and will set its variables to nil. the main resources used by this limiter will be freed, such as map and mutex. but the configuration variables such as message time out will remain the same and won't be set to 0.

type LimiterConfig

type LimiterConfig struct {
	ConsiderChannel  bool
	ConsiderUser     bool
	ConsiderEdits    bool
	IgnoreMediaGroup bool
	TextOnly         bool
	IsStrict         bool
	HandlerGroups    []int
	ConsiderInline   bool
	Timeout          time.Duration
	PunishmentTime   time.Duration
	MaxTimeout       time.Duration
	MessageCount     int
}

LimiterConfig is the config type of the limiter.

var (
	DefaultConfig *LimiterConfig = &LimiterConfig{
		ConsiderChannel:  false,
		ConsiderUser:     true,
		ConsiderEdits:    false,
		IgnoreMediaGroup: true,
		TextOnly:         false,
		ConsiderInline:   true,
		IsStrict:         false,
		Timeout:          DefaultTimeout,
		PunishmentTime:   DefaultPunishmentTime,
		MaxTimeout:       DefaultMaxTimeout,
		MessageCount:     DefaultMessageCount,
	}
)

type UserStatus

type UserStatus struct {
	// Last field is the last time that we received a message
	// from the user.
	Last time.Time
	// contains filtered or unexported fields
}

UserStatus is the status of a user in the map.

func (*UserStatus) IsCustomLimited

func (s *UserStatus) IsCustomLimited() bool

func (*UserStatus) IsLimited

func (s *UserStatus) IsLimited() bool

IsLimited will check and see if the chat (or user) is limited by this limiter or not.