store

Documentation

Overview

Package store contains interfaces of the state's storage and its implementations.

Getter Methods

All getter methods will be wrapped by the State. If the State can't find anything in the storage, it will call the API itself and automatically add what's missing into the storage.

Methods that return with a slice should pay attention to race conditions that would mutate the underlying slice (and as a result the returned slice as well). The best way to avoid this is to copy the whole slice, like defaultstore implementations do.

Getter methods should not care about returning slices in order, unless explicitly stated against.

ErrNotFound Rules

If a getter method cannot find something, it should return ErrNotFound. Callers including State may check if the error is ErrNotFound to do something else. For example, if Guilds currently stores nothing, then it should return an empty slice and a nil error.

In some cases, there may not be a way to know whether or not the store is unpopulated or is actually empty. In that case, implementations can return ErrNotFound when either happens. This will make State refetch from the API, so it is not ideal.

Remove Methods

Remove methods should return a nil error if the item it wants to delete is not found. This helps save some additional work in some cases.

Index

• Variables
• type Cabinet
  • func (sc *Cabinet) Reset() error
• type ChannelStore
• type CoreStorer
• type EmojiStore
• type GuildStore
• type MeStore
• type MemberStore
• type MessageStore
• type NoopStore
• type PresenceStore
• type ResetErrors
  • func (errs ResetErrors) Error() string
  • func (errs ResetErrors) Unwrap() error
• type Resetter
• type RoleStore
• type VoiceStateStore

Variables

var ErrNotFound = errors.New("item not found in store")

ErrNotFound is an error that a store can use to return when something isn't in the storage. There is no strict restrictions on what uses this (the default one does, though), so be advised.

var Noop = NoopStore{}

Noop is the value for a NoopStore.

var NoopCabinet = &Cabinet{
	MeStore:         Noop,
	ChannelStore:    Noop,
	EmojiStore:      Noop,
	GuildStore:      Noop,
	MemberStore:     Noop,
	MessageStore:    Noop,
	PresenceStore:   Noop,
	RoleStore:       Noop,
	VoiceStateStore: Noop,
}

NoopCabinet is a store cabinet with all store methods set to the Noop implementations.

Types

type Cabinet

type Cabinet struct {
	MeStore
	ChannelStore
	EmojiStore
	GuildStore
	MemberStore
	MessageStore
	PresenceStore
	RoleStore
	VoiceStateStore
}

Cabinet combines all store interfaces into one but allows swapping individual stores out for another. Since the struct only consists of interfaces, it can be copied around.

func (*Cabinet) Reset

func (sc *Cabinet) Reset() error

Reset resets everything inside the container.

type ChannelStore

type ChannelStore interface {
	Resetter

	// Channel searches for both DM and guild channels.
	Channel(discord.ChannelID) (*discord.Channel, error)
	// CreatePrivateChannel searches for private channels by the recipient ID.
	// It has the same API as *api.Client does.
	CreatePrivateChannel(recipient discord.UserID) (*discord.Channel, error)

	// Channels returns only channels from a guild.
	Channels(discord.GuildID) ([]discord.Channel, error)
	// PrivateChannels returns all private channels from the state.
	PrivateChannels() ([]discord.Channel, error)

	ChannelSet(c *discord.Channel, update bool) error
	ChannelRemove(*discord.Channel) error
}

ChannelStore is the store interface for all channels.

type CoreStorer

type CoreStorer interface {
	Resetter
	Lock()
	Unlock()
}

type EmojiStore

type EmojiStore interface {
	Resetter

	Emoji(discord.GuildID, discord.EmojiID) (*discord.Emoji, error)
	Emojis(discord.GuildID) ([]discord.Emoji, error)

	// EmojiSet should delete all old emojis before setting new ones. The given
	// emojis slice will be a complete list of all emojis.
	EmojiSet(guildID discord.GuildID, emojis []discord.Emoji, update bool) error
}

