state

Documentation

Overview

Package state provides interfaces for a local or remote state, as well as abstractions around the REST API and Gateway events.

Index

• Variables
• type GuildAvailableEvent
• type GuildJoinEvent
• type GuildLeaveEvent
• type GuildReadyEvent
• type GuildUnavailableEvent
• type State
  • func New(token string) (*State, error)
  • func NewFromSession(s *session.Session, cabinet store.Cabinet) *State
  • func NewWithIntents(token string, intents ...gateway.Intents) (*State, error)
  • func NewWithStore(token string, cabinet store.Cabinet) (*State, error)
  • func (s *State) AuthorColor(message *gateway.MessageCreateEvent) (discord.Color, error)
  • func (s *State) AuthorDisplayName(message *gateway.MessageCreateEvent) string
  • func (s *State) Channel(id discord.ChannelID) (c *discord.Channel, err error)
  • func (s *State) Channels(guildID discord.GuildID) (cs []discord.Channel, err error)
  • func (s *State) CreatePrivateChannel(recipient discord.UserID) (*discord.Channel, error)
  • func (s *State) Emoji(guildID discord.GuildID, emojiID discord.EmojiID) (e *discord.Emoji, err error)
  • func (s *State) Emojis(guildID discord.GuildID) (es []discord.Emoji, err error)
  • func (s *State) Guild(id discord.GuildID) (*discord.Guild, error)
  • func (s *State) Guilds() (gs []discord.Guild, err error)
  • func (s *State) Me() (*discord.User, error)
  • func (s *State) Member(guildID discord.GuildID, userID discord.UserID) (*discord.Member, error)
  • func (s *State) MemberColor(guildID discord.GuildID, userID discord.UserID) (discord.Color, error)
  • func (s *State) MemberDisplayName(guildID discord.GuildID, userID discord.UserID) (string, error)
  • func (s *State) Members(guildID discord.GuildID) (ms []discord.Member, err error)
  • func (s *State) Message(channelID discord.ChannelID, messageID discord.MessageID) (*discord.Message, error)
  • func (s *State) Messages(channelID discord.ChannelID) ([]discord.Message, error)
  • func (s *State) Permissions(channelID discord.ChannelID, userID discord.UserID) (discord.Permissions, error)
  • func (s *State) Presence(gID discord.GuildID, uID discord.UserID) (*gateway.Presence, error)
  • func (s *State) PrivateChannels() ([]discord.Channel, error)
  • func (s *State) Ready() gateway.ReadyEvent
  • func (s *State) Role(guildID discord.GuildID, roleID discord.RoleID) (target *discord.Role, err error)
  • func (s *State) Roles(guildID discord.GuildID) ([]discord.Role, error)
  • func (s *State) WithContext(ctx context.Context) *State

Variables

var (
	MaxFetchMembers uint = 1000
	MaxFetchGuilds  uint = 100
)

Types

type GuildAvailableEvent

type GuildAvailableEvent struct {
	*gateway.GuildCreateEvent
}

GuildAvailableEvent gets fired when a guild becomes available again, after being previously declared unavailable through a GuildUnavailableEvent. This event will not be fired for guilds that were already unavailable when connecting to the gateway.

type GuildJoinEvent

type GuildJoinEvent struct {
	*gateway.GuildCreateEvent
}

GuildJoinEvent gets fired if the bot/user joins a guild.

type GuildLeaveEvent

type GuildLeaveEvent struct {
	*gateway.GuildDeleteEvent
}

GuildLeaveEvent gets fired if the bot/user left a guild, was removed or the owner deleted the guild.

type GuildReadyEvent

type GuildReadyEvent struct {
	*gateway.GuildCreateEvent
}

GuildReady gets fired for every guild the bot/user is in, as found in the Ready event.

Guilds that are unavailable when connecting, will not trigger a GuildReadyEvent, until they become available again.

type GuildUnavailableEvent

type GuildUnavailableEvent struct {
	*gateway.GuildDeleteEvent
}

GuildUnavailableEvent gets fired if a guild becomes unavailable.

type State

type State struct {
	*session.Session
	store.Cabinet

	// StateLog logs all errors that come from the state cache. This includes
	// not found errors. Defaults to a no-op, as state errors aren't that
	// important.
	StateLog func(error)

	// PreHandler is the manual hook that is executed before the State handler
	// is. This should only be used for low-level operations.
	// It's recommended to set Synchronous to true if you mutate the events.
	PreHandler *handler.Handler // default nil

	// Command handler with inherited methods. Ran after PreHandler. You should
	// most of the time use this instead of Session's, to avoid race conditions
	// with the State.
	*handler.Handler
	// contains filtered or unexported fields
}

State is the cache to store events coming from Discord as well as data from API calls.

Store

The state basically provides abstractions on top of the API and the state storage (Store). The state storage is effectively a set of interfaces which allow arbitrary backends to be implemented.

