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
• func MemberColor(m *discord.Member, role func(discord.RoleID) *discord.Role) (discord.Color, bool)
• func NewShardFunc(opts func(*shard.Manager, *State)) shard.NewShardFunc
• type GuildAvailableEvent
• type GuildJoinEvent
• type GuildLeaveEvent
• type GuildReadyEvent
• type GuildUnavailableEvent
• type State
  • func New(token string) *State
  • func NewAPIOnlyState(token string, h *handler.Handler) *State
  • func NewFromSession(s *session.Session, cabinet *store.Cabinet) *State
  • func NewWithIdentifier(id gateway.Identifier) *State
  • func NewWithIntents(token string, intents ...gateway.Intents) *State
  • func NewWithStore(token string, cabinet *store.Cabinet) *State
  • func (s *State) AuthorColor(message *gateway.MessageCreateEvent) (discord.Color, bool)
  • 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, bool)
  • func (s *State) MemberDisplayName(guildID discord.GuildID, userID discord.UserID) (string, error)
  • func (s *State) MemberRoles(guildID discord.GuildID, userID discord.UserID) ([]discord.Role, 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, limit uint) ([]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) (*discord.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) SortedRoles(guildID discord.GuildID) ([]discord.Role, error)
  • func (s *State) WithContext(ctx context.Context) *State

Variables

var (
	MaxFetchMembers uint = 1000
	MaxFetchGuilds  uint = 100
)

Functions

func MemberColor

func MemberColor(m *discord.Member, role func(discord.RoleID) *discord.Role) (discord.Color, bool)

MemberColor is a weird variant of State's MemberColor method that allows a custom Role getter. If m is nil, then NullColor is returned.

func NewShardFunc

func NewShardFunc(opts func(*shard.Manager, *State)) shard.NewShardFunc

NewShardFunc creates a shard constructor with its own state registry and handlers. The given opts function is called everytime the State is created. The user should initialize handlers and intents in the opts function.

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

New creates a new state.

func NewAPIOnlyState

func NewAPIOnlyState(token string, h *handler.Handler) *State

NewAPIOnlyState creates a new State that only has API functions and no gateway (or state caches). Use this as a drop-in for InteractionServer usage.

This function may work for most use cases; however, it will not work for all use cases. For example, bots that need the gateway won't be able to fully work, which is expected.

func NewFromSession

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

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

func NewWithIdentifier

func NewWithIdentifier(id gateway.Identifier) *State

NewWithIdentifier creates a new state with the given gateway identifier.

func NewWithIntents

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

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

NewWithStore creates a new state with the given store cabinet.

func (*State) AuthorColor

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

AuthorColor is a variant of MemberColor that possibly uses the existing Member field inside MessageCreateEvent.

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, bool)

MemberColor fetches the color of the member with the given user ID inside the guild with the given ID.

func (*State) MemberDisplayName

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

func (*State) MemberRoles

func (s *State) MemberRoles(guildID discord.GuildID, userID discord.UserID) ([]discord.Role, error)

MemberRoles returns a list of roles that the given member has. The returned roles are sorted by their position.

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, limit uint) ([]discord.Message, error)

Messages returns a slice filled with the most recent messages sent in the channel with the passed ID. The method automatically paginates until it reaches the passed limit, or, if the limit is set to 0, has fetched all messages in the channel.

As the underlying endpoint is capped at a maximum of 100 messages per request, at maximum a total of limit/100 rounded up requests will be made, although they may be less, if no more messages are available or there are cached messages. When fetching the messages, those with the highest ID, will be fetched first. The returned slice will be sorted from latest to oldest.

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) (*discord.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) SortedRoles

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

SortedRoles returns a list of roles sorted by their position. The roles are fetched using (*State).Roles.

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.