EmojiStore is the store interface for all emojis.

type GuildStore

type GuildStore interface {
	Resetter

	Guild(discord.GuildID) (*discord.Guild, error)
	Guilds() ([]discord.Guild, error)

	GuildSet(g *discord.Guild, update bool) error
	GuildRemove(id discord.GuildID) error
}

GuildStore is the store interface for all guilds.

type MeStore

type MeStore interface {
	Resetter

	Me() (*discord.User, error)
	MyselfSet(me discord.User, update bool) error
}

MeStore is the store interface for the current user.

type MemberStore

type MemberStore interface {
	Resetter

	Member(discord.GuildID, discord.UserID) (*discord.Member, error)
	Members(discord.GuildID) ([]discord.Member, error)

	MemberSet(guildID discord.GuildID, m *discord.Member, update bool) error
	MemberRemove(discord.GuildID, discord.UserID) error
}

MemberStore is the store interface for all members.

type MessageStore

type MessageStore interface {
	Resetter

	// MaxMessages returns the maximum number of messages. It is used to know if
	// the state cache is filled or not for one channel
	MaxMessages() int

	Message(discord.ChannelID, discord.MessageID) (*discord.Message, error)
	// Messages should return messages ordered from latest to earliest.
	Messages(discord.ChannelID) ([]discord.Message, error)

	// MessageSet either updates or adds a new message.
	//
	// A new message can be added, by setting update to false. Depending on
	// timestamp of the message, it will either be prepended or appended.
	//
	// If update is set to true, MessageSet will check if a message with the
	// id of the passed message is stored, and update it if so. Otherwise, if
	// there is no such message, it will be discarded.
	MessageSet(m *discord.Message, update bool) error
	MessageRemove(discord.ChannelID, discord.MessageID) error
}

MessageStore is the store interface for all messages.

type NoopStore

type NoopStore = noop

NoopStore is a no-op implementation of all store interfaces. Its getters will always return ErrNotFound, and its setters will never return an error.

type PresenceStore

type PresenceStore interface {
	Resetter

	Presence(discord.GuildID, discord.UserID) (*discord.Presence, error)
	Presences(discord.GuildID) ([]discord.Presence, error)

	PresenceSet(guildID discord.GuildID, p *discord.Presence, update bool) error
	PresenceRemove(discord.GuildID, discord.UserID) error
}

PresenceStore is the store interface for all user presences. Presences don't get fetched from the API; they will only be updated through the Gateway.

type ResetErrors

type ResetErrors []error

ResetErrors represents the multiple errors when StoreContainer is being resetted. A ResetErrors value must have at least 1 error.

func (ResetErrors) Error

func (errs ResetErrors) Error() string

Error formats ResetErrors, showing the number of errors and the last error.

func (ResetErrors) Unwrap

func (errs ResetErrors) Unwrap() error

Unwrap returns the last error in the list.

type Resetter

type Resetter interface {
	// Reset resets the store to a new valid instance.
	Reset() error
}

Resetter is an interface to reset the store on every Ready event.

type RoleStore

type RoleStore interface {
	Resetter

	Role(discord.GuildID, discord.RoleID) (*discord.Role, error)
	Roles(discord.GuildID) ([]discord.Role, error)

	RoleSet(guildID discord.GuildID, r *discord.Role, update bool) error
	RoleRemove(discord.GuildID, discord.RoleID) error
}

RoleStore is the store interface for all member roles.

type VoiceStateStore

type VoiceStateStore interface {
	Resetter

	VoiceState(discord.GuildID, discord.UserID) (*discord.VoiceState, error)
	VoiceStates(discord.GuildID) ([]discord.VoiceState, error)

	VoiceStateSet(guildID discord.GuildID, s *discord.VoiceState, update bool) error
	VoiceStateRemove(discord.GuildID, discord.UserID) error
}

VoiceStateStore is the store interface for all voice states.