The default storage backend is a typical in-memory structure consisting of maps and slices. Custom backend implementations could embed this storage backend as an in-memory fallback. A good example of this would be embedding the default store for messages only, while handling everything else in Redis.

The package also provides a no-op store (NoopStore) that implementations could embed. This no-op store will always return an error, which makes the state fetch information from the API. The setters are all no-ops, so the fetched data won't be updated.

Handler

The state uses its own handler over session's to make all handlers run after the state updates itself. A PreHandler is exposed in any case the user needs the handlers to run before the state updates itself. Refer to that field's documentation.

The state also provides extra events and overrides to make up for Discord's inconsistencies in data. The following are known instances of such.

The Guild Create event is split up to make the state's Guild Available, Guild Ready and Guild Join events. Refer to these events' documentations for more information.

The Message Create and Message Update events with the Member field provided will have the User field copied from Author. This is because the User field will be empty, while the Member structure expects it to be there.

func New

func New(token string) (*State, error)

New creates a new state.

func NewFromSession

func NewFromSession(s *session.Session, cabinet store.Cabinet) *State

NewFromSession creates a new State from the passed Session and Cabinet.

func NewWithIntents

func NewWithIntents(token string, intents ...gateway.Intents) (*State, error)

NewWithIntents creates a new state with the given gateway intents. For more information, refer to gateway.Intents.

func NewWithStore

func NewWithStore(token string, cabinet store.Cabinet) (*State, error)

func (*State) AuthorColor

func (s *State) AuthorColor(message *gateway.MessageCreateEvent) (discord.Color, error)

func (*State) AuthorDisplayName

func (s *State) AuthorDisplayName(message *gateway.MessageCreateEvent) string

func (*State) Channel

func (s *State) Channel(id discord.ChannelID) (c *discord.Channel, err error)

func (*State) Channels

func (s *State) Channels(guildID discord.GuildID) (cs []discord.Channel, err error)

func (*State) CreatePrivateChannel

func (s *State) CreatePrivateChannel(recipient discord.UserID) (*discord.Channel, error)

func (*State) Emoji

func (s *State) Emoji(
	guildID discord.GuildID, emojiID discord.EmojiID) (e *discord.Emoji, err error)

func (*State) Emojis

func (s *State) Emojis(guildID discord.GuildID) (es []discord.Emoji, err error)

func (*State) Guild

func (s *State) Guild(id discord.GuildID) (*discord.Guild, error)

func (*State) Guilds

func (s *State) Guilds() (gs []discord.Guild, err error)

Guilds will only fill a maximum of 100 guilds from the API.

func (*State) Me

func (s *State) Me() (*discord.User, error)

func (*State) Member

func (s *State) Member(guildID discord.GuildID, userID discord.UserID) (*discord.Member, error)

func (*State) MemberColor

func (s *State) MemberColor(guildID discord.GuildID, userID discord.UserID) (discord.Color, error)

func (*State) MemberDisplayName

func (s *State) MemberDisplayName(guildID discord.GuildID, userID discord.UserID) (string, error)

func (*State) Members

func (s *State) Members(guildID discord.GuildID) (ms []discord.Member, err error)

func (*State) Message

func (s *State) Message(
	channelID discord.ChannelID, messageID discord.MessageID) (*discord.Message, error)

func (*State) Messages

func (s *State) Messages(channelID discord.ChannelID) ([]discord.Message, error)

Messages fetches maximum 100 messages from the API, if it has to. There is no limit if it's from the State storage.

func (*State) Permissions

func (s *State) Permissions(
	channelID discord.ChannelID, userID discord.UserID) (discord.Permissions, error)

Permissions gets the user's permissions in the given channel. If the channel is not in any guild, then an error is returned.

func (*State) Presence

func (s *State) Presence(gID discord.GuildID, uID discord.UserID) (*gateway.Presence, error)

Presence checks the state for user presences. If no guildID is given, it will look for the presence in all cached guilds.

func (*State) PrivateChannels

func (s *State) PrivateChannels() ([]discord.Channel, error)

PrivateChannels gets the direct messages of the user. This is not supported for bots.

func (*State) Ready

func (s *State) Ready() gateway.ReadyEvent

Ready returns a copy of the Ready event. Although this function is safe to call concurrently, its values should still not be changed, as certain types like slices are not concurrent-safe.

Note that if Ready events are not received yet, then the returned event will be a zero-value Ready instance.

func (*State) Role

func (s *State) Role(guildID discord.GuildID, roleID discord.RoleID) (target *discord.Role, err error)

func (*State) Roles

func (s *State) Roles(guildID discord.GuildID) ([]discord.Role, error)

func (*State) WithContext

func (s *State) WithContext(ctx context.Context) *State

WithContext returns a shallow copy of State with the context replaced in the API client. All methods called on the State will use this given context. This method is thread-safe.